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.

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.

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.

int boardctl(unsigned int cmd, uintptr_t arg)

Parameters

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.
arg – The argument that accompanies the command. The nature of the argument is determined by the specific command.

Returns

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 boardctl() commands. Besides this list, board logic can implement handling of custom commands by implementing the board_ioctl() interface.

System state control

BOARDIOC_INIT

Perform one-time application initialization.

Argument: The argument is passed to the 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 board_app_initialize().

BOARDIOC_POWEROFF

Power off the board

Argument: Integer value providing power off status information
Configuration: CONFIG_BOARDCTL_POWEROFF
Dependencies: Board logic must provide the board_power_off() interface.

BOARDIOC_RESET

Reset the board

Argument: Integer value providing power off status information
Configuration: CONFIG_BOARDCTL_RESET
Dependencies: Board logic must provide the board_reset() interface.

Power Management

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 Power Management).

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 boardioc_pm_ctrl_s.
Configuration: CONFIG_PM

Board information

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 CONFIG_BOARDCTL_UNIQUEID_SIZE in which to receive the board unique ID.
Dependencies: Board logic must provide the board_uniqueid() interface.

Filesystems

BOARDIOC_MKRD

Create a RAM disk

Argument: Pointer to read-only instance of boardioc_mkrd_s.
Configuration: CONFIG_BOARDCTL_MKRD

BOARDIOC_ROMDISK

Register a ROM disk

Argument: Pointer to read-only instance of boardioc_romdisk_s.
Configuration: CONFIG_BOARDCTL_ROMDISK

Symbol Handling

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 boardioc_symtab_s.
Configuration: CONFIG_BOARDCTL_APP_SYMTAB

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 boardioc_symtab_s.
Configuration: CONFIG_BOARDCTL_OS_SYMTAB

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 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

BOARDIOC_USBDEV_CONTROL

Manage USB device classes

Argument: A pointer to an instance of boardioc_usbdev_ctrl_s.
Configuration: CONFIG_BOARDCTL && CONFIG_BOARDCTL_USBDEVCTRL
Dependencies: Board logic must provide board_<usbdev>_initialize().

Graphics

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 nxmu_start().

BOARDIOC_VNC_START

Start the NX server and framebuffer driver.

Argument: A reference readable instance of boardioc_vncstart_s.
Configuration: CONFIG_VNCSERVER
Dependencies: VNC server provides nx_vnc_fbinitialize().

BOARDIOC_NXTERM

Create an NX terminal device

Argument: A reference readable/writable instance of boardioc_nxterm_create_s.
Configuration: CONFIG_NXTERM
Dependencies: Base NX terminal logic provides nx_register() and nxtk_register().

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 boardioc_nxterm_ioctl_s.
Configuration: CONFIG_NXTERM
Dependencies: Base NX terminal logic provides nxterm_ioctl_tap().

Testing

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 up_testset().