gdb2dict 1.0.0__tar.gz

gdb2dict-1.0.0/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2016 The Python Packaging Authority (PyPA)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gdb2dict-1.0.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.1
+Name: gdb2dict
+Version: 1.0.0
+Summary: A converter from GDB values to python dict
+Author-email: Zakaria FADLI <zakaria1193@gmail.com>
+Maintainer-email: Zakaria FADLI <zakaria1193@gmail.com>
+License: Copyright (c) 2016 The Python Packaging Authority (PyPA)
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of
+        this software and associated documentation files (the "Software"), to deal in
+        the Software without restriction, including without limitation the rights to
+        use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+        of the Software, and to permit persons to whom the Software is furnished to do
+        so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/zakaria1193/gdb2dict
+Project-URL: Bug Reports, https://github.com/zakaria1193/gdb2dict/issues
+Project-URL: Funding, https://donate.pypi.org
+Project-URL: Say Thanks!, http://saythanks.io/to/example
+Project-URL: Source, https://github.com/zakaria1193/gdb2dict
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: dev
+Requires-Dist: check-manifest; extra == "dev"
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+
+# GDB.value to python dict converter
+
+This tool extends GDB python scripting capabilities.
+
+gdb (GNU Debugger) use 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:
+
+```c
+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
+(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.
+
+```python
+import gdb2dict
+```
+
+Simply call the function `gdb_value_to_dict` with the value to convert,
+and it will return a python dictionary.
+
+```python
+> 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 ](https://gcc.gnu.org/onlinedocs/gcc/Unnamed-Fields.html)
+that can be sub-structs or sub-unions without a name.
+
+## 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](https://sourceware.org/gdb/onlinedocs/gdb/Python-API.html#Python-API).
+
+Or this article from [Memfault](https://interrupt.memfault.com/blog/automate-debugging-with-gdb-python-api)
+
+## 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.
+
+```python my_script.py
+
+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.
+
+```bash
+$ 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.

gdb2dict-1.0.0/README.md

@@ -0,0 +1,162 @@
+# GDB.value to python dict converter
+
+This tool extends GDB python scripting capabilities.
+
+gdb (GNU Debugger) use 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:
+
+```c
+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
+(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.
+
+```python
+import gdb2dict
+```
+
+Simply call the function `gdb_value_to_dict` with the value to convert,
+and it will return a python dictionary.
+
+```python
+> 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 ](https://gcc.gnu.org/onlinedocs/gcc/Unnamed-Fields.html)
+that can be sub-structs or sub-unions without a name.
+
+## 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](https://sourceware.org/gdb/onlinedocs/gdb/Python-API.html#Python-API).
+
+Or this article from [Memfault](https://interrupt.memfault.com/blog/automate-debugging-with-gdb-python-api)
+
+## 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.
+
+```python my_script.py
+
+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.
+
+```bash
+$ 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.

gdb2dict-1.0.0/pyproject.toml

@@ -0,0 +1,152 @@
+[project]
+# This is the name of your project. The first time you publish this
+# package, this name will be registered for you. It will determine how
+# users can install this project, e.g.:
+#
+# $ pip install sampleproject
+#
+# And where it will live on PyPI: https://pypi.org/project/sampleproject/
+#
+# There are some restrictions on what makes a valid project name
+# specification here:
+# https://packaging.python.org/specifications/core-metadata/#name
+name = "gdb2dict"  # Required
+
+# Versions should comply with PEP 440:
+# https://www.python.org/dev/peps/pep-0440/
+#
+# For a discussion on single-sourcing the version, see
+# https://packaging.python.org/guides/single-sourcing-package-version/
+version = "1.0.0"  # Required
+
+# This is a one-line description or tagline of what your project does. This
+# corresponds to the "Summary" metadata field:
+# https://packaging.python.org/specifications/core-metadata/#summary
+description = "A converter from GDB values to python dict" # Required
+
+# This is an optional longer description of your project that represents
+# the body of text which users will see when they visit PyPI.
+#
+# Often, this is the same as your README, so you can just read it in from
+# that file directly (as we have already done above)
+#
+# This field corresponds to the "Description" metadata field:
+# https://packaging.python.org/specifications/core-metadata/#description-optional
+readme = "README.md" # Optional
+
+# Specify which Python versions you support. In contrast to the
+# 'Programming Language' classifiers above, 'pip install' will check this
+# and refuse to install the project if the version does not match. See
+# https://packaging.python.org/guides/distributing-packages-using-setuptools/#python-requires
+requires-python = ">=3.7"
+
+# This is either text indicating the license for the distribution, or a file
+# that contains the license
+# https://packaging.python.org/en/latest/specifications/core-metadata/#license
+license = {file = "LICENSE.txt"}
+
+# This field adds keywords for your project which will appear on the
+# project page. What does your project relate to?
+#
+# Note that this is a list of additional keywords, separated
+# by commas, to be used to assist searching for the distribution in a
+# larger catalog.
+keywords = []  # Optional
+
+# This should be your name or the name of the organization who originally
+# authored the project, and a valid email address corresponding to the name
+# listed.
+authors = [
+  {name = "Zakaria FADLI", email = "zakaria1193@gmail.com" } # Optional
+]
+
+# This should be your name or the names of the organization who currently
+# maintains the project, and a valid email address corresponding to the name
+# listed.
+maintainers = [
+  {name = "Zakaria FADLI", email = "zakaria1193@gmail.com" } # Optional
+]
+
+# Classifiers help users find your project by categorizing it.
+#
+# For a list of valid classifiers, see https://pypi.org/classifiers/
+classifiers = [  # Optional
+  # How mature is this project? Common values are
+  #   3 - Alpha
+  #   4 - Beta
+  #   5 - Production/Stable
+  "Development Status :: 3 - Alpha",
+
+  # Indicate who your project is intended for
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Build Tools",
+
+  # Pick your license as you wish
+  "License :: OSI Approved :: MIT License",
+
+  # Specify the Python versions you support here. In particular, ensure
+  # that you indicate you support Python 3. These classifiers are *not*
+  # checked by "pip install". See instead "python_requires" below.
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.7",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+# This field lists other packages that your project depends on to run.
+# Any package you put here will be installed by pip when your project is
+# installed, so they must be valid existing projects.
+#
+# For an analysis of this field vs pip's requirements files see:
+# https://packaging.python.org/discussions/install-requires-vs-requirements/
+dependencies = [ # Optional
+]
+
+# List additional groups of dependencies here (e.g. development
+# dependencies). Users will be able to install these using the "extras"
+# syntax, for example:
+#
+#   $ pip install sampleproject[dev]
+#
+# Similar to `dependencies` above, these must be valid existing
+# projects.
+[project.optional-dependencies] # Optional
+dev = ["check-manifest"]
+test = ["coverage"]
+
+# List URLs that are relevant to your project
+#
+# This field corresponds to the "Project-URL" and "Home-Page" metadata fields:
+# https://packaging.python.org/specifications/core-metadata/#project-url-multiple-use
+# https://packaging.python.org/specifications/core-metadata/#home-page-optional
+#
+# Examples listed include a pattern for specifying where the package tracks
+# issues, where the source is hosted, where to say thanks to the package
+# maintainers, and where to support the project financially. The key is
+# what's used to render the link text on PyPI.
+[project.urls]  # Optional
+"Homepage" = "https://github.com/zakaria1193/gdb2dict"
+"Bug Reports" = "https://github.com/zakaria1193/gdb2dict/issues"
+"Funding" = "https://donate.pypi.org"
+"Say Thanks!" = "http://saythanks.io/to/example"
+"Source" = "https://github.com/zakaria1193/gdb2dict"
+
+# The following would provide a command line executable called `sample`
+# which executes the function `main` from this package when invoked.
+[project.scripts]  # Optional
+
+# This is configuration specific to the `setuptools` build backend.
+# If you are using a different build backend, you will need to change this.
+[tool.setuptools]
+# If there are data files included in your packages that need to be
+# installed, specify them here.
+package-data = {}
+
+[build-system]
+# These are the assumed default build requirements from pip:
+# https://pip.pypa.io/en/stable/reference/pip/#pep-517-and-518-support
+requires = ["setuptools>=43.0.0", "wheel"]
+build-backend = "setuptools.build_meta"

gdb2dict-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gdb2dict-1.0.0/src/gdb2dict/__init__.py

@@ -0,0 +1,6 @@
+from .gdb_value_to_dict import gdb_value_to_dict
+
+# Export all imported
+__all__ = [
+    "gdb_value_to_dict",
+]

gdb2dict-1.0.0/src/gdb2dict/gdb_value_to_dict.py

@@ -0,0 +1,171 @@
+import json
+
+import gdb
+
+DEBUG = False
+
+if DEBUG:
+    def print_debug(msg):
+        print(msg)
+else:
+    def print_debug(msg):
+        pass
+
+
+OBJ_TYPE_NEEDS_RECURSIVE_CALL = [
+    gdb.TYPE_CODE_STRUCT,
+    gdb.TYPE_CODE_UNION,
+    gdb.TYPE_CODE_ARRAY
+]
+
+
+def gdb_value_to_dict(gdb_value: gdb.Value):
+    """
+    Converts a gdb.Value to a json string
+
+    :param gdb_value: gdb.Value -> Must be a struct or union
+    :return: data: dict -> The data of the gdb.Value as a dict
+    """
+
+    data: dict = {}
+    append_gdb_value_to_dict(gdb_value, data)
+    return data
+
+
+def gdb_value_primitive_to_str(gdb_value: gdb.Value):
+    """
+    Converts a primitive gdb.Value to a str or hex
+
+    A primitive gdb.Value is a value that is not of the types listed in
+    OBJ_TYPE_NEEDS_RECURSIVE_CALL (struct, union, array, etc...)
+
+    :param gdb_value: gdb.Value to be converted
+    :return: str or hex of the gdb.Value
+    """
+
+    print_debug("gdb_value_primitive_to_str: {}".format(gdb_value))
+
+    gdb_value_type_code = gdb_value.type.strip_typedefs().code
+
+    if gdb_value_type_code in OBJ_TYPE_NEEDS_RECURSIVE_CALL:
+        raise Exception("obj_value_to_value called on a non primitive type")
+
+    if gdb_value_type_code == gdb.TYPE_CODE_INT:
+        return hex(int(gdb_value))
+
+    return str(gdb_value)
+
+
+def append_gdb_value_to_dict(gdb_value: gdb.Value, data: dict):
+    """
+    Recursive function to convert gdb.Value object to dict key/values
+    and add them into given dict.
+
+    //!\\ Function is recursive
+
+    :param gdb_value: gdb.Value to be appended (Can be any C type)
+    :param data: dict to be filled
+    :return: None
+    """
+
+    print_debug("append_gdb_value_to_dict: {}".format(gdb_value))
+
+    assert isinstance(data, dict), f"data must be a dict, not {type(data)}"
+
+    gdb_value_type_code = gdb_value.type.strip_typedefs().code
+
+    print_debug("-- struct_type: {} code: {}".format(gdb_value.type,
+                                                     gdb_value.type.code))
+
+    if gdb_value_type_code not in OBJ_TYPE_NEEDS_RECURSIVE_CALL:
+        raise Exception("obj_value_to_dict called on a primitive type")
+
+    # Recursively extract data from nested structs/unions/arrays
+    fields = gdb_value.type.fields()
+
+    for i, field in enumerate(fields):
+        field_name = field.name
+
+        if field_name is None:
+            # This happens with anonymous struct field (C11)
+            # https://gcc.gnu.org/onlinedocs/gcc/Unnamed-Fields.html
+            field_name = "::unnamed_field_{}".format(i)
+            # Field value should not be accessed by field_name
+            # This is documented in:
+            # https://sourceware.org/bugzilla/show_bug.cgi?id=15464
+
+        field_value = gdb_value[field]
+
+        field_value = gdb_value[field]
+
+        field_type = field_value.type.strip_typedefs()
+        field_type_code = field_type.code
+
+        print_debug("---- subfield_name: {} "
+                    "type_raw: {} {} "
+                    "type_: {} {} ".format(
+                        field_name,
+                        field.type,
+                        field.type.code,
+                        field_type, field_type.code))
+
+        if field_type_code in (gdb.TYPE_CODE_STRUCT, gdb.TYPE_CODE_UNION):
+            print_debug("Creating struct under data [{}]".format(field_name))
+
+            # If the field is a nested struct, recursively extract its data
+            struct_data: dict = {}
+            append_gdb_value_to_dict(field_value, struct_data)
+            if field_type_code == gdb.TYPE_CODE_STRUCT:
+                key_ = field_name + "::struct"
+            else:  # gdb.TYPE_CODE_UNION
+                key_ = field_name + "::union"
+            data[key_] = struct_data
+
+        elif field_type_code == gdb.TYPE_CODE_ARRAY:
+            print_debug("Creating array under data [{}]".format(field_name))
+            # Initialize it as a list
+            key_ = field_name + "::array"
+            data[key_] = []
+
+            # For each item in the array, recursively extract its data and
+            # append it to the list
+            for j in range(field_type.range()[1]):
+                append_gdb_value_to_list(field_value[j], data[key_])
+
+        else:
+            print_debug("Creating primitive under [{}]".format(field_name))
+            data[field_name] = gdb_value_primitive_to_str(field_value)
+
+
+def append_gdb_value_to_list(gdb_value: gdb.Value,
+                             list_to_fill: list):
+    """
+    Recursive function to convert gdb.Value object to dict key/values and adds
+    them into given dict
+
+    //!\\ Function is recursive (indirectly through append_gdb_value_to_dict)
+
+    :param gdb_value: gdb.Value to be appended (Can be any C type)
+    :param data: dict to be filled
+    :return: None
+    """
+
+    print_debug("append_gdb_value_to_list: {}".format(gdb_value))
+
+    assert isinstance(list_to_fill, list), "list_to_fill must be a list, "\
+                                           f"not {type(list_to_fill)}"
+
+    obj_value_code = gdb_value.type.strip_typedefs().code
+    # If the object is a struct, union, array...
+    # put it in a dict then append it
+    if obj_value_code in OBJ_TYPE_NEEDS_RECURSIVE_CALL:
+        item: dict = {}
+        append_gdb_value_to_dict(gdb_value, item)
+        list_to_fill.append(item)
+
+    # Primitive type (int, char, enum, etc) append it directly
+    else:
+        list_to_fill.append(gdb_value_primitive_to_str(gdb_value))
+
+    print_debug("Returning data: {}".format(json.dumps(list_to_fill,
+                                                       indent=4)))

gdb2dict-1.0.0/src/gdb2dict.egg-info/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.1
+Name: gdb2dict
+Version: 1.0.0
+Summary: A converter from GDB values to python dict
+Author-email: Zakaria FADLI <zakaria1193@gmail.com>
+Maintainer-email: Zakaria FADLI <zakaria1193@gmail.com>
+License: Copyright (c) 2016 The Python Packaging Authority (PyPA)
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of
+        this software and associated documentation files (the "Software"), to deal in
+        the Software without restriction, including without limitation the rights to
+        use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+        of the Software, and to permit persons to whom the Software is furnished to do
+        so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/zakaria1193/gdb2dict
+Project-URL: Bug Reports, https://github.com/zakaria1193/gdb2dict/issues
+Project-URL: Funding, https://donate.pypi.org
+Project-URL: Say Thanks!, http://saythanks.io/to/example
+Project-URL: Source, https://github.com/zakaria1193/gdb2dict
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: dev
+Requires-Dist: check-manifest; extra == "dev"
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+
+# GDB.value to python dict converter
+
+This tool extends GDB python scripting capabilities.
+
+gdb (GNU Debugger) use 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:
+
+```c
+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
+(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.
+
+```python
+import gdb2dict
+```
+
+Simply call the function `gdb_value_to_dict` with the value to convert,
+and it will return a python dictionary.
+
+```python
+> 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 ](https://gcc.gnu.org/onlinedocs/gcc/Unnamed-Fields.html)
+that can be sub-structs or sub-unions without a name.
+
+## 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](https://sourceware.org/gdb/onlinedocs/gdb/Python-API.html#Python-API).
+
+Or this article from [Memfault](https://interrupt.memfault.com/blog/automate-debugging-with-gdb-python-api)
+
+## 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.
+
+```python my_script.py
+
+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.
+
+```bash
+$ 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.

gdb2dict-1.0.0/src/gdb2dict.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE.txt
+README.md
+pyproject.toml
+src/gdb2dict/__init__.py
+src/gdb2dict/gdb_value_to_dict.py
+src/gdb2dict.egg-info/PKG-INFO
+src/gdb2dict.egg-info/SOURCES.txt
+src/gdb2dict.egg-info/dependency_links.txt
+src/gdb2dict.egg-info/requires.txt
+src/gdb2dict.egg-info/top_level.txt

gdb2dict-1.0.0/src/gdb2dict.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gdb2dict-1.0.0/src/gdb2dict.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+check-manifest
+
+[test]
+coverage

gdb2dict-1.0.0/src/gdb2dict.egg-info/top_level.txt

@@ -0,0 +1 @@
+gdb2dict