.SH SYNOPSIS
.I none
.SH DESCRIPTION
-When booting Plan 9 on a PC, the DOS program
+When booting Plan 9 on a PC, the bootloader program
.IR 9boot (8)
-first reads a DOS file
-containing configuration information from the boot disk.
+first reads configuration information from a file
+on the boot media.
This file,
.BR plan9.ini ,
looks like a shell script containing lines of the form
.PP
The following sections describe how variables are used.
.SS ETHERNET
-.SS \fLetherX=value\fP
+.SS \fLether\fIX\fL=\fIvalue\fP
This defines an Ethernet interface.
.IR X ,
a unique monotonically increasing number beginning at 0,
.EE
BUG: On many machines only the 16 bit card works.
.TP
+.B bcm
+Broadcom BCM57xx Gigabit Ethernet controllers.
+Completely configurable, no options need be given.
+.TP
+.B yuk
+Marvell 88e8057 Yukon2 Gigabit Ethernet controller.
+Completely configurable, no options need be given.
+.TP
+.B virtio
+Virtual Ethernet interface provided by QEMU/KVM and VirtualBox.
+No options need be given. The MAC address can be changed with the
+.B ea=
+option.
+.TP
.B sink
A
.B /dev/null
Currently the only tested cards are those based on the
Intersil Prism 2.5 chipset.
.
+.TP
+.B iwl
+Intel Wireless WiFi Link mini PCI-Express adapters require
+firmware from
+.B http://firmware.openbsd.org/firmware/*/iwn-firmware*.tgz
+to be present on attach in
+.B /lib/firmware
+or
+.B /boot.
+To limit the selected APs the options
+.B essid=
+and
+.B bssid=
+may be set at boot or in the ether interface clone file
+using a space as the separator between option and value, e.g.
+.EX
+ echo essid left-armpit >/net/ether1/clone
+.EE
+Scan results appear in the
+.B ifstats
+file and can be read out like:
+.EX
+ cat /net/ether1/ifstats
+.EE
+Ad-hoc mode or WEP encryption is currently not supported.
+.TP
+.B rt2860
+Ralink Technology PCI/PCI-Express wireless adapters require
+firmware from
+.B http://firmware.openbsd.org/firmware/*/ral-firmware*.tgz
+to be present on attach in
+.B /lib/firmware
+or
+.B /boot.
+See iwl section above for configuration details.
+.TP
+.B wpi
+Intel PRO Wireless 3945abg PCI/PCI-Express wireless adapters require
+firmware from
+.B http://firmware.openbsd.org/firmware/*/wpi-firmware*.tgz
+to be present on attach in
+.B /lib/firmware
+or
+.B /boot.
+See iwl section above for configuration details.
+.SS \fLwpapsk\fI=password\fP
+WPA/WPA2 encryption
+is detected automatically and a prompt for the
+.I password
+will appear when using the WIFI interface for netbooting.
+To avoid the prompt, the
+.I password
+can be specified with the boot parameter above.
+.SS \fLnora6=
+Disable automatic IPv6 configuration from incoming router advertisements.
.SS DISKS, TAPES
(S)ATA controllers are autodetected.
.SS \fL*nodma=\fP
-disable DMA on ata devices.
-.SS \fLusbX=type=uhci\fP
-.SS \fLusbX=type=ohci\fP
-This specifies the settings for a USB UHCI or OHCI controller.
-Like the Ethernet controllers, USB controllers are autodetected
-after scanning for the ones listed in
-.IR plan9.ini .
-Thus, most systems will not need a
-.B usbX
-line.
-Also like the Ethernet controllers, USB autoprobing can be
-disabled by specifying the line
-.BR *nousbprobe= .
-.SS \fLscsiX=value\fP
+disables dma on ata devices.
+.SS \fL*sd\fIXX\fLdma=on\fP
+explicitly enables dma on a specific ata device.
+.SS \fLscsi\fIX\fL=value\fP
This defines a SCSI interface which cannot be automatically detected
by the kernel.
.PP
and
.I slot
to use as a root device for bootstrapping.
+.SS \fLramdisk\fIX\fL=\fIsize\fP
+.SS \fLramdisk\fIX\fL=\fIsize sectorsize\fP
+.SS \fLramdisk\fIX\fL=\fIaddress size sectorsize\fP
+This reserves physical memory as a ramdisk that will appear as
+.IR sd (3)
+device \fLsdZ\fIX\fR.
+When the
+.I address
+argument is omited or zero, then the ramdisk will be allocated
+from the top of physical memory.
.SS AUDIO
-.SS \fLaudioX=value\fP
-This defines a sound interface.
+.SS \fLaudio\fIX\fL=\fIvalue\fP
+This defines a sound interface. PCI based audio devices such as
+Intel HD audio or AC97 are autodetected and do not require any settings.
.PP
Known types are
.TF ess1688
.PD
.TP
+.B hda
+Intel HD audio.
+.TP
+.B ac97
+AC97 based card.
+.TP
.B sb16
Sound Blaster 16.
.TP
.EX
port=0x220 irq=7 dma=5
.EE
-.SS Uarts
+.SS UARTS
Plan 9 automatically configures COM1 and COM2, if found,
as
.B eia0
.LP
This is typically done in order to reuse the IRQ for
another device.
+.P
+.PP
+Additional i8250 (ISA) uarts (uart2 to uart5) can be
+configured using:
+.IP
+.EX
+uart\fIX\fP=type=isa port=\fIport\fP irq=\fIirq
+.EE
.PP
-Plan 9 used to support various serial concentrators,
-including the TTC 8 serial line card and various models
-in the Star Gate Avanstar series of intelligent serial boards.
-These are no longer supported; the much simpler
Perle PCI-Fast4, PCI-Fast8, and PCI-Fast16 controllers
-have taken their places.
-These latter cards are automatically detected
-and need no configuration lines.
+are automatically detected and need no configuration lines.
.PP
The line
.B serial=type=com
can be used to specify settings for a PCMCIA modem.
-.SS \fLmouseport=value\fP
+.SS \fLkbmap=\fIvalue\fP
+This specifies the keyboard map to use.
+.I Value
+can be a map file found in
+.B /sys/lib/kbmap
+on the ramdisk.
+.PP
+For example:
+.TP
+.B kbmap=colemak
+.SS \fLmouseport=\fIvalue\fP
This specifies where the mouse is attached.
.I Value
-can be
+can be a map file found in
+.B /sys/lib/kbmap
+on the ramdisk.
.TP
.B ps2
the PS2 mouse/keyboard port. The BIOS setup procedure
.TP
.B 1
for COM2
-.SS \fLmodemport=value\fP
+.SS \fLmodemport=\fIvalue\fP
Picks the UART line to call out on.
This is used when connecting to a file server over
an async line.
.I Value
is the number of the port.
-.SS \fLconsole=value params\fP
+.SS \fLconsole=\fIvalue params\fP
This is used to specify the console device.
The default
-value is
+.I value
+is
.BR cga ;
a number
.B 0
.LP
would use COM1 at 19,200 baud
with odd parity.
+.LP
+The value
+.B net
+specifies ``netconsole'' which sends console messages as UDP packets over the network.
+It bypasses the IP stack and writes Ethernet packets directly to the NIC.
+In this case
+.I params
+is mandatory and takes the form
+.IP
+\fIsrcip\fR [ \fB!\fIsrcport \fR] [ \fB/\fIdevno \fR] \fB, \fIdstip\fR [ \fB!\fIdstport \fR] [ \fB/\fIdstmac \fR]
+.LP
+\fISrcip\fR, \fIsrcport\fR (default 6665), \fIdstip\fR and \fIdstport\fR (default 6666) specify the source IP address, source port, destination IP address and destination port, respectively.
+\fIDevno\fR (default 0) specifies which NIC to use, a value of \fIn\fR corresponds to NIC at \fL#l\fIn\fR (see
+.IR ether (3)).
+\fIDstmac\fR specifies the destination MAC address; broadcast packets are sent if it is unspecified.
+Note that it is possible, but not recommended, to send packets to a host outside the local network by specifying the MAC address of the gateway as \fIdstmac\fR.
+Example lines are
+.IP
+.EX
+console=net 192.168.0.4,192.168.0.8
+console=net 192.168.2.10!1337/1,192.168.2.3!1337/0ea7deadbeef
+.EE
+.LP
.SS "PC CARD"
.SS \fLpccard0=disabled\fP
Disable probing for and automatic configuration of PC card controllers.
-.SS \fLpcmciaX=type=XXX irq=value\fP
+.SS \fLpcmcia\fIX\fL=type=XXX irq=\fIvalue\fP
If the default IRQ for the
PCMCIA
is correct, this entry can be omitted. The value of
.SS \fLpcmcia0=disabled\fP
Disable probing for and automatic configuration of PCMCIA controllers.
.SS BOOTING
-.SS \fLbootfile=value\fP
+.SS \fLbootfile=\fIvalue\fP
This is used to direct the actions of
.IR 9boot (8)
by naming the file from which to load the kernel in
the current BIOS boot device.
-.SS \fLbootargs=value\fP
-The value of this variable is passed to
+.SS \fLbootargs=\fIvalue\fP
+The
+.I value
+of this variable is passed to
.IR boot (8)
-by the kernel as the name of the root file system.
+by the kernel as the name of the root file system to
+automatically mount and boot into.
It is typically used to specify additional arguments to
pass to
-.IR kfs (4)
+.IR cwfs (4)
or
.IR ipconfig (8).
For example, if the system is to run from a local
-.IR kfs (4)
+.IR cwfs (4)
partition, the definition might read
-.BR bootargs=local!#S/sdC0/fs .
+.BR bootargs=local!/dev/sdC0/fscache .
See
.IR boot (8)
for more.
-.SS \fLnobootprompt=value\fP
+.SS \fLnobootprompt=\fIvalue\fP
Suppress the
-.L "root from"
+.L bootargs
prompt and use
.I value
as the answer instead.
-.SS \fLuser=value\fP
+.SS \fLrootdir=\fB/root/\fIdir\fP
+.SS \fLrootspec=\fIspec\fP
+Changes the mount arguments for the root file server
+that was specified by
+.I bootargs
+above.
+By changing
+.I dir
+in
+.BR $rootdir ,
+a different sub-directory on the root file server
+can be used as the system root. see
+.IR boot (8)
+for details.
+.SS \fLuser=\fIvalue\fP
Suppress the
.L "user"
prompt and use
.I value
as the answer instead.
+.SS \fLservice=\fIvalue\fP
+Changes the systems default role. Possible
+settings for
+.I value
+are
+.B cpu
+and
+.B terminal.
.SS \fLdebugfactotum=\fP
Causes
.IR boot (8)
with the
.B -p
option, so that it can be debugged.
-.SS \fLfactotumopts=options\fP
-Causes
-.IR boot (8)
-to start
-.I factotum
-with the given
-.IR options ,
-which must be a single word (i.e., contain no whitespace).
-.SS \fLventi=value\fP
-When booting from a local server backed by a local
-or remote venti server,
-this variable specifies how to establish the connection to the
-venti server.
-See
-.IR boot (8)
-for more.
-.SS \fLcfs=value\fP
+.SS \fLcfs=\fIvalue\fP
This gives the name of the file holding the disk partition
for the cache file system,
.IR cfs (4).
.B bootargs
example, one would write
.BR cfs=#S/sdC0/cache .
-.SS \fLbootdisk=value\fP
+.SS \fLbootdisk=\fIvalue\fP
This deprecated variable was used to specify the disk used by
the cache file system and other disk-resident services.
It is superseded by
.B bootargs
and
.BR cfs .
-.SS \fLfs=a.b.c.d\fP
-.SS \fLauth=a.b.c.d\fP
-These specify the IP address of the file and authentication server
+.SS \fLfs=\fIaddress\fP
+.SS \fLauth=\fIaddress\fP
+.SS \fLsecstore=\fIaddress\fP
+These specify the network address (IP or domain name)
+of the file, authentication and secstore server
to use when mounting a network-provided root file system.
-They are used only if the addresses cannot be determined via DHCP.
+When not specified, then these settings are determined via DHCP.
+When
+.B secstore
+is not specified, then the authentication server is used.
.SS PROCESSOR
-.SS \fL*norealmode=\fP
-The PC kernel switches the processor to 16-bit real mode
-to run BIOS interrupts, for example to find the memory map or to enable VESA.
-This variable disables such switches.
-.SS \fL*noe820scan=\fP
-When available, the PC kernel uses the BIOS E820 memory map
-to size memory. This variable disables the scan.
-.SS \fL*maxmem=value\fP
+.SS \fL*e820=\fItype \fB0x\fIstart \fB0x\fIend ...\fP
+This variable is automatically generated by the boot loader (see
+.IR 9boot (8))
+by doing a BIOS E820 memory scan while still in realmode and
+passed to the kernel. The format is a unordered list of
+decimal region
+.I type
+and hexadecimal 64-bit
+.I start
+and
+.I end
+addresses of the area.
+.SS \fL*maxmem=\fIvalue\fP
This defines the maximum physical address that the system will scan when sizing memory.
By default the PC operating system will scan up to 3.75 gigabytes
(0xF0000000, the base of kernel virtual address space), but setting
.B *maxmem
must be less than 3.75 gigabytes.
This variable is not consulted if using the E820 memory map.
-.SS \fL*kernelpercent=value\fP
+.SS \fL*kernelpercent=\fIvalue\fP
This defines what percentage of available memory is reserved for the kernel allocation pool.
The remainder is left for user processes. The default
.I value
.IR draw (3)
maintains its graphic images in kernel memory.
This deprecated option is rarely necessary in newer kernels.
-.SS \fL*nomce=value\fP
+.SS \fL*imagemaxmb=\fIvalue\fP
+This limits the maximum amount of memory (in megabytes) the graphics
+image memory pool can grow. The default is unlimited for terminals
+and cpu servers.
+.SS \fL*noavx=\fP
+Disables AVX and AVX2 on AMD64 CPUs.
+.SS \fL*nomce=\fP
If machine check exceptions are supported by the processor,
then they are enabled by default.
-Setting this variable to
-.B 1
+Setting
+.B *nomce
causes them to be disabled even when available.
.SS \fL*nomp=\fP
A multiprocessor machine will enable all processors by default.
.B *nomp
restricts the kernel to starting only one processor and using the
traditional interrupt controller.
-.SS \fL*ncpu=value\fP
+.SS \fL*ncpu=\fIvalue\fP
Setting
.B *ncpu
restricts the kernel to starting at most
.I value
processors.
+.SS \fL*apicdebug=\fP
+Prints a summary of the multiprocessor APIC interrupt configuration.
+.SS \fL*nomsi=\fP
+Disables message signaled interrupts for PCI devices.
+This option has no effect when
+.B *nomp
+is set.
+.SS \fL*nomtrr=\fP
+Disables memory type range register (MTRR) support when set. (debug)
+.SS \fL*notsc=\fP
+Disables the use of the per processor timestamp counter registers
+as high resolution clock.
+.SS \fL*nohpet=\fP
+Disables the HPET timer to be used as the high resolution clock.
.SS \fL*pcimaxbno=value\fP
This puts a limit on the maximum bus number probed
on a PCI bus (default 7).
This, and
.B *pcimaxdno
below are rarely used and only on troublesome or suspect hardware.
-.SS \fL*pcimaxdno=value\fP
+.SS \fL*pcimaxdno=\fIvalue\fP
This puts a limit on the maximum device number probed
on a PCI bus (default 31).
.SS \fL*nopcirouting=\fP
Disable pci routing during boot. May solve interrupt routing
problems on certain machines.
+.SS \fL*pcihinv=\fP
+Prints a summary of the detected PCI busses and devices.
.SS \fL*nodumpstack=\fP
Disable printing a stack dump on panic.
Useful if there is only a limited cga screen available,
otherwise the textual information about the panic may scroll off.
.\" .SS \fL*nobios=\fP
.\" what does this do? something with pci
-.SS \fLioexclude=value\fP
+.SS \fLioexclude=\fIvalue\fP
Specifies a list of ranges of I/O ports to exclude from use by drivers.
Ranges are inclusive on both ends and separated by commas.
For example:
.EX
ioexclude=0x330-0x337,0x430-0x43F
.EE
-.SS \fLumbexclude=value\fP
+.SS \fLumbexclude=\fIvalue\fP
Specifies a list of ranges of UMB to exclude from use by drivers.
Ranges are inclusive on both ends and separated by commas.
For example:
.EX
umbexclude=0xD1800-0xD3FFF
.EE
+.SS \fL*acpi=\fIvalue\fP
+This option controls the search for ACPI tables by the kernel.
+The
+.I value
+is the hexadecimal physical address of the RSD structure
+and is passed by the EFI bootloer
+.IR 9boot (8)
+automatically.
+The special
+.I value
+of 1 or empty make the kernel search for the structure
+in BIOS memory area (This is the default).
+The
+special
+.I value
+of 0 will disable ACPI support (for interrupt routing)
+in the kernel,
+but still make table data available in
+.B #P/acpitbls
+file of the
+.IR arch (3)
+device.
.SS \fLapm0=\fP
This enables the ``advanced power management'' interface
as described in
battery life (see
.IR stats (8)).
It is not on by default because it causes problems on some laptops.
+.SS USB
+.SS \fL*nousbprobe=\fP
+Disable USB host controller detection.
+.SS \fL*nousbohci=\fP
+.SS \fL*nousbuhci=\fP
+.SS \fL*nousbehci=\fP
+.SS \fL*nousbxhci=\fP
+Disable specific USB host controller types.
+.SS \fLnousbrc=\fP
+Disable
+.IR nusbrc (8)
+startup at boot time.
+.SS \fLnousbhname=\fP
+When defined,
+.IR nusbrc (8)
+will use the dynamically assigned usb device address to name
+usb devices instead of the device unique name.
.SS VIDEO
-.SS \fLmonitor=value\fP
-.SS \fLvgasize=value\fP
+.SS \fLmonitor=\fIvalue\fP
+.SS \fLvgasize=\fIvalue\fP
These are used not by the kernel but by
.I termrc
(see
.IR cpurc (8))
when starting
.IR vga (8).
-.SS \fL*dpms=value\fP
+If
+.I value
+is set to
+.B ask
+then the user is prompted for a choice on boot.
+.SS \fL*bootscreen=\fIvalue\fP
+This is used by the kernel to attach a pre-initialized
+linear framebuffer that was setup by the bootloader
+or firmware.
+The
+.I value
+has four space separated fields: the resolution and bitdepth
+of the screen, the color channel descriptor, the physical
+address of the framebuffer and a optional aperture size.
+.EX
+ *bootscreen=800x600x32 x8r8g8b8 0x80000000 0x001d4c00
+.EE
+.SS \fL*dpms=\fIvalue\fP
This is used to specify the screen blanking behavior of the MGA4xx
video driver.
Values are
The first two specify differing levels of power saving;
the third turns the monitor off completely.
.SS NVRAM
-.SS \fLnvram=file\fP
-.SS \fLnvrlen=length\fP
-.SS \fLnvroff=offset\fP
+.SS \fLnvram=\fIfile\fP
+.SS \fLnvrlen=\fIlength\fP
+.SS \fLnvroff=\fIoffset\fP
This is used to specify an nvram device and optionally the length of the ram
and read/write offset to use.
These values are consulted by
.IR secstore (1)
password for use by
.IR factotum (4).
-.SS \fLnvr=value\fP
+.SS \fLnvr=\fIvalue\fP
This is used by the WORM file server kernel to locate a file holding information
to configure the file system.
The file cannot live on a SCSI disk.
serial0=type=generic port=0x3E8 irq=5
monitor=445x
vgasize=1600x1200x8
-bootfile=/386/9pcf
+bootfile=/386/9pc
%
.EE
.SH "SEE ALSO"
.IR 9boot (8),
.IR booting (8),
.IR boot (8)
-.SH BUGS
-Being able to set the console device to other than a
-display is marginally useful on file servers; MS-DOS
-and the programs which run under it are so tightly bound
-to the display that it is necessary to have a display if any
-setup or reconfiguration programs need to be run.
-Also, the delay before any messages appear at boot time
-is disconcerting, as any error messages from the BIOS
-are lost.
-.PP
-This idea is at best an interesting experiment that needs another iteration.
projects / plan9front.git / blobdiff