4.15. Boot-Time Kernel Arguments
Arguments can be passed to the Mac OS X kernel through the boot-args NVRAM variable. The kernel parses these arguments as it boots, and in some cases, kernel extensions refer to boot arguments too. In this section, a large number of kernel arguments are tabulated. We will come across some of the arguments, and the contexts in which they are used, in subsequent chapters. Only brief explanations are provided in this section for the rest. Note the following points about the use of these arguments.
The set of available kernel arguments may change across kernel revisions. Therefore, some arguments listed here may not be available on certain kernel versions. Conversely, some kernels may support arguments that are not listed here.
Many of these arguments are intended for debugging or developmental purposes only. However, classifying them as appropriate or inappropriate for production use is an exercise in subjectivityconsequently, the arguments are listed as is.
The arguments are roughly classified based on the purposes they serve. However, there may be some overlap between these categories.
The value of the boot-args variable can be programmatically obtained on Mac OS X through the I/O Kit or the Mach user-level APIs. Moreover, as we saw earlier, the nvram utility displays the contents of boot-args from the command line.
Table 47 lists arguments that affect the overall booting behavior of the system. Note that most of these arguments are deprecated in Mac OS X 10.4 or newer.
Table 47. Kernel Arguments for Boot Behavior
The kernel sets RB_NOBOOTRC in its reboot flags variable to indicate that /etc/rc.boot should not be run. Deprecated.
mach_init starts in normal mode. Core dumps are not taken for launched servers. Deprecated.
mach_init starts in debug mode, with extensive logging. Core dumps are taken for any launched servers that crash. On Mac OS X 10.4 or newer, this argument causes the launchd program to daemonize early during its initialization.
mach_init forks during initialization. Note that it always forks if its process ID is 1. Deprecated.
This argument is passed to the init program to indicate that a fast boot is desired. Deprecated.
mach_init registers itself in a previously running copy of itself. Deprecated.
This specifies single-user mode.
This specifies a verbose boot.
The system attempts to boot conservatively in safe mode.
Table 48 lists arguments that can be used to alter the kernel's allocation of key data structures.
Table 48. Kernel Arguments for Resource Allocation
This argument is used to scale the hash table size during system page table allocation. By default, the kernel uses one page table entry group (PTEG) per four physical pages. Positive values of ht_shift make the hash table larger, and negative values make it smaller.
This specifies the number of mbuf clusters to allocate during mbuf initialization.
This sets the maximum descriptor-based DMA (DBDMA) segment size.
This specifies the number of I/O buffers to allocate. It defaults to 1% of physical memory pages, up to a maximum of 8192 and a minimum of 256.
This indicates the number of mbuf clusters used to calculate the nmbclusters value, which is the number of mapped clusters.
This sets the target zone size used while allocating address space for zones during virtual memory subsystem initialization. It defaults to 25% of physical memory, with 12MB and 768MB being the minimum and maximum values, respectively.
Table 49 lists arguments that affect the behavior of the kernel's locking mechanisms.
Table 49. Kernel Arguments for Locking Behavior
Setting dfnl=1 disables the split funnel. Removed in Mac OS X 10.4.
This argument specifies various locking options found in osfmk/ppc/locks.h and osfmk/i386/locks.h.
This sets the lock timeout in microseconds.
This enables the "refunnel" hint. Removed in Mac OS X 10.4.
Table 410 lists arguments that can be used either by themselves or in conjunction with other arguments to specify the root device.
Table 410. Kernel Arguments for Root Devices
This argument specifies a root device by its UUID. Used along with rd=uuid.
This specifies the root device as a device string. A string of the form /dev/diskY specifies a disk, where Y is the slice. Similarly, a string of the form /dev/mdx specifies a RAM disk, where x is a single-digit hexadecimal number. Other alternatives include cdrom, enet, and uuid.
This indicates the booter-specified root path.
Setting vndevice=1 causes the kernel to use the vnode disk driver instead of the disk image controller (hdix) while accessing an image remotely. Note that HTTP can be used only with hdix.
Table 411 lists arguments that affect the kernel's scheduling behavior.
Table 411. Kernel Arguments for Scheduling Behavior
Setting idlehalt=1 causes the kernel to halt a CPU core if no other thread in that core is active, causing the core to go into a low-power mode. An x86-only argument.
This argument sets the maximum poll quanta. Default value is 2.
This specifies the preemption rate in hertz. Default value is 100.
This identifies the maximum unsafe quanta. Default value is 800.
This is used to set the sched_poll_yield_shift scheduling variable, which is used while computing the time value for a polled depress thread yield. Default value is 4.
Table 412 lists arguments that can be used to enable or disable certain hardware and software features. It also lists arguments that are useful for various types of debugging.
Table 412. Kernel Arguments for Modifying Hardware/Software Properties and Debugging
Specifies the number of pages to be used for the address resolution table (ART).
The BootCache driver is loadedbut does not runin the case of a network boot. Setting BootCacheOverride=1 overrides this behavior.
Specifying cpus=N limits the number of CPUs to N, which must be a number less than or equal to the number of physically available CPUs.
Limits tracing to a specific processor (see the tb argument).
Setting dart=0 turns off the system PCI address mapper (DART) on 64-bit hardware. DART is required on machines with more than 2GB of physical memory but is enabled by default on all machines, regardless of their memory sizes.
Specifies a variety of debug flags including those for kernel-debugging behavior. See Table 413 for details of these flags.
Enables the kernel's built-in diagnostics API and its specific features.
Setting fhrdl1=1 forces hardware recovery of data cache level 1 (L1 D-cache) errors. Deprecated (see the mcksoft argument).
Specifies an integer value that is used to fill all memory pages at boot time.
Alters the processor's force-nap behavior. Setting fn=1 turns force-nap off; setting fn=2 turns force-nap on.
Disables FPU features on the x86. A string value of 387 disables FXSR/SSE/SSE2, whereas a string value of sse disables SSE2.
Name of the hibernate file (also stored in the kern.hibernatefile sysctl variable).
Specifies I/O Kit debugging flags. In particular, setting the kIOLogSynchronous bit (the value 0x00200000) ensures that the IOLog() function will complete synchronously. Normally, IOLog() output goes to a circular buffer that is emptied periodically.
Specifies a MAC address that is to be used by the remote kernel-debugging protocol.
Specifies a BSD network interface name that is to be used by the remote kernel-debugging protocol.
Setting maxmem=N limits the available physical memory to N (in mega-bytes). N must be less than or equal to the actual amount of physical memory installed.
Specifies machine check flags.
Setting mcksoft=1 enables machine check software recovery.
Setting novmx=1 disables AltiVec.
Specifies the IP address of a remote kernel-core-dump server machine, which is expected to be running the kdumpd daemon on UDP port 1069.
Setting pcata=0 disables the onboard PC ATA driver. This may be useful during developmentfor example, if a polled-mode driver is to be loaded.
Specifies a string to be used as the platform name in the fake device tree on the x86. The default platform name used is ACPI.
Setting pmsx=1 enables the experimental Power Management Stepper (PMS) mode introduced in Mac OS X 10.4.3.
Setting romndrv=1 allows a native graphics driver (ndrv) to be used even if its creation date is older than a predefined minimum date, which is March 1, 2001.
Specifies the router through which the remote kernel-debugging protocol is to be routed while transmitting kernel core dumps to a remote machine.
Setting serial=1 enables the serial console.
Specifies the baud rate for the serial port. The initialization routine for the kprintf() function checks this argument.
Setting smbios=1 enables detailed log messages in the SMBIOS driver. An x86-only argument.
Setting srv=1 indicates a server boot. The kernel may check the value of this variable to alter its behavior.
The kernel supports event tracing to a circular in-memory buffer. A nondefault trace buffer size can be specified through the tb argument. By default, the kernel uses 32 pages in debug mode and 8 pages in nondebug mode. The minimum and maximum values are 1 and 256 pages, respectively.
Cause the kernel to attempt to create a memory disk at boot time. Used as vmdx=base.size, where x is a single-digit hexadecimal number (0f), base is a page-aligned memory address, and size is a multiple of the page size. The v specifies virtual memory. A p can be used instead to specify physical memory. If the creation is successful, device nodes /dev/mdx and /dev/rmdx will appear after boot.
Specifies virtual machine monitor (VMM) features as a logical OR of feature bits. The features so specified are enforced for all virtual machine instances.
Setting wcte=1 enables the write combine timer (or store gather timer) in the PowerPC noncacheable unit (NCU). By default, this timer is disabled.
Table 413 lists the various bits that can be set in the kernel's debug argument, which is perhaps the most versatile and useful argument available for kernel-level debugging.
Table 413. Details of the debug Kernel Argument
Halt at boot time and wait for a debugger connection.
Send kernel-debugging output generated by the kernel's printf() function to the console.
Enable the kernel-debugging facility, including support for generating a nonmaskable interrupt (NMI) without a physical programmer's switch. On a Power Mac, an NMI can be generated by briefly pressing the power button. On a notebook computer, the command key must be held down while pressing the power button. If the power button is held down for more than five seconds, the system will power off. The DB_NMI bit is cleared if you use System Preferences to change the startup disk.
Send kernel-debugging output generated by kprintf() to the remote output device, which is typically a serial port (if one is available). Note that kprintf() output is synchronous.
Use KDB instead of GDB as the default kernel debugger. Unlike GDB, KDB must be explicitly compiled into the kernel. Moreover, KDB-based debugging requires native serial port hardware (as opposed to, say, USB-based serial port adapters).
Enable logging of miscellaneous diagnostics to the system log. For example, the load_shared_file() kernel function logs extra information if this bit is set.
Allow the kernel debugger nub to use ARP, allowing debugging across subnets.
Deprecated. Used for supporting old versions of GDB.
Disable the graphical panic screen so that panic data can be logged to the screen. It is also useful for monitoring the progress of a kernel core dump transmission.
Prompt for one of the c, r, and k characters to continue, reboot, or enter KDB, respectively, after a kernel panic.
Trigger core dump on panic.
Trigger core dump on NMI.
Wait for a debugger connection (if using GDB) or wait in the debugger (if using KDB) after an NMI-induced core dump. If DB_DBG_POST_CORE is not set, the kernel continues after the core dump.
Send only a panic lognot a full core dumpon panic.