Add more bits for native hammer boot support.
[dragonfly.git] / sys / boot / README
CommitLineData
5ee58eed 1$FreeBSD: src/sys/boot/README,v 1.3 2000/05/01 20:26:17 peter Exp $
365ae791 2$DragonFly: src/sys/boot/README,v 1.4 2005/02/26 12:00:55 swildner Exp $
984263bc
MD
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
365ae791
SW
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
984263bc
MD
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).