Re: [patch][python] Add symbol, symbol table and frame block support to GDB API

[Phil Muldoon <pmuldoon@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 2035 bytes --]

On 02/02/2010 08:14 PM, Eli Zaretskii wrote:

>>>> +All of the name-scope contours of a program are represented as 'block'
>>>
>>> What are "contours"?  Is this a widespread enough terminology to be
>>> understood without defining it first?  If not, I suggest to define it.
>>
>>
>> I really agonized over the whole block description, as there is no (as
>> far as I know) analogue to the GDB CLI for blocks.  It's revealing an
>> API that GDB uses to manipulate blocks in a frame.  I could use some
>> help making this more palatable enough to the consumer of the API,
>> over trying to teach the user compiler/runtime semantics (which is not
>> the purpose of the GDB manual).  What do you think?
> 
> How about if you tell what you want in the most technical way you
> think about these issues, disregarding the fact that it's for GDB
> users, and I will then rephrase it to be palatable to mere mortals?


I've attached an updated patch.  What do you think?


>>>> +@item SYMBOL_LOC_REF_ARG
>>>> +Value address is an offset in arglist.
>>>
>>> I couldn't understand what this means.
>>
>>
>> Yeah, this is a concept expressed in the comments of the code.
> 
> Where?  I don't see it in the patch you submitted.
> 


I was referring to the comments in the GDB code that this Python API
was exposing:


http://sourceware.org/cgi-bin/cvsweb.cgi/src/gdb/symtab.h?rev=1.146&content-type=text/x-cvsweb-markup&cvsroot=src&only_with_tag=MAIN

under the LOC_REF_ARG entry in the address_class enum. Though I'm not
sure that under the current Python API the the user can access
arglist, but we still have to add it so the symbol address location
type can be tested (and in this case, discarded).


>>> Do we need a NEWS entry for this?
>>
>> Not sure. From my point of view I am merging code from Archer to FSF
>> GDB. I'll happily write one up if you think we need one? What do you
>> think?
> 
> Something like
> 
>   The GDB Python API now has access to symbols, symbol tables, and
>   frame's code blocks.

Added, thanks


Cheers,

Phil


