Add initial support for analyzing AMDGPU binaries (#900)
[dyninst.git] / stackwalk / doc / API / SymbolLookup.tex
1 \subsubsection{Class SymbolLookup}
2 \definedin{symlookup.h}
3
4 The \code{SymbolLookup} virtual class is an interface for associating a symbolic
5 name with a stack frame. Each \code{Frame} object contains an address (the RA)
6 pointing into the function (or function-like object) that created its stack
7 frame. However, users do not always want to deal with addresses when symbolic
8 names are more convenient. This class is an interface for mapping a \code{Frame} object's RA into a name.
9
10 In addition to getting a name, this class can also associate an opaque object
11 (via a \code{void*}) with a Frame object. It is up to the \code{SymbolLookup}
12 implementation what to return in this opaque object.
13
14 The default implementation of \code{SymbolLookup} provided by StackwalkerAPI
15 uses the \code{SymLite} tool to lookup symbol names. It returns a Symbol
16 object in the anonymous \code{void*}.
17
18 \begin{apient}
19 SymbolLookup(std::string exec_path = "");
20 \end{apient}
21 \apidesc{Constructor for a \code{SymbolLookup} object.}
22
23 \begin{apient}
24 virtual bool lookupAtAddr(Address addr, 
25                           string &out_name, 
26                           void* &out_value) = 0
27 \end{apient}
28 \apidesc{
29     This method takes an address, \code{addr}, as input and returns the function name,
30     \code{out\_name}, and an opaque value, \code{out\_value}, at that address. Output parameter
31     \code{out\_name} should be the name of the function that contains
32     \code{addr}. Output
33     parameter \code{out\_value} can be any opaque value determined by the
34     \code{SymbolLookup}
35     implementation. The values returned are used by the \code{Frame::getName} and
36     \code{Frame::getObject} functions.
37
38     This method returns \code{true} on success and \code{false} on error.
39 }
40
41 \begin{apient}
42 virtual Walker *getWalker()
43 \end{apient}
44 \apidesc{
45     This method returns the \code{Walker} object associated with this
46     \code{SymbolLookup}.
47 }
48
49 \begin{apient}
50 virtual ProcessState *getProcessSate()
51 \end{apient}
52 \apidesc{
53     This method returns the \code{ProcessState} object associated with this
54     \code{SymbolLookup}.
55 }
56