= RTEMS GDB Python =

[[TOC(Developer/Tools/RTEMS_GDB_Python , depth=2)]]

Tools built with the [wiki:Developer/Tools/RSB RTEMS Source Builder] enable [http://www.python.org Python] support in GDB. [https://sourceware.org/gdb/onlinedocs/gdb/Python-API.html#Python-API GDB Python] support provides a clean structured way to control GDB with the flexibility of Python from inside GDB. The RTEMS GDB Python project provides a way to inspect RTEMS kernel structures in a clean simple way.

Inspecting RTEMS kernel structures in a debugger is complex and error prone. The structures used in RTEMS are designed for performance and mirror the complexity of a real-time operating system. Target errors can happen is pointers held in structures reference `NULL` or `union` data that is not valid can result in invalid accesses on a target and unexpected behaviours. Using Python we can develop code that understand the kernel structures and can perform safe access on the target presenting the data to you in a user friendly manner.

The RTEMS GDB Python code is held in the https://git.rtems.org/rtems-tools repo under `tools/gdb/python`. Building and installing the RTEMS Tools package will also install the RTEMS GDB Python scripts under the configure prefix you use.

''Note: this package is under work to bring it up to date with the recent RTEMS kernel changes and it is experimental.''

== GDB Commands ==

To load and enable the RTEMS GDB Python support enter at the GDB prompt:

{{{
(gdb) python import rtems
RTEMS GDB Support
}}}

Help can be listed with:
{{{
(gdb) help rtems
help rtems
Prefix command for RTEMS.

List of rtems subcommands:

rtems mqueue -- Display RTEMS message_queue(s) by index(es)
rtems object -- Display the RTEMS object given a numeric ID(Or a reference to the object)
rtems semaphore -- Display RTEMS semaphore(s) by index(es)
rtems task -- Display RTEMS task(s) by index(es)
rtems tod -- Display RTEMS time of day
rtems wdseconds -- Display watchdog seconds chain
rtems wdticks -- Display watchdog ticks chain

Type "help rtems" followed by rtems subcommand name for full documentation.
Type "apropos word" to search for commands related to "word".
Command name abbreviations are allowed if unambiguous.
}}}

Currently the follow has been tested and seems to work:

* task
* semaphore