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.





Mac OS X Internals. A Systems Approach
Mac OS X Internals: A Systems Approach
ISBN: 0321278542
EAN: 2147483647
Year: 2006
Pages: 161
Authors: Amit Singh

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net