/[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.19 - (show annotations) (download) (as text)
Tue Apr 1 08:53:46 2008 UTC (6 years, 3 months ago) by nightmorph
Branch: MAIN
Changes since 1.18: +3 -3 lines
File MIME type: application/xml
release time. note that since this is beta1, the release dir and stage/media names have been adjusted accordingly. also, the handbooks are marked with a disclaimer=draft, so once the final is out, that will be removed and the release names adjusted. in the mean time, these are live. the beta is officially released. no, it's not april fools, but it is april 1st. :)

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

  ViewVC Help
Powered by ViewVC 1.1.20