linguini1 commented on code in PR #18521: URL: https://github.com/apache/nuttx/pull/18521#discussion_r2912433565
########## Documentation/components/drivers/character/serial.rst: ########## @@ -48,3 +48,125 @@ 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 +~~~~~~~~~~~~ + +When the ioctl is issued, the driver uses ``memcpy`` to copy data from its +device structure into the caller-supplied buffer. The buffer is cast to a +driver-specific type, for example: + +- ``struct u16550_s`` for the generic 16550 UART driver, +- ``struct up_dev_s`` for most MCU serial drivers (STM32, Tiva, LPC, etc.), +- ``struct usbhost_cdcacm_s`` for the USB host CDC/ACM serial driver. + +The copy source is the ``uart_dev_s`` pointer obtained from the device node. +In drivers where the private state structure embeds ``struct uart_dev_s`` as +its first member (e.g. STM32), the copy captures the complete driver state. +In other drivers the copy starts at the ``uart_dev_s`` address. + +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. Review Comment: This is the only relevant bit to keep I should think; let the user know to consult the code. Everything above in this section isn't particularly useful. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
