From db2f74555d3d28feb4247376c55eaea79d5130d2 Mon Sep 17 00:00:00 2001
From: Yong Cong Sin <ycsin@meta.com>
Date: Mon, 27 May 2024 22:31:27 +0800
Subject: [PATCH] doc: services: debugging: add documentation for symtab

Add a simple documentation for symbol table.

Signed-off-by: Yong Cong Sin <ycsin@meta.com>
---
 doc/services/debugging/index.rst  |  1 +
 doc/services/debugging/symtab.rst | 31 +++++++++++++++++++++++++++++++
 include/zephyr/debug/symtab.h     | 17 +++++++++++++++++
 3 files changed, 49 insertions(+)
 create mode 100644 doc/services/debugging/symtab.rst

diff --git a/doc/services/debugging/index.rst b/doc/services/debugging/index.rst
index 259fd894ac4..cbc566bdbf0 100644
--- a/doc/services/debugging/index.rst
+++ b/doc/services/debugging/index.rst
@@ -11,3 +11,4 @@ Debugging
    gdbstub.rst
    debugmon.rst
    mipi_stp_decoder.rst
+   symtab.rst
diff --git a/doc/services/debugging/symtab.rst b/doc/services/debugging/symtab.rst
new file mode 100644
index 00000000000..a85bdbb10e2
--- /dev/null
+++ b/doc/services/debugging/symtab.rst
@@ -0,0 +1,31 @@
+.. _symtab:
+
+Symbol Table (Symtab)
+#####################
+
+The Symtab module, when enabled, will generate full symbol table during the Zephyr linking
+stage that keep tracks of the information about the functions' name and address, for advanced application
+with a lot of functions, this is expected to consume a sizable amount of ROM.
+
+Currently, this is being used to look up the function names during a stack trace in supported architectures.
+
+
+Usage
+*****
+
+Application can gain access to the symbol table data structure by including the :file:`symtab.h` header
+file and call :c:func:`symtab_get`. For now, we only provide :c:func:`symtab_find_symbol_name`
+function to look-up the symbol name and offset of an address. More advanced functionalities and be
+achieved by directly accessing the members of the data structure.
+
+Configuration
+*************
+
+Configure this module using the following options.
+
+* :kconfig:option:`CONFIG_SYMTAB`: enable the generation of the symbol table.
+
+API documentation
+*****************
+
+.. doxygengroup:: symtab_apis
diff --git a/include/zephyr/debug/symtab.h b/include/zephyr/debug/symtab.h
index 7556222cff8..41bf0b1b0c4 100644
--- a/include/zephyr/debug/symtab.h
+++ b/include/zephyr/debug/symtab.h
@@ -9,6 +9,15 @@
 
 #include <stdint.h>
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @defgroup symtab_apis Symbol Table API
+ * @{
+ */
+
 /**
  * @cond INTERNAL_HIDDEN
  */
@@ -49,4 +58,12 @@ const struct symtab_info *const symtab_get(void);
  */
 const char *const symtab_find_symbol_name(uintptr_t addr, uint32_t *offset);
 
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* ZEPHYR_INCLUDE_DEBUG_SYMTAB_H_ */