20060303-partial

1 files changed, 789 insertions, 0 deletions

diff --git a/man/10/plan9.ini b/man/10/plan9.ini
new file mode 100644
index 00000000..71e8559d
--- /dev/null
+++ b/man/10/plan9.ini
@@ -0,0 +1,789 @@
+.TH PLAN9.INI 10.6
+.SH NAME
+plan9.ini \- configuration file for PCs
+.SH SYNOPSIS
+.I none
+.SH DESCRIPTION
+When booting Inferno on a PC, the Plan 9 bootstrap programs
+are used, hence the references to Plan 9 below.
+The DOS program
+.IR 9load (10.8)
+first reads a DOS file
+containing configuration information from the boot disk.
+This file,
+.BR plan9.ini ,
+looks like a shell script containing lines of the form
+.PP
+.EX
+	name=\f2value\fP
+.EE
+.LP
+each of which defines a kernel or device parameter.
+.PP
+For devices, the generic format of
+.I value
+is
+.PP
+.EX
+	type=TYPE [port=N] [irq=N] [mem=N] [size=N] [dma=N] [ea=N]
+.EE
+.LP
+specifying the controller type,
+the base I/O port of the interface, its interrupt
+level, the physical starting address of any mapped memory,
+the length in bytes of that memory, the DMA channel,
+and for Ethernets an override of the physical network address.
+Not all elements are relevant to all devices; the relevant values
+and their defaults are defined below in the description of each device.
+.PP
+The file is used by
+.B 9load
+and the kernel to configure the hardware available.
+The information it contains is also passed to the boot
+process, and subsequently other programs,
+as environment variables
+(see also
+.B osinit.dis
+in
+.IR root (3)).
+However, values whose names begin with an asterisk
+.B *
+are used by the kernel and are not converted into environment variables.
+.PP
+The following sections describe how variables are used.
+.SS \fLetherX=value\fP
+This defines an Ethernet interface.
+.IR X ,
+a unique monotonically increasing number beginning at 0,
+identifies an Ethernet card to be probed at system boot.
+Probing stops when a card is found or there is no line for
+.BR etherX+1 .
+After probing as directed by the
+.BI ether X
+lines, any remaining ethernet cards that can be automatically
+detected are added.
+Almost all cards can be automatically detected.
+For debugging purposes, automatic probing can
+be disabled by specifying the line
+.BR *noetherprobe= .
+This automatic probing is only done by the kernel, not by
+.IR 9load (10.8).
+Thus, if you want to load a kernel over the ethernet, you need
+to specify an
+.B ether0
+line so that
+.I 9load
+can find the ethernet card, even if the kernel would
+have automatically detected it.
+.PP
+Some cards are software configurable and do not require all options.
+Unspecified options default to the factory defaults.
+.PP
+Known types are
+.TP
+.B ne2000
+Not software configurable. 16-bit card.
+Defaults are
+.EX
+	port=0x300 irq=2 mem=0x04000 size=0x4000
+.EE
+The option (no value)
+.B nodummyrr
+is needed on some (near) clones to turn off a dummy remote read in the driver.
+.TP
+.B amd79c970
+The AMD PCnet PCI Ethernet Adapter (AM79C970).
+(This is the ethernet adapter used by VMware.)
+Completely configurable, no options need be given.
+.TP
+.B wd8003
+Includes WD8013 and SMC Elite and Elite Ultra cards. There are varying degrees
+of software configurability. Cards may be in either 8-bit or 16-bit slots.
+Defaults are
+.EX
+	port=0x280 irq=3 mem=0xD0000 size=0x2000
+.EE
+BUG: On many machines only the 16 bit card works.
+.TP
+.B elnk3
+The 3COM Etherlink III series of cards including the 5x9, 59x, and 905 and 905B.
+Completely configurable, no options need be given.
+The media may be specified by setting
+.B media=
+to the value
+.BR 10BaseT ,
+.BR 10Base2 ,
+.BR 100BaseTX ,
+.BR 100BaseFX ,
+.BR aui ,
+and
+.BR mii .
+If you need to force full duplex, because for example the Ethernet switch does not negotiate correctly,
+just name the word (no value)
+.B fullduplex
+or
+.BR 100BASE-TXFD .
+Similarly, to force 100Mbit operation, specify
+.BR force100 .
+Port 0x110 is used for the little ISA configuration dance.
+.TP
+.B 3c589
+The 3COM 3C589 series PCMCIA cards, including the
+3C562 and the 589E.
+There is no support for the modem on the 3C562.
+Completely configurable, no options need be given.
+Defaults are
+.EX
+	port=0x240 irq=10
+.EE
+The media may be specified as
+.B media=10BaseT
+or
+.BR media=10Base2 .
+.TP
+.B ec2t
+The Linksys Combo PCMCIA EthernetCard (EC2T),
+EtherFast 10/100 PCMCIA cards (PCMPC100) and integrated controllers (PCM100),
+the Netgear FA410TX 10/100 PCMCIA card
+and the Accton EtherPair-PCMCIA (EN2216).
+Completely configurable, no options need be given.
+Defaults are
+.EX
+	port=0x300 irq=9
+.EE
+These cards are NE2000 clones.
+Other NE2000 compatible PCMCIA cards may be tried
+with the option
+.EX
+	id=string
+.EE
+where
+.B string
+is a unique identifier string contained in the attribute
+memory of the card (see
+.IR pcmcia (8));
+unlike most options in 
+.BR plan9.ini ,
+this string is case-sensitive.
+The option
+.B dummyrr=[01]
+can be used to turn off (0) or on (1) a dummy remote read in the driver
+in such cases,
+depending on how NE2000 compatible they are.
+.TP
+.B i82557
+Cards using the Intel 8255[789] Fast Ethernet PCI Bus LAN Controller such as the
+Intel EtherExpress PRO/100B.
+Completely configurable, no options need be given.
+If you need to force the media, specify
+one of the options (no value)
+.BR 10BASE-T ,
+.BR 10BASE-2 ,
+.BR 10BASE-5 ,
+.BR 100BASE-TX ,
+.BR 10BASE-TFD ,
+.BR 100BASE-TXFD ,
+.BR 100BASE-T4 ,
+.BR 100BASE-FX ,
+or
+.BR 100BASE-FXFD .
+.TP
+.B 2114x
+Cards using the Digital Equipment (now Intel) 2114x PCI Fast Ethernet Adapter Controller,
+for example the Netgear FA310.
+Completely configurable, no options need be given.
+Media can be specified the same was as for the
+.BR i82557 .
+Some cards using the
+.B PNIC
+and
+.B PNIC2
+near-clone chips may also work.
+.\" .TP
+.\" .B ga620
+.\" Netgear GA620 and GA620T Gigabit Ethernet cards,
+.\" and other cards using the Alteon Acenic chip such as the
+.\" Alteon Acenic fiber and copper cards,
+.\" the DEC DEGPA-SA and the SGI Acenic.
+.\" Completely configurable.
+.TP
+.B wavelan
+Lucent Wavelan (Orinoco) IEEE 802.11b 
+and compatible PCMCIA cards.
+Compatible cards include the Dell TrueMobile 1150
+and the Linksys Instant Wireless Network PC Card.
+Port and IRQ defaults are 0x180 and 3 respectively.
+
+These cards take a number of unique options to aid in
+identifying the card correctly on the 802.11b network.
+The network may be
+.I "ad hoc"
+or
+.I managed
+(i.e. use an access point):
+.EX
+	mode=[adhoc, managed]
+.EE
+and defaults to
+.IR managed .
+The 802.11b network to attach to
+.RI ( managed
+mode)
+or identify as
+.RI ( "ad hoc"
+mode),
+is specified by
+.EX
+	essid=string
+.EE
+and defaults to a null string.
+The card station name is given by
+.EX
+	station=string
+.EE
+and defaults to
+.IR "Plan 9 STA" .
+The channel to use is given by
+.EX
+	channel=number
+.EE
+where
+.I number
+lies in the range 1 to 16 inclusive;
+the channel is normally negotiated automatically.
+
+If the card is capable of encryption,
+the following options may be used:
+.EX
+	crypt=[off, on]
+.EE
+and defaults to
+.IR on .
+.EX
+	key\fIN\fP=string
+.EE
+sets the encryption key
+.I n
+(where
+.I n
+is in the range 1 to 4 inclusive) to
+.IR string ;
+this will also set the transmit key to
+.I n
+(see below).
+.EX
+	txkey=number
+.EE
+sets the transmit key to use to be
+.I number
+in the range 1 to 4 inclusive.
+If it is desired to exclude or include unencrypted packets
+.EX
+	clear=[off, on]
+.EE
+configures reception and defaults to inclusion.
+
+The defaults are intended to match the common case of
+a managed network with encryption and a typical entry would 
+only require, for example
+.EX
+	essid=left-armpit key2=fishcalledraawaru
+.EE
+if the port and IRQ defaults are used.
+These options may be set after boot by writing to the device's
+.I ctl
+file using a space as the separator between option and value, e.g.
+.EX
+	echo 'key2 fishcalledraawaru' > /net/ether0/0/ctl
+.EE
+.TP
+.B wavelanpci
+PCI ethernet adapters that use the same Wavelan
+programming interface.
+Currently the only tested cards are those based on the
+Intersil Prism 2.5 chipset.
+.TP
+.B 83815
+National Semiconductor DP83815-based adapters, notably
+the Netgear FA311, Netgear FA312, and various SiS built-in
+controllers such as the SiS900.
+On the SiS controllers, the ethernet address is not detected properly;
+specify it with an
+.B ea=
+attribute.
+.\" .TP
+.\" .B 83820
+.\" National Semiconductor DP83820-based gigabit ethernet adapters, notably
+.\" the D-Link DGE-500T.
+.TP
+.B rtl8139
+The Realtek 8139.
+.TP
+.B 82543gc
+The Intel RS-82543GC gigabit ethernet controller,
+as found on the Intel PRO/1000[FT] server adapter.
+The older non-[FT] cards based on the 82542 (LSI L2A1157)
+chip are not supported, although support would probably be
+easy to add.
+.TP
+.B smc91cxx
+SMC 91cXX chip-based PCMCIA adapters, notably the SMC EtherEZ card.
+.TP
+.B sink
+A
+.B /dev/null
+for ethernet packets \(em the interface discards sent
+packets and never receives any.
+This is used to provide a test bed for
+some experimental ethernet bridging software.
+.SS \fLusbX=type=uhci port=xxx irq=xxx\fP
+This specifies the settings for a USB UHCI 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
+This defines a SCSI interface which cannot be automatically detected
+by the kernel.
+.PP
+Known types are
+.TP
+.B aha1542
+The Adaptec 154x series of controllers (and clones).
+Almost completely configurable, only the
+.EX
+	port=0x300
+.EE
+option need be given.
+.PP
+NCR/Symbios/LSI Logic 53c8xx-based adapters
+and Mylex MultiMaster (Buslogic BT-*) adapters are
+automatically detected and need no entries.
+.PP
+By default, the NCR 53c8xx driver searches for up to 32 controllers.
+This can be changed by setting the variable
+.BR *maxsd53c8xx .
+.PP
+By default the Mylex driver resets SCSI cards by using
+both the hard reset and SCSI bus reset flags in the driver interface.
+If a variable
+.BR *noscsireset
+is defined, the SCSI bus reset flag is omitted.
+.SS Uarts
+Plan 9 automatically configures COM1 and COM2, if found,
+as
+.B eia0
+(port 0x3F8, IRQ4)
+and
+.B eia1
+(port 0x2F8, IRQ3)
+respectively.
+These devices can be disabled by adding a line:
+.EX
+    eia\fIX\fP=disabled
+.EE
+This is typically done in order to reuse the IRQ for 
+another device.
+.PP
+The system 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.
+.PP
+The line
+.B serial=type=com
+can be used to specify settings for a PCMCIA modem.
+.SS \fLmouseport=value\fP
+This specifies where the mouse is attached.
+.I Value
+can be
+.TP
+.B ps2
+the PS2 mouse/keyboard port.  The BIOS setup procedure
+should be used to configure the machine appropriately.
+.TP
+.B ps2intellimouse
+an Intellimouse on the PS2 port.
+.TP
+.B 0
+for COM1
+.TP
+.B 1
+for COM2
+.SS \fLmodemport=value\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 \fLpccard0=disabled\fP
+Disable probing for and automatic configuration of PC card controllers.
+.SS \fLpcmciaX=type=XXX irq=value\fP
+If the default IRQ for the
+PCMCIA
+is correct, this entry can be omitted.  The value of
+.B type
+is ignored.
+.SS \fLpcmcia0=disabled\fP
+Disable probing for and automatic configuration of PCMCIA controllers.
+.SS \fLconsole=value params\fP
+This is used to specify the console device.
+The default
+value is
+.BR cga ;
+a number
+.B 0
+or
+.B 1
+specifies
+.I COM1
+or
+.I COM2
+respectively.
+A serial console is initially configured with the
+.IR eia (3)
+configuration string
+.B b9600
+.B l8
+.B pn
+.BR s1 ,
+specifying 9600 baud,
+8 bit bytes, no parity, and one stop bit.
+If
+.I params
+is given, it will be used to further
+configure the uart.
+Notice that there is no
+.B =
+sign in the
+.I params
+syntax.
+For example,
+.EX
+    console=0 b19200 po
+.EE
+would use COM1 at 19,200 baud
+with odd parity.
+.SS \fLbootfile=value\fP
+This is used to direct the actions of
+.IR 9load (10.8)
+by naming the device and file from which to load the kernel.
+.SS \fLpartition=value\fP
+This defines the partition table
+.IR 9load (10.8)
+will examine to find disk partitioning information.
+By default, a partition table in a Plan 9 partition
+is consulted; if no such table is found, an old-Plan 9
+partition table on the next-to-last or last sector
+of the disk is consulted.
+A value of 
+.B new
+consults only the first table,
+.B old
+only the second.
+.SS \fL*maxmem=value\fP
+This defines the maximum physical address that the system will scan when sizing memory.
+By default the operating system will scan up to 768 megabytes, but setting
+.B *maxmem
+will limit the scan.
+If the system has more than 768 megabytes, you must set
+.B *maxmem
+for the kernel to find it.
+.B *maxmem
+must be less than 1.75 gigabytes.
+.SS \fL*kernelpercent=value\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
+is
+.B 30
+on CPU servers,
+.B 60
+on terminals with less than 16MB of memory,
+and
+.B 40
+on terminals with memories of 16MB or more.
+Terminals use more kernel memory because
+.IR draw (3)
+maintains its graphic images in kernel memory.
+This deprecated option is rarely necessary in newer kernels.
+.SS \fL*nomce=value\fP
+If machine check exceptions are supported by the processor,
+then they are enabled by default.
+Setting this variable to
+.B 1
+causes them to be disabled even when available.
+.SS \fL*nomp=\fP
+A multiprocessor machine will enable all processors by default.
+Setting
+.B *nomp
+restricts the kernel to starting only one processor and using the
+traditional interrupt controller.
+.SS \fL*ncpu=value\fP
+Setting
+.B *ncpu
+restricts the kernel to starting at most
+.I value
+processors.
+.SS \fL*pcimaxbno=value\fP
+This puts a limit on the maximum bus number probed
+on a PCI bus (default 255).
+For example, a
+.I value
+of 1 should suffice on a 'standard' motherboard with an AGP slot.
+This, and 
+.B *pcimaxdno
+below are rarely used and only on troublesome or suspect hardware.
+.SS \fL*pcimaxdno=value\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*nobios=\fP
+.\" what does this do?  something with pci
+.SS \fLioexclude=value\fP
+Specifies a list of ranges 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 \fLapm0=\fP
+This enables the ``advanced power management'' interface
+as described in
+.IR apm (3).
+....and
+.....IR apm (8).
+The main feature of the interface is the ability to watch
+battery life.
+....battery life (see
+.....IR stats (8)).
+It is not on by default because it causes problems on some laptops.
+.SS \fLmonitor=value\fP
+.SS \fLvgasize=value\fP
+These are used not by the kernel but by system initialisation.
+.SS \fL*dpms=value\fP
+This is used to specify the screen blanking behavior of the MGA4xx
+video driver.
+Values are
+.BR standby ,
+.BR suspend ,
+and
+.BR off .
+The first two specify differing levels of power saving;
+the third turns the monitor off completely.
+.SS \fLnvr=value\fP
+This is used by a file server kernel to locate a file holding information
+to configure the file system.
+The file cannot live on a SCSI disk.
+The default is
+.B fd!0!plan9.nvr
+(sic),
+unless
+.B bootfile
+is set, in which case it is
+.B plan9.nvr
+on the same disk as
+.BR bootfile .
+The syntax is either
+.BI fd! unit ! name
+or
+.BI hd! unit ! name
+where
+.I unit
+is the numeric unit id.
+This variant syntax is a vestige of the file server kernel's origins.
+.SS \fLaudioX=value\fP
+This defines a sound interface.
+.PP
+Known types are
+.TP
+.B sb16
+Sound Blaster 16.
+.TP
+.B ess1688
+A Sound Blaster clone.
+.PP
+The DMA channel may be any of 5, 6, or 7.
+The defaults are
+.EX
+	port=0x220 irq=7 dma=5
+.EE
+.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
+to use when mounting a network-provided root file system.
+They are used only if the addresses cannot be determined via DHCP.
+.SH Multiple Configurations
+.PP
+A
+.B plan9.ini
+file may contain multiple configurations,
+each within a block beginning with a line
+.EX
+	[tag]
+.EE
+A special block with the tag
+.B menu
+gives a list of blocks from which the user may
+interactively select the contents of
+.BR plan9.ini .
+There may also be multiple blocks with the tag
+.B common
+which will be included in all selections;
+if any lines appear in
+.B plan9.ini
+before the first block,
+they are treated as a
+.B common
+block.
+.LP
+Within the
+.B menu
+block the following configuration lines are allowed:
+.SS \fLmenuitem=tag[, description]
+The block identified by
+.B tag
+will appear in the presented menu.
+The menu entry will consist of the
+.B tag
+unless the optional
+.B description
+is given.
+.SS \fLmenudefault=tag[, timeout]
+Identifies a default block to be given in the
+menu selection prompt.
+If the optional
+.B timeout
+is given (in seconds),
+the default block will be selected if there is no user
+input within the timeout period.
+.SS \fLmenuconsole=value[, baud]
+Selects a serial console upon which to present the menu
+as no
+.B console
+or
+.B baud
+configuration information will have been processed yet
+(the
+.B plan9.ini
+contents are still to be decided...).
+.LP
+In response to the menu being printed,
+the user is prompted to select a menu item from the list.
+If the numeric response is followed by a
+.BR p ,
+the selected configuration is printed and the menu presented
+again.
+.LP
+The line
+.EX
+	menuitem=tag
+.EE
+is prefixed to the selected configuration as an aid to
+user-level initialization scripts.
+.SH EXAMPLES
+.PP
+A representative
+.BR plan9.ini :
+.IP
+.EX
+% cat /n/c:/plan9.ini
+ether0=type=3C509
+mouseport=ps2
+modemport=1
+serial0=type=generic port=0x3E8 irq=5
+monitor=445x
+vgasize=1600x1200x8
+% 
+.EE
+.PP
+Minimum CONFIG.SYS and AUTOEXEC.BAT files to use
+COM2 as a console:
+.IP
+.EX
+% cat /n/c:/config.sys
+SHELL=COMMAND.COM COM2 /P
+% cat /n/c:/autoexec.bat
+@ECHO OFF
+PROMPT $p$g
+PATH C:\eDOS;C:\eBIN
+mode com2:96,n,8,1,p
+SET TEMP=C:\eTMP
+% 
+.EE
+.PP
+Simple
+.B plan9.ini
+with multiple configurations:
+.IP
+.EX
+[menu]
+menuitem=vga, Plan 9 with VGA
+menuitem=novga, Plan 9 no automatic VGA
+menudefault=vga
+
+[vga]
+monitor=multisync135
+vgasize=1024x768x8
+
+[novga]
+
+[common]
+ether0=type=i82557
+audio0=type=sb16 port=0x220 irq=5 dma=1
+.EE
+.PP
+With this, the following menu will be presented on boot:
+.IP
+.EX
+Plan 9 Startup Menu:
+====================
+    1. Plan 9 with VGA
+    2. Plan 9 no automatic VGA
+Selection[default==1]: 
+.EE
+.PP
+Selecting item 1 generates the following
+.B plan9.ini
+to be used by the remainder of the bootstrap process:
+.IP
+.EX
+menuitem=vga
+monitor=multisync135
+vgasize=1024x768x8
+ether0=type=i82557
+audio0=type=sb16 port=0x220 irq=5 dma=1
+.EE
+.PP
+and selecting item 2:
+.IP
+.EX
+menuitem=novga
+ether0=type=i82557
+audio0=type=sb16 port=0x220 irq=5 dma=1
+.EE
+.SH "SEE ALSO"
+.IR root (3),
+.IR 9load (10.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.