startup-* options

Updated: April 19, 2023

Generic options for startup programs (QNX Neutrino)

Description:

All QNX Neutrino startup programs support the generic options described below. There are additional options for the following architectures:

Note: Individual startup programs can override these options and may support additional board-specific options. The order of precedence is as follows:
  1. board-specific options
  2. architecture-specific options
  3. generic options

Generic options

-A
Set the SYSTEM_PRIVATE_FLAG_ABNORMAL_REBOOT bit on SYSPAGE_ENTRY(system_private)->private_flags. This bit (or flag) determines how an abnormal termination is handled by the default version of the reboot kernel callout. If this flag is set, the callout proceeds to reboot the system.
The system can terminate abnormally for many reasons, including:
  • the kernel detects internal inconsistencies
  • the kernel runs out of memory doing work that is guaranteed to succeed
  • a critical process terminates

For more information about this kernel callout, see System reboot in the Building Embedded Systems guide.

If this flag isn't set, the default reboot callout doesn't reboot the system but instead halts execution, allowing you to attach a debugger and investigate the processor state. Also, this flag applies only to abnormal shutdowns. With normal shutdowns, which are those initiated by a call to sysmgr_reboot(), shutdown_system(), or shutdown_system_with_reason(), this flag isn't considered.

-C
Clear (i.e., zero) any memory allocated by the startup library.
-D channel[.channel_opts]
Specify an output channel for debugging information. The format of this option and the default value vary from board to board.
-F [~]value
Control the flags field in the cpuinfo section of the system page:
  • value — OR the flags field with value
  • ~value — AND the flags field with ~value

For more information about the flags, see the System Page chapter of Building Embedded Systems.

