Kernel objects introspection symbols

[trond-snekvik]

This is a continuation of the discussion in #56293.

Is your enhancement proposal related to a problem? Please describe.

PRs #54446, #56293 and related architecture specific PRs removes several offset symbols used by tooling to do introspection on the kernel state. Together with thread_info.c, symbols like these are used by debuggers and similar tools to:

• View diagnostics and status information about the kernel state
  • Scheduler state and thread usage per CPU core
  • Active thread
  • Heap usage
• Get a list of threads and their state
  • Thread state
  • Current instruction address
  • Options, name and entry point
  • Priority
  • Stack usage

To provide this information, the tools need to interpret the kernel objects by mapping the live memory data to corresponding fields. As the kernel objects' exact layout depends on the selected options and Zephyr version, the tools use the offset symbols, absolute symbols and information in the thread_info.c object to locate the various data in the memory.

There are several shortcomings in the current support for introspection based tooling:

• With the recent removal of some absolute symbols (kernel: Remove unused absolute symbols #56293) and offset symbols (kernel: Remove unused generated symbol offset macros #54446), some objects can't be mapped out by the tooling in a future proof manner anymore. The required symbols would need to be reintroduced.
• The thread_info.c object's information is only available by reading its memory content, which causes several issues:
  • It takes up ROM space on the device
  • Reading its values at compile time is non-trivial
  • It's disabled by default to save space
• thread_info.c can't be enabled if CONFIG_MP_MAX_NUM_CPUS > 1, as it's missing information about the size of the _cpu struct.
• The names and exact set of data generated is not considered part of the API, and can be changed or removed at any time. They're also unused in the zephyr repo itself, so they're likely targets for maintainers looking to clean up unused functionality.

It's also worth mentioning that although tools like GDB clients can understand and parse C code to interpret the raw memory, tooling like the RTOS awareness plugins run in the GDB server, which does not expose an API for this. Even if the tooling has C language intelligence, the names of the kernel object fields are not necessarily considered part of the API either, and would be subject to abrupt change.

Describe the solution you'd like

For the various introspection mechanisms to work, the address of the following objects would need to be made available:

• _kernel
• _system_heap
• _kernel_thread_info_offsets

Additionally, the offset and size of the following fields would need to be exposed:

• Kernel state:
  • _kernel_t::cpus
  • _cpu_t::current
  • sizeof(_cpu_t)
• Thread usage:
  • _cpu_t::usage0
  • _cpu_t::usage
  • _thread_t::base::usage
  • Every field in struct k_cycle_stats
• Heap usage:
  • struct k_heap::heap
  • struct sys_heap::heap
  • Every field in struct z_heap
• Thread runtime information:
  • _kernel_t::threads
  • _thread_t::next_thread (available in thread_info.c)
  • _thread_t::base::thread_state (available in thread_info.c)
  • _thread_t::base::user_options
  • _thread_t::base::prio (available in thread_info.c)
• Thread static information:
  • _thread_t::entry (available in thread_info.c)
  • _thread_t::name (available in thread_info.c)
• Thread stack usage:
  • _thread_t::stack_info
  • Every field in struct _thread_stack_info

Checked items are already available in kernel_offsets.

The format and naming of the generated information would need to be considered part of the API, and should not be changeable without a deprecation period. Not all these fields would be available in all configurations, but ideally, the symbols should be available for tooling whenever the corresponding fields exist in the kernel objects, and not just when CONFIG_DEBUG and its child options are enabled. The current implementation of kernel_offsets could support this use case without overhead on the target.

Describe alternatives you've considered

The layout of the kernel objects that can't be changed by the configuration could be frozen, but this seems less flexible, and still doesn't solve the issue for configurable objects.

The output could be provided through some additional output file in a machine readable format, but this would not work for the RTOS awareness plugins passed to the runners in west debug, as they can't accept arguments, and don't have portable file access mechanisms.

[trond-snekvik]

cc @peter-mitsis

[trond-snekvik]

cc @carlocaione

[carlocaione]

Ok, I'm a bit dull about this topic. What's preventing us to extend kernel_offsets.h with all the missing items and mark it as standard API / ABI ?

[trond-snekvik]

What's preventing us to extend kernel_offsets.h with all the missing items and mark it as standard API / ABI ?

Nothing really, but Peter made this comment:

In the longer term, my aim is to eliminate the GEN_OFFSET_SYM and GEN_ABSOLUTE_SYM macros. If this can be done cleanly, then it sets the stage for simplifying the build process (as their use requires a separate compilation and custom python script just to create the defines used in assembly).

and this would probably not help his efforts, so I wanted to have a discussion first.

[carlocaione]

tagging @andyross as well

[kylebonnici]

@trond-snekvik what is the status on this?

[trond-snekvik]

No progress that I am aware of