This is an automated email from the ASF dual-hosted git repository. xiaoxiang pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 6b3f7e0939f0b948b7591271eb7ac1f55b28172f Author: Kevin Witteveen (MartiniMarter) <[email protected]> AuthorDate: Thu Mar 20 19:46:12 2025 +0100 Documentation/components/drivers/character/wireless: IOCTL interface initial documentation. Adds initial documentation to the IOCTL commands of wireless character devices. Signed-off-by: Kevin Witteveen (MartiniMarter) <[email protected]> --- .../drivers/character/wireless/index.rst | 45 +++++++++++++++++++++ .../wireless/wireless_ioctl_white.drawio.png | Bin 0 -> 108447 bytes 2 files changed, 45 insertions(+) diff --git a/Documentation/components/drivers/character/wireless/index.rst b/Documentation/components/drivers/character/wireless/index.rst index 7312e24c03..63f2cfcfcc 100644 --- a/Documentation/components/drivers/character/wireless/index.rst +++ b/Documentation/components/drivers/character/wireless/index.rst @@ -6,3 +6,48 @@ Wireless character drivers :maxdepth: 1 lpwan/index.rst + +IOCTL Interface +=============== + +Before this interface, the IOCTL API for character-driven RF devices lacked +a common interface across different modulation technologies, +such as LoRa, FSK, and OOK. The result was, driver-specific IOCTL commands +were created even when they could be shared across multiple radios. +This fragmentation made application portability more difficult to maintain. + +To solve this issue, groups of commands have been created that are "selected" +by using ``WLIOC_SETMODU``. +See image below for a representation. + +.. figure:: wireless_ioctl_white.drawio.png + +.. note:: This image does not show all features. This is purely a + representation of command relations under WLIOC_SETMODU. + +read() +------ + +Reading a radio will take a ``wlioc_rx_hdr_s``, where information about the +payload will be read and written to. + +- ``FAR uint8_t *payload_buffer`` Pointer to **user buffer**. This is where + the payload will be written to. +- ``size_t payload_length`` **Initially**: User must set this to the size + of ``payload_buffer``. **After reading**: This will become the amount of + bytes written to the ``payload_buffer``. +- ``uint8_t error`` When greater than 0, there are errors detected in the + payload. The payload can still be returned, which allows the user to repair + it if desired. +- ``int32_t rssi_dbm`` The Received Signal Strength Indicator in + 1/100 decibel-milliwatts of the received signal. + When unsupported, this returns ``INT32_MIN``. +- ``int32_t snr_db`` The signal to noise ratio in 1/100 decibels of the + received signal. When unsupported, this returns ``INT32_MIN``. + +write() +------- + +Writing to a radio will attempt to send the given bytes. The radio must be +configured before doing so. +Unlike ``read()``, this will simply take uint8_t bytes as payload. \ No newline at end of file diff --git a/Documentation/components/drivers/character/wireless/wireless_ioctl_white.drawio.png b/Documentation/components/drivers/character/wireless/wireless_ioctl_white.drawio.png new file mode 100644 index 0000000000..41be954a3d Binary files /dev/null and b/Documentation/components/drivers/character/wireless/wireless_ioctl_white.drawio.png differ
