Summary

This PR introduces the ability to record selected configuration settings used to build the binary in debug mode, and embed the encoded representation of said information in the produced executable binary itself.

GDB can parse special sections as containers for either references to external debug scripts or as embedded python/scheme code. Since there are some configuration settings that are not persisted in the MicroPython binary, GDB helper scripts would have to either guess the values of some configuration definitions or prompt the user for the values themselves. For example, the chosen object representation scheme is not tracked anywhere in the binary for space reasons, and the value of the appropriate preprocessor definition is lost once the build process ends.

The changes in this PR encode a few definitions used by GDB helper scripts into a dictionary called "MPY_BINARY_DEBUG_INFO", which can be queried from a GDB session via GDB's Python API.

GDB doesn't load the encoded contents unless it is explicitly configured to either ignore any safeguards regarding foreign scripts, or if the currently debugged executable is in the "safe" script sources.

GDB documents this facility here: https://sourceware.org/gdb/current/onlinedocs/gdb.html/dotdebug_005fgdb_005fscripts-section.html

Right now this is used by the Unix port and the debug information gets embedded only for debug builds if the "EMBED_DEBUG_INFO" variable is set in the make command line.

This came up during a discussion between @AJMansfield and I - as we both wrote our own GDB helper scripts/printers to decode container objects, QSTRs, raw mp_obj_t payloads and so on - and we both ended up having the same pain points regarding how to find out configuration settings that were lost in the build process (like the chosen object representation).

Even though this PR does not embed configuration information on anything but the Unix port when compiled for Linux, this method is also safe for embedded targets. Board deployment programs/flashers/etc already ignore non-relevant sections, so an ELF size increase does not correspond to an on-flash size increase.

The configuration encoding mechanism can also be changed to also be available for non-debug builds, but the main use case is to augment GDB helper scripts - which greatly benefit from having debug symbols in.

That said, this can also be the starting point for an official GDB printers/helpers script that could be either provided in a separate repo or shipped with MicroPython itself (like other projects do, including CPython).

Testing

Debug information was retrieved from a GDB session with this commands sequence:

$ make -C ports/unix DEBUG=1 EMBED_DEBUG_INFO=1
$ gdb \
	-q \
	-iex "set auto-load safe-path $(pwd)/ports/unix/build-standard/micropython" \
	ports/unix/build-standard/micropython

Reading symbols from ports/unix/build-standard/micropython...
(gdb) python print(MPY_BINARY_DEBUG_INFO)
{'float_impl': 2, 'longint_impl': 2, 'mpz_dig_size': 16, 'obj_immediate_objs': True, 'obj_repr': 0, 'timestamp_impl': 2}
(gdb)

Trade-offs and Alternatives

There may be some security concerns related to the mechanisms used to generate and load the encoded data.

For data generation, since these changes interact directly with the preprocessor and use Python's eval to clean data up, this functionality is enabled only in response to explicit user input, at which point an eventual attacker already has full control of the execution environment.

Data consumption events only occur in rather specialised situations and they also require an explicit configuration from the user or a general misconfiguration of the GDB installation. In the latter case, literally any other malicious binary would already have exploited all that's available to exploit.

An alternative could be to generate a json/yaml/etc. version of the collected debug information and store it in the build directory, however that's one more file to keep track of when having to debug certain issues reported by third parties - where an ELF file is usually provided but not even core files are a given.

Generative AI

I did not use generative AI tools when creating this PR.