-f [cpu_freq][,[cycles_freq][,timer_freq][,timer_prog_time]]
Specify CPU frequencies and if necessary, the timer programming time. All frequencies can be followed by H for hertz, K for kilohertz, or M for megahertz (these suffixes aren't case-sensitive). If no suffix is given, the library assumes megahertz if the number is less than 1000; otherwise it assumes hertz.

If they're specified, cpu_freq, cycles_freq, and timer_freq are used to set the corresponding variables in the startup code:

  • cpu_freq — the CPU clock frequency. It's also used to set the speed field in the cpuinfo section of the system page.
  • cycles_freq — the frequency at which the value returned by ClockCycles() increments. It's also used to set the cycles_per_sec field in the qtime section of the system page.
  • timer_freq — the frequency at which the timer chip input runs. It's also used to set the timer_rate and timer_scale values of the qtime section of the system page.
  • (QNX Neutrino 7.1 or later) timer_prog_time — the time required to write to the hardware timer that's used to drive the system clock. This is only needed on systems where time can disappear during QNX early bootup (e.g., running on a hypervisor and the thread simulating the CPU is taken away, but the ClockCycles() clock keeps ticking), and the window of opportunity for the problem to occur is small.

    To prevent the problem, you can characterize the time it takes to write to the hardware timer (i.e., the time for one call to the timer_load() callout). The value is in nanoseconds; for example, use -f 0,0,0,5000 for 5000 ns.

    Passing in 0 or leaving the field empty causes procnto to sample the time, and is the current mode of operation.

If a variable is zero when it comes time to set the field(s) on the system page, the library code attempts to deduce the proper value by using one of the other frequency variables. Which one it uses depends on the particular CPU and hardware.

-I flag
Enable kernel restoration as part of IFS restoration. The flag is 0 to disable checksum verification, or 1 to enable it.

If checksum verification is enabled and fails, the entire image is reloaded.

Note: Even if the IFS checksum verification is disabled, a checksum is still performed on the IFS Restoration internal data structure (approximately 32 bytes) to ensure at least some data integrity.

For more information, see Reloadable Image Filesystems in the QNX Neutrino technotes.

-i ifs2_size[,flags][,paddr_src][,paddr_dst]
Enable secondary IFS restoration.

The arguments are:

ifs2_size
The size of the secondary IFS (note: this can be larger than the actual size).
flags
  • Not specified — load the secondary IFS but don't try to restore on wake-up
  • R — load the secondary IFS and restore
  • K or RK — load the secondary IFS and restore with a checksum
paddr_src
  • Not specified — the secondary IFS is located in flash after the primary IFS
  • Specified — the secondary IFS is located at the physical address specified
paddr_dst
  • Not specified — the secondary IFS will be copied to a default location in RAM
  • Specified — the secondary IFS will be copied to the physical address specified (choose an address in a “safe” place, such as at the end of RAM away from where the primary image is copied)

If the checksum is enabled and fails, the entire secondary IFS is reloaded.

Note: Even if the secondary IFS checksum is disabled, a checksum is still performed on the IFS Restoration internal data structure (approximately 16 bytes) to ensure at least some data integrity.

For more information, see Reloadable Image Filesystems in the QNX Neutrino technotes.

-j addr
For use with JTAG/hardware debuggers.

Reserve 4 bytes of RAM at the physical address specified by addr, and copy the physical address of the location of the system page to addr in RAM so that it can be retrieved by a hardware debugger.

-K channel[.channel_opts]
Specify an output channel for kernel debugger information. The format of this option and the default value vary from board to board.
-N hostname
Specify the node name. The default is the local host.
-P max_CPUs
Specify the maximum number of processors to activate in a multicore system. This is useful for testing how well your application runs on a system with fewer CPUs.
-R size[,align[,name[,use_low_memory]]]
Remove size memory from system use, optionally specifying the alignment and the name of the reserved area. This is useful for testing in a restricted-memory environment. The size and alignment are in bytes, unless followed by one of K (kilobytes), M (megabytes), or G (gigabytes). You can specify more than one instance of the -R option.

If you specify the align argument, the reserved area is aligned on the boundary it specifies. The default is 0, meaning no alignment.

If you specify the name argument, the reserved RAM area is available through the POSIX typed memory interface under /memory/ram/name. If you don't specify the name argument, the area is available under /memory/ram/reserved.

The optional use_low_memory argument is an unsigned integer. If it's zero (the default), startup gets memory from the top of memory, which doesn't work for drivers with 32-bit DMA address restrictions if the target has RAM available above 4 GB. If use_low_memory is nonzero, startup tries to allocate from the lower end of memory, in the hope that there's enough below4G memory to work with 32-bit DMA restrictions. If below4G is already full, the driver can still get an address that's above 4 GB.

-r addr,size[,flag]
Remove size memory from system use starting at addr.

The flag is an optional argument used to specify if the memory should be cleared:

Flag: Memory:
None Clears to 0
0 Clears to 0
1 Does not clear
Warning: During the boot process, the value of -r is ignored when the IFS is loaded and decompressed. Therefore, when you use -r to reserve a specific address range, make sure that neither the IFS load address nor the decompressed IFS size overlap with the reserved range.
-S [~]section
Turn on (or, if you use ~section, off) output of the specified syspage section's information. Use this to restrict the amount of syspage information. For more information, see the description of print_syspage() in the Startup Library chapter of Building Embedded Systems.
-T
Prevent the startup program from setting the SYSPAGE_ENTRY(qtime)->boot_time field. If this field is 0 the first time you call ClockTime() to change the time of day, the kernel sets it to the appropriate value. This is useful if the RTC hardware isn't in UTC.
-v[v]...
Be verbose. More v characters cause even more verbosity.
-Z
Enable tickless operation. In this mode, when the system is idle, the clock tick is “turned off” until just after the next active timer is to fire. For more information, see Clocks, timers, and power management in the “Understanding the Microkernel's Concept of Time” chapter of the QNX Neutrino Programmer's Guide.

If you specify this option, the QTIME_FLAG_TICKLESS flag is set in the qtime member of the system page (see the System Page chapter of Building Embedded Systems).

Options for 32-bit ARM targets

The following options are supported in the startup programs for 32-bit ARM targets:

-x
Enable extended addressing. This lets you access physical addresses above 4 GB. This option is only applicable on supported hardware where the CPU supports Large Physical Address Extension (LPAE).

Options for 64-bit ARM (AArch64) startups

The following options are supported in the startup programs for 64-bit ARM (AArch64) targets:

-E option, -E ~option
Apply (-E option) or don't apply (-E ~option) the following:
  • meltdown — The workaround for the meltdown exploit (CVE-2017-5754) erratum; see https://meltdownattack.com/. By default, this workaround isn't applied.
  • spectrev2 — The workaround for the spectre variant 2 erratum; see https://developer.arm.com/support/arm-security-updates/speculative-processor-vulnerability. By default, this workaround isn't applied.
  • ssbs — Set the flag AARCH64_CPU_SSBS for each cpuinfo entry in the system page.

    If this flag is set for CPU 0, the kernel checks each CPU to determine if it supports FEAT_SSBS (Speculative Store Bypass Safe (SSBS)). To determine whether a CPU supports SSBS, the kernel queries the CPU's ID_AA64PFR1_EL1 feature register (not its cpuinfo entry). If the CPU supports SSBS, its PSTATE.SSBS bit is set.

    A CPU's PSTATE.SSBS bit is not cleared if AARCH64_CPU_SSBS is not set for cpuinfo for CPU 0.

    For more information, see cpuinfo in the “System Page” chapter of Building Embedded Systems.

-U
Check each CPU to determine if it supports Pointer Authentication. If it does, set the flag AARCH64_CPU_PAUTH for its cpuinfo entry in the system page.

For more information, see cpuinfo in the “System Page” chapter of Building Embedded Systems.

Options for 64-bit x86 targets

The following options are supported in the startup programs for 64-bit x86 targets:

-B
By default, x86 startups use the Advanced Control and Power Interface (ACPI) table to determine information such as the number of logical CPUs on hyperthreaded systems. Use this option to avoid checking for ACPI in the case of buggy BIOSs; if ACPI isn't present or you specify -B, the startup uses the Intel Multiprocessor Specification.
-E erratum, -E ~erratum
Apply (-E erratum) or don't apply (-E ~erratum) the workaround for the specified erratum:
-z[z]
Specify the source of the system clock. By default, the startup program tries to initialize the clock from the sources in the following order, using the first that's available:
  1. LAPIC (Local Advanced Programmable Interrupt Controller) timer on CPU 0
  2. HPET (High Precision Event Timer)
  3. 8254 Programmable Interval Timer

You can use the -z[z] option to affect the selection:

  • -z — skip the LAPIC and HPET, and use the 8254.
  • -zz — skip the LAPIC, and use the HPET if it's available, falling back on the 8254 otherwise.

To determine which clock source was selected, do one of the following:

  • Specify the -v option for the startup program; the output indicates the clock source.
  • Use pidin to display the qtime area of the system page. The output might look like this:
    # pidin syspage=qtime
    Header size=0x00000108, Total Size=0x00000cc0, #Cpu=2, Type=256
    Section:qtime offset:0x00000258 size:0x00000060
      boot:5b35f6a0 CPS:00000000a1ca3421 rate/scale:69841279/-15 intr:2
      flags:00000002 load:14318 epoch:1970 rr_mul:0 adj count/inc:0/0
      nsec:0000014dba1b3f2b stable:0000014dba1b3f2b inc:000f4233
      nsec_tod_adj:153c9645d0da4000
    

    The clock period (rate * 10scale) indicates which clock is being used. Typical numbers are as follows:

    Clock source Rate Scale Period (femtoseconds)
    LAPIC 1 -8 10,000,000
    HPET 69841279 -15 69,841,279
    8259 838095345 -15 838,095,345

    For more information about the contents of the system page, see the System Page chapter of Building Embedded Systems.