[-- Attachment #2: gdb_merge_doc.patch --]
[-- Type: text/plain, Size: 11902 bytes --]

diff --git a/gdb/NEWS b/gdb/NEWS
index 867b51f..a7bdec8 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -203,6 +203,11 @@ QTDisconnected
 qTfP, qTsP
    Get data about the tracepoints currently in use.
 
+* Python scripting
+
+The GDB Python API now has access to symbols, symbol tables, and
+frame's code blocks.
+
 * Bug fixes
 
 Process record now works correctly with hardware watchpoints.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 2145f2b..1830356 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -19538,7 +19538,10 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
 * Commands In Python::          Implementing new commands in Python.
 * Functions In Python::         Writing new convenience functions.
 * Objfiles In Python::          Object files.
-* Frames In Python::            Acessing inferior stack frames from Python.
+* Frames In Python::            Accessing inferior stack frames from Python.
+* Blocks In Python::            Accessing frame blocks from Python.
+* Symbols In Python::           Python representation of symbols.
+* Symbol Tables In Python::     Python representation of symbol tables.
 * Lazy Strings In Python::      Python representation of lazy strings.
 @end menu
 
@@ -20698,7 +20701,7 @@ information.
 @end defivar
 
 @node Frames In Python
-@subsubsection Acessing inferior stack frames from Python.
+@subsubsection Accessing inferior stack frames from Python.
 
 @cindex frames in python
 When the debugged program stops, @value{GDBN} is able to analyze its call
@@ -20761,6 +20764,15 @@ function to a string.
 Returns the frame's resume address.
 @end defmethod
 
+@defmethod Frame block
+Returns the frame's code block.  @xref{Blocks In Python}.
+@end defmethod
+
+@defmethod Frame function
+Returns the symbol for the function corresponding to this frame.
+@xref{Symbols In Python}.
+@end defmethod
+
 @defmethod Frame older
 Return the frame that called this frame.
 @end defmethod
@@ -20769,10 +20781,308 @@ Return the frame that called this frame.
 Return the frame called by this frame.
 @end defmethod
 
+@defmethod Frame find_sal
+Return the frame's symtab and line object.
+@xref{Symbol Tables In Python}.
+@end defmethod
+
 @defmethod Frame read_var variable
 Return the value of the given variable in this frame.  @var{variable} must
 be a string.
 @end defmethod
+
+@defmethod Frame select
+Set this frame to be the selected frame.  @xref{Stack, ,Examining the
+Stack}.
+@end defmethod
+@end table
+
+@node Blocks In Python
+@subsubsection Accessing frame blocks from Python.
+
+@cindex blocks in python
+@tindex gdb.Block
+
+Within each frame, @value{GDBN} maintains information on each block
+stored in that frame.  These blocks are organized in a hierarchical
+order, and are represented individually within Python as a
+@code{gdb.Block}.  Please see @ref{Frames In Python} for a more in-depth
+discussion on frames.  Furthermore, see @ref{Stack, ,Examining the
+Stack} for more detailed technical information on @value{GDBN}'s
+book-keeping of the stack.
+
+The following block-related functions are available in the @code{gdb}
+module:
+
+@findex gdb.block_for_pc
+@defun block_for_pc pc
+Return the @code{gdb.Block} containing the given @var{pc} value.  If the
+block cannot be found for the @var{pc} value specified, the function
+will return @code{None}.
+@end defun
+
+A @code{gdb.Block} object has the following attributes:
+
+@table @code
+@defivar Block start
+This attribute holds the start address of the block.  This attribute is not
+writable.
+@end defivar
+
+@defivar Block end
+This attribute holds the end address of the block.  This attribute
+is not writable.
+@end defivar
+
+@defivar Block function
+This attribute holds the name of the block represented as a
+@code{gdb.Symbol}.  If the block is not named, then this attribute
+returns @code{None}.  This attribute is not writable.
+@end defivar
+
+@defivar Block superblock
+This attribute holds the block containing this block.  If this parent
+block does not exist, this attribute holds @code{None}.  This
+attribute is not writable.
+@end defivar
+@end table
+
+@node Symbols In Python
+@subsubsection Python representation of Symbols.
+
+@cindex symbols in python
+@tindex gdb.Symbol
+
+@value{GDBN} represents every variable, function and type as an
+entry in a symbol table.  @xref{Symbols, ,Examining the Symbol Table}.
+Similarly, Python represents these symbols in @value{GDBN} with the
+@code{gdb.Symbol} object.
+
+The following symbol-related functions are available in the @code{gdb}
+module:
+
+@findex gdb.lookup_symbol
+@defun lookup_symbol name [block] [domain]
+This function looks up a symbol by name.  The search scope can be
+restricted to the parameters defined in the optional domain and block
+arguments.
+
+@var{name} is the name of the symbol to look-up.  It must be a
+string.  The optional @var{block} argument restricts the look-up to
+symbols visible in that @var{block}.  The @var{block} argument must be a
+@code{gdb.Block} object.  The optional @var{domain} argument restricts
+the look-up to the domain type.  The @var{domain} argument must be a
+domain constant defined in the @code{gdb} module and described later
+in this chapter.
+@end defun
+
+A @code{gdb.Symbol} object has the following attributes:
+
+@table @code
+@defivar Symbol symtab
+The symbol table in which the symbol appears.  This attribute is
+represented as a @code{gdb.Symtab} object.  @xref{Symbol Tables In
+Python}.  This attribute is not writable.
+@end defivar
+
+@defivar Symbol name
+The name of the symbol as a string.  This attribute is not writable.
+@end defivar
+
+@defivar Symbol linkage_name
+The name of the symbol, as used by the linker (i.e., may be mangled).
+This attribute is not writable.
+@end defivar
+
+@defivar Symbol print_name
+The name of the symbol in a form suitable for output.  This is either
+@code{name} or @code{linkage_name}, depending on whether the user
+asked @value{GDBN} to display demangled or mangled names.
+@end defivar
+
+@defivar Symbol addr_class
+The address class of the symbol.  This classifies how to find the value
+of a symbol.  Each address class is a constant defined in the
+@code{gdb} module and described later in this chapter.
+@end defivar
+
+@defivar Symbol is_argument
+Is @code{True} if the symbol is an argument of a function.
+@end defivar
+
+@defivar Symbol is_constant
+Is @code{True} if the symbol is a constant.
+@end defivar
+
+@defivar Symbol is_function
+Is @code{True} if the symbol is a function or a method.
+@end defivar
+
+@defivar Symbol is_variable
+Is @code{True} if the symbol is a variable.
+@end defivar
+@end table
+
+The available domain categories in @code{gdb.Symbol} are represented
+as constants in the @code{gdb} module:
+
+@table @code
+@findex SYMBOL_UNDEF_DOMAIN
+@findex gdb.SYMBOL_UNDEF_DOMAIN
+@item SYMBOL_UNDEF_DOMAIN
+This is used when a domain has not been discovered or none of the
+following domains apply.  This usually indicates an error either
+in the symbol information or in @value{GDBN}'s handling of symbols.
+@findex SYMBOL_VAR_DOMAIN
+@findex gdb.SYMBOL_VAR_DOMAIN
+@item SYMBOL_VAR_DOMAIN
+This domain contains variables, function names, typedef names and enum
+type values.
+@findex SYMBOL_STRUCT_DOMAIN
+@findex gdb.SYMBOL_STRUCT_DOMAIN
+@item SYMBOL_STRUCT_DOMAIN
+This domain holds struct, union and enum type names.
+@findex SYMBOL_LABEL_DOMAIN
+@findex gdb.SYMBOL_LABEL_DOMAIN
+@item SYMBOL_LABEL_DOMAIN
+This domain contains names of labels (for gotos).
+@findex SYMBOL_VARIABLES_DOMAIN
+@findex gdb.SYMBOL_VARIABLES_DOMAIN
+@item SYMBOL_VARIABLES_DOMAIN
+This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
+contains everything minus functions and types.
+@findex SYMBOL_FUNCTIONS_DOMAIN
+@findex gdb.SYMBOL_FUNCTIONS_DOMAIN
+@item SYMBOL_FUNCTION_DOMAIN
+This domain contains all functions.
+@findex SYMBOL_TYPES_DOMAIN
+@findex gdb.SYMBOL_TYPES_DOMAIN
+@item SYMBOL_TYPES_DOMAIN
+This domain contains all types.
+@end table
+
+The available address class categories in @code{gdb.Symbol} are represented
+as constants in the @code{gdb} module:
+
+@table @code
+@findex SYMBOL_LOC_UNDEF
+@findex gdb.SYMBOL_LOC_UNDEF
+@item SYMBOL_LOC_UNDEF
+If this is returned by address class, it indicates an error either in
+the symbol information or in @value{GDBN}'s handling of symbols.
+@findex SYMBOL_LOC_CONST
+@findex gdb.SYMBOL_LOC_CONST
+@item SYMBOL_LOC_CONST
+Value is constant int.
+@findex SYMBOL_LOC_STATIC
+@findex gdb.SYMBOL_LOC_STATIC
+@item SYMBOL_LOC_STATIC
+Value is at a fixed address.
+@findex SYMBOL_LOC_REGISTER
+@findex gdb.SYMBOL_LOC_REGISTER
+@item SYMBOL_LOC_REGISTER
+Value is in a register.
+@findex SYMBOL_LOC_ARG
+@findex gdb.SYMBOL_LOC_ARG
+@item SYMBOL_LOC_ARG
+Value is an argument.
+@findex SYMBOL_LOC_REF_ARG
+@findex gdb.SYMBOL_LOC_REF_ARG
+@item SYMBOL_LOC_REF_ARG
+Value address is an offset in arglist.
+@findex SYMBOL_LOC_REGPARM_ADDR
+@findex gdb.SYMBOL_LOC_REGPARM_ADDR
+@item SYMBOL_LOC_REGPARM_ADDR
+Value is a specified register.  Just like @code{LOC_REGISTER} except
+the register holds the address of the argument instead of the argument
+itself.
+@findex SYMBOL_LOC_LOCAL
+@findex gdb.SYMBOL_LOC_LOCAL
+@item SYMBOL_LOC_LOCAL
+Value is a local variable.
+@findex SYMBOL_LOC_TYPEDEF
+@findex gdb.SYMBOL_LOC_TYPEDEF
+@item SYMBOL_LOC_TYPEDEF
+Value not used.  Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
+have this class.
+@findex SYMBOL_LOC_BLOCK
+@findex gdb.SYMBOL_LOC_BLOCK
+@item SYMBOL_LOC_BLOCK
+Value is a block.
+@findex SYMBOL_LOC_CONST_BYTES
+@findex gdb.SYMBOL_LOC_CONST_BYTES
+@item SYMBOL_LOC_CONST_BYTES
+Value is a byte-sequence.
+@findex SYMBOL_LOC_UNRESOLVED
+@findex gdb.SYMBOL_LOC_UNRESOLVED
+@item SYMBOL_LOC_UNRESOLVED
+Value is at a fixed address, but the address of the variable has to be
+determined from the minimal symbol table whenever the variable is
+referenced.
+@findex SYMBOL_LOC_OPTIMIZED_OUT
+@findex gdb.SYMBOL_LOC_OPTIMIZED_OUT
+@item SYMBOL_LOC_OPTIMIZED_OUT
+The value does not actually exist in the program.
+@findex SYMBOL_LOC_COMPUTED
+@findex gdb.SYMBOL_LOC_COMPUTED
+@item SYMBOL_LOC_COMPUTED
+The value's address is a computed location.
+@end table
+
+@node Symbol Tables In Python
+@subsubsection Symbol table representation in Python.
+
+@cindex symbol tables in python
+@tindex gdb.Symtab
+@tindex gdb.Symtab_and_line
+
+Access to symbol table data maintained by @value{GDBN} on the inferior
+is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
+@code{gdb.Symtab}.  Symbol table and line data for a frame is returned
+from the @code{find_sal} method in @code{gdb.Frame} object.
+@xref{Frames In Python}.
+
+For more information on @value{GDBN}'s symbol table management, see
+@ref{Symbols, ,Examining the Symbol Table} for more information.
+
+A @code{gdb.Symtab_and_line} object has the following attributes:
+
+@table @code
+@defivar Symtab_and_line symtab
+The symbol table object (@code{gdb.Symtab}) for this frame.
+This attribute is not writable.
+@end defivar
+
+@defivar Symtab_and_line pc
+Indicates the current program counter address.  This attribute is not
+writable.
+@end defivar
+
+@defivar Symtab_and_line line
+Indicates the current line number for this object.  This
+attribute is not writable.
+@end defivar
+@end table
+
+A @code{gdb.Symtab} object has the following attributes:
+
+@table @code
+@defivar Symtab filename
+The symbol table's source filename.  This attribute is not writable.
+@end defivar
+
+@defivar Symtab objfile
+The symbol table's backing object file.  @xref{Objfiles In Python}.
+This attribute is not writable.
+@end defivar
+@end table
+
+The following methods are provided:
+
+@table @code
+@defmethod Symtab fullname
+Return the symbol table's  source absolute file name.
+@end defmethod
 @end table
 
 @node Lazy Strings In Python