IOLauncher
IOLauncher is a tool to spawn processes with specific credentials, procmgr abilities, NvSciIpc endpoint information, process scheduling policies, ASID, and dual execution mode.
IOLauncher also provides an option to spawn a group of pre-defined processes with pre-defined configurations for specific drivers.
Usage
IOLauncher has three ways to launch processes.
Generic usage for one process is:
# iolauncher [options] [program] [program options]
The usage for specific drivers with the pre-defined configuration is:
# iolauncher [options] -c [command]
The usage for running multiple commands from a configuration file is:
# iolauncher --cfg <iolauncher cfg file>
IOLauncher Options
The supported options are summarized in the following table.
Option | Optional Argument(s) | Description |
-A or --ability | <ability-spec> | QNX procmgr ability |
--cfg | <IOLauncher config file> | Launch programs which are specified in <IOLauncher config file> |
--critical | N/A | Launch program with SPAWN_CRITICAL attribute. |
--enable-de | N/A | Enable per-process Dual Execution Mode |
--setasid | <asid> | Set ASID |
-T or --sciipctag | <tag> | Set NvSciIpc program tag |
-U | <IDString> | Set credentials |
-C or --cpumask | <cpu mask> | Set CPU affinity |
-P or --priority | <priority[:policy]> | Set process priority and scheduler policy |
--dt | <dt path or alias> | Set ranged MEM_PHYS, INTERRUPT, INTERRUPTEVENT ability by reading the DT node |
--sid | <dt path or alias> | Set ranged SMMU/SID ability by reading the DT node |
--done | <done file path> | Set .done file path which is created after IOLauncher launches program successfully |
--prewait | <path> | Set file path that IOLauncher waits before launch program |
--prewait-timeout | <timeout> | Set timeout value for waiting the path before launch |
--waitfor | <path> | Set file path that IOLauncher waits after launch program |
--wait-timeout | <timeout> | Set timeout value for waiting the path after launch |
--wait or --waitcld | N/A | Wait for the launched process termination |
--waitcld-time | <timeout> | Set timeout value for waiting the launched process termination |
--nvivc | N/A | Use for devv-nvivc only |
Set procmgr abilities
Set QNX procmgr abilities in launching the process.
Option:
• Short option: -A
• Long option: --ability
• Argument: <ability-spec>
The <ability-spec> argument is a comma-separated list that contains the following:
• the ability identifier
• one or more of the following operations: allow or deny, lock, inherit or noinherit
• a subrange as optional, the argument string must conclude with a colon, in the following form:
• two numbers separated by a hyphen (e.g., 1-10). If the first characters are 0x or 0X, the digits are treated as hexadecimal. If the first character is 0, the digits are treated as octal. Otherwise, the digits are treated as decimal.
• root, nonroot, or all to specify the applicable domain
• Dynamic ability, which is created by procmgr_ability_create() API, can be specified with able= operation keyword.
Example:
# iolauncher -A mem_phys,io
# iolauncher -A mem_phys:0x10000000-0x20000000,interrupt:13-14
# iolauncher -A able=vfs/mount-blk
The ability identifier is the same as the QNX "on" utility. But iolauncher only supports the abilities in the whitelist for security reasons.
IOLauncher only allows the QNX procmgr abilities in the list below:
• spawn_setuid
• spawn_setgid
• setuid
• setgid
• pathspace
• reboot
• rsrcdbmgr
• session
• event
• rlimit
• mem_phys
• mem_special
• mem_global
• mem_peer
• mem_lock
• spawn
• fork
• prot_exec
• wait
• qnet
• clockset
• clockperiod
• interrupt
• keydata
• io
• priority
• connection
• schedule
• signal
• map_fixed
• path_trust
• child_newapp
• public_channel
• aps_root
• able_create
• runstate_burst
• default_timer_tolerance
• power
• prot_write_and_exec
• srandom
• rlimit_peer
• channel_connect
• settypeid
• able_priv
• interruptevent
• high_resolution_timer
• privreg
IOLauncher allows the following dynamic abilities that are created by NVIDIA regardless of the "able=" keyword:
• NVSCIIPC_ABILITY_ID
• NvMap/Interface
• SMMU/SID
IOLauncher allows any other dynamic abilities which are created by procmgr_ability_create().
Run multiple commands from config file
IOLauncher reads the command line options from the specified config file, then run.
Option:
• Short option: N/A
• Long option: --cfg
• Argument: <cfg file>
The <cfg file> consists of the following lines:
• A comment starting with "#"
• A blank line
• A line contains iolauncher command line options, including program name and program options except --cfg option
Example:
# Launch "/proc/boot/my_driver opt1=1 opt2=2" as non-root (1000:1000) with SGID 1200
iolauncher -U 1000:1000,1200 /proc/boot/my_driver opt1=1 opt2=2
# Launch "/proc/boot/your_driver opt1=3 opt2=4" as root
iolauncher /proc/boot/your_driver opt1=3 opt2=4
Set Dual Execution Mode
Enables Dual Execution EL0 Bit in ACTLR_EL1 ARM register in launching process. If EL1 bit is not set, the iolauncher fails to launch the process.
Option:
• Short option: N/A
• Long option: --enable-de
• Argument: N/A
Note: | This option is only available in the standard release. |
Set ASID
Set ASID to the launched process.
Option:
• Short Option: N/A
• Long option: --setasid
• Argument: <ASID>
<ASID> is an integer value between 1 to maximum value in device tree. If 0 is specified, QNX System assigns any unassigned ASID in the valid range.
Set NvSciIpc Program Tag
Set applicable NvSciIpc endpoints in launching process.
IOLauncher reads NvSciIpc endpoint names using <NvSciIpc program tag> from NvSciIpc security configuration file and sets the endpoint specific abilities and SGIDs for the applicable NvSciIpc endpoints.
Option:
• Short option: -T
• Long option: --sciipctag
• Argument: <NvSciIpc program tag>
Set Credentials
Set UID and GID, and/or SGID(s) to the launched process.
Option:
• Short option: -U
• Argument: <UID:GID[,SGID1,SGID2,...]>
Set CPU affinity
Set CPU affinity(runmask) while launching a process.
Option:
• Short option: -C
• Long option: --cpumask
• Argument: <CPU Mask>
If the first characters of <CPU Mask> are 0x or 0X, the digits are treated as hexadecimal. If the first character is 0, the digits are treated as octal. Otherwise, the digits are treated as decimal.
The valid range of <CPU Mask> is variable as per the vCPU configuration of the system.
If the given <CPU Mask> is out of valid range, QNX OS assigns all CPUs as default without any error.
Set process priority and scheduling policy
Set process priority and scheduler policy.
Option:
• Short option: -P
• Long option: --priority
• Argument: <priority[:policy]>
Priorities are in the range from 1 through 255 (highest priority). If 0 is specified, the program launches with default priority (10) by OS.
The scheduler policy must be one of below if specified:
• f - FIFO
• r - Round-robin
If any other policy is specified, IOLauncher fails to launch.
Set MEM_PHYS, INTERRUPT, INTERRUPTEVENT ability with address range and IRQs from DT
Set MEM_PHYS ability with the address ranges from “regs” in the specified dt node and “mem” property, and INTERRUPTEVENT or INTERRUPT ability with the interrupt numbers from “interrupts” property in the specified DT node and linked typed-memory nodes by "memory-phandles" property.
IOLauncher set INTERRUPTEVENT ability for "interrupts" property by default even if INTERRUPT ability is not specified by -A option before using this option.
Option:
• Short option: N/A
• Long option: --dt
• Argument: <path or alias>
Set SMMU/SID ability with SIDs from DT
Set SMMU/SID ability with a list of SID from “iommus” property in the specified DT node.
Option:
• Short option: N/A
• Long option: --sid
• Argument: <path or alias>
Set done file path
IOLauncher creates the specified path after launch program successfully.
Done file can be used as an indicator b/w programs and scripts that to check the dependency is launched or not.
For example:
• Run MyI2C driver with setting done file path
• Wait until the done file exists
• Run MyCamera application which requires the MyI2C driver
# iolauncher --done /tmp/myi2c.done myi2c_driver
# waitfor /tmp/myi2c.done
# iolauncher mycamera
In general, done file path is specified as following form - '/tmp/[program name].done'. Because, /tmp is a temporary file system path and it's initialized at every booting.
Option:
• Short option: N/A
• Long option: --done
Set file path for waiting before launch
IOLauncher waits until the path exists before launch the program.
IOLauncher has configurable timeout value for waiting. If timeout occurs, IOLauncher exits with failure.
Option:
• Short option: N/A
• Long option: --prewait
Set timeout value for waiting before launch
Set timeout value for waiting the path before launch.
The timeout value must be specified b/w minimum and maximum value. If 0 is specified, the default timeout value is used.
• Default timeout: 10 seconds
• Minimum timeout: 1 milli-seconds
• Maximum timeout: 30 seconds
Option:
• Short option: N/A
• Long option: --prewait-timeout
• Argument: <time in ms>
Note: | The timeout is not a hard timeout. IOLauncher does not guarantee the precision of the timeout. |
Set file path for waiting after launch
IOLauncher waits until the path exists after launch the program.
IOLauncher has configurable timeout value for waiting. If timeout occurs, IOLauncher exits with failure.
Option:
• Short option: N/A
• Long option: --waitfor
Set timeout value for waiting after launch
Set timeout value for waiting the path.
The timeout value must be specified b/w minimum and maximum value. If 0 is specified, the default timeout value is used.
• Default timeout: 10 seconds
• Minimum timeout: 1 milli-seconds
• Maximum timeout: 30 seconds
Option:
• Short option: N/A
• Long option: --wait-timeout
• Argument: <time in ms>
Note: | The timeout is not a hard timeout. IOLauncher does not guarantee the precision of the timeout. |
Launch with SPAWN_CRITICAL attribute
Set SPAWN_CRITICAL attribute for the launched program.
If the launched program is terminated, the QNX OS shutdown automatically regardless of the exit status of the terminated program.
Option:
• Short option: N/A
• Long option: --critical
• Argument: N/A
Note: | The SPAWN_CRITICAL attribute must be set to the safety critical processes which impacts the system stability when the process is terminated, and the process termination cannot be detected. QNX System shutdown skips to send SIGTERM (and SIGKILL) to the SPAWN_CRITICAL process during shutdown. Hence, this attribute can be used to keep alive the process even if the system is in shutting down. |
Wait for the launched process termination.
IOLauncher waits for the termination of the launched program and returns EXIT_SUCCESS if the program is terminated with EXIT_SUCCESS or returns EXIT_FAILURE if the program is terminated with other exit code.
Option:
• Short option: N/A
• Long option: --wait or --waitcld
• Argument: N/A
Set timeout value for waiting for the launched process termination
Set timeout value for waiting the process termination using --wait or --waicld option.
The timeout value must be specified b/w minimum and maximum value. If 0 is specified, the default timeout value is used.
• Default timeout: 10 seconds
• Minimum timeout: 1 milli-seconds
• Maximum timeout: 30 seconds
Option:
• Short option: N/A
• Long option: --waitcld-time
• Argument: <time in ms>
--wait or --waitcld | N/A | Wait for the launched program termination |
--waitcld-time | <timeout> | Set timeout value for waiting the launched program termination |
Set timeout value for waiting for the launched process termination
Set timeout value for waiting the process termination using --wait or --waicld option.
The timeout value must be specified b/w minimum and maximum value. If 0 is specified, the default timeout value is used.
• Default timeout: 10 seconds
• Minimum timeout: 1 milli-seconds
• Maximum timeout: 30 seconds
Pre-Defined Configuration for Specific Drivers
The "-c" or "--command" option is used to launch specific drivers with pre-defined configuration.
<command> is an option argument of "-c" or "--command" option that specifies what pre-defined driver to be launched.
The --done option and --waitfor option are not applicable, because IOLauncher has pre-defined or programmed value for each <command>.
The optional <command> argument is summarized in the table below:
<command> | Launched program | Pre-defined --done option |
i2c | I2C driver | /tmp/i2c_iolauncher.done |
pci | PCIe driver | /tmp/pci_iolauncher.done |
sdl_ccplex | CCPLEX_SDL driver | /tmp/ccplex_sdl.done |
spi | SPI driver | /tmp/spi_iolauncher.done |
virt_qspi | Virtual QSPI driver by Virtual Storage Client | /tmp/vqspi_iolauncher.done |
vscd | Virtual eMMC and UFS driver by Virtual Storage Client | /tmp/vscd_iolauncher.done |
This option may require additional options summarized in the following table:
Option | Optional Argument | Description |
--d or
--storagetype | emmc or
qspi | Sets the storage type for VSC driver. |
Set Storage Type for VSC driver
Set the storage type used by the virtual storage client driver.
Option:
• Short option: -d
• Long option: -- storagetype
• Argument: <emmc or qspi>
Show usage
IOLauncher shows the usage and description of IOLauncher options.
Option:
• Short option: -h
• Long option: --help
• Argument: N/A
Limitations
1. Maximum number of Virtual QSPI driver instances (-c virt_qspi option): Up to 24.
2. Maximum number of Virtual eMMC and UFS driver instances (-c vscd option): Up to 24.
3. Maximum number of SGIDs: up to 384 (QNX System limitation).
4. Maximum number of NvSciIpc endpoints: up to 50 (Limited by maximum number of channels per process in QNX System.).
5. Maximum number of the command line options: Up to 256
6. Maximum command line length: Up to 4KB
7. Maximum line length of NvSciIpc security policy config file: Up to 4KB including NULL termination.
A NvSciIpc program tag and an endpoint name can have around 80 bytes including a delimiter.