GDB.value to python dict converter

This tool extends GDB python scripting capabilities.

gdb (GNU Debugger) uses a specific format to print C/C++ programs data, this format is not easy to parse, so this tool converts the output of gdb to python dictionaries.

So it can also be used to serialize C data structures to JSON objects, or to any other format.

Example of conversion:

If you have a structure like this in you C code:

struct Shape {
    int id;
    enum {
        RED,
        GREEN,
        BLUE
    } color;
    union {
        int intValue;
        float floatValue;
    }; // unnamed union (C11)
    struct {
        int x;
        int y;
    } center;
    union {
        int intValue;
        float floatValue;
    } data;
};

When you print an instance of this struct in python gdb script (or in the classic gdb console), both will give this printable string that is not a native python object

(gdb) p my_struct
OR
(gdb) python print(gdb.parse_and_eval("my_struct"))
{
  id = 0x1,
  color = RED,
  {
    intValue = 0x2a,
    floatValue = 5.88545355e-44
  },
  center = {
    x = 0x1e,
    y = 0x28
  },
  data = {
    intValue = 0x6c6c6548,
    floatValue = 1.14313912e+27,
  }
}

gdb2dict lets convert the output of gdb to a python dictionary.

import gdb2dict

Simply call the function gdb_value_to_dict with the value to convert, and it will return a python dictionary.

> output_dict = gdb2dict.gdb_value_to_dict(gdb.parse_and_eval("my_struct"))

output_dict =
{
    'id': '0x1',
    'color': 'RED',
    '##unnamed_field_1##union':
    {
        'floatValue': '5.88545355e-44',
        'intValue': '0x2a'
    },
    'center##struct': {'x': '0x1e', 'y': '0x28'},
    'data##union':
    {
        'floatValue': '1.14313912e+27',
        'intValue': '0x6c6c6548'
    },
}

Metatada

As you can see some field names (keys after conversion) have added metadata ##struct, ##union That's needed to differentiate between fields that are structs and fields that are unions.

Another metadata can be added to the keys, it's ##unnamed_field_1##struct, ##unnamed_field_2##union etc...

That's to cover for C11's unnanmed fields that can be sub-structs or sub-unions without a name.

C++ support

C++ objects are supported as well. A class is a struct as far as gdb is concerned, so class members come out under the same ##struct key as C struct members do. On top of that:

• Inheritance: every base class subobject is dumped under its own BaseName##base key. Nesting the bases instead of flattening them keeps a derived member that hides a base member of the same name distinguishable from the one it hides.
• Polymorphism: passing a Base * or a Base & that really points at a Derived dumps the Derived. The dynamic type is resolved when the pointer is dereferenced.
• Static data members are included alongside the instance members. A static that the program never defines out of line has no storage to read and is left out.
• References are always resolved to the object they refer to.
• The vtable pointer and other compiler generated members are skipped.

# obj is a Base* that points at a Derived
gdb2dict.gdb_value_to_dict(obj)
{
    "Base##base": {
        "base_public_int": "0x1",
        "static_base_public_int": "0x65"
    },
    "derived_public_int": "0x4"
}

Following pointers

By default a pointer member is rendered as its address, exactly as it always was. Pass follow_pointers=True to dereference pointers that point at a struct, class or union and dump them inline instead:

gdb2dict.gdb_value_to_dict(value, follow_pointers=True)

Null pointers stay as "0x0" rather than being followed. Structures that point back at themselves are detected and reported as "##cycle" instead of recursing forever, and max_depth (64 by default) stops a dump that nests deeper than expected, reporting "##max_depth_reached".

A member gdb refuses to read is reported under a ##unreadable key rather than being silently dropped.

Use cases

Imagine you are trying to automatize the debugging of a measuring, and you want to parse the output of a measure function that returns a structure, you can use this tool to convert the output of gdb to a JSON format, you can do that manually by reading field by and field and making your own python dictionary, but this tool does that for you.

It comes handy when you have a lot of structures and unions to parse, and you don't want to write a lot of code to parse them, since gdb already knows how to parse them.

The printer can be used in your custom breakpoints, or your custom commands, or in your custom pretty printers.

If you don't know how to make those, refer to the GDB documentation.

Or this article from Memfault

Usage example: Parse TLV data from breakpoint and write to file

Let's use it in a python scripted gdb breakpoint handler. The idea is catch the functions that identifies the TLV type and value, then cast to a structure and write to a file in JSON format.

import gdb2dict

OUTPUT_LIST = []

class MyCustomBreakpoint(gdb.Breakpoint):
    def stop(self):
        # Access arguments
        arg1_payload = gdb.parse_and_eval("arg1_payload")
        arg2_payload_type = gdb.parse_and_eval("arg2_paytload_type")
        arg3_payload_size = gdb.parse_and_eval("arg3_payload_size") # Not needed here

        # Convert the payload type to a structure using some custom mapping function
        type_to_cast = my_custom_payload_type_to_struct(arg2_payload_type)

        # Cast to a structure pointer
        arg1_payload = arg1_payload.cast(type_to_cast)

        OUTPUT_LIST.append(gdb2dict.gdb_value_to_dict(arg1_payload))

        # Return False to not halt (Automatically continue)
        return False

with open("output.json", "w") as f:
    f.write("{\"output\": [\n")
    f.write(",\n".join(OUTPUT_LIST))
    f.write("]}")

Source this script in gdb will set the breakpoint and fill the output file with the parsed values.

$ gdb -x my_script.py --batch --nw --nx --return-child-result

--batch --nw --nx --return-child-result are recommended for automated gdb scripting, see gdb --help for more information.

Then you can post process the output file with your favorite language.

Installation

pip install gdb2dict preferably in your virual env.

You'll probably face issues importing custom python modules from within gdb scripts, for that refer to this article