Section 4.15. Boot-Time Kernel Arguments

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

Argument	Description
-b	The kernel sets RB_NOBOOTRC in its reboot flags variable to indicate that /etc/rc.boot should not be run. Deprecated.
-D	mach_init starts in normal mode. Core dumps are not taken for launched servers. Deprecated.
-d	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.
-F	mach_init forks during initialization. Note that it always forks if its process ID is 1. Deprecated.
-f	This argument is passed to the init program to indicate that a fast boot is desired. Deprecated.
-r	mach_init registers itself in a previously running copy of itself. Deprecated.
-s	This specifies single-user mode.
-v	This specifies a verbose boot.
-x	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

Argument	Description
ht_shift	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.
initmcl	This specifies the number of mbuf clusters to allocate during mbuf initialization.
mseg	This sets the maximum descriptor-based DMA (DBDMA) segment size.
nbuf	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.
ncl	This indicates the number of mbuf clusters used to calculate the nmbclusters value, which is the number of mapped clusters.
zsize	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

Argument	Description
dfnl	Setting dfnl=1 disables the split funnel. Removed in Mac OS X 10.4.
lcks	This argument specifies various locking options found in osfmk/ppc/locks.h and osfmk/i386/locks.h.
mtxspin	This sets the lock timeout in microseconds.
refunn	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

Argument	Description
boot-uuid	This argument specifies a root device by its UUID. Used along with rd=uuid.
rd, rootdev	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.
rp, rootpath	This indicates the booter-specified root path.
vndevice	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

Argument	Description
idlehalt	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.
poll	This argument sets the maximum poll quanta. Default value is 2.
preempt	This specifies the preemption rate in hertz. Default value is 100.
unsafe	This identifies the maximum unsafe quanta. Default value is 800.
yield	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

Argument	Description
artsize	Specifies the number of pages to be used for the address resolution table (ART).
BootCacheOverride	The BootCache driver is loadedbut does not runin the case of a network boot. Setting BootCacheOverride=1 overrides this behavior.
cpus	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.
ctrc	Limits tracing to a specific processor (see the tb argument).
dart	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.
debug	Specifies a variety of debug flags including those for kernel-debugging behavior. See Table 413 for details of these flags.
diag	Enables the kernel's built-in diagnostics API and its specific features.
fhrdl1	Setting fhrdl1=1 forces hardware recovery of data cache level 1 (L1 D-cache) errors. Deprecated (see the mcksoft argument).
fill	Specifies an integer value that is used to fill all memory pages at boot time.
fn	Alters the processor's force-nap behavior. Setting fn=1 turns force-nap off; setting fn=2 turns force-nap on.
_fpu	Disables FPU features on the x86. A string value of 387 disables FXSR/SSE/SSE2, whereas a string value of sse disables SSE2.
hfile	Name of the hibernate file (also stored in the kern.hibernatefile sysctl variable).
io	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.
kdp_match_mac	Specifies a MAC address that is to be used by the remote kernel-debugging protocol.
kdp_match_name	Specifies a BSD network interface name that is to be used by the remote kernel-debugging protocol.
maxmem	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.
mcklog	Specifies machine check flags.
mcksoft	Setting mcksoft=1 enables machine check software recovery.
novmx	Setting novmx=1 disables AltiVec.
_panicd_ip	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.
pcata	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.
platform	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.
pmsx	Setting pmsx=1 enables the experimental Power Management Stepper (PMS) mode introduced in Mac OS X 10.4.3.
romndrv	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.
_router_ip	Specifies the router through which the remote kernel-debugging protocol is to be routed while transmitting kernel core dumps to a remote machine.
serial	Setting serial=1 enables the serial console.
serialbaud	Specifies the baud rate for the serial port. The initialization routine for the kprintf() function checks this argument.
smbios	Setting smbios=1 enables detailed log messages in the SMBIOS driver. An x86-only argument.
srv	Setting srv=1 indicates a server boot. The kernel may check the value of this variable to alter its behavior.
tb	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.
vmdx, pmdx	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.
vmmforce	Specifies virtual machine monitor (VMM) features as a logical OR of feature bits. The features so specified are enforced for all virtual machine instances.
wcte	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

Bit	Name	Description
0x1	DB_HALT	Halt at boot time and wait for a debugger connection.
0x2	DB_PRT	Send kernel-debugging output generated by the kernel's printf() function to the console.
0x4	DB_NMI	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.
0x8	DB_KPRT	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.
0x10	DB_KDB	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).
0x20	DB_SLOG	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.
0x40	DB_ARP	Allow the kernel debugger nub to use ARP, allowing debugging across subnets.
0x80	DB_KDP_BP_DIS	Deprecated. Used for supporting old versions of GDB.
0x100	DB_LOG_PI_SCRN	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.
0x200	DB_KDP_GETC_ENA	Prompt for one of the c, r, and k characters to continue, reboot, or enter KDB, respectively, after a kernel panic.
0x400	DB_KERN_DUMP_ON_PANIC	Trigger core dump on panic.
0x800	DB_KERN_DUMP_ON_NMI	Trigger core dump on NMI.
0x1000	DB_DBG_POST_CORE	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.
0x2000	DB_PANICLOG_DUMP	Send only a panic lognot a full core dumpon panic.