Zircon Kernel Commandline Options

{# DO NOT EDIT THIS FILE DIRECTLY #} {# Instead see //zircon/kernel/lib/boot-options:markdown. #} {# Run fx set core.x64 --args="update_goldens='true'" --with //zircon/kernel/lib/boot-options:check-markdown #} {# Then fx build and //docs/gen/boot-options.md will be updated. #}

Options common to all machines

aslr.disable=<bool>

Default: false

If this option is set, the system will not use Address Space Layout Randomization.

aslr.entropy_bits=<uint8_t>

Default: 0x1e

For address spaces that use ASLR this controls the number of bits of entropy in the randomization. Higher entropy results in a sparser address space and uses more memory for page tables. Valid values range from 0-36.

kernel.cprng-reseed-require.hw-rng=<bool>

Default: false

When enabled and if HW RNG fails at reseeding, CPRNG panics.

kernel.cprng-reseed-require.jitterentropy=<bool>

Default: false

When enabled and if jitterentropy fails at reseeding, CPRNG panics.

kernel.cprng-seed-require.hw-rng=<bool>

Default: false

When enabled and if HW RNG fails at initial seeding, CPRNG panics.

kernel.cprng-disable.jitterentropy=<bool>

Default: false

Determines whether jitterentropy will be used as an entropy source (used for testing)

kernel.cprng-disable.hw-rng=<bool>

Default: false

Determines whether HW RNG will be used as an entropy source (used for testing)

kernel.cprng-seed-require.jitterentropy=<bool>

Default: false

When enabled and if jitterentropy fails initial seeding, CPRNG panics.

kernel.cprng-seed-require.cmdline=<bool>

Default: false

When enabled and if you do not provide entropy input from the kernel command line, CPRNG panics.

kernel.entropy-mixin=<hexadecimal>

Provides entropy to be mixed into the kernel's CPRNG. The value must be a string of lowercase hexadecimal digits.

The original value will be scrubbed from memory as soon as possible and will be redacted from all diagnostic output.

kernel.jitterentropy.bs=<uint32_t>

Default: 0x40

Sets the “memory block size” parameter for jitterentropy. When jitterentropy is performing memory operations (to increase variation in CPU timing), the memory will be accessed in blocks of this size.

kernel.jitterentropy.bc=<uint32_t>

Default: 0x200

Sets the “memory block count” parameter for jitterentropy. When jitterentropy is performing memory operations (to increase variation in CPU timing), this controls how many blocks (of size kernel.jitterentropy.bs) are accessed.

kernel.jitterentropy.ml=<uint32_t>

Default: 0x20

Sets the “memory loops” parameter for jitterentropy. When jitterentropy is performing memory operations (to increase variation in CPU timing), this controls how many times the memory access routine is repeated. This parameter is only used when kernel.jitterentropy.raw is true. If the value of this parameter is 0 or if kernel.jitterentropy.raw is false, then jitterentropy chooses the number of loops is a random-ish way.

kernel.jitterentropy.ll=<uint32_t>

Default: 0x1

Sets the “LFSR loops” parameter for jitterentropy. When jitterentropy is performing CPU-intensive LFSR operations (to increase variation in CPU timing), this controls how many times the LFSR routine is repeated. This parameter is only used when kernel.jitterentropy.raw is true. If the value of this parameter is 0 or if kernel.jitterentropy.raw is false, then jitterentropy chooses the number of loops is a random-ish way.

kernel.jitterentropy.raw=<bool>

Default: true

When true, the jitterentropy entropy collector will return raw, unprocessed samples. When false, the raw samples will be processed by jitterentropy, producing output data that looks closer to uniformly random. Note that even when set to false, the CPRNG will re-process the samples, so the processing inside of jitterentropy is somewhat redundant.

kernel.lockup-detector.critical-section-threshold-ms=<uint64_t>

Default: 0xbb8

When a CPU remains in a designated critical section for longer than this threshold, a KERNEL OOPS will be emitted.

See also k lockup status and lockup detector.

When 0, critical section lockup detection is disabled.

When kernel.lockup-detector.heartbeat-period-ms is 0, critical section lockup detection is disabled.

kernel.lockup-detector.critical-section-fatal-threshold-ms=<uint64_t>

Default: 0x2710

When a CPU remains in a designated critical section for longer than this threshold, a crashlog will be generated and the system will reboot, indicating a reboot reason of SOFTWARE_WATCHDOG as it does.

See also k lockup status and lockup detector.

When 0, critical section crashlog generation and reboot is disabled.

When kernel.lockup-detector.heartbeat-period-ms is 0, critical section lockup detection is disabled.

kernel.lockup-detector.heartbeat-period-ms=<uint64_t>

Default: 0x3e8

How frequently a secondary CPU should emit a heartbeat via kernel timer. This value should be large enough to not impact system performance, but should be smaller than the heartbeat age threshold. 1000 is a reasonable value.

See also lockup detector.

When 0, heartbeat detection is disabled.

kernel.lockup-detector.heartbeat-age-threshold-ms=<uint64_t>

Default: 0xbb8

The maximum age of a secondary CPU's last heartbeat before it is considered to be locked up. This value should be larger than the heartbeat period, but small enough so as to not miss short-lived lockup events. 3000 is a reasonable value.

See also lockup detector.

When 0, heartbeat detection is disabled.

kernel.lockup-detector.heartbeat-age-fatal-threshold-ms=<uint64_t>

Default: 0x2710

The maximum age of a CPU's last heartbeat before it is considered to be locked up, triggering generation of a crashlog indicating a reboot reason of SOFTWARE_WATCHDOG followed by a reboot.

See also lockup detector.

When 0, heartbeat crashlog generation and reboot is disabled.

kernel.lockup-detector.diagnostic-query-timeout-ms=<uint64_t>

Default: 0x64

The maximum amount of time to spend trying to get diagnostic data from an unresponsive CPU before giving up.

When 0, querying for diagnostic data is disabled.

kernel.oom.behavior=[reboot | jobkill]

Default: reboot

This option can be used to configure the behavior of the kernel when encountering an out-of-memory (OOM) situation. Valid values are jobkill, and reboot.

If set to jobkill, when encountering OOM, the kernel attempts to kill jobs that have the ZX_PROP_JOB_KILL_ON_OOM bit set to recover memory.

If set to reboot, when encountering OOM, the kernel signals an out-of-memory event (see zx_system_get_event()), waits some period, and then reboots the system. The length of the wait period is set by the kernel.oom.reboot-timeout-ms boot option, and the expectation is that during this wait period, userspace will trigger a shutdown upon receiving the OOM signal.

kernel.oom.reboot-timeout-ms=<uint32_t>

Default: 0xc350

This option sets the amount of time the kernel will wait before rebooting the system after it has signaled an out-of-memory (OOM) event. This option is only relevant when kernel.oom.behavior is set to reboot.

kernel.mexec-force-high-ramdisk=<bool>

Default: false

This option is intended for test use only. When set to true it forces the mexec syscall to place the ramdisk for the following kernel in high memory (64-bit address space, >= 4GiB offset).

kernel.mexec-pci-shutdown=<bool>

Default: true

If false, this option leaves PCI devices running when calling mexec.

kernel.oom.enable=<bool>

Default: true

This option turns on out-of-memory (OOM) monitoring in the kernel, which takes action per kernel.oom.behavior when the PMM has less than kernel.oom.outofmemory-mb free memory, and no memory can be reclaimed.

An OOM can be manually triggered by the command k mem oom, which will cause free memory to fall below the kernel.oom.outofmemory-mb threshold. An allocation rate can be provided with k mem oom <rate>, where <rate> is in MB. This will cause the specified amount of memory to be allocated every second, which can be useful for observing memory pressure state transitions.

Refer to kernel.oom.outofmemory-mb, kernel.oom.critical-mb, kernel.oom.warning-mb, and zx_system_get_event() for further details on memory pressure state transitions.

The current memory availability state can be queried with the command k mem dump.

kernel.oom.outofmemory-mb=<uint64_t>

Default: 0x32

This option specifies the free memory threshold at which the kernel will signal an out-of-memory event and take action as specified by kernel.oom.behavior, if there is no reclaimable memory that can be freed up.

kernel.oom.critical-mb=<uint64_t>

Default: 0x96

This option specifies the free memory threshold at which the kernel will signal a Critical memory pressure event, signaling that processes should free up memory.

kernel.oom.warning-mb=<uint64_t>

Default: 0x12c

This option specifies the free memory threshold at which the kernel will signal a Warning memory pressure event, signaling that processes should slow down memory allocations.

kernel.oom.debounce-mb=<uint64_t>

Default: 0x1

This option specifies the memory debounce value used when computing the memory pressure state based on the free memory thresholds (kernel.oom.outofmemory-mb, kernel.oom.critical-mb and kernel.oom.warning-mb). Transitions between memory availability states are debounced by not leaving a state until the amount of free memory is at least kernel.oom.debounce-mb outside of that state.

For example, consider the case where kernel.oom.critical-mb is set to 100 MB and kernel.oom.debounce-mb set to 5 MB. If we currently have 90 MB of free memory on the system, i.e. we're in the Critical state, free memory will have to increase to at least 105 MB (100 MB + 5 MB) for the state to change from Critical to Warning.

kernel.oom.evict-at-warning=<bool>

Default: false

If set to true, this option triggers kernel eviction of reclaimable memory at the Warning memory pressure state. If set to false, eviction is instead triggered at the Critical memory pressure state.

kernel.oom.evict-continuous=<bool>

Default: false

This option configures kernel eviction to run continually in the background to try and keep the system out of memory pressure, as opposed to triggering one-shot eviction only at memory pressure state transitions.

kernel.oom.hysteresis-seconds=<uint64_t>

Default: 0xa

This option specifies the hysteresis interval (in seconds) between memory pressure state transitions. Note that hysteresis is only applicable for transitions from a state with less free memory to a state with more free memory; transitions in the opposite direction are not delayed.

kernel.oom.imminent-oom-delta-mb=<uint64_t>

Default: 0xa

This option specifies the delta (in MB) above the out-of-memory threshold at which an imminent-out-of-memory event will be signaled. This signal is intended to be used for capturing diagnostic memory information close to the OOM, since capturing state exactly at the OOM might not be possible.

For example, if kernel.oom.outofmemory-mb is set to 50 and kernel.oom.imminent-oom-delta-mb is set to 20, an imminent-out-of-memory event will be signaled at 70MB (i.e. 50MB + 20MB) free memory, while out-of-memory will be signaled at 50MB free memory.

kernel.oom.trigger-on-alloc-failure=<bool>

Default: true

This option controls whether potentially user-visible PMM allocation failures due to running out of memory trigger an OOM response.

kernel.phys.next=<string>

Default: physboot

The name of the file within the kernel storage filesystem physload will load.

kernel.phys.verbose=<bool>

Default: true

This controls the degree of logging to the serial console in the kernel's early boot phase; if false, only error-related logging will take place.

One utility of this option is for benchmarking: synchronous, single-threaded UART writing can be relatively costly (10 chars/ms) to the entire time spent in physboot and it is desirable to exclude this sort of work from holistic time measurements.

kernel.phys.backtrace-max=<uint32_t>

Default: 0x40

When there is a crash in the kernel's early boot phase, it can print out backtraces on the serial console; it prints both a backtrace based on frame pointers and, when built to use shadow call stacks also a parallel backtrace based on the shadow call stack. Each backtrace will print no more than this many frames. (Most backtraces will end with the outermost frame before hitting the limit.) Setting the limit to zero prints unlimited frames, which for the frame-pointers backtrace can get into an infinite loop with some bugs.

kernel.phys.print-stack-max=<uint32_t>

Default: 0x400

When there is a crash in the kernel's early boot phase, it can print out stack contents on the serial console. This is the maximum size (in bytes) of stack memory that will be dumped; the actual amount dumped depends on stack depth. Each 16 bytes of stack is printed on one line using up to 75 characters.

kernel.ppb.borrow-in-supplypages=<bool>

Default: false

This controls whether zx_pager_supply_pages can borrow loaned pages. If true, zx_pager_supply_pages will copy supplied page contents into borrowed pages, if any loaned pages are available and the supplied pages aren't already loaned, else zx_pager_supply_pages will install the supplied pages into the VMO. If false, zx_pager_supply_pages will install the supplied pages into the VMO (regardless of whether they are already loaned or not).

kernel.ppb.borrow-on-mru=<bool>

Default: false

This controls whether non-loaned pages will be replaced with loaned pages (if any loaned pages are available) when non-loaned pages are moved to the MRU queue. This moving is done lazily under normal circumstances, but near OOM as eviction proceeds, any pages that should be in the MRU queue are moved to the MRU queue.

kernel.ppb.loan=<bool>

Default: false

This controls whether ZX_VMO_OP_DECOMMIT is enabled on a contiguous VMO. If true, decommit on a contiguous VMO can work and return ZX_OK. The pages are loaned to the rest of the system for potential borrowing. If false, decommit will return ZX_ERR_NOT_SUPPORTED.

kernel.ppb.replace-on-unloan=<bool>

Default: false

This controls what happens when a loaned page is re-committed to its original contiguous VMO. If false, the page is evicted from where it is loaned from, requiring that content to be faulted back in. If true, the contents are copied to a new page that is swapped in to replace the loaned page.

kernel.render-dlog-to-crashlog=<bool>

Default: false

When set to true, as much of the recent kernel debuglog as will fit will be appended to the generated crashlog during a kernel panic to assist in debugging.

kernel.serial=[none | legacy | qemu | <type>,<base>,<irq>]

Default: none

This controls what serial port is used. If provided, it overrides the serial port described by the system's bootdata. The kernel debug serial port is a reserved resource and may not be used outside of the kernel.

If set to “none”, the kernel debug serial port will be disabled and will not be reserved, allowing the default serial port to be used outside the kernel.

The configuration string format is as follows: For MMIO UART: “kernel.serial=UART_MODEL,MMIO_ADDR,IRQ,FLAGS” For PIO UART: “kernel.serial=UART_MODEL,IOPORT,IRQ”

kernel.vdso.always_use_next=<bool>

Default: false

If this option is set, the kernel will supply userspace with the “next” vDSO rather than the “stable” vDSO as the default vDSO.

vdso.ticks_get_force_syscall=<bool>

Default: false

If this option is set, the zx_ticks_get vDSO call will be forced to be a true syscall, even if the hardware cycle counter registers are accessible from user-mode.

vdso.clock_get_force_syscall=<bool>

Default: false

If this option is set, the zx_clock_get_monotonic and zx_clock_get_boot vDSO calls will be forced to be a true syscall, instead of simply performing a transformation of the tick counter in user-mode.

kernel.userpager.overtime_wait_seconds=<uint64_t>

Default: 0x14

This option configures how long a user pager fault may block before being considered overtime and printing an information message to the debuglog and continuing to wait. A value of 0 indicates a wait is never considered to be overtime.

kernel.userpager.overtime_timeout_seconds=<uint64_t>

Default: 0x12c

This option configures how long a user pager fault may block before being aborted. For a hardware page fault, the faulting thread will terminate with a fatal page fault exception. For a software page fault triggered by a syscall, the syscall will fail with ZX_ERR_TIMED_OUT. A value of 0 indicates a page fault is never aborted due to a time out.

kernel.heap-max-size-mb=<uint64_t>

Default: 0x800

This option configures the maximum size of the heap. Only has effect if kernel has been compiled to use a virtual heap.

kernel.heap.alloc_fill_threshold=<uint64_t>

Default: 0x0

When set, the kernel heap will fill allocations below this size (in bytes).

kernel.bufferchain.reserve-pages=<uint64_t>

Default: 0x20

Specifies the number of pages per CPU to reserve for buffer chain allocations (channel messages). Higher values reduce contention on the PMM when the system is under load at the cost of using more memory when the system is idle.

TODO(https://fxbug.dev/42147481): Determine an upper bound for this value to prevent consuming too much memory.

kernel.bypass-debuglog=<bool>

Default: false

When enabled, forces output to the console instead of buffering it. The reason we have both a compile switch and a cmdline parameter is to facilitate prints in the kernel before cmdline is parsed to be forced to go to the console. The compile switch setting overrides the cmdline parameter (if both are present). Note that both the compile switch and the cmdline parameter have the side effect of disabling irq driven uart Tx.

kernel.debug_uart_poll=<bool>

Default: false

If true, will periodically poll UART and forwards its contents into the console.

kernel.enable-debugging-syscalls=<bool>

Default: false

When disabled, certain debugging-related syscalls will fail with ZX_ERR_NOT_SUPPORTED. These are:

  • zx_debug_send_command()
  • zx_ktrace_control()
  • zx_ktrace_init()
  • zx_ktrace_read()
  • zx_ktrace_write()
  • zx_mtrace_control()
  • zx_object_get_property() with ZX_PROP_PROCESS_HW_TRACE_CONTEXT_ID
  • zx_process_write_memory()
  • zx_system_mexec()
  • zx_system_mexec_payload_get()
  • zx_thread_write_state() (When using the ZX_THREAD_STATE_DEBUG_REGS kind.)
  • zx_vmo_op_range() with ZX_VMO_OP_CACHE_INVALIDATE

kernel.enable-serial-syscalls=[false | true | output-only]

Default: false

When false, both zx_debug_read() and zx_debug_write() will fail with ZX_ERR_NOT_SUPPORTED.

When output-only, zx_debug_read() will fail with ZX_ERR_NOT_SUPPORTED, but zx_debug_write() will work normally.

When true, both will work normally.

kernel.entropy-test.src=[hw_rng | jitterentropy]

Default: hw_rng

When running an entropy collector quality test, use the provided entropy source. This option is ignored unless the kernel was built with ENABLE_ENTROPY_COLLECTOR_TEST=1.

kernel.entropy-test.len=<uint64_t>

Default: 0x100000

When running an entropy collector quality test, collect the provided number of bytes.

The maximum value can be increased by defining ENTROPY_COLLECTOR_TEST_MAXLEN as such value.

kernel.force-watchdog-disabled=<bool>

Default: false

When set, the system will attempt to disable any hardware watchdog timer armed and passed by the bootloader as soon as it possibly can in the boot sequence, presuming that the bootloader provides enough information to know how to disable the WDT at all.

kernel.halt-on-panic=<bool>

Default: false

If this option is set, the system will halt on a kernel panic instead of rebooting. To enable halt-on-panic, pass the kernel command line argument kernel.halt-on-panic=true.

Since the kernel can't reliably draw to a framebuffer when the GPU is enabled, the system will reboot by default if the kernel crashes or panics.

If the kernel crashes and the system reboots, the log from the kernel panic will appear at /boot/log/last-panic.txt, suitable for viewing, downloading, etc.

Please attach your last-panic.txt and zircon.elf files to any kernel panic bugs you file.

If there's a last-panic.txt, that indicates that this is the first successful boot since a kernel panic occurred.

It is not “sticky” -- if you reboot cleanly, it will be gone, and if you crash again it will be replaced.

ktrace.bufsize=<uint32_t>

Default: 0x20

This option specifies the number of megabytes allocated for ktrace records.

ktrace.grpmask=<uint32_t>

Default: 0x0

This option specifies what ktrace records are emitted. The value is a bitmask of KTRACE_GRP_* values from zircon/ktrace.h. Hex values may be specified as 0xNNN.

kernel.memory-limit-dbg=<bool>

Default: true

This option enables verbose logging from the memory limit library.

kernel.memory-limit-mb=<uint64_t>

Default: 0x0

This option sets an upper-bound in megabytes for the system memory. If set to zero, then no upper-bound is set.

For example, choosing a low enough value would allow a user simulating a system with less physical memory than it actually has.

kernel.page-scanner.enable-eviction=<bool>

Default: true

When set, allows the kernel to free up reclaimable memory, by evicting file pages and unlocked discardable VMOs, or by performing page compressions. Reclamation can reduce memory usage and prevent out of memory scenarios, but removes some timing predictability from system behavior.

kernel.page-scanner.page-table-eviction-policy=[always | never | on_request]

Default: always

Sets the reclamation policy for user page tables that are not accessed.

When on_request, only performs eviction on request, such as in response to a low memory scenario.

When never, page tables are never evicted.

When always, Unused page tables are evicted periodically. The period can be controlled by kernel.page-scanner.page-table-eviction-period.

kernel.page-scanner.page-table-eviction-period-ms=<uint32_t>

Default: 0x2710

Sets the rate, in milliseconds, that page tables will be scanned. Any page tables not used between two successive scans are candidates for eviction.

This option only has an effect if kernel.page-scanner.page-table-eviction-policy=always.

kernel.page-scanner.min-aging-interval-ms=<uint32_t>

Default: 0x7d0

Sets the minimum time, in milliseconds, between successive aging events. Higher values here will provide a more stable active set with less chance of thrashing like behavior and less time spent harvesting page access information. Lower values will allow for smaller active sets, increasing opportunities for reclamation.

This value should be less than or equal to kernel.page-scanner.max-aging-interval-ms.

kernel.page-scanner.max-aging-interval-ms=<uint32_t>

Default: 0x3a98

Sets the maximum time, in milliseconds, between successive aging events. This time is the potential worst case coarseness of page age information, and higher values can result in not having sufficient age information to perform reclamation if system behavior rapidly changes. Lower values will cause pages to lose fidelity information by accumulating in the oldest bucket increasing the chance that when reclamation happens a sub-optimal page is chosen.

This value should be greater than or equal to kernel.page-scanner.min-aging-interval-ms.

kernel.page-scanner.accessed-scan-interval-ms=<uint32_t>

Default: 0xbb8

Sets the time, in milliseconds, between harvesting page access information. Lower values provide greater age fidelity and will improve accuracy of page reclamation choices at the expense of increased CPU time spent harvesting.

There is no benefit to setting this to be lower than the kernel.page-scanner.min-aging-interval-ms.

kernel.page-scanner.active-ratio-multiplier=<uint32_t>

Default: 0x2

Controls the allowable ratio of active pages, compared to inactive pages, before aging is triggered. The ratio is represented as a multiplier to simplify the kernel algorithm which is should_age = active_page_count * active_ratio_multiplier > inactive_page_count. Higher multipliers will result in more frequent aging events and hence less pages being in the active set. A multiplier of 0 will disable aging based on the active page ratio.

The active ratio only triggers aging in the period between the kernel.page-scanner.min-aging-interval-ms and the kernel.page-scanner.max-aging-interval-ms, and as such has no effect if the intervals are equal.

kernel.page-scanner.start-at-boot=<bool>

Default: true

This option causes the kernels active memory scanner to be initially enabled on startup. You can also enable and disable it using the kernel console. If you disable the scanner, you can have additional system predictability since it removes time based and background memory reclamation.

Every action the scanner performs can be individually configured and disabled. If all actions are disabled then enabling the scanner has no effect.

kernel.page-scanner.zero-page-scans-per-second=<uint64_t>

Default: 0x4e20

This option configures the maximal number of candidate pages the zero page scanner will consider every second.

Setting to zero means no zero page scanning will occur. This can provide additional system predictability for benchmarking or other workloads.

The page scanner must be running for this option to have any effect. It can be enabled at boot with the kernel.page-scanner.start-at-boot option.

This value was chosen to consume, in the worst case, 5% CPU on a lower-end arm device. Individual configurations may wish to tune this higher (or lower) as needed.

kernel.page-scanner.lru-action=[none | evict_only | compress_only | evict_and_compress]

Default: none

Sets any reclamation action to take on old pages in the LRU queue. These actions occur regardless of memory pressure. If the none action is specified then pages will not be reclaimed just because they are old.

Supported actions are:

  • none
  • evict_only
  • compress_only
  • evict_and_compress

kernel.compression.random-debug-compress=<bool>

Default: false

Enables a testing option that causes the VM to random immediately compress pages, regardless of their age. This is intended to facilitate testing of the compression paths without needing to wait for pages to age and put the system into a low memory state. It is an error to enable this option if the kernel is not built with debugging assertions enabled, or if a compression and storage strategy are not set.

kernel.compression.strategy=[none | lz4]

Default: none

Supported compression strategies are:

  • none
  • lz4

This option selects the desired compression strategy to be used when a page needs to be compressed. If none is set then kernel.compression.storage-strategy must also be none. Selecting none effectively disables compression.

kernel.compression.storage-strategy=[none | tri_page]

Default: none

Supported compression storage strategies are:

  • none
  • tri_page

This option selects the desired storage strategy to be used for storing data that has been compressed. If none is set then kernel.compression.strategy must also be none.

kernel.compression.threshold=<uint32_t>

Default: 0x46

This option controls the compression threshold that must be achieved for a compressed page to be stored. Pages that do not achieve this threshold will continue to be stored uncompressed instead.

The option is a percentage, with a value of 100 meaning a page just needs to compress to at least its original size, and a value of 0 meaning that page would need to compress to a zero size.

Valid values are between 1 and 100, inclusive.

kernel.compression.lz4.acceleration=<uint32_t>

Default: 0xb

This option controls the acceleration factor provided to the LZ4 compression implementation. Refer to the current LZ4 implementation for how this value will be interpreted.

kernel.compression.at_memory_pressure=<bool>

Default: false

This option controls whether page compression should be performed in response to memory pressure.

For this option to have any effect kernel.page-scanner.enable-eviction needs to be enabled and both kernel.compression.strategy and kernel.compression.storage-strategy need to be set.

kernel.compression.reclaim_anonymous=<bool>

Default: false

This option controls whether anonymous pages are placed in the reclaimable page queues and have associated age information. Enabling this adds a small overhead to anonymous pages for age tracking, but is required for options like “kernel.compression.at_memory_pressure” to have any effect.

kernel.compression.reclaim_zero_forks=<bool>

Default: false

This option is similar to “kernel.compression.reclaim_anonymous” but applies to the zero forks of anonymous pages. Enabling this makes the “kernel.page-scanner.zero-page-scans-per-second” option have no effect, and it is an error to enable this without enabling “kernel.compression.reclaim_anonymous”.

kernel.pmm-checker.action=[oops | panic]

Default: oops

This option specifies which action is taken when the PMM checker detects corruption. Values must be one of:

  • oops
    • A non-fatal kernel OOPS will be emitted when corruption is detected.
  • panic
    • A fatal kernel panic will occur when corruption is detected.

kernel.pmm-checker.enable=[true | false | auto]

Default: false

This controls whether the PMM's use-after-free checker is enabled. The PMM checker can be expensive and is intended for use in debug and development builds. Values must be one of:

  • true
    • Checker is always enabled.
  • false
    • Checker is never enabled.
  • auto
    • Kernel makes a decision to enable checker based on the environment and its performance characteristics. Running under a hypervisor is one factor taken into consideration. See also “k pmm checker”.

kernel.pmm-checker.fill-size=<uint64_t>

Default: 0x1000

This option specifies how many bytes of each free page is filled or checked when the PMM's use-after-free checker is enabled. Valid values are multiples of 8, between 8 and PAGE_SIZE, inclusive.

kernel.pmm.alloc-random-should-wait=<bool>

Default: false

Enables a testing option that causes the PMM to randomly fail wait-able page allocations with ZX_ERR_SHOULD_WAIT, regardless of the current memory level. This is intended to facilitate testing of the waiting paths without needing to put the system into a low memory state. It is an error to enable this option if the kernel is not built with debugging assertions enabled.

kernel.portobserver.reserve-pages=<uint64_t>

Default: 0x8

Specifies the number of pages per CPU to reserve for port observer (async wait) allocations. Higher values reduce contention on the PMM when the system is under load at the cost of using more memory when the system is idle.

kernel.portpacket.reserve-pages=<uint64_t>

Default: 0x1

Specifies the number of pages per CPU to reserve for port packet (port_queue) allocations. Higher values reduce contention on the PMM when the system is under load at the cost of using more memory when the system is idle.

kernel.root-job.behavior=[halt | reboot | bootloader | recovery | shutdown]

Default: reboot

This option specifies what action the kernel should take when the root job is either terminated, or has no jobs and no processes.

When halt, will halt the system.

When reboot, will reboot the system.

When bootloader, will reboot the system into the bootloader.

When recovery, will reboot the system into the recovery partition.

When shutdown, will shutdown the system.

kernel.root-job.notice=<string>

The option allows a notice to be printed when the root job is either terminated, or has no jobs and no processes.

kernel.shell=<bool>

Default: false

Tells the kernel to start its own shell on the kernel console instead of starting userspace.

kernel.shell.script=<string>

Tells the kernel to run a canned script of kernel.shell commands. If kernel.shell is also specified, the kernel shell command prompt comes after the script completes unless the script shuts down the system. Since whitespace on the kernel command line separates different boot options, + characters in the script are replaced with spaces to allow for commands with arguments, and ; characters can separate commands in the script.

kernel.smp.ht=<bool>

Default: true

This option specifies whether the HyperThreading (HT) logical CPUs should be enabled or not.

kernel.test.ram.reserve=<std::optional>

Specifies a range of physical RAM to be reserved for testing purposes. This should be written as just SIZE (an integer byte quantity, which should be page-aligned) but will be read back as SIZE,ADDRESS after the kernel assigns an address in early boot.

kernel.port.max-observers=<uint64_t>

Default: 0xc350

Specifies the maximum number of observers any single port may have. When this limit is reached, a Zircon exception is raised in the process that crosses the limit. This value should be high enough that well behaved programs will not hit the limit, but low enough to terminate misbehaving programs before they impact the system.

kernel.select=<string>

Default: zircon

The name of the kernel package to boot from the STORAGE_KERNEL item in the ZBI.

kernel.scheduler.prefer-little-cpus=<bool>

Default: false

When searching for a CPU on which to place a task, prefer little cores over big cores. Enabling this option trades off improved performance in favor of reduced power consumption.

DEPRECATED - This option is scheduled to be removed in an upcoming release. Do not take any critical dependencies on it.

kernel.ubsan.action=[oops | panic]

Default: panic

When the kernel is instrumented with UndefinedBehaviorSanitizer, problems it detects are reported on the serial console. These can be fatal or not. Values must be one of:

  • oops
    • Detected undefined behavior causes a non-fatal kernel OOPS.
  • panic
    • Detected undefined behavior causes a fatal kernel panic.

Options available only on arm64 machines

kernel.arm64.disable_spec_mitigations=<bool>

Default: false

If set, disables all speculative execution information leak mitigations.

If unset, the per-mitigation defaults will be used.

kernel.arm64.event-stream.enable=<bool>

Default: true

When enabled, each ARM cpu will enable an event stream generator, which per-cpu sets the hidden event flag at a particular rate. This has the effect of kicking cpus out of any WFE states they may be sitting in.

kernel.arm64.event-stream.freq-hz=<uint32_t>

Default: 0x2710

If the event stream is enabled, specifies the frequency at which it will attempt to run. The resolution is limited, so the driver will only be able to pick the nearest power of 2 from the cpu timer counter.

kernel.arm64.debug.dap-rom-soc=<string>

If set, tries to initialize the dap debug aperture at a hard coded address for the particular system on chip. Currently accepted values are amlogic-t931g, amlogic-s905d2, amlogic-s905d3g, and amlogic-a311d.

kernel.smp.maxcpus=<uint32_t>

Default: 0x10

This option caps the number of CPUs to initialize. It cannot be greater than SMP_MAX_CPUS for a specific architecture.

Note: The default value may vary for each architecture.

kernel.phys.psci-reset=[disabled | shutdown | reboot | reboot-bootloader | reboot-recovery]

Default: reboot

This option determines what kind of PSCI reset operation (if any) the early boot kernel will use if it needs to panic and crash. If this is “disabled”, the machine may enter an infinite loop on panic.

kernel.arm64.phys.mmu=<bool>

Default: true

This enables use of the MMU and caches during the kernel's early boot phase.

kernel.arm64.enable-asid=<bool>

Default: true

This enables use of ASIDs. True by default if the underlying hardware supports 16-bit ASIDs.

kernel.arm64.alternate-vbar=[none | auto | arch3 | arch1 | psci | smccc10]

Default: auto

This selects the alternate exception vector implementation used to work around CPU-specific issues on entry to EL1 from EL0. Values can be:

  • none - No mitigations performed in early EL0 exception paths.
  • auto (default) - Select SMCCC function identifier based on availability reported by firmware via SMCCC / PSCI interfaces. Then each individual CPU queries the firmware for whether the workaround is needed at all. If the firmware is not SMCCC >= 1.1 that reports it supports the SMCCC_ARCH_WORKAROUND_3 and/or SMCCC_ARCH_WORKAROUND_1 function identifiers, then this has the same effect as none. If the firmware does support it, then each CPU either uses the firmware workaround or not, according to what the firmware says is needed on that CPU. Either way, alternative spectre mitigations, that are either redundant with the firmware workaround or not needed if the firmware workaround is not needed, are disabled.
  • arch3 - Always use SMCCC_ARCH_WORKAROUND_3 on every CPU. This may have unpredictable effects if the firmware does not support SMCCC 1.1 or does not support SMCCC_ARCH_WORKAROUND_3. This makes every CPU do what auto will select for each individual CPU that the firmware says should use it, when the firmware supports the function. This also disables alternative spectre mitigations that are redundant with SMCCC_ARCH_WORKAROUND_3.
  • arch1 - Always use SMCCC_ARCH_WORKAROUND_1 on every CPU. This may have unpredictable effects if the firmware does not support SMCCC 1.1 or does not support SMCCC_ARCH_WORKAROUND_1. This makes every CPU do what auto will select for each individual CPU that the firmware says should use it, when the firmware supports the “1” function but not the “3” function. This also disables alternative spectre mitigations that are redundant with SMCCC_ARCH_WORKAROUND_1.
  • psci - Always use PSCI_VERSION with SMCCC 1.1 calling conventions, on every CPU. This may have unpredictable effects if the firmware does not support SMCCC 1.1. Currently auto never selects this behavior for any CPU.
  • smccc10 - Always use PSCI_VERSION with SMCCC 1.0 calling conventions, on every CPU. This is safe on all systems, though has it more overhead than SMCCC 1.1 options and may not be necessary on all CPUs. Currently auto never selects this behavior for any CPU. As on SoCs with heterogeneous cores, a different selection should be made for each individual CPU, values other than auto should only be used in testing.

kernel.arm64.force-pct=<bool>

Default: false

By default, the kernel will select the ARM virtual counter (VCT) to use as the time reference for the system. It will only choose the physical counter (PCT) if it was given an IRQ for the physical timer hardware, but not the virtual timer hardware. When the force-pct option is set, the kernel will always choose to use the PCT as the time reference, even if a VCT IRQ is offered in the ZBI. Please note, setting force-pct on a target which has no defined PCT IRQ will result in a panic during early boot.

Options available only on riscv64 machines

kernel.smp.maxcpus=<uint32_t>

Default: 0x10

This option caps the number of CPUs to initialize. It cannot be greater than SMP_MAX_CPUS for a specific architecture.

Note: The default value may vary for each architecture.

kernel.riscv64.enable-asid=<bool>

Default: true

This enables use of ASIDs. True by default if the underlying hardware supports 16-bit ASIDs.

kernel.riscv64.phys.mmu=<bool>

Default: true

This enables use of the MMU in the kernel's early boot phase.

Options available only on x86 machines

kernel.x86.disable_spec_mitigations=<bool>

Default: false

If set, disables all speculative execution information leak mitigations.

If unset, the per-mitigation defaults will be used.

kernel.x86.hwp=<bool>

Default: true

This settings enables HWP (hardware P-states) on supported chips. This feature lets Intel CPUs automatically scale their own clock speed.

kernel.x86.hwp_policy=[bios-specified | performance | balanced | power-save | stable-performance]

Default: bios-specified

Set a power/performance tradeoff policy of the CPU. x86 CPUs with HWP (hardware P-state) support can be configured to autonomusly scale their frequency to favour different policies.

Currently supported policies are:

  • bios-specified: Use the power/performance tradeoff policy specified in firmware/BIOS settings. If no policy is available, falls back to balanced.
  • performance: Maximise performance.
  • balanced: Balance performance / power savings.
  • power-save: Reduce power usage, at the cost of lower performance.
  • stable-performance: Use settings that keep system performance consistent. This may be useful for benchmarking, for example, where keeping performance predictable is more important than maximising performance.

kernel.x86.md_clear_on_user_return=<bool>

Default: true

MDS (Microarchitectural Data Sampling) is a family of speculative execution information leak bugs that allow the contents of recent loads or stores to be inferred by hostile code, regardless of privilege level (CVE-2019-11091, CVE-2018-12126, CVE-2018-12130, CVE-2018-12127). For example, this could allow user code to read recent kernel loads/stores.

To avoid this bug, it is required that all microarchitectural structures that could leak data be flushed on trust level transitions. Also, it is important that trust levels do not concurrently execute on a single physical processor core.

This option controls whether microarchitectual structures are flushed on the kernel to user exit path, if possible. It may have a negative performance impact.

  • If set to true (the default), structures are flushed if the processor is vulnerable.
  • If set to false, no flush is executed on structures.

kernel.x86.spec_store_bypass_disable=<bool>

Default: false

Spec-store-bypass (Spectre V4) is a speculative execution information leak vulnerability that affects many Intel and AMD x86 CPUs. It targets memory disambiguation hardware to infer the contents of recent stores. The attack only affects same-privilege-level, intra-process data.

This command line option controls whether a mitigation is enabled. The mitigation has negative performance impacts.

  • If true, the mitigation is enabled on CPUs that need it.
  • If false (the default), the mitigation is not enabled.

kernel.x86.turbo=<bool>

Default: true

Turbo Boost or Core Performance Boost are mechanisms that allow processors to dynamically vary their performance at runtime based on available thermal and electrical budget. This may provide improved interactive performance at the cost of performance variability. Some workloads may benefit from disabling Turbo; if this command line flag is set to false, turbo is disabled for all CPUs in the system.

kernel.x86.enable_pcid=<bool>

Default: true

This option controls whether PCIDs are used, if there is sufficient CPU support. If this option is enabled and there is not sufficient CPU support, then this option has no effect.

kernel.smp.maxcpus=<uint32_t>

Default: 0x20

This option caps the number of CPUs to initialize. It cannot be greater than SMP_MAX_CPUS for a specific architecture.

Note: The default value may vary for each architecture.

kernel.wallclock=[auto | tsc | pit | hpet]

Default: auto

This option can be used to force the selection of a particular wall clock on pc builds.

{# DO NOT EDIT THIS FILE DIRECTLY #} {# Instead see the top of the file for instructions. #}