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