/[gentoo]/xml/htdocs/doc/en/handbook/hb-install-mips-bootloader.xml
Gentoo

Contents of /xml/htdocs/doc/en/handbook/hb-install-mips-bootloader.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.23 - (show annotations) (download) (as text)
Mon May 9 19:47:22 2011 UTC (3 years, 2 months ago) by nightmorph
Branch: MAIN
Changes since 1.22: +7 -6 lines
File MIME type: application/xml
update  handbooks for lazy unmount, bug 361561, thanks to swift for the patches

1 <?xml version='1.0' encoding='UTF-8'?>
2 <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
4 <!-- The content of this document is licensed under the CC-BY-SA license -->
5 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6
7 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-mips-bootloader.xml,v 1.22 2011/03/23 09:16:01 nightmorph Exp $ -->
8
9 <sections>
10
11 <abstract>
12 On both Silicon Graphics machines, and on Cobalt servers, both require the use
13 of a bootloader to load the kernel. This section covers setting up
14 arcboot/arcload (for SGI machines) and colo for Cobalt servers.
15 </abstract>
16
17 <version>11</version>
18 <date>2011-05-09</date>
19
20 <section id="sgi">
21 <title>Silicon Graphics Machines -- Setting Up arcload</title>
22 <subsection>
23 <title>Which one?</title>
24 <body>
25
26 <p>
27 On SGI machines, we use the <c>arcload</c> boot loader. In previous releases,
28 we also provided <c>arcboot</c>, however it has been officially declared
29 obsolete, in favour of <c>arcload</c>.
30 </p>
31
32 <note>
33 The SGI volume header filenames are limited to 8 characters, and there may be
34 no more than 16 files contained in a single volume header.
35 </note>
36
37 </body>
38 </subsection>
39
40 <subsection>
41 <title>Installing arcload</title>
42 <body>
43
44 <p>
45 <c>arcload</c> was written for machines that require 64-bit kernels, and
46 therefore can't use <c>arcboot</c> (which can't easily be compiled as a 64-bit
47 binary). It also works around peculiarities that arise when loading kernels
48 directly from the volume header. So, now you know what this is about, we can
49 proceed with the installation:
50 </p>
51
52 <pre caption="Merging arcload and dvhtool">
53 # <i>emerge arcload dvhtool</i>
54 </pre>
55
56 <p>
57 Once this has finished, you should find the <c>arcload</c> binary in
58 <path>/usr/lib/arcload</path>. Now, two files exist:
59 </p>
60
61 <ul>
62 <li>
63 <c>sashARCS</c>: The 32-bit binary for Indy, Indigo2 (R4k), Challenge S and
64 O2 systems
65 </li>
66 <li>
67 <c>sash64</c>: The 64-bit binary for Octane/Octane2, Origin 200/2000 and
68 Indigo2 Impact systems
69 </li>
70 </ul>
71
72 <p>
73 Use <c>dvhtool</c> to install the appropriate binary for your system into the
74 volume header:
75 </p>
76
77 <pre caption="Placing arcload in the volume header">
78 <comment>(Indy/Indigo2/Challenge S/O2 users)</comment>
79 # <i>dvhtool --unix-to-vh /usr/lib/arcload/sashARCS sashARCS</i>
80
81 <comment>(Indigo2 Impact/Octane/Octane2/Origin 200/Origin 2000 users)</comment>
82 # <i>dvhtool --unix-to-vh /usr/lib/arcload/sash64 sash64</i>
83 </pre>
84
85 <note>
86 You don't have to use the name <c>sashARCS</c> or <c>sash64</c>, unless you are
87 installing to the volume header of a bootable CD. For normal boot from
88 hard-disk, you may name them something else if you wish.
89 </note>
90
91 <p>
92 Now just use <c>dvhtool</c> to verify they are in the volume header.
93 </p>
94
95 <pre caption="Checking arcload is present in the volume header">
96 # <i>dvhtool --print-volume-directory</i>
97 ----- directory entries -----
98 Entry #0, name "sash64", start 4, bytes 55859
99 #
100 </pre>
101
102 <p>
103 Now, the <c>arc.cf</c> file has a C-like syntax. For the full detail on how one
104 configures it, see the <uri
105 link="http://www.linux-mips.org/wiki/Arcload">arcload page on the Linux/MIPS
106 wiki</uri>. In short, you define a number of options, which you enable and
107 disable at boot time using the <c>OSLoadFilename</c> variable.
108 </p>
109
110 <pre caption="An example arc.cf">
111 <comment># ARCLoad Configuration</comment>
112
113 <comment># Some default settings...</comment>
114 append "root=/dev/sda3";
115 append "ro";
116 append "console=ttyS0,9600";
117
118 <comment># Our main definition. ip28 may be changed if you wish.</comment>
119 ip28 {
120 <comment># Definition for a "working" kernel</comment>
121 <comment># Select this by setting OSLoadFilename="ip28(working)"</comment>
122 working {
123 description "SGI Indigo2 Impact R10000\n\r";
124 image system "/working";
125 }
126
127 <comment># Definition for a "new" kernel</comment>
128 <comment># Select this by setting OSLoadFilename="ip28(new)"</comment>
129 new {
130 description "SGI Indigo2 Impact R10000 - Testing Kernel\n\r";
131 image system "/new";
132 }
133
134 <comment># For debugging a kernel</comment>
135 <comment># Select this by setting OSLoadFilename="ip28(working,debug)"</comment>
136 <comment># or OSLoadFilename="ip28(new,debug)"</comment>
137 debug {
138 description "Debug console";
139 append "init=/bin/bash";
140 }
141 }
142 </pre>
143
144 <p>
145 Starting with <c>arcload-0.5</c>, <path>arc.cf</path> and kernels may reside
146 either in the volume header, or on a partition. If you wish to utilise this
147 newer feature, you may instead place the files in your <path>/boot</path>
148 partition (or <path>/</path> if your boot partition is not separate).
149 <c>arcload</c> uses the filesystem driver code from the popular <c>grub</c>
150 bootloader, and thus supports the same range of filesystems.
151 </p>
152
153 <pre caption="Placing arc.cf and kernel in the volume header">
154 # <i>dvhtool --unix-to-vh arc.cf arc.cf</i>
155 # <i>dvhtool --unix-to-vh /usr/src/linux/vmlinux new</i>
156 </pre>
157
158 <p>
159 With this done, now all that's left is to set some options in the PROM. See the
160 section on <uri link="#reboot">Rebooting the System</uri>.
161 </p>
162
163 </body>
164 </subsection>
165
166 </section>
167
168 <section id="cobalt">
169 <title>Cobalt MicroServers -- Setting Up CoLo</title>
170 <subsection>
171 <title>Installing CoLo</title>
172 <body>
173
174 <p>
175 On Cobalt servers, these machines have a much less capable firmware installed
176 on chip. The Cobalt BOOTROM is primitive, by comparison to the SGI PROM, and
177 has a number of serious limitations.
178 </p>
179
180 <ul>
181 <li>
182 There's a 675kB (approximate) limit on kernels. The current size of Linux
183 2.4 makes it nearly impossible to make a kernel this size. Linux 2.6 is
184 totally out of the question.
185 </li>
186 <li>
187 64-bit kernels are not supported by the stock firmware (although these are
188 highly experimental on Cobalt machines at this time)
189 </li>
190 <li>
191 The shell is basic at best
192 </li>
193 </ul>
194
195 <p>
196 To overcome these limitations, an alternative firmware, called <uri
197 link="http://www.colonel-panic.org/cobalt-mips/">CoLo</uri> (Cobalt Loader) was
198 developed. This is a BOOTROM image that can either be flashed into the chip
199 inside the Cobalt server, or loaded from the existing firmware.
200 </p>
201
202 <note>
203 This guide will take you through setting up CoLo so that it is loaded by the
204 stock firmware. This is the only truly safe, and recommended way to set up
205 CoLo.
206 </note>
207
208 <warn>
209 You may, if you wish, flash it into the server, and totally replace the
210 original firmware -- however, you are entirely on your own in that endeavour.
211 Should anything go wrong, you will need to physically remove the BOOTROM and
212 reprogram it yourself with the stock firmware. If you are not sure how to do
213 this -- then <e>DO NOT</e> flash your machine. We take no responsibility for
214 whatever happens if you ignore this advice.
215 </warn>
216
217 <p>
218 Okay, with the warnings over now, we'll get on with installing CoLo. First,
219 start by emerging the package.
220 </p>
221
222 <pre caption="Emerging colo">
223 # <i>emerge colo</i>
224 </pre>
225
226 <p>
227 With that installed (I hope you read those messages ;-) you should be able to
228 look inside the <path>/usr/lib/colo</path> directory to find two files,
229 <path>colo-chain.elf</path>: the "kernel" for the stock firmware to load, and
230 <path>colo-rom-image.bin</path>: a ROM image for flashing into the BOOTROM. We
231 start by mounting /boot and dumping a compressed copy of
232 <path>colo-chain.elf</path> in <path>/boot</path> where the system expects it.
233 </p>
234
235 <pre caption="Putting CoLo in its place">
236 # <i>gzip -9vc /usr/lib/colo/colo-chain.elf &gt; /boot/vmlinux.gz</i>
237 </pre>
238
239 </body>
240 </subsection>
241
242 <subsection>
243 <title>Configuring CoLo</title>
244
245 <body>
246
247 <p>
248 Now, when the system first boots up, it'll load CoLo which will spit up a menu
249 on the back LCD. The first option (and default that is assumed after roughly 5
250 seconds) is to boot to the hard disk. The system would then attempt to mount
251 the first Linux partition it finds, and run the script
252 <path>default.colo</path>. The syntax is fully documented in the CoLo
253 documentation (have a peek at
254 <path>/usr/share/doc/colo-X.YY/README.shell.gz</path> -- where X.YY is the
255 version installed), and is very simple.
256 </p>
257
258 <note>
259 Just a tip: when installing kernels, I usually create two kernel images,
260 <path>kernel.gz.working</path> -- a known working kernel, and
261 <path>kernel.gz.new</path> -- a kernel that's just been compiled. You can
262 either use symlinks to point to the curent "new" and "working" kernels, or just
263 rename the kernel images.
264 </note>
265
266 <pre caption="A basic default.colo">
267 <comment>#:CoLo:#</comment>
268 mount hda1
269 load /kernel.gz.working
270 execute root=/dev/sda3 ro console=ttyS0,115200
271 </pre>
272
273 <note>
274 CoLo will refuse to load a script that does not begin with the <c>#:CoLo:#</c>
275 line. Think of it as the equivalent of saying <c>#!/bin/sh</c> in shell
276 scripts.
277 </note>
278
279 <p>
280 It is also possible to ask a question, such as which kernel &amp; configuration
281 you'd like to boot, with a default timeout. This configuration does exactly
282 this, asks the user which kernel they wish to use, and executes the chosen
283 image. <path>vmlinux.gz.new</path> and <path>vmlinux.gz.working</path> may be
284 actual kernel images, or just symlinks pointing to the kernel images on that
285 disk. The <c>50</c> argument to <c>select</c> specifies that it should proceed
286 with the first option ("Working") after 50/10 seconds.
287 </p>
288
289 <pre caption="Menu-based configuration">
290 <comment>#:CoLo:#</comment>
291
292 lcd "Mounting hda1"
293 mount hda1
294 select "Which Kernel?" 50 Working New
295
296 goto {menu-option}
297 var image-name vmlinux.gz.working
298 goto 3f
299 @var image-name vmlinux.gz.working
300 goto 2f
301 @var image-name vmlinux.gz.new
302
303 @lcd "Loading Linux" {image-name}
304 load /{image-name}
305 lcd "Booting..."
306 execute root=/dev/sda5 ro console=ttyS0,115200
307 boot
308 </pre>
309
310 <p>
311 See the documentation in <path>/usr/share/doc/colo-VERSION</path> for more
312 details.
313 </p>
314
315 </body>
316
317 </subsection>
318 </section>
319
320 <section>
321 <title>Setting up for Serial Console</title>
322
323 <subsection>
324 <body>
325
326 <p>
327 Okay, the Linux installation as it stands now, would boot fine, but assumes
328 you're going to be logged in at a physical terminal. On Cobalt machines, this
329 is particularly bad -- there's no such thing as a physical terminal.
330 </p>
331
332 <note>
333 Those who do have the luxury of a supported video chipset may skip this section
334 if they wish.
335 </note>
336
337 <p>
338 First, pull up an editor and hack away at <path>/etc/inittab</path>. Further
339 down in the file, you'll see something like this:
340 </p>
341
342 <pre caption="inittab Configuration">
343 <comment># SERIAL CONSOLE</comment>
344 <comment>#c0:12345:respawn:/sbin/agetty 9600 ttyS0 vt102</comment>
345
346 <comment># TERMINALS</comment>
347 c1:12345:respawn:/sbin/agetty 38400 tty1 linux
348 c2:12345:respawn:/sbin/agetty 38400 tty2 linux
349 c3:12345:respawn:/sbin/agetty 38400 tty3 linux
350 c4:12345:respawn:/sbin/agetty 38400 tty4 linux
351 c5:12345:respawn:/sbin/agetty 38400 tty5 linux
352 c6:12345:respawn:/sbin/agetty 38400 tty6 linux
353
354 <comment># What to do at the "Three Finger Salute".</comment>
355 ca:12345:ctrlaltdel:/sbin/shutdown -r now
356 </pre>
357
358 <p>
359 First, uncomment the <c>c0</c> line. By default, it's set to use a terminal
360 baud rate of 9600 bps. On Cobalt servers, you may want to change this to 115200
361 to match the baud rate decided by the BOOT ROM. This is how that section looks
362 on my machine. On a headless machine (e.g. Cobalt servers), I'll also recommend
363 commenting out the local terminal lines (<c>c1</c> through to <c>c6</c>) as
364 these have a habit of misbehaving when they can't open <path>/dev/ttyX</path>.
365 </p>
366
367 <pre caption="Example snippet from inittab">
368 <comment># SERIAL CONSOLE</comment>
369 c0:12345:respawn:/sbin/agetty 115200 ttyS0 vt102
370
371 <comment># TERMINALS -- These are useless on a headless qube</comment>
372 <comment>#c1:12345:respawn:/sbin/agetty 38400 tty1 linux</comment>
373 <comment>#c2:12345:respawn:/sbin/agetty 38400 tty2 linux</comment>
374 <comment>#c3:12345:respawn:/sbin/agetty 38400 tty3 linux</comment>
375 <comment>#c4:12345:respawn:/sbin/agetty 38400 tty4 linux</comment>
376 <comment>#c5:12345:respawn:/sbin/agetty 38400 tty5 linux</comment>
377 <comment>#c6:12345:respawn:/sbin/agetty 38400 tty6 linux</comment>
378 </pre>
379
380 <p>
381 Now, lastly... we have to tell the system, that the local serial port can be
382 trusted as a secure terminal. The file we need to poke at is
383 <path>/etc/securetty</path>. It contains a list of terminals that the system
384 trusts. We simply stick in two more lines, permitting the serial line to be
385 used for <c>root</c> logins.
386 </p>
387
388 <pre caption="Enabling root logins on serial console">
389 <comment>(/dev/ttyS0 -- the traditional name for the first serial port)</comment>
390 # <i>echo 'ttyS0' >> /etc/securetty</i>
391
392 <comment>(Lately, Linux also calls this /dev/tts/0 -- so we add this
393 too)</comment>
394 # <i>echo 'tts/0' >> /etc/securetty</i>
395 </pre>
396
397 </body>
398 </subsection>
399 </section>
400
401 <section id="reboot">
402 <title>Rebooting the System</title>
403 <subsection>
404 <body>
405
406 <p>
407 Exit the chrooted environment and unmount all mounted partitions. Then type in
408 that one magical command you have been waiting for: <c>reboot</c>.
409 </p>
410
411 <pre caption="Exiting the chroot, unmounting all partitions and rebooting">
412 # <i>exit</i>
413 cdimage ~# <i>cd</i>
414 cdimage ~# <i>umount -l /mnt/gentoo/dev{/shm,/pts,}</i>
415 cdimage ~# <i>umount -l /mnt/gentoo{/boot,/proc,}</i>
416 cdimage ~# <i>reboot</i>
417 </pre>
418
419 <note>
420 <e>Cobalt Users:</e> The rest of this section covers the setting up of the SGI
421 PROM so that it boots <c>arcload</c> off disk and loads
422 Linux.
423 This is not applicable to the setup of Cobalt servers. In fact, all your work
424 is done -- there is no configuration needed for the first boot up, you can skip
425 to the next section: <uri link="?part=1&amp;chap=11">Finalising your Gentoo
426 Installation</uri>
427 </note>
428
429 </body>
430 </subsection>
431 </section>
432 <section>
433 <title>Tweaking the SGI PROM</title>
434 <subsection>
435 <title>Setting generic PROM settings</title>
436 <body>
437
438 <p>
439 Now that you've installed the bootloader, you're ready to reboot the machine.
440 </p>
441
442 <pre caption="Rebooting">
443 <comment>(Exit the chroot environment)</comment>
444 # <i>exit</i>
445
446 <comment>(Unmount the drives)</comment>
447 cdimage ~# <i>umount -l /mnt/gentoo/dev{/shm,/pts,}</i>
448 cdimage ~# <i>umount -l /mnt/gentoo{/boot,/proc,}</i>
449
450 <comment>(Reboot)</comment>
451 # <i>reboot</i>
452 </pre>
453
454 <p>
455 When you are rebooted, go to the <e>System Maintenance Menu</e> and select
456 <e>Enter Command Monitor</e> (<c>5</c>) like you did when you netbooted the
457 machine.
458 </p>
459
460 <pre caption="Configuring the PROM to Boot Gentoo">
461 1) Start System
462 2) Install System Software
463 3) Run Diagnostics
464 4) Recover System
465 5) Enter Command Monitor
466
467 Option? <i>5</i>
468 Command Monitor. Type "exit" to return to the menu.
469
470 <comment>(Set some options for arcload)</comment>
471
472 <comment>(Provide the location of the Volume Header)</comment>
473 &gt;&gt; <i>setenv SystemPartition scsi(0)disk(1)rdisk(0)partition(8)</i>
474
475 <comment>(Automatically boot Gentoo)</comment>
476 &gt;&gt; <i>setenv AutoLoad Yes</i>
477
478 <comment>(Set the timezone)</comment>
479 &gt;&gt; <i>setenv TimeZone EST5EDT</i>
480
481 <comment>(Use the serial console - graphic adapter users should have "g" instead of "d1" (one))</comment>
482 &gt;&gt; <i>setenv console d1</i>
483
484 <comment>(Setting the serial console baud rate. This is optional, 9600 is the )
485 (default setting, although one may use rates up to 38400 if that is desired. )</comment>
486 &gt;&gt; <i>setenv dbaud 9600</i>
487 </pre>
488
489 <p>
490 Now, the next settings depend on how you are booting the system.
491 </p>
492
493 </body>
494 </subsection>
495
496 <subsection>
497 <title>Settings for direct volume-header booting</title>
498 <body>
499
500 <p>
501 This is covered here for completeness. It's recommended that users look into
502 installing <c>arcload</c> instead.
503 </p>
504
505 <note>
506 This only works on the Indy, Indigo2 (R4k) and Challenge S.
507 </note>
508
509 <pre caption="PROM settings for booting off the volume header">
510 <comment>(&lt;root device&gt; = Gentoo's root partition, e.g. /dev/sda3)</comment>
511 &gt;&gt; <i>setenv OSLoadPartition &lt;root device&gt;</i>
512
513 <comment>(To list the available kernels, type "ls")</comment>
514 &gt;&gt; <i>setenv OSLoader &lt;kernel name&gt;</i>
515 &gt;&gt; <i>setenv OSLoadFilename &lt;kernel name&gt;</i>
516
517 <comment>(Declare the kernel parameters you want to pass)</comment>
518 &gt;&gt; <i>setenv OSLoadOptions &lt;kernel parameters&gt;</i>
519 </pre>
520
521 <p>
522 If you wish to try a kernel without messing with kernel parameters, you may do
523 so using the <c>boot -f</c> PROM command:
524 </p>
525
526 <pre caption="Booting without changing environment variables">
527 <comment>(Booting a kernel, "new", with additional options)</comment>
528 # <i>boot -f new root=/dev/sda3 ro</i>
529 </pre>
530
531 </body>
532 </subsection>
533
534 <subsection>
535 <title>Settings for arcload</title>
536 <body>
537
538 <p>
539 <c>arcload</c> uses the <c>OSLoadFilename</c> option to specify which options
540 to set from <path>arc.cf</path>. The configuration file is essentially a
541 script, with the top-level blocks defining boot images for different systems,
542 and inside that, optional settings. Thus, setting
543 <c>OSLoadFilename=mysys(serial)</c> pulls in the settings for the <c>mysys</c>
544 block, then sets further options overridden in <c>serial</c>.
545 </p>
546
547 <p>
548 In the example file above, we have one system block defined, <c>ip28</c> with
549 <c>working</c>, <c>new</c> and <c>debug</c> options available. We define our
550 PROM variables as so:
551 </p>
552
553 <pre caption="PROM settings for using arcload">
554 <comment>(Select arcload as the bootloader:- sash64 or sashARCS)</comment>
555 &gt;&gt; <i>setenv OSLoader sash64</i>
556
557 <comment>(Use the "working" kernel image, defined in "ip28" section of arc.cf)</comment>
558 &gt;&gt; <i>setenv OSLoadFilename ip28(working)</i>
559 </pre>
560
561 <p>
562 Starting with <c>arcload-0.5</c>, files no longer need to be placed in the
563 volume header -- they may be placed in a partition instead. To tell
564 <c>arcload</c> where to look for its configuration file and kernels, one must
565 set the <c>OSLoadPartition</c> PROM variable. The exact value here will depend
566 on where your disk resides on the SCSI bus. Use the <c>SystemPartition</c> PROM
567 variable as a guide -- only the partition number should need to change.
568 </p>
569
570 <note>
571 Partitions are numbered starting at 0, not 1 as is the case in Linux.
572 </note>
573
574 <pre caption="Telling arcload where to find arc.cf">
575 <comment>(If you wish to load from the volume header -- use partition 8)</comment>
576 &gt;&gt; <i>setenv OSLoadPartition scsi(0)disk(1)rdisk(0)partition(8)</i>
577
578 <comment>(Otherwise, specify the partition and filesystem type)</comment>
579 &gt;&gt; <i>setenv OSLoadPartition scsi(0)disk(1)rdisk(0)partition(0)[ext2]</i>
580 </pre>
581
582 </body>
583 </subsection>
584
585 <subsection>
586 <title>All Done</title>
587 <body>
588
589 <p>
590 Now you're ready to enjoy Gentoo! Boot up your Gentoo installation and finish
591 up with <uri link="?part=1&amp;chap=11">Finalizing your Gentoo
592 Installation</uri>.
593 </p>
594
595 </body>
596 </subsection>
597 </section>
598 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20