Merge http://jdike.stearns.org:5000/doc-2.5

into hostme.bitkeeper.com:/ua/repos/u/uml/doc-2.5

arch/um/Kconfig

@@ -64,9 +64,41 @@ config BINFMT_MISC
 
 config HOSTFS
 	tristate "Host filesystem"
+	help
+        While the User-Mode Linux port uses its own root file system for
+        booting and normal file access, this module lets the UML user
+        access files stored on the host.  It does not require any
+        network connection between the Host and UML.  An example use of
+        this might be:
+
+        mount none /tmp/fromhost -t hostfs -o /tmp/umlshare
+
+        where /tmp/fromhost is an empty directory inside UML and
+        /tmp/umlshare is a directory on the host with files the UML user
+        wishes to access.
+
+        For more information, see
+        <http://user-mode-linux.sourceforge.net/hostfs.html>.
+
+        If you'd like to be able to work with files stored on the host, 
+        say Y or M here; otherwise say N.
+
 
 config MCONSOLE
 	bool "Management console"
+	help
+        The user mode linux management console is a low-level interface to
+        the kernel, somewhat like the i386 SysRq interface.  Since there is
+        a full-blown operating system running under every user mode linux
+        instance, there is much greater flexibility possible than with the
+        SysRq mechanism.
+
+        If you answer 'Y' to this option, to use this feature, you need the
+        mconsole client (called uml_mconsole) which is present in CVS in
+        2.4.5-9um and later (path /tools/mconsole), and is also in the
+        distribution RPM package in 2.4.6 and later.
+
+        It is safe to say 'Y' here.
 
 config MAGIC_SYSRQ
 	bool "Magic SysRq key"
@@ -77,6 +109,16 @@ config HOST_2G_2G
 
 config UML_SMP
 	bool "Symmetric multi-processing support"
+	help
+        This option enables UML SMP support.  UML implements virtual SMP by
+        allowing as many processes to run simultaneously on the host as
+        there are virtual processors configured.  Obviously, if the host is
+        a uniprocessor, those processes will timeshare, but, inside UML,
+        will appear to be running simultaneously.  If the host is a
+        multiprocessor, then UML processes may run simultaneously, depending
+        on the host scheduler.
+        CONFIG_SMP will be set to whatever this option is set to.
+        It is safe to leave this unchanged.
 
 config SMP
 	bool
@@ -90,10 +132,27 @@ config NR_CPUS
 config NEST_LEVEL
 	int "Nesting level"
 	default "0"
+	help
+        This is set to the number of layers of UMLs that this UML will be run
+        in.  Normally, this is zero, meaning that it will run directly on the
+        host.  Setting it to one will build a UML that can run inside a UML
+        that is running on the host.  Generally, if you intend this UML to run
+        inside another UML, set CONFIG_NEST_LEVEL to one more than the host 
+        UML.
+
+        Note that if the hosting UML has its CONFIG_KERNEL_HALF_GIGS set to 
+        greater than one, then the guest UML should have its CONFIG_NEST_LEVEL 
+        set to the host's CONFIG_NEST_LEVEL + CONFIG_KERNEL_HALF_GIGS.
+        Only change this if you are running nested UMLs.
 
 config KERNEL_HALF_GIGS
 	int "Kernel address space size (in .5G units)"
 	default "1"
+	help
+        This determines the amount of address space that UML will allocate for
+        its own, measured in half Gigabyte units.  The default is 1.
+        Change this only if you need to boot UML with an unusually large amount
+        of physical memory.
 
 config HIGHMEM
 	bool "Highmem support"
@@ -156,6 +215,14 @@ config DEBUG_SLAB
 
 config DEBUGSYM
 	bool "Enable kernel debugging symbols"
+	help
+        When this is enabled, the User-Mode Linux binary will include
+        debugging symbols.  This enlarges the binary by a few megabytes,
+        but aids in tracking down kernel problems in UML.  It is required
+        if you intend to do any kernel development.
+
+        If you're truly short on disk space or don't expect to report any
+        bugs back to the UML developers, say N, otherwise say Y.
 
 config PT_PROXY
 	bool "Enable ptrace proxy"
