nuttx/Documentation/reference/user/13_boardctl.rst

===========
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_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_<operation>`` functions
   (see :doc:`/components/drivers/special/power/pm/index`).

   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.

.. c:macro:: BOARDIOC_MACADDR

   Get the network driver MAC address.

   :Argument: A pointer to an instance of :c:struct:`boardioc_macaddr_s`.

   :configuration: CONFIG_BOARDCTL_MACADDR

   :dependencies: Board logic must provide the :c:func:`board_macaddr` 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 is 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_BOARDCTL && CONFIG_BOARDCTL_USBDEVCTRL

   :dependencies: Board logic must provide `board_<usbdev>_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:`nx_vnc_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`.