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 <arjav1528@gmail.com>

Author: arjav1528

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.