@@ -164,10 +231,28 @@ config PT_PROXY
 config GPROF
 	bool "Enable gprof support"
 	depends on DEBUGSYM
+	help
+        This allows profiling of a User-Mode Linux kernel with the gprof
+        utility.
+
+        See <http://user-mode-linux.sourceforge.net/gprof.html> for more
+        details.
+
+        If you're involved in UML kernel development and want to use gprof,
+        say Y.  If you're unsure, say N.
 
 config GCOV
 	bool "Enable gcov support"
 	depends on DEBUGSYM
+	help
+        This option allows developers to retrieve coverage data from a UML
+        session.
+
+        See <http://user-mode-linux.sourceforge.net/gcov.html> for more
+        details.
+
+        If you're involved in UML kernel development and want to use gcov,
+        say Y.  If you're unsure, say N.
 
 endmenu
 

arch/um/Kconfig_block

@@ -3,10 +3,31 @@ menu "Block Devices"
 
 config BLK_DEV_UBD
 	bool "Virtual block device"
+	help
+        The User-Mode Linux port includes a driver called UBD which will let
+        you access arbitrary files on the host computer as block devices.
+        Unless you know that you do not need such virtual block devices say
+        Y here.
 
 config BLK_DEV_UBD_SYNC
 	bool "Always do synchronous disk IO for UBD"
 	depends on BLK_DEV_UBD
+	help
+        Writes to the virtual block device are not immediately written to the 
+	host's disk; this may cause problems if, for example, the 
+	User-Mode Linux 'Virtual Machine' uses a journalling filesystem and 
+	the host computer crashes.
+
+        Synchronous operation (i.e. always writing data to the host's disk
+        immediately) is configurable on a per-UBD basis by using a special
+        kernel command line option.  Alternatively, you can say Y here to
+        turn on synchronous operation by default for all block devices.
+
+        If you're running a journalling file system (like reiserfs, for
+        example) in your virtual machine, you will want to say Y here.  If
+        you care for the safety of the data in your virtual machine, Y is a
+        wise choice too.  In all other cases (for example, if you're just
+        playing around with User-Mode Linux) you can choose N.
 
 config BLK_DEV_LOOP
 	tristate "Loopback device support"
@@ -29,6 +50,19 @@ config BLK_DEV_INITRD
 
 config MMAPPER
 	tristate "Example IO memory driver"
+	help
+        The User-Mode Linux port can provide support for IO Memory
+        emulation with this option.  This allows a host file to be
+        specified as an I/O region on the kernel command line. That file
+        will be mapped into UML's kernel address space where a driver can
+        locate it and do whatever it wants with the memory, including
+        providing an interface to it for UML processes to use.
+
+        For more information, see
+        <http://user-mode-linux.sourceforge.net/iomem.html>.
+
+        If you'd like to be able to provide a simulated IO port space for
+        User-Mode Linux processes, say Y.  If unsure, say N.
 
 endmenu
 

arch/um/Kconfig_char

@@ -7,36 +7,104 @@ config STDIO_CONSOLE
 
 config SSL
 	bool "Virtual serial line"
+	help
+        The User-Mode Linux environment allows you to create virtual serial
+        lines on the UML that are usually made to show up on the host as
+        ttys or ptys.
+
+        See <http://user-mode-linux.sourceforge.net/input.html> for more
+        information and command line examples of how to use this facility.
+
+        Unless you have a specific reason for disabling this, say Y.
 
 config FD_CHAN
 	bool "file descriptor channel support"
+	help
+        This option enables support for attaching UML consoles and serial
+        lines to already set up file descriptors.  Generally, the main
+        console is attached to file descriptors 0 and 1 (stdin and stdout),
+        so it would be wise to leave this enabled unless you intend to
+        attach it to some other host device.
 
 config NULL_CHAN
 	bool "null channel support"
