This is a temporary README file, to help those trying to experiment

with the new boot loader configuration process.  I got a lot of
help from Daniel Sobral, and both Dan and I got help from Mike
Smith.  This really belongs in Warner's UPDATING, but he's not
been answering his email recently, so that will wait a little.

Robert Nordier also gave me a lot of help, but he hasn't seen the
last version, and can't be blamed for my errors.

Approved by:	jkh

Reviewed by:	Mike Smith

1 files changed, 246 insertions, 0 deletions

diff --git a/sys/boot/README b/sys/boot/README
new file mode 100644
index 0000000..aec1c20
--- /dev/null
+++ b/sys/boot/README
@@ -0,0 +1,246 @@
+       README file, for the boot config file setup.  This is meant
+       to explain how to manage the loader configuration process.
+       The boot and loading process is either defined, or being
+       defined in boot(8) and loader(8).
+
+       The ongoing development of the FreeBSD bootloader, and its
+       rapid deployment while still in the development phase, has
+       resulted in a large number of installations with outdated
+       configurations.  Those installations actively tracking the
+       FreeBSD development should also ensure that their bootloader
+       configurations are updated.  If you see files discussed here
+       that your system doesn't yet have, add them yourself.
+
+       This is an effort to give the currently correct method for
+       setting up your boot process.  It includes information on
+       setting up screen savers and plug and play information, and
+       also on recording any changes you make in your kernel
+       configuration.  This file is temporary, because as I noted,
+       the process is still undergoing development, and will still
+       change.  Man pages are coming out, but they're still going
+       to be somewhat fragile for a while.  If you note anything in
+       here that's broken, it would be a good idea to report it to
+       the FreeBSD-current list, or to Daniel C. Sobral
+       <dcs@FreeBSD.org> or Mike Smith <msmith@FreeBSD.org>.
+
+       NOTE:
+
+       Please understand, all this is very current development, and
+       while getting this working for STABLE is a goal, it's not
+       yet ready for that.  It's possible that parts of this might
+       indeed work for stable, but if you're not absolutely sure
+       what you're doing, you're better off not using the
+       information in this README for STABLE.  Use this for current
+       only for a while longer, please!
+
+       After the first two stages in the booting process (described
+       in boot(8)), the last stage of the booting process, called
+       the loader (see loader(8)) reads in the /boot/loader.rc
+       file.  The two lines you should have there are:
+
+       include /boot/loader.4th
+       start
+
+       This reads the ficl (forth) initialization files, then
+       /boot/default/loader.conf.  This file, which strongly
+       resembles in form /etc/rc.conf but functions quite
+       differently, has spots for endless user customization but
+       isn't yet completely finished.  For one thing, it used to
+       assume a /kernel.config instead of a /boot/kernel.conf.
+       Watch the first few lines of /boot/defaults/loader.conf to
+       see if the file name changes.
+
+       [See the section at the end on loader.conf syntax]
+
+       You don't actually want to make any changes to
+       /boot/defaults/loader.conf, the file that is a  hacking-
+       target is:
+
+       /boot/loader.conf
+
+       and might very likely not exist yet on your system).  You
+       should copy /boot/defaults/loader.conf to /boot/loader.conf,
+       and then cut out anything you didn't want changed.
+
+       The start command also loads your kernel for you, so don't
+       put any lines in there like "load kernel", they'll fail (but
+       really have already worked for you).  Start also reads in
+       the file /boot/defaults/loader.conf and /boot/loader.conf.
+       If you don't have /boot/loader.conf, you'll see a message on
+       boot about it, but it's a warning only, no other effects.
+       See the section on loader.conf syntax at the end of this
+       document, for some more pointers on loader.conf syntax.
+
+       The best way to manage splash screens is with entries in
+       /boot/loader.conf, and this is very clearly illustrated in
+       /boot/defaults/loader.conf (which you could just copy over
+       to /boot/loader.conf).  I'm going to illustrate here how you
+       *could* do it in /boot/loader.conf (for information only)
+       but I don't recommend you do this; use the
+       /boot/defaults/loader.conf syntax, it's easier to get it
+       correct.
+
+       You can load your splash screen by putting the following
+       lines into /boot/loader.conf:
+
+       load splash_bmp
+       load -t splash_image_data /path/to/file.bmp
+
+       The top line causes the splash_bmp module to get loaded.
+       The second line has the parameter "-t" which tells the
+       loader that the class of DATA being loaded is not a module,
+       but instead a splash_image_data located in file
+       /path/to/file.bmp.
+
+       To get your plug and play data correctly set, run kget,
+       redirecting the output to /boot/kernel.conf.  Note that kget
+       right now adds an extra "q" to it's output (from the q for
+       quit you press when you exit config), and if you want, you
+       can remove that from the file.  Kget reports data only, so
+       feel free to run it, just to see the output.  Make certain
+       you have the kernel option USERCONFIG set in your kernel, so
+       that you can do a boot -c, to initially set your cards up.
+       Then, edit /boot/loader.conf so that the following line
+       shows up (overwriting, in effect, a similar line in
+       /boot/default/loader.conf):
+
+       userconfig_script_load="YES"
+
+       My own pnp line looks like:
+       pnp 1 0 os irq0 15 irq1 0 drq0 1 drq1 0 port0 1332
+       (kget changes numbers from hexadecimal to decimal).  Note
+       that, at this moment, the change from using /kernel.config
+       to using /boot/kernel.conf as the storage place for kernel
+       config changes is going on.  Take a look at your
+       /boot/defaults/loader.conf, see what's defined as
+       userconfig_script_name, and if you override, make sure the
+       file exists.  Note that the loader only has access to the
+       root filesystem, so be careful where you tell it to read
+       from.
+
+
+          o If you interrupt autoboot, you'll engage interactive
+            mode with loader. Everything you type will have the
+            same effects as if it were lines in /boot/loader.rc.
+
+          o While in interactive mode, you can get help by typing
+            "?", "help [<topic> [<subtopic>]]" and "help index".
+            These are mostly commands one would expect a normal
+            user to use. I recommend you play with them a little,
+            to gain further familiarity with what's going on.
+
+            Note that it is not possible to damage or corrupt your
+            system while experimenting with the loader, as it
+            cannot write to any of your filesystems.
+
+          o The command "unload" will unload everything. This is
+            very useful.  Once loader.rc has finished and the
+            system is in the autoboot count-down, you will usually
+            have the kernel and other modules loaded. Now, suppose
+            your new /kernel is broken, how do you load
+            /kernel.old? By typing:
+
+                 unload
+                 load kernel.old
+                 [any other modules you wish to load]
+                 boot
+
+          o If you use loader.conf, you can do:
+
+                 unload
+                 set kernel_name=kernel.old
+                 boot-conf
+
+            this will then load all the modules you have
+            configured, using kernel.old as kernel, and boot.
+
+          o From loader, you can use the command "more" to read the
+            contents of /boot/loader.rc, if you wish. This is not
+            FreeBSD's more. It is one of loader's builtin commands.
+            Useful if you can't quite recall what you have there.
+            :-) Of course, you can use this command to read
+            anything else you want.
+
+          o "boot -flag" works, "boot kernelname" works, "boot
+            -flag kernelname" doesn't. "boot kernelname -flag"
+            might work, but I'm not sure. The problem is that these
+            flags are kernel's flags, not boot's flags.
+
+          o There are a number of variables that can be set. You
+            can see them in loader.conf, but you can get much more
+            detailed information using the "help" command, eg. help
+            set <variablename>.
+
+          o The variable root_disk_unit is particularly important,
+            as it solves a relatively common problem. This problem
+            shows when the BIOS assign disk units in a different
+            way than the kernel. For example, if you have two IDE
+            disks, one on the primary, the other on the secondary
+            controller, and both as master, the default in most
+            kernels is having the first as wd0, and the second as
+            wd2. If your root partition is in wd2, you'll get an
+            error, because the BIOS sees these disks as 0 and 1
+            (well, 1 and 2), and that's what loader tells the
+            kernel. In this case, "set root_disk_unit=2" solves the
+            problem.  You use this whenever the kernel fails to
+            mount to root partition because it has a wrong unit
+            number.
+
+       FILE OVERVIEW
+
+
+          o /boot/defaults/loader.conf -- Master configuration
+            file, not to be edited.  Overridden by
+            /boot/loader.conf.
+
+          o /boot/loader.conf -- local system customization file,
+            in form very much like /boot/defaults/loader.conf.
+            This file is meant to be used by local users and the
+            sysinstall process.
+
+          o /boot/loader.conf.local -- local installation override
+            file.  This is intended for use by installations with
+            large numbers of systems, to allow global policy
+            overrides.  No FreeBSD tools should ever write this
+            file.
+
+          o /kernel.config -- old location of kernel configuration
+            changes (like pnp changes).
+
+          o /boot/kernel.conf -- new location for kernel
+            configuration changes.
+
+          o /boot/loader.rc -- loader initial configuration file,
+            chiefly used to source in a forth file, and start the
+            configuration process.
+
+       NOTES ON LOADER.CONF SYNTAX
+
+       I'm copy here from the last 11 lines from
+       /boot/defaults/loader.conf:
+
+       ##############################################################
+       ###  Module loading syntax example  ##########################
+       ##############################################################
+
+       #module_load="YES"              # loads module "module"
+       #module_name="realname"         # uses "realname" instead of "module"
+       #module_type="type"             # passes "-t type" to load
+       #module_flags="flags"           # passes "flags" to the module
+       #module_before="cmd"            # executes "cmd" before loading module
+       #module_after="cmd"             # executes "cmd" after loading module
+       #module_error="cmd"             # executes "cmd" if load fails
+
+       The way this works, the command processor used by the loader
+       (which is a subset of forth) inspects  these  variables  for
+       their  suffix,  and  the  7  lines  above illustrate all the
+       currently defined suffixes, and their use.   Take  the  part
+       before  the  underscore,  and customize it i(make it unique)
+       for your particular use, keeping the  suffix  to  allow  the
+       particular function you want to activate.  Extra underscores
+       are fine, because it's only the  sufixes  that  are  scanned
+       for.
+
+
+
+       (authors Chuck Robey and Daniel Sobral).