From 75b13c835358cdfc04d340bc2a56ea8261fdb636 Mon Sep 17 00:00:00 2001 From: Matias N Date: Thu, 25 Mar 2021 13:16:42 -0300 Subject: [PATCH] documentation: improve boardctl() docs --- Documentation/reference/os/boardctl.rst | 40 --- Documentation/reference/os/index.rst | 1 - Documentation/reference/user/13_boardctl.rst | 252 +++++++++++++++++++ include/sys/boardctl.h | 2 +- 4 files changed, 253 insertions(+), 42 deletions(-) delete mode 100644 Documentation/reference/os/boardctl.rst create mode 100644 Documentation/reference/user/13_boardctl.rst diff --git a/Documentation/reference/os/boardctl.rst b/Documentation/reference/os/boardctl.rst deleted file mode 100644 index d3b81f5a2c..0000000000 --- a/Documentation/reference/os/boardctl.rst +++ /dev/null @@ -1,40 +0,0 @@ -==================================== -``boardctl()`` Application Interface -==================================== - -.. c:function:: int boardctl(unsigned int cmd, uintptr_t arg) - - In a small embedded system, there will typically be a much - greater interaction between application and low-level board features. - The canonically correct to implement such interactions is by - implementing a character driver and performing the interactions - via low level ioctl() calls. This, however, may not be practical - in many cases and will lead to "correct" but awkward implementations. - - boardctl() is non-standard OS interface to alleviate the problem. - It basically circumvents the normal device driver ioctl() - interlace and allows the application to perform direct - IOCTL-like calls to the board-specific logic. It is especially - useful for setting up board operational and test configurations. - - NOTE: The other interfaces described in this document are internal - OS interface. boardctl() is an application interface to the OS. - There is no point, in fact, of using boardctl() within the OS; - the board interfaces prototyped in include/nuttx/board.h may - be called directly from within the OS. - - Application interfaces are described in the NuttX User Guide. - This application interface interface is described here only - because it is so non-standard and because it is so closely - tied to board porting logic. - - :param cmd: Identifies the board command to be executed. See - ``include/sys/boardctl.h`` for the complete list of common - board commands. Provisions are made to support non-common, - board-specific commands as well. - :param arg: The argument that accompanies the command. The nature - of the argument is determined by the specific command. - - :return: On success zero (OK) is returned; -1 (ERROR) is - returned on failure with the errno variable set to indicate the nature of the failure. - diff --git a/Documentation/reference/os/index.rst b/Documentation/reference/os/index.rst index 75f53bad32..c3bfdf6dbd 100644 --- a/Documentation/reference/os/index.rst +++ b/Documentation/reference/os/index.rst @@ -17,7 +17,6 @@ in other header files. addrenv.rst nuttx.rst app_vs_os.rst - boardctl.rst smp.rst shm.rst paging.rst diff --git a/Documentation/reference/user/13_boardctl.rst b/Documentation/reference/user/13_boardctl.rst new file mode 100644 index 0000000000..2e6a973bd2 --- /dev/null +++ b/Documentation/reference/user/13_boardctl.rst @@ -0,0 +1,252 @@ +=========== +Board IOCTL +=========== + +In a small embedded system, there will typically be a much +greater interaction between application and low-level board features. +The canonically correct to implement such interactions is by +implementing a character driver and performing the interactions +via low level ``ioctl()`` calls. This, however, may not be practical +in many cases and will lead to "correct" but awkward implementations. + +:c:func:`boardctl` is non-standard OS interface to alleviate the problem. +It basically circumvents the normal device driver ``ioctl()`` +interface and allows the application to perform direct +IOCTL-like calls to the board-specific logic. It is especially +useful for setting up board operational and test configurations. + +:c:func:`boardctl` is an application interface to the OS. +There is no point, in fact, of using :c:func:`boardctl` within the OS; +the board interfaces prototyped in :file:`include/nuttx/board.h` may +be called directly from within the OS. + +.. c:function:: int boardctl(unsigned int cmd, uintptr_t arg) + + :param cmd: Identifies the board command to be executed. See + :file:`include/sys/boardctl.h` for the complete list of common + board commands. Provisions are made to support non-common, + board-specific commands as well. + :param arg: The argument that accompanies the command. The nature + of the argument is determined by the specific command. + + :return: On success zero (OK) is returned; -1 (ERROR) is + returned on failure with the errno variable set to indicate the nature of the failure. + +Supported commands +================== + +The following is the list of supported :c:func:`boardctl` commands. +Besides this list, board logic can implement handling of custom commands by +implementing the :c:func:`board_ioctl` interface. + +System state control +-------------------- + +.. c:macro:: BOARDIOC_INIT + + Perform one-time application initialization. + + :Argument: The argument is passed to the + :c:func:`board_app_initialize` implementation without modification. + The argument has no meaning to NuttX; the meaning of the + argument is a contract between the board-specific + initialization logic and the matching application logic. + The value could be such things as a mode enumeration value, + a set of DIP switch switch settings, a pointer to + configuration data read from a file or serial FLASH, or + whatever you would like to do with it. Every + implementation should accept zero/NULL as a default + configuration. + + :Dependencies: Board logic must provide :c:func:`board_app_initialize`. + +.. c:macro:: BOARDIOC_POWEROFF + + Power off the board + + :Argument: Integer value providing power off status information + + :configuration: CONFIG_BOARDCTL_POWEROFF + + :dependencies: Board logic must provide the :c:func:`board_power_off` interface. + +.. c:macro:: BOARDIOC_RESET + + Reset the board + + :Argument: Integer value providing power off status information + + :configuration: CONFIG_BOARDCTL_RESET + + :dependencies: Board logic must provide the :c:func:`board_reset` interface. + +Power Management +---------------- + +.. c:macro:: BOARDIOC_PM_CONTROL + + Manage power state transition and query. The supplied argument + indicates the specific PM operation to perform, which map to + corresponding internal ``pm_`` functions + (see :doc:`/components/power`). + + With this interface you can interact with PM handling arch/board logic + (typically done in IDLE loop) or you can directly manage state transitions + from userspace. + + :Argument: A pointer to an instance of :c:struct:`boardioc_pm_ctrl_s`. + + :configuration: CONFIG_PM + +Board information +----------------- + +.. c:macro:: BOARDIOC_UNIQUEID + + Return a unique ID associated with the board (such as a + serial number or a MAC address). + + :Argument: A writable array of size :c:macro:`CONFIG_BOARDCTL_UNIQUEID_SIZE` in + which to receive the board unique ID. + + :dependencies: Board logic must provide the :c:func:`board_uniqueid` interface. + +Filesystems +----------- + +.. c:macro:: BOARDIOC_MKRD + + Create a RAM disk + + :Argument: Pointer to read-only instance of :c:struct:`boardioc_mkrd_s`. + + :configuration: CONFIG_BOARDCTL_MKRD + +.. c:macro:: BOARDIOC_ROMDISK + + Register a ROM disk + + :Argument: Pointer to read-only instance of :c:struct:`boardioc_romdisk_s`. + + :configuration: CONFIG_BOARDCTL_ROMDISK + +Symbol Handling +--------------- + +.. c:macro:: BOARDIOC_APP_SYMTAB + + Select the application symbol table. This symbol table + provides the symbol definitions exported to application + code from application space. + + :Argument: A pointer to an instance of :c:struct:`boardioc_symtab_s`. + + :configuration: CONFIG_BOARDCTL_APP_SYMTAB + +.. c:macro:: BOARDIOC_OS_SYMTAB + + Select the OS symbol table. This symbol table provides + the symbol definitions exported by the OS to kernel + modules. + + :Argument: A pointer to an instance of :c:struct:`boardioc_symtab_s`. + + :configuration: CONFIG_BOARDCTL_OS_SYMTAB + +.. c:macro:: BOARDIOC_BUILTINS + + Provide the user-space list of built-in applications for + use by BINFS in protected mode. Normally this is small + set of globals provided by user-space logic. It provides + name-value pairs for associating built-in application + names with user-space entry point addresses. These + globals are only needed for use by BINFS which executes + built-in applications from kernel-space in PROTECTED mode. + In the FLAT build, the user space globals are readily + available. (BINFS is not supportable in KERNEL mode since + user-space address have no general meaning that + configuration). + + :Argument: A pointer to an instance of :c:struct:`boardioc_builtin_s`. + + :configuration: This command is always available when + CONFIG_BUILTIN is enabled, but does nothing unless + CONFIG_BUILD_PROTECTED and CONFIG_FS_BINFS are also + selected. + +USB +--- + +.. c:macro:: BOARDIOC_USBDEV_CONTROL + + Manage USB device classes + + :Argument: A pointer to an instance of :c:struct:`boardioc_usbdev_ctrl_s`. + + :configuration: CONFIG_LIB_BOARDCTL && CONFIG_BOARDCTL_USBDEVCTRL + + :dependencies: Board logic must provide ``board__initialize()`. + +Graphics +-------- + +.. c:macro:: BOARDIOC_NX_START + + Start the NX server + + :Argument: Integer display number to be served by this NXMU instance. + + :configuration: CONFIG_NX + + :dependencies: Base graphics logic provides :c:func:`nxmu_start`. + +.. c:macro:: BOARDIOC_VNC_START + + Start the NX server and framebuffer driver. + + :Argument: A reference readable instance of :c:struct:`boardioc_vncstart_s`. + + :configuration: CONFIG_VNCSERVER + + :dependencies: VNC server provides :c:func:`vnc_default_fbinitialize`. + +.. c:macro:: BOARDIOC_NXTERM + + Create an NX terminal device + + :Argument: A reference readable/writable instance of + :c:struct:`boardioc_nxterm_create_s`. + + :configuration: CONFIG_NXTERM + + :dependencies: Base NX terminal logic provides :c:func:`nx_register` and + :c:func:`nxtk_register`. + +.. c:macro:: BOARDIOC_NXTERM_IOCTL + + Create an NX terminal IOCTL command. Normal IOCTLs + cannot be be performed in most graphics contexts since + the depend on the task holding an open file descriptor + + :Argument: A reference readable/writable instance of + :c:struct:`boardioc_nxterm_ioctl_s`. + + :configuration: CONFIG_NXTERM + + :dependencies: Base NX terminal logic provides :c:func:`nxterm_ioctl_tap`. + +Testing +------- + +.. c:macro:: BOARDIOC_TESTSET + + Access architecture-specific up_testset() operation + + :Argument: A pointer to a write-able spinlock object. On success + the preceding spinlock state is returned: 0=unlocked, + 1=locked. + + :configuration: CONFIG_BOARDCTL_TESTSET + + :dependencies: Architecture-specific logic provides :c:func:`up_testset`. + diff --git a/include/sys/boardctl.h b/include/sys/boardctl.h index 314dfffa8f..63bf7dd4a9 100644 --- a/include/sys/boardctl.h +++ b/include/sys/boardctl.h @@ -98,7 +98,7 @@ * DEPENDENCIES: None * * CMD: BOARDIOC_ROMDISK - * DESCRIPTION: Register + * DESCRIPTION: Register a ROM disk * ARG: Pointer to read-only instance of struct boardioc_romdisk_s. * CONFIGURATION: CONFIG_BOARDCTL_ROMDISK * DEPENDENCIES: None