+	help
+        This option enables support for attaching UML consoles and serial
+        lines to a device similar to /dev/null.  Data written to it disappears
+        and there is never any data to be read.
 
 config PORT_CHAN
 	bool "port channel support"
+	help
+        This option enables support for attaching UML consoles and serial
+        lines to host portals.  They may be accessed with 'telnet <host>
+        <port number>'.  Any number of consoles and serial lines may be
+        attached to a single portal, although what UML device you get when
+        you telnet to that portal will be unpredictable.
+        It is safe to say 'Y' here.
 
 config PTY_CHAN
 	bool "pty channel support"
+	help
+        This option enables support for attaching UML consoles and serial
+        lines to host pseudo-terminals.  Access to both traditional
+        pseudo-terminals (/dev/pty*) and pts pseudo-terminals are controlled
+        with this option.  The assignment of UML devices to host devices
+        will be announced in the kernel message log.
+        It is safe to say 'Y' here.
 
 config TTY_CHAN
 	bool "tty channel support"
+	help
+        This option enables support for attaching UML consoles and serial
+        lines to host terminals.  Access to both virtual consoles
+        (/dev/tty*) and the slave side of pseudo-terminals (/dev/ttyp* and
+        /dev/pts/*) are controlled by this option.
+        It is safe to say 'Y' here.
 
 config XTERM_CHAN
 	bool "xterm channel support"
+	help
+        This option enables support for attaching UML consoles and serial
+        lines to xterms.  Each UML device so assigned will be brought up in
+        its own xterm.
+        If you disable this option, then CONFIG_PT_PROXY will be disabled as
+        well, since UML's gdb currently requires an xterm.
+        It is safe to say 'Y' here.
 
 config CON_ZERO_CHAN
 	string "Default main console channel initialization"
 	default "fd:0,fd:1"
+	help
+        This is the string describing the channel to which the main console
+        will be attached by default.  This value can be overridden from the
+        command line.  The default value is "fd:0,fd:1", which attaches the
+        main console to stdin and stdout.
+        It is safe to leave this unchanged.
 
 config CON_CHAN
 	string "Default console channel initialization"
 	default "xterm"
+	help
+        This is the string describing the channel to which all consoles
+        except the main console will be attached by default.  This value can
+        be overridden from the command line.  The default value is "xterm",
+        which brings them up in xterms.
+        It is safe to leave this unchanged, although you may wish to change
+        this if you expect the UML that you build to be run in environments
+        which don't have X or xterm available.
 
 config SSL_CHAN
 	string "Default serial line channel initialization"
 	default "pty"
+	help
+        This is the string describing the channel to which the serial lines
+        will be attached by default.  This value can be overridden from the
+        command line.  The default value is "pty", which attaches them to
+        traditional pseudo-terminals.
+        It is safe to leave this unchanged, although you may wish to change
+        this if you expect the UML that you build to be run in environments
+        which don't have a set of /dev/pty* devices.
 
 config UNIX98_PTYS
 	bool "Unix98 PTY support"
@@ -63,6 +131,11 @@ config UML_WATCHDOG
 
 config UML_SOUND
 	tristate "Sound support"
+	help
+        This option enables UML sound support.  If enabled, it will pull in
+        soundcore and the UML hostaudio relay, which acts as a intermediary
+        between the host's dsp and mixer devices and the UML sound system.
+        It is safe to say 'Y' here.
 
 config SOUND
 	tristate
@@ -72,8 +145,5 @@ config HOSTAUDIO
 	tristate
 	default UML_SOUND
 
-config TTY_LOG
-	bool "Enable tty logging"
-
 endmenu
 

arch/um/config_block.in

-mainmenu_option next_comment
-comment 'Block Devices'
-
-bool 'Virtual block device' CONFIG_BLK_DEV_UBD
-dep_bool '  Always do synchronous disk IO for UBD' CONFIG_BLK_DEV_UBD_SYNC $CONFIG_BLK_DEV_UBD
-tristate 'Loopback device support' CONFIG_BLK_DEV_LOOP
-dep_tristate 'Network block device support' CONFIG_BLK_DEV_NBD $CONFIG_NET
-tristate 'RAM disk support' CONFIG_BLK_DEV_RAM
-if [ "$CONFIG_BLK_DEV_RAM" = "y" -o "$CONFIG_BLK_DEV_RAM" = "m" ]; then
-	int '   Default RAM disk size' CONFIG_BLK_DEV_RAM_SIZE 4096
-fi
-dep_bool '  Initial RAM disk (initrd) support' CONFIG_BLK_DEV_INITRD $CONFIG_BLK_DEV_RAM
-
-tristate 'Example IO memory driver' CONFIG_MMAPPER
-
-endmenu

arch/um/config_char.in

-mainmenu_option next_comment
-comment 'Character Devices'
-
-define_bool CONFIG_STDIO_CONSOLE y
-
-bool 'Virtual serial line' CONFIG_SSL
-
-bool 'file descriptor channel support' CONFIG_FD_CHAN
-bool 'null channel support' CONFIG_NULL_CHAN
-bool 'port channel support' CONFIG_PORT_CHAN
-bool 'pty channel support' CONFIG_PTY_CHAN
-bool 'tty channel support' CONFIG_TTY_CHAN
-bool 'xterm channel support' CONFIG_XTERM_CHAN
-string 'Default main console channel initialization' CONFIG_CON_ZERO_CHAN \
-            "fd:0,fd:1"
-string 'Default console channel initialization' CONFIG_CON_CHAN "xterm"
-string 'Default serial line channel initialization' CONFIG_SSL_CHAN "pty"
-
-
-bool 'Unix98 PTY support' CONFIG_UNIX98_PTYS
-if [ "$CONFIG_UNIX98_PTYS" = "y" ]; then
-   int 'Maximum number of Unix98 PTYs in use (0-2048)' CONFIG_UNIX98_PTY_COUNT 256
-fi
-
-bool 'Watchdog Timer Support' CONFIG_WATCHDOG
-dep_bool '  Disable watchdog shutdown on close' CONFIG_WATCHDOG_NOWAYOUT \
-	$CONFIG_WATCHDOG
-dep_tristate '  Software Watchdog' CONFIG_SOFT_WATCHDOG $CONFIG_WATCHDOG
-dep_tristate '  UML watchdog' CONFIG_UML_WATCHDOG $CONFIG_WATCHDOG
-
-tristate 'Sound support' CONFIG_UML_SOUND
-define_tristate CONFIG_SOUND $CONFIG_UML_SOUND
-define_tristate CONFIG_HOSTAUDIO $CONFIG_UML_SOUND
-
-bool 'Enable tty logging' CONFIG_TTY_LOG
-
-endmenu

arch/um/config_net.in

-mainmenu_option next_comment
-comment 'Network Devices'
-
-# UML virtual driver
-bool 'Virtual network device' CONFIG_UML_NET
-
-dep_bool '  Ethertap transport' CONFIG_UML_NET_ETHERTAP $CONFIG_UML_NET
-dep_bool '  TUN/TAP transport' CONFIG_UML_NET_TUNTAP $CONFIG_UML_NET
-dep_bool '  SLIP transport' CONFIG_UML_NET_SLIP $CONFIG_UML_NET
-dep_bool '  Daemon transport' CONFIG_UML_NET_DAEMON $CONFIG_UML_NET
-dep_bool '  Multicast transport' CONFIG_UML_NET_MCAST $CONFIG_UML_NET
-dep_bool '  pcap transport' CONFIG_UML_NET_PCAP $CONFIG_UML_NET
-
-# Below are hardware-independent drivers mirrored from
-# drivers/net/Config.in. It would be nice if Linux
-# had HW independent drivers separated from the other
-# but it does not. Until then each non-ISA/PCI arch
-# needs to provide it's own menu of network drivers
-
-tristate 'Dummy net driver support' CONFIG_DUMMY
-tristate 'Bonding driver support' CONFIG_BONDING
-tristate 'EQL (serial line load balancing) support' CONFIG_EQUALIZER
-tristate 'Universal TUN/TAP device driver support' CONFIG_TUN
-if [ "$CONFIG_EXPERIMENTAL" = "y" ]; then
-   if [ "$CONFIG_NETLINK" = "y" ]; then
-      tristate 'Ethertap network tap (OBSOLETE)' CONFIG_ETHERTAP
-   fi
-fi
-
-tristate 'PPP (point-to-point protocol) support' CONFIG_PPP
-if [ ! "$CONFIG_PPP" = "n" ]; then
-   dep_bool '  PPP multilink support (EXPERIMENTAL)' CONFIG_PPP_MULTILINK $CONFIG_EXPERIMENTAL
-   dep_bool '  PPP filtering' CONFIG_PPP_FILTER $CONFIG_FILTER
-   dep_tristate '  PPP support for async serial ports' CONFIG_PPP_ASYNC $CONFIG_PPP
-   dep_tristate '  PPP support for sync tty ports' CONFIG_PPP_SYNC_TTY $CONFIG_PPP
-   dep_tristate '  PPP Deflate compression' CONFIG_PPP_DEFLATE $CONFIG_PPP
-   dep_tristate '  PPP BSD-Compress compression' CONFIG_PPP_BSDCOMP $CONFIG_PPP
-   dep_tristate '  PPP over Ethernet (EXPERIMENTAL)' CONFIG_PPPOE $CONFIG_PPP $CONFIG_EXPERIMENTAL
-fi
-
-tristate 'SLIP (serial line) support' CONFIG_SLIP
-dep_bool '  CSLIP compressed headers' CONFIG_SLIP_COMPRESSED $CONFIG_SLIP
-dep_bool '  Keepalive and linefill' CONFIG_SLIP_SMART $CONFIG_SLIP
-dep_bool '  Six bit SLIP encapsulation' CONFIG_SLIP_MODE_SLIP6 $CONFIG_SLIP
-
-endmenu

arch/um/config_scsi.in

-comment 'SCSI support type (disk, tape, CD-ROM)'
-
-dep_tristate '  SCSI disk support' CONFIG_BLK_DEV_SD $CONFIG_SCSI
-
-if [ "$CONFIG_BLK_DEV_SD" != "n" ]; then
-   int  'Maximum number of SCSI disks that can be loaded as modules' CONFIG_SD_EXTRA_DEVS 40
-fi
-
-dep_tristate '  SCSI tape support' CONFIG_CHR_DEV_ST $CONFIG_SCSI
-
-dep_tristate '  SCSI CD-ROM support' CONFIG_BLK_DEV_SR $CONFIG_SCSI
-
-if [ "$CONFIG_BLK_DEV_SR" != "n" ]; then
-   bool '    Enable vendor-specific extensions (for SCSI CDROM)' CONFIG_BLK_DEV_SR_VENDOR
-   int  'Maximum number of CDROM devices that can be loaded as modules' CONFIG_SR_EXTRA_DEVS 2
-fi
-dep_tristate '  SCSI generic support' CONFIG_CHR_DEV_SG $CONFIG_SCSI
-
-comment 'Some SCSI devices (e.g. CD jukebox) support multiple LUNs'
-
-#if [ "$CONFIG_EXPERIMENTAL" = "y" ]; then
-   bool '  Enable extra checks in new queueing code' CONFIG_SCSI_DEBUG_QUEUES
-#fi
-
-bool '  Probe all LUNs on each SCSI device' CONFIG_SCSI_MULTI_LUN
-  
-bool '  Verbose SCSI error reporting (kernel size +=12K)' CONFIG_SCSI_CONSTANTS
-bool '  SCSI logging facility' CONFIG_SCSI_LOGGING
-
-dep_tristate 'SCSI debugging host simulator (EXPERIMENTAL)' CONFIG_SCSI_DEBUG $CONFIG_SCSI