This is an automated email from the ASF dual-hosted git repository.
linguini pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new cc464ea7f3b docs: Add documentation for TIOCSERGSTRUCT ioctl in serial
driver
cc464ea7f3b is described below
commit cc464ea7f3bdd0cce6a67f5b48b0cc3cef607e26
Author: Arjav Patel <[email protected]>
AuthorDate: Tue Mar 10 23:20:57 2026 +0530
docs: Add documentation for TIOCSERGSTRUCT ioctl in serial driver
Add a new section documenting the TIOCSERGSTRUCT debug ioctl and
CONFIG_SERIAL_TIOCSERGSTRUCT Kconfig option. The section covers enabling the
feature, how the ioctl copies driver-internal state to user space, example
usage with the 16550 UART driver, and a warning about the non-stable nature of
exposed structures.
Signed-off-by: Arjav Patel <[email protected]>
---
.../components/drivers/character/serial.rst | 109 +++++++++++++++++++++
1 file changed, 109 insertions(+)
diff --git a/Documentation/components/drivers/character/serial.rst
b/Documentation/components/drivers/character/serial.rst
index 81cb0d28237..7af619f1270 100644
--- a/Documentation/components/drivers/character/serial.rst
+++ b/Documentation/components/drivers/character/serial.rst
@@ -48,3 +48,112 @@ Serial Error Reporting
It is possible to check if there are some frame, parity, overrun, break, or
other error using the ioctl TIOCGICOUNT just like on Linux.
+
+Serial Debug Structure (TIOCSERGSTRUCT)
+---------------------------------------
+
+.. note::
+ This is a **debug-only** ioctl. The internal structures it exposes are
+ driver-specific, may change without notice, and must not be relied upon
+ as a stable ABI.
+
+The ``TIOCSERGSTRUCT`` ioctl allows a developer to retrieve a copy of the
+serial driver's internal state structure for diagnostic and debugging purposes.
+It is defined in ``include/nuttx/serial/tioctl.h``::
+
+ #define TIOCSERGSTRUCT _TIOC(0x0032) /* Get device TTY structure */
+
+Enabling ``TIOCSERGSTRUCT``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Support is controlled by the Kconfig option ``CONFIG_SERIAL_TIOCSERGSTRUCT``.
+To enable it:
+
+1. ``CONFIG_DEBUG_FEATURES`` must be enabled (the option depends on it).
+2. Either ``CONFIG_MCU_SERIAL`` or ``CONFIG_16550_UART`` must be active (i.e.,
+ the board must use an MCU serial driver or the generic 16550 UART driver).
+3. The specific low-level serial driver for your hardware must implement the
+ ``TIOCSERGSTRUCT`` case in its ``ioctl`` method. Most serial drivers in
+ the tree already do (63+ drivers across ARM, ARM64, RISC-V, Xtensa, and
+ MIPS architectures).
+
+Via ``menuconfig``, navigate to:
+
+.. code-block:: text
+
+ Device Drivers --->
+ Serial Driver Support --->
+ [*] Support TIOCSERGSTRUCT
+
+If the option is not visible, ensure that ``CONFIG_DEBUG_FEATURES`` is enabled
+first.
+
+How It Works
+~~~~~~~~~~~~
+
+Because the exact layout depends on the serial driver selected for your board,
+there is no single portable structure definition. The caller must consult the
+driver source for the struct definition and size the buffer accordingly.
+
+If ``arg`` is ``NULL``, the ioctl returns ``-EINVAL``.
+
+Example Usage
+~~~~~~~~~~~~~
+
+The following example shows how an application might use ``TIOCSERGSTRUCT``
+with the 16550 UART driver to inspect internal state. Adapt the structure type
+and header to match the serial driver used on your board.
+
+.. code-block:: c
+
+ #include <stdio.h>
+ #include <fcntl.h>
+ #include <unistd.h>
+ #include <sys/ioctl.h>
+ #include <nuttx/serial/tioctl.h>
+
+ /* Include the driver-specific header for the struct definition.
+ * This example uses the 16550 UART; replace with the header that
+ * defines your board's serial driver state structure.
+ */
+
+ #include <nuttx/serial/uart_16550.h>
+
+ int main(int argc, char *argv[])
+ {
+ struct u16550_s devstate;
+ int fd;
+ int ret;
+
+ fd = open("/dev/ttyS0", O_RDONLY);
+ if (fd < 0)
+ {
+ perror("open");
+ return 1;
+ }
+
+ ret = ioctl(fd, TIOCSERGSTRUCT, (unsigned long)&devstate);
+ if (ret < 0)
+ {
+ perror("ioctl TIOCSERGSTRUCT");
+ close(fd);
+ return 1;
+ }
+
+ /* Inspect driver-internal fields for debugging. Field names
+ * are specific to the driver; consult the driver source for
+ * the struct definition.
+ */
+
+ printf("UART base address: 0x%08lx\n",
+ (unsigned long)devstate.uartbase);
+
+ close(fd);
+ return 0;
+ }
+
+.. warning::
+ The structure layout and field names are internal to each driver
+ implementation and **may change between NuttX releases**. Use this ioctl
+ for interactive debugging and diagnostics only — never in production
+ application logic.
