Initial import

[external/libunwind.git] / doc / unw_create_addr_space.tex

\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}

\input{common.tex}

\begin{document}

\begin{Name}{3}{unw\_create\_addr\_space}{David Mosberger-Tang}{Programming Library}{unw\_create\_addr\_space}unw\_create\_addr\_space -- create address space for remote unwinding
\end{Name}

\section{Synopsis}

\File{\#include $<$libunwind.h$>$}\\

\Type{unw\_addr\_space\_t} \Func{unw\_create\_addr\_space}(\Type{unw\_accessors\_t~*}\Var{ap}, \Type{int} \Var{byteorder});\\

\section{Description}

The \Func{unw\_create\_addr\_space}() routine creates a new unwind
address-space and initializes it based on the call-back routines
passed via the \Var{ap} pointer and the specified \Var{byteorder}.
The call-back routines are described in detail below.  The
\Var{byteorder} can be set to 0 to request the default byte-order of
the unwind target.  To request a particular byte-order,
\Var{byteorder} can be set to any constant defined by
\File{$<$endian.h$>$}.  In particular, \Const{\_\_LITTLE\_ENDIAN} would
request little-endian byte-order and \Const{\_\_BIG\_ENDIAN} would
request big-endian byte-order.  Whether or not a particular byte-order
is supported depends on the target platform.

\section{Call-back Routines}

\Prog{Libunwind} uses a set of call-back routines to access the
information it needs to unwind a chain of stack-frames.  These
routines are specified via the \Var{ap} argument, which points to a
variable of type \Type{unw\_accessors\_t}.  The contents of this
variable is copied into the newly-created address space, so the
variable must remain valid only for the duration of the call to
\Func{unw\_create\_addr\_space}().

The first argument to every call-back routine is an address-space
identifier (\Var{as}) and the last argument is an arbitrary,
application-specified void-pointer (\Var{arg}).  When invoking a
call-back routine, \Prog{libunwind} sets the \Var{as} argument to the
address-space on whose behalf the invocation is made and the \Var{arg}
argument to the value that was specified when
\Func{unw\_init\_remote}(3) was called.

The synopsis and a detailed description of every call-back routine
follows below.

\subsection{Call-back Routine Synopsis}

\Type{int} \Func{find\_proc\_info}(\Type{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_word\_t} \Var{ip}, \Type{unw\_proc\_info\_t~*}\Var{pip},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{int} \Var{need\_unwind\_info}, \Type{void~*}arg);\\
\Type{void} \Func{put\_unwind\_info}(\Type{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_proc\_info\_t~*}pip, \Type{void~*}\Var{arg});\\
\Type{int} \Func{get\_dyn\_info\_list\_addr}(\Type{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_word\_t~*}\Var{dilap}, \Type{void~*}\Var{arg});\\
\Type{int} \Func{access\_mem}(\Var{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_word\_t} \Var{addr}, \Type{unw\_word\_t~*}\Var{valp},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{int} \Var{write}, \Type{void~*}\Var{arg});\\
\Type{int} \Func{access\_reg}(\Var{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_regnum\_t} \Var{regnum}, \Type{unw\_word\_t~*}\Var{valp},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{int} \Var{write}, \Type{void~*}\Var{arg});\\
\Type{int} \Func{access\_fpreg}(\Var{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_regnum\_t} \Var{regnum}, \Type{unw\_fpreg\_t~*}\Var{fpvalp},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{int} \Var{write}, \Type{void~*}\Var{arg});\\
\Type{int} \Func{resume}(\Var{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_cursor\_t~*}\Var{cp}, \Type{void~*}\Var{arg});\\
\Type{int} \Func{get\_proc\_name}(\Type{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_word\_t} \Var{addr}, \Type{char~*}\Var{bufp},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{size\_t} \Var{buf\_len}, \Type{unw\_word\_t~*}\Var{offp},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{void~*}\Var{arg});\\

\subsection{find\_proc\_info}

\Prog{Libunwind} invokes the \Func{find\_proc\_info}() call-back to
locate the information need to unwind a particular procedure.  The
\Var{ip} argument is an instruction-address inside the procedure whose
information is needed.  The \Var{pip} argument is a pointer to the
variable used to return the desired information.  The type of this
variable is \Type{unw\_proc\_info\_t}.  See
\Func{unw\_get\_proc\_info(3)} for details.  Argument
\Var{need\_unwind\_info} is zero if the call-back does not need to
provide values for the following members in the
\Type{unw\_proc\_info\_t} structure: \Var{format},
\Var{unwind\_info\_size}, and \Var{unwind\_info}.  If
\Var{need\_unwind\_info} is non-zero, valid values need to be returned
in these members.  Furthermore, the contents of the memory addressed
by the \Var{unwind\_info} member must remain valid until the info is
released via the \Func{put\_unwind\_info} call-back (see below).

On successful completion, the \Func{find\_proc\_info}() call-back must
return zero.  Otherwise, the negative value of one of the
\Type{unw\_error\_t} error-codes may be returned.  In particular, this
call-back may return -\Const{UNW\_ESTOPUNWIND} to signal the end of
the frame-chain.

\subsection{put\_unwind\_info}

\Prog{Libunwind} invokes the \Func{put\_unwind\_info}() call-back to
release the resources (such as memory) allocated by a previous call to
\Func{find\_proc\_info}() with the \Var{need\_unwind\_info} argument
set to a non-zero value.  The \Var{pip} argument has the same value as
the argument of the same name in the previous matching call to
\Func{find\_proc\_info}().  Note that \Prog{libunwind} does \emph{not}
invoke \Func{put\_unwind\_info} for calls to \Func{find\_proc\_info}()
with a zero \Var{need\_unwind\_info} argument.


\subsection{get\_dyn\_info\_list\_addr}

\Prog{Libunwind} invokes the \Func{get\_dyn\_info\_list\_addr}()
call-back to obtain the address of the head of the dynamic unwind-info
registration list.  The variable stored at the returned address must
have a type of \Type{unw\_dyn\_info\_list\_t} (see
\Func{\_U\_dyn\_register}(3)).  The \Var{dliap} argument is a pointer
to a variable of type \Type{unw\_word\_t} which is used to return the
address of the dynamic unwind-info registration list.  If no dynamic
unwind-info registration list exist, the value pointed to by
\Var{dliap} must be cleared to zero.  \Prog{Libunwind} will cache the
value returned by \Func{get\_dyn\_info\_list\_addr}() if caching is
enabled for the given address-space.  The cache can be cleared with a
call to \Func{unw\_flush\_cache}().

On successful completion, the \Func{get\_dyn\_info\_list\_addr}()
call-back must return zero.  Otherwise, the negative value of one of
the \Type{unw\_error\_t} error-codes may be returned.

\subsection{access\_mem}

\Prog{Libunwind} invokes the \Func{access\_mem}() call-back to read
from or write to a word of memory in the target address-space.  The
address of the word to be accessed is passed in argument \Var{addr}.
To read memory, \Prog{libunwind} sets argument \Var{write} to zero and
\Var{valp} to point to the word that receives the read value.  To
write memory, \Prog{libunwind} sets argument \Var{write} to a non-zero
value and \Var{valp} to point to the word that contains the value to
be written.  The word that \Var{valp} points to is always in the
byte-order of the host-platform, regardless of the byte-order of the
target.  In other words, it is the responsibility of the call-back
routine to convert between the target's and the host's byte-order, if
necessary.

On successful completion, the \Func{access\_mem}()
call-back must return zero.  Otherwise, the negative value of one of
the \Type{unw\_error\_t} error-codes may be returned.

\subsection{access\_reg}

\Prog{Libunwind} invokes the \Func{access\_reg}() call-back to read
from or write to a scalar (non-floating-point) CPU register.  The
index of the register to be accessed is passed in argument
\Var{regnum}.  To read a register, \Prog{libunwind} sets argument
\Var{write} to zero and \Var{valp} to point to the word that receives
the read value.  To write a register, \Prog{libunwind} sets argument
\Var{write} to a non-zero value and \Var{valp} to point to the word
that contains the value to be written.  The word that \Var{valp}
points to is always in the byte-order of the host-platform, regardless
of the byte-order of the target.  In other words, it is the
responsibility of the call-back routine to convert between the
target's and the host's byte-order, if necessary.

On successful completion, the \Func{access\_reg}() call-back must
return zero.  Otherwise, the negative value of one of the
\Type{unw\_error\_t} error-codes may be returned.

\subsection{access\_fpreg}

\Prog{Libunwind} invokes the \Func{access\_fpreg}() call-back to read
from or write to a floating-point CPU register.  The index of the
register to be accessed is passed in argument \Var{regnum}.  To read a
register, \Prog{libunwind} sets argument \Var{write} to zero and
\Var{fpvalp} to point to a variable of type \Type{unw\_fpreg\_t} that
receives the read value.  To write a register, \Prog{libunwind} sets
argument \Var{write} to a non-zero value and \Var{fpvalp} to point to
the variable of type \Type{unw\_fpreg\_t} that contains the value to
be written.  The word that \Var{fpvalp} points to is always in the
byte-order of the host-platform, regardless of the byte-order of the
target.  In other words, it is the responsibility of the call-back
routine to convert between the target's and the host's byte-order, if
necessary.

On successful completion, the \Func{access\_fpreg}() call-back must
return zero.  Otherwise, the negative value of one of the
\Type{unw\_error\_t} error-codes may be returned.

\subsection{resume}

\Prog{Libunwind} invokes the \Func{resume}() call-back to resume
execution in the target address space.  Argument \Var{cp} is the
unwind-cursor that identifies the stack-frame in which execution
should resume.  By the time \Prog{libunwind} invokes the \Func{resume}
call-back, it has already established the desired machine- and
memory-state via calls to the \Func{access\_reg}(),
\Func{access\_fpreg}, and \Func{access\_mem}() call-backs.  Thus, all
the call-back needs to do is perform whatever action is needed to
actually resume execution.

The \Func{resume} call-back is invoked only in response to a call to
\Func{unw\_resume}(3), so applications which never invoke
\Func{unw\_resume}(3) need not define the \Func{resume} callback.

On successful completion, the \Func{resume}() call-back must return
zero.  Otherwise, the negative value of one of the
\Type{unw\_error\_t} error-codes may be returned.  As a special case,
when resuming execution in the local address space, the call-back will
not return on success.

\subsection{get\_proc\_name}

\Prog{Libunwind} invokes the \Func{get\_proc\_name}() call-back to
obtain the procedure-name of a static (not dynamically generated)
procedure.  Argument \Var{addr} is an instruction-address within the
procedure whose name is to be obtained.  The \Var{bufp} argument is a
pointer to a character-buffer used to return the procedure name.  The
size of this buffer is specified in argument \Var{buf\_len}.  The
returned name must be terminated by a NUL character.  If the
procedure's name is longer than \Var{buf\_len} bytes, it must be
truncated to \Var{buf\_len}\Prog{-1} bytes, with the last byte in the
buffer set to the NUL character and -\Const{UNW\_ENOMEM} must be
returned.  Argument \Var{offp} is a pointer to a word which is used to
return the byte-offset relative to the start of the procedure whose
name is being returned.  For example, if procedure \Func{foo}() starts
at address 0x40003000, then invoking \Func{get\_proc\_name}() with
\Var{addr} set to 0x40003080 should return a value of 0x80 in the word
pointed to by \Var{offp} (assuming the procedure is at least 0x80
bytes long).

On successful completion, the \Func{get\_proc\_name}() call-back must
return zero.  Otherwise, the negative value of one of the
\Type{unw\_error\_t} error-codes may be returned.


\section{Return Value}

On successful completion, \Func{unw\_create\_addr\_space}() returns a
non-\Const{NULL} value that represents the newly created
address-space.  Otherwise, \Const{NULL} is returned.

\section{Thread and Signal Safety}

\Func{unw\_create\_addr\_space}() is thread-safe but \emph{not}
safe to use from a signal handler.

\section{See Also}

\SeeAlso{\_U\_dyn\_register(3)},
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_destroy\_addr\_space(3)},
\SeeAlso{unw\_get\_proc\_info(3)},
\SeeAlso{unw\_init\_remote(3)},
\SeeAlso{unw\_resume(3)}

\section{Author}

\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd

\end{document}