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 two ways to launch processes.
Generic usage is:
# iolauncher [options] [program] [program options]
The usage for specific drivers with the pre-defined configuration is:
# iolauncher [options] -c [command]
IOLauncher Options
The supported options are summarized in the following table.
Option | Optional Argument(s) | Description |
-A or --ability | <ability-spec> | QNX procmgr ability |
--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 will be created after IOLauncher launches program successfully |
--prewait | <path> | Set file path that IOLauncher will wait before launch program |
--prewait-timeout | <timeout> | Set timeout value for waiting the path before launch |
--waitfor | <path> | Set file path that IOLauncher will wait after launch program |
--wait-timeout | <timeout> | Set timeout value for waiting the path after launch |
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
Example:
# iolauncher -A mem_phys,io
# iolauncher -A mem_phys:0x10000000-0x20000000,interrupt:13-14
The ability identifier is same as QNX "on" utility. But, iolauncher only supports the abilities in the whitelist for security reason.
IOLauncher only allows the QNX procmgr abilities in the whitelist 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 also:
• NVSCIIPC_ABILITY_ID
• NvMap/Interface
• SMMU/SID
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
Set ASID
Set ASID to the launched process.
Option:
• Short Option: N/A
• Long option: --setasid
<ASID> is an integer value between 1 to 4095(0xFFF). If 0 is specified, QNX System assigns any 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 will be launched 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, which means the timeout happens after the specified time, but 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, which means the timeout happens after the specified time, but IOLauncher does not guarantee the precision of the timeout. |
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 |
sdl_ccplex | CCPLEX_SDL driver | /tmp/ccplex_sdl.done |
virt_qspi | Virtual QSPI driver by Virtual Storage Client | /tmp/vqspi_iolauncher.done |
vscd | Virtual eMMC driver by Virtual Storage Client | /tmp/vscd_iolauncher.done |
This option may require additional options summarized in the following table:
Option | Optional Argument | Description |
--loopback-uid | <UID[:GID]> | Sets UID/GID for loopback device driver. |
--d or
--storagetype | emmc or
ufs or
qspi | Sets the storage type for VSC driver. |
Set credentials for the loopback device driver
Sets UID and GID for the loopback device driver after launching Virtual Storage Client driver.
Option:
• Short option: N/A
• Long option: --loopback-uid
• Argument: <UID[:GID]>
Set Storage Type for VSC driver
Set the storage type which will be used by Virtual Storage Client driver.
Option:
• Short option: -d
• Long option: -- storagetype
• Argument: <emmc or ufs or qspi>
Limitations
1. Maximum number of Virtual QSPI driver instances (-c virt_qspi option): Up to 24.
2. Maximum number of Virtual eMMC driver instances (-c vscd option): Up to 24.
3. Maximum number of SGIDs: up to 384 (QNX OS limitation).
4. Maximum number of NvSciIpc endpoints: up to 384 (limited by 3.).
