freebsd-skq/sys/boot
pjd 891c7fcf8c - Split code shared by almost any boot loader into separate files and
clean up most layering violations:

	sys/boot/i386/common/rbx.h:

		RBX_* defines
		OPT_SET()
		OPT_CHECK()

	sys/boot/common/util.[ch]:

		memcpy()
		memset()
		memcmp()
		bcpy()
		bzero()
		bcmp()
		strcmp()
		strncmp() [new]
		strcpy()
		strcat()
		strchr()
		strlen()
		printf()

	sys/boot/i386/common/cons.[ch]:

		ioctrl
		putc()
		xputc()
		putchar()
		getc()
		xgetc()
		keyhit() [now takes number of seconds as an argument]
		getstr()

	sys/boot/i386/common/drv.[ch]:

		struct dsk
		drvread()
		drvwrite() [new]
		drvsize() [new]

	sys/boot/common/crc32.[ch] [new]

	sys/boot/common/gpt.[ch] [new]

- Teach gptboot and gptzfsboot about new files. I haven't touched the
  rest, but there is still a lot of code duplication to be removed.

- Implement full GPT support. Currently we just read primary header and
  partition table and don't care about checksums, etc. After this change we
  verify checksums of primary header and primary partition table and if
  there is a problem we fall back to backup header and backup partition
  table.

- Clean up most messages to use prefix of boot program, so in case of an
  error we know where the error comes from, eg.:

	gptboot: unable to read primary GPT header

- If we can't boot, print boot prompt only once and not every five
  seconds.

- Honour newly added GPT attributes:

	bootme - this is bootable partition
	bootonce - try to boot from this partition only once
	bootfailed - we failed to boot from this partition

- Change boot order of gptboot to the following:

	1. Try to boot from all the partitions that have both 'bootme'
	   and 'bootonce' attributes one by one.
	2. Try to boot from all the partitions that have only 'bootme'
	   attribute one by one.
	3. If there are no partitions with 'bootme' attribute, boot from
	   the first UFS partition.

- The 'bootonce' functionality is implemented in the following way:

	1. Walk through all the partitions and when 'bootonce'
	   attribute is found without 'bootme' attribute, remove
	   'bootonce' attribute and set 'bootfailed' attribute.
	   'bootonce' attribute alone means that we tried to boot from
	   this partition, but boot failed after leaving gptboot and
	   machine was restarted.
	2. Find partition with both 'bootme' and 'bootonce' attributes.
	3. Remove 'bootme' attribute.
	4. Try to execute /boot/loader or /boot/kernel/kernel from that
	   partition. If succeeded we stop here.
	5. If execution failed, remove 'bootonce' and set 'bootfailed'.
	6. Go to 2.

   If whole boot succeeded there is new /etc/rc.d/gptboot script coming
   that will log all partitions that we failed to boot from (the ones with
   'bootfailed' attribute) and will remove this attribute. It will also
   find partition with 'bootonce' attribute - this is the partition we
   booted from successfully. The script will log success and remove the
   attribute.

   All the GPT updates we do here goes to both primary and backup GPT if
   they are valid. We don't touch headers or partition tables when
   checksum doesn't match.

Reviewed by:	arch (Message-ID: <20100917234542.GE1902@garage.freebsd.pl>)
Obtained from:	Wheel Systems Sp. z o.o. http://www.wheelsystems.com
MFC after:	2 weeks
2010-09-24 19:49:12 +00:00
..
arm MFtbemd: 2010-08-23 22:24:11 +00:00
common - Split code shared by almost any boot loader into separate files and 2010-09-24 19:49:12 +00:00
efi MF tbemd: move to using specific architecture makefiles 2010-08-23 01:48:07 +00:00
fdt Add custom kernel configuration and device tree source files for 2010-09-08 19:50:47 +00:00
ficl MF tbemd: Minor tweaks, prefer MACHINE_CPUARCH generally to MACHINE_ARCH (which simplifies some powerpc/powerpc64 ifs) 2010-08-23 01:43:47 +00:00
forth Add support 'device tpm' for amd64. 2010-09-19 14:40:37 +00:00
i386 - Split code shared by almost any boot loader into separate files and 2010-09-24 19:49:12 +00:00
ia64 MF tbemd: Minor tweaks, prefer MACHINE_CPUARCH generally to MACHINE_ARCH (which simplifies some powerpc/powerpc64 ifs) 2010-08-23 01:50:34 +00:00
ofw In the case of non-sequential mappings, ofw_mapmem() could ask Open 2010-09-02 22:26:49 +00:00
pc98 When building world with clang, for gnu/lib/libobjc, sys/boot/i386/boot2 2010-09-21 21:41:45 +00:00
powerpc Provide support in loader for booting 64-bit PowerPC kernels. Like amd64, 2010-07-12 00:49:22 +00:00
sparc64 Merge from powerpc: 2010-09-16 12:05:00 +00:00
uboot MF tbemd: Minor tweaks, prefer MACHINE_CPUARCH generally to MACHINE_ARCH (which simplifies some powerpc/powerpc64 ifs) 2010-08-23 01:50:34 +00:00
zfs - Split code shared by almost any boot loader into separate files and 2010-09-24 19:49:12 +00:00
Makefile MF tbemd: move to using specific architecture makefiles 2010-08-23 01:48:07 +00:00
Makefile.amd64 MF tbemd: move to using specific architecture makefiles 2010-08-23 01:48:07 +00:00
Makefile.arm MF tbemd: move to using specific architecture makefiles 2010-08-23 01:48:07 +00:00
Makefile.i386 MF tbemd: move to using specific architecture makefiles 2010-08-23 01:48:07 +00:00
Makefile.ia64 MF tbemd: move to using specific architecture makefiles 2010-08-23 01:48:07 +00:00
Makefile.inc Fix build when WITH_SSP is set explicitly. 2009-02-21 15:04:31 +00:00
Makefile.pc98 MF tbemd: move to using specific architecture makefiles 2010-08-23 01:48:07 +00:00
Makefile.powerpc MF tbemd: move to using specific architecture makefiles 2010-08-23 01:48:07 +00:00
Makefile.sparc64 MF tbemd: move to using specific architecture makefiles 2010-08-23 01:48:07 +00:00
README Remove obsolete note about the boot loader not being ready for stable. 2005-01-05 22:16:10 +00:00

$FreeBSD$

       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>.

       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.rc (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.rc:

       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=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).