| # 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. | |
| These defaults should generally not be used, and need to be tuned specifically | |
| for each CPU as per go/fuchsia-per-device:jitter. | |
| ### 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. | |
| These defaults should generally not be used, and need to be tuned specifically | |
| for each CPU as per go/fuchsia-per-device:jitter. | |
| ### 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. | |
| These defaults should generally not be used, and need to be tuned specifically | |
| for each CPU as per go/fuchsia-per-device:jitter. | |
| ### 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. | |
| These defaults should generally not be used, and need to be tuned specifically | |
| for each CPU as per go/fuchsia-per-device:jitter. | |
| ### 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.jitterentropy.entropy_per_1000_bytes=\<uint32_t> | |
| **Default:** `0x32` | |
| Sets the "entropy per 1000 bytes" parameter for jitterentropy. This is an | |
| estimate of how many bits of entropy are collected for every 1000 bytes of | |
| output from the collector. | |
| With default parameters (bs=64, bc=512, ml=32, ll=1, raw=true), each byte | |
| of data contributes approximately 0.5 bit of entropy on astro. A safety | |
| factor of 0.1 gives us 0.5 * 0.1 * 1000 = 50 bits of entropy for 1000 | |
| bytes of data. | |
| These defaults should generally not be used, and need to be tuned specifically | |
| for each CPU as per go/fuchsia-per-device:jitter. | |
| ### 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](/zircon/kernel/lib/lockup_detector/README.md). | |
| 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](/zircon/kernel/lib/lockup_detector/README.md). | |
| 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](/zircon/kernel/lib/lockup_detector/README.md). | |
| 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](/zircon/kernel/lib/lockup_detector/README.md). | |
| 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](/zircon/kernel/lib/lockup_detector/README.md). | |
| 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.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.eviction-delay-ms=\<uint64_t> | |
| **Default:** `0x1388` | |
| This option specifies the duration (in milliseconds) by which the kernel delays eviction when | |
| eviction is required by a change in memory pressure state. This delay allows userspace components | |
| responding to memory pressure to reclaim memory first, avoiding thrash due to interference with | |
| kernel eviction. | |
| ### kernel.oom.evict-with-min-target=\<bool> | |
| **Default:** `true` | |
| This option specifies whether the kernel should also evict a minimum amount of memory along with | |
| trying to meet the target free memory goal. If userspace also frees memory in response to memory | |
| pressure, this ensures some fairness by having kernel eviction share the load. | |
| ### kernel.oom.eviction-delta-at-oom-mb=\<uint64_t> | |
| **Default:** `0xa` | |
| This option specifies the granularity (in MB) at which the kernel will try to synchronously evict | |
| memory to avoid entering the out-of-memory state. Note that this value is independent of the | |
| kernel.oom.evict-with-min-target, and they do not influence each other. | |
| ### 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. | |
| Setting this value to 0 will disable the imminent-out-of-memory event. | |
| ### 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.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-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:** _from ZBI item_ | |
| This controls what serial port is used. 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. | |
| If there is no explicit setting of this option, then an equivalent value is | |
| derived from the last ZBI item of type `ZBI_TYPE_KERNEL_DRIVER` with one of the | |
| `ZBI_KERNEL_DRIVER_*_UART` subtypes, either one provided in the original ZBI or | |
| one appended by the boot loader (or boot shim). An explicit boot option always | |
| overrides the ZBI item, even `none`. (The order of `ZBI_TYPE_CMDLINE` items | |
| with respect to `ZBI_TYPE_KERNEL_DRIVER` items does not matter.) | |
| 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` | |
| * For the default used in common QEMU virtual machines on this architecture: | |
| - `qemu` | |
| * For the traditional `COM1` setting on x86: | |
| - `legacy` | |
| ### 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.userpager.overtime_printout_limit=\<uint32_t> | |
| **Default:** `0x4` | |
| This options configures the maximum number of outstanding requests to emit to the debuglog when | |
| reporting an overtime condition. If there are a large number of outstanding requests, the details of | |
| all of them may not be useful, and can overload the debuglog. | |
| ### kernel.heap.enable-virtual=\<bool> | |
| **Default:** `false` | |
| If set to true, enables the use of a virtually managed kernel heap instead of one managed directly | |
| out of the physmap. The virtual heap may have some performance and memory usage overheads, but will | |
| not exhaust due to fragmentation. | |
| ### 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 zero-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_mtrace_control()` | |
| * `zx_object_get_property()` with `ZX_PROP_PROCESS_HW_TRACE_CONTEXT_ID` | |
| * `zx_process_write_memory()` | |
| * `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`. | |
| This option is ignored (i.e. the system will reboot) if the kernel panics while | |
| usermode has suspended the kernel's access to the debug serial port (see | |
| `zx_debug_suspend`), since the panic shell would be unreachable. | |
| 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 `vmzircon` 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 | slot\] | |
| **Default:** `none` | |
| Supported compression storage strategies are: | |
| - `none` | |
| - `slot` | |
| 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=\[auto | \<uint64>\] | |
| **Default:** `auto` | |
| 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. The default "auto" value represents PAGE_SIZE. | |
| ### 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.stack.canary-percent-free=\<uint64_t> | |
| **Default:** `0x0` | |
| This controls the offset at which a canary will be placed on the kernel stacks. If the canary is | |
| corrupted this indicates that the stack reached at least that depth during usage, and this can be | |
| used as an early warning for stack usage nearing the limit. The offset is defined using a | |
| percentage to account for the variability of kernel stack sizes. e.g. a value of 0 will place the | |
| canary at the very end of the stack, meaning it will get corrupted at the same time as the stack | |
| overflows. | |
| Canary detection is performed on stack free, i.e. thread termination, and will generate a kernel | |
| OOPS if the canary is corrupted. | |
| ### 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=\<stdbind::optional<RamReservation>> | |
| 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.select.userboot=\<string> | |
| **Default:** `userboot` | |
| Program to run in the first (and only) user process the kernel creates: an ELF | |
| static PIE file inside the package chosen by `kernel.select`. The first user | |
| process starts with a handle to a channel on which it receives a single message | |
| containing initial handles holding all the privileged and essential | |
| capabilities for the initial process itself and for the system. | |
| ### 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.scheduler.enable-new-wakeup-accounting=\<bool> | |
| **Default:** `false` | |
| This option disables emulation of the previous scheduling behavior that makes a | |
| newly woken thread less likely to preempt a currently running thread. While the | |
| previous behavior is less fair to newly woken threads than the improved | |
| behavior, emulating the previous behavior reduces the likelihood of certain | |
| types of latent race conditions causing problems in the system. These race | |
| conditions need to be fixed before fully adopting the improved wakeup behavior | |
| on all products. | |
| TODO(https://fxbug.dev/322207536): Stop resetting start and finish times when | |
| unblocking once we solve races higher in the stack. | |
| ### kernel.scheduler.fair-demand-weighted-decay=\<bool\> | |
| **Default:** `true` | |
| When enabled, the per-thread estimate of a fair thread's runtime that feeds the | |
| scheduler's variable bandwidth demand decays in proportion to the length of each | |
| sample. A sample closed by a brief run before blocking (for example one leg of an | |
| IPC round trip) then lowers the estimate only slightly, while a sample that | |
| spans a full time slice decays it at the full rate. Increases in the estimate | |
| are unaffected. | |
| When disabled, every sample decays the estimate at the full rate regardless of | |
| its length, so a thread alternating brief runs and blocks can lose its estimate | |
| within a few milliseconds. | |
| TODO(https://fxbug.dev/448195120): Remove the option once the default has | |
| baked. | |
| ### kernel.scheduler.variable-demand-placement=\<bool\> | |
| **Default:** `false` | |
| When enabled, the scheduler accounts for the estimated (variable) bandwidth | |
| demand of fair threads, in addition to the declared (constant) bandwidth demand | |
| of deadline threads, when selecting a CPU for a waking or migrating thread. A | |
| fair thread whose estimated demand cannot be supplied by a candidate CPU at its | |
| maximum processing rate is placed elsewhere when a feasible candidate exists. | |
| When disabled, only constant bandwidth demand is considered and fair placement | |
| falls back to `kernel.scheduler.fair-placement-affinity` (`idle` by default), | |
| which prefers an idle CPU over a busy CPU in the thread's last cluster. | |
| TODO(https://fxbug.dev/448195120): Enable by default once synchronous | |
| hand-offs and producer/consumer pairs on homogeneous cores keep their | |
| co-location (perfcompare regressions on x64 and VIM3 otherwise). | |
| ### kernel.scheduler.variable-demand-migration=\<bool\> | |
| **Default:** `false` | |
| When enabled, together with kernel.scheduler.variable-demand-placement, a fair | |
| thread that keeps exhausting its time slice on a CPU whose capacity is saturated | |
| is periodically re-placed as if it demanded more than that CPU can supply at its | |
| maximum processing rate. If another CPU with a higher maximum processing rate | |
| can accommodate it, the thread migrates there. This moves CPU-bound work off | |
| small cores on heterogeneous systems without requiring affinity configuration. | |
| Has no effect on systems with a single power domain, or when | |
| kernel.scheduler.variable-demand-placement is disabled. | |
| TODO(https://fxbug.dev/448195120): Enable by default together with | |
| kernel.scheduler.variable-demand-placement. | |
| ### kernel.scheduler.variable-demand-reservation=\<bool\> | |
| **Default:** `false` | |
| When enabled, together with kernel.power.rppm, the estimated (variable) bandwidth | |
| demand of a fair thread remains reserved on the CPU it blocked on for one fair | |
| period after it blocks, instead of being withdrawn immediately. A thread that | |
| runs periodically therefore finds the CPU's processing rate still provisioned | |
| for it when its next job begins, rather than having the rate drop between jobs | |
| and ramp again after it wakes. A reservation is withdrawn when the thread wakes | |
| on the same CPU, where its demand is counted again directly; one left on a | |
| different CPU expires on its own. | |
| When disabled, variable demand is withdrawn as soon as the thread blocks. | |
| TODO(https://fxbug.dev/448195120): Enable by default once the reservation is | |
| retuned. With kernel.scheduler.fair-demand-weighted-decay the reserved | |
| estimates are larger and longer-lived, and on a heterogeneous device the | |
| reservations held about 25 units of demand on each idle mid/big CPU, raising | |
| the processing rate request by about 13% while idle. | |
| ### kernel.scheduler.pi-target-eligibility=\<bool\> | |
| **Default:** `true` | |
| When enabled, priority inheritance keeps the thread it boosts (the target, e.g. | |
| a lock holder) eligible to run: | |
| * A deadline target joined by a deadline thread keeps at least its own | |
| remaining time slice, bounded by the time until the combined deadline and | |
| the combined capacity. Without this, a target that has consumed more of its | |
| capacity than its share of the shorter inherited window allows is issued a | |
| zero time slice, exhausts immediately, and is ineligible until the deadline | |
| of the very thread waiting on it. The preserved slice is granted in addition | |
| to what lag conservation allows (by at most the target's old remaining time | |
| slice) and is reported by the scheduler.pi.join-slice-preserved counters. | |
| * A fair target whose start time is in the future (it exhausted its previous | |
| activation) starts a new activation immediately when it gains inherited | |
| weight, rather than remaining ineligible for the rest of its period while | |
| the fair thread that boosted it waits. | |
| * A target that becomes fair again, by shedding an inherited deadline or by | |
| a base profile change, starts a new fair activation immediately instead of | |
| running out its stale deadline activation. (A target that becomes deadline | |
| always starts a new deadline activation, carrying over the consumed | |
| fraction of its fair time slice; that is not gated by this option.) | |
| When disabled, the time slice of a deadline target is composed strictly by the | |
| lag equation and clamped at zero, and fair activations are left as they are. | |
| TODO(https://fxbug.dev/573204130): Remove the option once the default has | |
| baked. | |
| ### kernel.scheduler.fair-placement-affinity=\[cluster | idle | headroom | queue-time\] | |
| **Default:** `queue-time` | |
| When a fair thread wakes or migrates, candidate CPUs that can supply its | |
| estimated demand about equally well are ordered by a secondary policy. This | |
| option selects how the thread's last cluster (cache affinity) is weighed against | |
| CPUs that are available right now: | |
| * `cluster`: prefer the last cluster, then an idle CPU, then the lowest power | |
| cost. A busy CPU in the last cluster is preferred over an idle CPU elsewhere, | |
| which keeps cache affinity but leaves a thread whose demand is not yet | |
| known waiting behind other work in a small cluster (measured as a ~20 ms | |
| cold-start regression on a heterogeneous device). | |
| * `idle` (default): prefer an idle CPU, then the last cluster, then the lowest power | |
| cost. Any idle CPU is preferred over a busy CPU in the last cluster, | |
| including an idle CPU of a slower class. On a device whose big cores | |
| greatly outnumber its little cores this spreads waking threads to free | |
| capacity at the cost of occasionally running a thread on a little core; | |
| refusing the slower class instead was measured to be far worse on a device | |
| with a single top-class core, because it keeps work queued on that core. | |
| * `queue-time`: order candidates by their estimated queue time | |
| (the runtime estimates of their runnable fair threads, at the CPU's | |
| processing rate). Within the last cluster the least-loaded CPU wins, an | |
| idle CPU having no queue time; a CPU in another cluster is chosen only | |
| when the one the thread would otherwise take has more than 250us queued, | |
| and the search stops at the first CPU with 25us or less. This is the | |
| ordering in use before share-based placement; measured on a heterogeneous | |
| device, replacing it with the policies above cost a large messaging app | |
| about 20 ms of cold-start time that `idle` only partly recovered. | |
| * `headroom`: prefer an available CPU, then the last cluster, then an idle CPU, | |
| then the lowest power cost. A CPU is available if it is idle or if its | |
| projected fair headroom for the thread covers the thread's estimated demand | |
| (at least a tenth of a CPU when the demand is not yet known). Measured on a | |
| heterogeneous device, this keeps too many waking threads on busy CPUs in | |
| their cluster (about 20% fewer migrations to idle CPUs) and costs about | |
| 17 ms on cold app launches against `idle`, whether or not the thread's | |
| demand is known. | |
| The remaining tie-breaks (projected headroom, weight entitlement, deadline load) | |
| are the same under `cluster`, `idle` and `headroom`; `queue-time` uses the | |
| deadline load as its only further tie-break. Deadline threads are not affected. | |
| TODO(https://fxbug.dev/448195120): Remove once a policy is chosen. | |
| ### kernel.scheduler.deadline-wake-affinity=\<bool> | |
| **Default:** `false` | |
| When enabled, a waking deadline thread stays on its last CPU when that CPU can | |
| admit it and has no other runnable deadline work, even if another CPU is idle. | |
| A deadline thread preempts fair work immediately, so moving it from a CPU | |
| running only fair threads to an idle CPU trades cache affinity and an IPI for | |
| no earlier execution. | |
| When disabled, an idle CPU is preferred. | |
| TODO(https://fxbug.dev/448195120): Remove once enabled by default. | |
| ### 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. | |
| ### kernel.debug.boot-spin=\<bool> | |
| **Default:** `false` | |
| _**NOTE:** This is only meant for kernel debugging and is not available in | |
| production kernel builds. In a kernel compiled without assertions and other | |
| debugging features, the option will have no effect._ | |
| When set, some of the first code in the kernel proper (after physboot hands off) | |
| will be to spin as long as a certain global variable is zero. The variable must | |
| be set from the debugger attached to the kernel (e.g. via QEMU's -s) for boot to | |
| continue. This makes it easy to let the virtual boot CPU run through the boot | |
| loader and early boot code with the debugger attached and then interrupt the | |
| spin interactively in the debugger to set breakpoints or step through boot code. | |
| ## 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. | |
| ### kernel.arm64.pci=\<bool> | |
| **Default:** `true` | |
| Enables kernel mode PCI support and kernel PCI syscalls. | |
| ### kernel.arm64.smccc-qcom=\<bool> | |
| **Default:** `false` | |
| Enables kernel assisted Yielding SMCCC calls that conform to QCOM's protocol. | |
| The kernel will automatically resume preempted SMCCC Yielding calls on behalf of the caller. | |
| ### kernel.arm-smmu-mode=\<string> | |
| **Default:** `disabled` | |
| This option determines how the kernel handles SMMU instances that it is told | |
| about via ZBI parameters at boot time. The format is a comma-separated list | |
| starting with the default mode, and having zero or more `<base-address>=<mode>` | |
| segments following it which may be used to override the default mode for specific | |
| SMMU instances as identified by the base physical address of the SMMU's registers. | |
| There are three valid values which may be used for modes: | |
| * `disabled` | |
| - SMMU hardware is ignored. Its register regions are not reserved (allowing | |
| user-mode to claim the registers), and the state of the SMMU hardware is | |
| left as it was when handed off to Zircon via the bootloader chain. Requests | |
| to create IOMMU instances of type `ZX_IOMMU_TYPE_ARM_SMMU` will have a | |
| StubIommu instance substituted instead. Leaked PMT pages will be | |
| quarantined as usual. | |
| * `passthru` | |
| - SMMU hardware is claimed and the register regions are reserved. User-mode | |
| will not be able to access this HW. BTIs must have valid stream | |
| identifiers supplied, and are used to configure contexts where all | |
| operations for all memory are permitted for the associated stream ID. | |
| Address translation and per-page permissions will not be performed/enforced. | |
| Leaked PMT pages will be returned to the main page pool after the BTI's | |
| context has been locked down and denied access. Passthru mode for a BTI | |
| resumes when the quarantine is released. | |
| * `enforced` | |
| - SMMU hardware is claimed and the register regions are reserved. User-mode | |
| will not be able to access this HW. BTIs must have valid stream | |
| identifiers supplied and will be used to configure an independent device | |
| address space for that BTI. Address translation will take place and | |
| per-page permissions for pinned memory will be enforced. Leaked PMT pages | |
| will be returned to the main page pool after the PTEs for the pinned memory | |
| have been removed, revoking HW access to those pages in the process. | |
| ## 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. #} |