Add more bits for native hammer boot support.
[dragonfly.git] / sys / boot / README
1 $FreeBSD: src/sys/boot/README,v 1.3 2000/05/01 20:26:17 peter Exp $
2 $DragonFly: src/sys/boot/README,v 1.4 2005/02/26 12:00:55 swildner Exp $
3
4        README file, for the boot config file setup.  This is meant
5        to explain how to manage the loader configuration process.
6        The boot and loading process is either defined, or being
7        defined in boot(8) and loader(8).
8
9        The ongoing development of the FreeBSD bootloader, and its
10        rapid deployment while still in the development phase, has
11        resulted in a large number of installations with outdated
12        configurations.  Those installations actively tracking the
13        FreeBSD development should also ensure that their bootloader
14        configurations are updated.  If you see files discussed here
15        that your system doesn't yet have, add them yourself.
16
17        This is an effort to give the currently correct method for
18        setting up your boot process.  It includes information on
19        setting up screen savers and plug and play information, and
20        also on recording any changes you make in your kernel
21        configuration.  This file is temporary, because as I noted,
22        the process is still undergoing development, and will still
23        change.  Man pages are coming out, but they're still going
24        to be somewhat fragile for a while.  If you note anything in
25        here that's broken, it would be a good idea to report it to
26        the FreeBSD-current list, or to Daniel C. Sobral
27        <dcs@FreeBSD.org> or Mike Smith <msmith@FreeBSD.org>.
28
29        NOTE:
30
31        Please understand, all this is very current development, and
32        while getting this working for STABLE is a goal, it's not
33        yet ready for that.  It's possible that parts of this might
34        indeed work for stable, but if you're not absolutely sure
35        what you're doing, you're better off not using the
36        information in this README for STABLE.  Use this for current
37        only for a while longer, please!
38
39        After the first two stages in the booting process (described
40        in boot(8)), the last stage of the booting process, called
41        the loader (see loader(8)) reads in the /boot/loader.rc
42        file.  The two lines you should have there are:
43
44        include /boot/loader.4th
45        start
46
47        This reads the ficl (forth) initialization files, then
48        /boot/default/loader.conf.  This file, which strongly
49        resembles in form /etc/rc.conf but functions quite
50        differently, has spots for endless user customization but
51        isn't yet completely finished.  For one thing, it used to
52        assume a /kernel.config instead of a /boot/kernel.conf.
53        Watch the first few lines of /boot/defaults/loader.conf to
54        see if the file name changes.
55
56        [See the section at the end on loader.conf syntax]
57
58        You don't actually want to make any changes to
59        /boot/defaults/loader.conf, the file that is a  hacking-
60        target is:
61
62        /boot/loader.conf
63
64        and might very likely not exist yet on your system).  You
65        should copy /boot/defaults/loader.conf to /boot/loader.conf,
66        and then cut out anything you didn't want changed.
67
68        The start command also loads your kernel for you, so don't
69        put any lines in there like "load kernel", they'll fail (but
70        really have already worked for you).  Start also reads in
71        the file /boot/defaults/loader.conf and /boot/loader.conf.
72        If you don't have /boot/loader.conf, you'll see a message on
73        boot about it, but it's a warning only, no other effects.
74        See the section on loader.conf syntax at the end of this
75        document, for some more pointers on loader.conf syntax.
76
77        The best way to manage splash screens is with entries in
78        /boot/loader.conf, and this is very clearly illustrated in
79        /boot/defaults/loader.conf (which you could just copy over
80        to /boot/loader.conf).  I'm going to illustrate here how you
81        *could* do it in /boot/loader.rc (for information only)
82        but I don't recommend you do this; use the
83        /boot/defaults/loader.conf syntax, it's easier to get it
84        correct.
85
86        You can load your splash screen by putting the following
87        lines into /boot/loader.rc:
88
89        load splash_bmp
90        load -t splash_image_data /path/to/file.bmp
91
92        The top line causes the splash_bmp module to get loaded.
93        The second line has the parameter "-t" which tells the
94        loader that the class of DATA being loaded is not a module,
95        but instead a splash_image_data located in file
96        /path/to/file.bmp.
97
98        To get your plug and play data correctly set, run kget,
99        redirecting the output to /boot/kernel.conf.  Note that kget
100        right now adds an extra "q" to it's output (from the q for
101        quit you press when you exit config), and if you want, you
102        can remove that from the file.  Kget reports data only, so
103        feel free to run it, just to see the output.  Make certain
104        you have the kernel option USERCONFIG set in your kernel, so
105        that you can do a boot -c, to initially set your cards up.
106        Then, edit /boot/loader.conf so that the following line
107        shows up (overwriting, in effect, a similar line in
108        /boot/default/loader.conf):
109
110        userconfig_script_load="YES"
111
112        My own pnp line looks like:
113        pnp 1 0 os irq0 15 irq1 0 drq0 1 drq1 0 port0 1332
114        (kget changes numbers from hexadecimal to decimal).  Note
115        that, at this moment, the change from using /kernel.config
116        to using /boot/kernel.conf as the storage place for kernel
117        config changes is going on.  Take a look at your
118        /boot/defaults/loader.conf, see what's defined as
119        userconfig_script_name, and if you override, make sure the
120        file exists.  Note that the loader only has access to the
121        root filesystem, so be careful where you tell it to read
122        from.
123
124
125           o If you interrupt autoboot, you'll engage interactive
126             mode with loader. Everything you type will have the
127             same effects as if it were lines in /boot/loader.rc.
128
129           o While in interactive mode, you can get help by typing
130             "?", "help [<topic> [<subtopic>]]" and "help index".
131             These are mostly commands one would expect a normal
132             user to use. I recommend you play with them a little,
133             to gain further familiarity with what's going on.
134
135             Note that it is not possible to damage or corrupt your
136             system while experimenting with the loader, as it
137             cannot write to any of your filesystems.
138
139           o The command "unload" will unload everything. This is
140             very useful.  Once loader.rc has finished and the
141             system is in the autoboot count-down, you will usually
142             have the kernel and other modules loaded. Now, suppose
143             your new /kernel is broken, how do you load
144             /kernel.old? By typing:
145
146                  unload
147                  load kernel.old
148                  [any other modules you wish to load]
149                  boot
150
151           o If you use loader.conf, you can do:
152
153                  unload
154                  set kernel=kernel.old
155                  boot-conf
156
157             this will then load all the modules you have
158             configured, using kernel.old as kernel, and boot.
159
160           o From loader, you can use the command "more" to read the
161             contents of /boot/loader.rc, if you wish. This is not
162             FreeBSD's more. It is one of loader's builtin commands.
163             Useful if you can't quite recall what you have there.
164             :-) Of course, you can use this command to read
165             anything else you want.
166
167           o "boot -flag" works, "boot kernelname" works, "boot
168             -flag kernelname" doesn't. "boot kernelname -flag"
169             might work, but I'm not sure. The problem is that these
170             flags are kernel's flags, not boot's flags.
171
172           o There are a number of variables that can be set. You
173             can see them in loader.conf, but you can get much more
174             detailed information using the "help" command, eg. help
175             set <variablename>.
176
177           o The variable root_disk_unit is particularly important,
178             as it solves a relatively common problem. This problem
179             shows when the BIOS assign disk units in a different
180             way than the kernel. For example, if you have two IDE
181             disks, one on the primary, the other on the secondary
182             controller, and both as master, the default in most
183             kernels is having the first as ad0, and the second as
184             ad2. If your root partition is in ad2, you'll get an
185             error, because the BIOS sees these disks as 0 and 1
186             (well, 1 and 2), and that's what loader tells the
187             kernel. In this case, "set root_disk_unit=2" solves the
188             problem.  You use this whenever the kernel fails to
189             mount to root partition because it has a wrong unit
190             number.
191
192        FILE OVERVIEW
193
194
195           o /boot/defaults/loader.conf -- Master configuration
196             file, not to be edited.  Overridden by
197             /boot/loader.conf.
198
199           o /boot/loader.conf -- local system customization file,
200             in form very much like /boot/defaults/loader.conf.
201             This file is meant to be used by local users and the
202             sysinstall process.
203
204           o /boot/loader.conf.local -- local installation override
205             file.  This is intended for use by installations with
206             large numbers of systems, to allow global policy
207             overrides.  No FreeBSD tools should ever write this
208             file.
209
210           o /kernel.config -- old location of kernel configuration
211             changes (like pnp changes).
212
213           o /boot/kernel.conf -- new location for kernel
214             configuration changes.
215
216           o /boot/loader.rc -- loader initial configuration file,
217             chiefly used to source in a forth file, and start the
218             configuration process.
219
220        NOTES ON LOADER.CONF SYNTAX
221
222        I'm copy here from the last 11 lines from
223        /boot/defaults/loader.conf:
224
225        ##############################################################
226        ###  Module loading syntax example  ##########################
227        ##############################################################
228
229        #module_load="YES"              # loads module "module"
230        #module_name="realname"         # uses "realname" instead of "module"
231        #module_type="type"             # passes "-t type" to load
232        #module_flags="flags"           # passes "flags" to the module
233        #module_before="cmd"            # executes "cmd" before loading module
234        #module_after="cmd"             # executes "cmd" after loading module
235        #module_error="cmd"             # executes "cmd" if load fails
236
237        The way this works, the command processor used by the loader
238        (which is a subset of forth) inspects  these  variables  for
239        their  suffix,  and  the  7  lines  above illustrate all the
240        currently defined suffixes, and their use.   Take  the  part
241        before  the  underscore,  and customize it i(make it unique)
242        for your particular use, keeping the  suffix  to  allow  the
243        particular function you want to activate.  Extra underscores
244        are fine, because it's only the  sufixes  that  are  scanned
245        for.
246
247
248
249        (authors Chuck Robey and Daniel Sobral).