Add documentation for instrumentation subsystem

[Copilot]

The instrumentation subsystem lacked documentation explaining its architecture, usage patterns, and tradeoffs.

Changes

• Created doc/services/instrumentation/index.rst with comprehensive coverage:

  • Architecture: GCC's -finstrument-functions hooks with __cyg_profile_func_enter/exit handlers
  • Two modes: callgraph (tracing) and statistical (profiling)
  • Retained memory integration for persisting trigger/stopper addresses across reboots
  • Performance impact: 20-40% code size, 5-20% runtime overhead
  • Comparison table with tracing subsystem (RTOS-aware vs compiler-based)
  • Configuration examples and zaru.py tool workflow
  • Limitations: GCC-only, RAM initialization dependency, buffer constraints

• Updated doc/services/index.rst to include instrumentation in OS services TOC

• Added Doxygen group tags to include/zephyr/instrumentation/instrumentation.h for API reference generation

Usage Example

CONFIG_INSTRUMENTATION=y
CONFIG_INSTRUMENTATION_MODE_CALLGRAPH=y
CONFIG_INSTRUMENTATION_MODE_STATISTICAL=y
CONFIG_INSTRUMENTATION_TRIGGER_FUNCTION="my_critical_function"

# Set trigger dynamically
zaru.py trace -c my_function

# Reboot to apply, collect profile
zaru.py reboot
zaru.py profile -v -n 10

Key distinction: instrumentation provides automatic function-level profiling via compiler hooks, while tracing offers RTOS-aware event collection with manual instrumentation points.

Original prompt

add a documentation page for the instrumentation subsystem
it should explain things like how it generally works, when to use retained memory,some of the caveats like tjr fact it increases code size or might slow things down, how it's different from zephyr tracing capabilities (they are rtos aware), etc.
there's no limit to how exhaustive the documentation page should be but it should remain to the point and not be verbose for the sake of it

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.