share/man/man8/man8.macppc/boot.8

   1 .\" $NetBSD: boot.8,v 1.5 2007/12/14 21:16:01 pavel Exp $
   2 .\"
   3 .\" Copyright (c) 2003 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Michael Wolfson and Erik E. Fair.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd March 28, 2004
  31 .Dt BOOT 8 macppc
  32 .Os
  33 .Sh NAME
  34 .Nm boot
  35 .Nd Macppc system bootstrapping procedures
  36 .Sh DESCRIPTION
  37 .Ss Power fail and crash recovery
  38 Normally, the system will reboot itself at power-up or after crashes.
  39 An automatic consistency check of the file systems will be performed
  40 as described in
  41 .Xr fsck 8 ,
  42 and unless this fails, the system will resume multi-user operations.
  43 .Ss Cold starts
  44 The boot ROM performs a Power On Self Test (POST) then loads Open
  45 Firmware.
  46 Depending on the Open Firmware variable
  47 .Sq Ev auto-boot?
  48 it will either stop at the Open Firmware
  49 prompt or attempt to boot an operating system.
  50 Depending on the contents
  51 of the
  52 .Sq Ev use-nvramrc? ,
  53 .Sq Ev boot-command ,
  54 .Sq Ev boot-device ,
  55 and
  56 .Sq Ev boot-file
  57 Open Firmware variables, it will attempt to boot
  58 .Tn MacOS ,
  59 .Tn "MacOS X" ,
  60 or
  61 .Nx .
  62 .Pp
  63 To boot
  64 .Nx ,
  65 Open Firmware loads the bootloader
  66 .Xr ofwboot 8
  67 from the specified
  68 .Sq Ev boot-device .
  69 The bootloader then loads the kernel from the
  70 .Sq Ev boot-file ,
  71 .Pq if it exists .
  72 Otherwise, it tries to load (in the following order):
  73 .Pa netbsd , netbsd.gz ,
  74 or
  75 .Pa netbsd.macppc
  76 on the
  77 .Dq a
  78 partition of the same device that had the bootloader.
  79 .Ss "Open Firmware Commands"
  80 An essential but incomplete list of Open Firmware commands follows.
  81 A more thorough list is contained in the FAQ.
  82 .Lk http://www.NetBSD.org/ports/macppc/faq.html#ofw-use
  83 .Pp
  84 .Ic boot
  85 .Op Ar boot-device Op Ar boot-file
  86 .Op Ar options
  87 .Pp
  88 Boot an operating system.
  89 The default arguments for this command are taken from the Open Firmware
  90 environment variables:
  91 .Bl -tag -width boot-device -compact
  92 .It Ar boot-device
  93 primary bootloader location
  94 .It Ar boot-file
  95 kernel location
  96 .It Ar options
  97 flags passed to the kernel
  98 .El
  99 .Pp
 100 .Ic reset-all
 101 .Pp
 102 Reset the system, and proceed as specified by the
 103 .Sq Ev use-nvramrc?
 104 and
 105 .Sq Ev auto-boot?
 106 variables.
 107 If
 108 .Sq Ev use-nvramrc?
 109 is set to
 110 .Sq Ev true ,
 111 then the system will attempt to execute the commands stored in the
 112 .Sq Ev nvramrc
 113 variable.
 114 If
 115 .Sq Ev auto-boot?
 116 is set to
 117 .Sq Ev true ,
 118 the system will attempt to use the values stored in
 119 .Sq Ev boot-command ,
 120 .Sq Ev boot-device ,
 121 and
 122 .Sq Ev boot-file
 123 to boot the system.
 124 If
 125 .Sq Ev auto-boot?
 126 is set to
 127 .Sq Ev false ,
 128 the system will halt at the Open Firmware prompt.
 129 .Pp
 130 .Ic shut-down
 131 .Pp
 132 Power off the system.
 133 .Pp
 134 .Ic setenv Ar variable Ar value
 135 .Pp
 136 Set an Open Firmware variable, e.g.,
 137 .Bd -literal -offset indent
 138 setenv auto-boot? false
 139 setenv boot-device hd:,\eofwboot.xcf
 140 setenv boot-file netbsd-GENERIC.gz
 141 .Ed
 142 .Pp
 143 .Ic set-default Ar variable
 144 .Pp
 145 Set an Open Firmware variable to its default value.
 146 .Pp
 147 .Ic printenv Op Ar variable
 148 .Pp
 149 Show Open Firmware variables and values.
 150 .Pp
 151 .Ic eject fd
 152 .Pp
 153 Eject floppy disk on systems with on-board floppy drives.
 154 .Pp
 155 .Ic mac-boot
 156 .Pp
 157 Attempt to boot
 158 .Tn MacOS
 159 on an Open Firmware 3 system.
 160 .Pp
 161 .Ic bye
 162 .Pp
 163 Attempt to boot
 164 .Tn MacOS
 165 on an Open Firmware 1.0.5, 2.0.x, or 2.4 system.
 166 .Ss "Open Firmware Variables"
 167 An essential but incomplete list of Open Firmware variables follows.
 168 A more thorough list is contained in the FAQ.
 169 .Lk http://www.NetBSD.org/ports/macppc/faq.html#ofw-variables
 170 .Bl -tag -width "ew*0_protocols"
 171 .It Ev auto-boot?
 172 What Open Firmware will do at system startup or reset:
 173 .Bl -tag -width false
 174 .It Ar true
 175 automatically bootstrap an operating system using values from the
 176 .Sq Ev boot-command ,
 177 .Sq Ev boot-device ,
 178 and
 179 .Sq Ev boot-file
 180 variables.
 181 .It Ar false
 182 stop at the Open Firmware prompt.
 183 .El
 184 .Pp
 185 .It Ev use-nvramrc?
 186 If
 187 .Sq Ev true
 188 runs commands in variable
 189 .Sq Ev nvramrc .
 190 .Pp
 191 .It Ev real-base
 192 Kernel memory location.
 193 .Em "Do not modify this value on Open Firmware 3 systems \(em you may"
 194 .Em "damage your computer" .
 195 All other Open Firmware versions should use
 196 .Li F00000 .
 197 .Pp
 198 .It Ev load-base
 199 Bootloader memory location.
 200 .Em "Do not modify this value on Open Firmware 3 systems \(em you may"
 201 .Em "damage your computer" .
 202 All other Open Firmware versions should use
 203 .Li 600000 .
 204 .Pp
 205 .It Ev boot-command
 206 The command to use for booting.
 207 Typically, the default of
 208 .Sq Ev boot
 209 is used.
 210 .Pp
 211 .It Ev boot-device
 212 Device from which to load primary bootloader.
 213 Value depends on a variety of factors.
 214 See
 215 .Xr ofwboot 8 .
 216 .It Ev boot-file
 217 Kernel location.
 218 Value depends on a variety of factors.
 219 See
 220 .Xr ofwboot 8 .
 221 .Pp
 222 .It Ev input-device
 223 What type of console input device
 224 .Po
 225 .Tn ADB
 226 keyboard,
 227 .Tn USB
 228 keyboard, or serial port
 229 .Pc .
 230 .Bl -tag -width ttya
 231 .It Ar kbd
 232 .Tn ADB
 233 keyboard on models with
 234 .Tn ADB ,
 235 .Tn USB
 236 keyboard on models with
 237 .Tn USB ,
 238 and built-in keyboard on laptops.
 239 This is the default on some Open Firmware
 240 2.0.x machines and all Open Firmware 2.4 and 3 machines.
 241 .It Ar ttya
 242 .Sq Modem
 243 serial port on machines with serial ports.
 244 Properties are 38400 bps, 8 bits, no parity, 1 stop bit, no handshaking.
 245 This is the default on all
 246 Open Firmware 1.0.5 systems and some Open Firmware 2.0.x systems.
 247 .It Ar ttyb
 248 .Sq Printer
 249 serial port on machines with serial ports.
 250 Properties are the same as the
 251 .Sq Modem
 252 port.
 253 .It Ar scca
 254 Serial port on Xserve models.
 255 Properties are 57600 bps, 8 bits, no
 256 parity, 1 stop bit, no handshaking.
 257 .El
 258 .Pp
 259 .It output-device
 260 What type of console output device (On-board video, AGP video, PCI video,
 261 built-in LCD, or serial console).
 262 Value depends on a variety of factors.
 263 See
 264 .Xr ofwboot 8
 265 and
 266 .Lk http://www.NetBSD.org/ports/macppc/faq.html#ofw-input-output-devices
 267 .Pp
 268 .It nvramrc
 269 If
 270 .Sq Ev use-nvramrc?
 271 is set to true, these
 272 .Tn FORTH
 273 commands will be run when the computer is reset
 274 .Pp
 275 .El
 276 .Ss "Normal Operation"
 277 When Open Firmware loads the primary bootloader, it will print something
 278 like the following:
 279 .Bd -unfilled -offset indent
 280  loading XCOFF
 281  tsize=CC50 dsize=14AC bsize=2668 entry=640000
 282  SECTIONS:
 283  .text    00640000 00640000 0000CC50 000000E0
 284  .data    0064D000 0064D000 000014AC 0000CD30
 285  .bss     0064E4B0 0064E4B0 00002668 00000000
 286  loading .text, done..
 287  loading .data, done..
 288  clearing .bss, done..
 289 .Ed
 290 .Pp
 291 When
 292 .Xr ofwboot 8
 293 is started, it prints something like the following:
 294 .Bd -unfilled -offset indent
 295  \*[Gt]\*[Gt] NetBSD/macppc OpenFirmware Boot, Revision 1.7
 296  \*[Gt]\*[Gt] (autobuild@tgm.daemon.org, Thu Feb  6 17:50:27 UTC 2003)
 297 .Ed
 298 .Pp
 299 When
 300 .Xr ofwboot 8
 301 is loading the kernel, it prints something like the following:
 302 .Bd -unfilled -offset indent
 303  4395364+254568 [220144+193803]=0x4d477c
 304   start=0x100000
 305 .Ed
 306 .Pp
 307 When the
 308 .Nx
 309 kernel has started it prints a banner similar to the following:
 310 .Bd -literal -offset indent
 311  Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003
 312      The NetBSD Foundation, Inc.  All rights reserved.
 313  Copyright (c) 1982, 1986, 1989, 1991, 1993
 314      The Regents of the University of California.  All rights reserved.
 315
 316  NetBSD 1.6ZC (GENERIC) #0: Tue Sep 30 13:09:10 UTC 2003
 317         autobuild@tgm.NetBSD.org:/autobuild/HEAD/macppc/OBJ/autobuild/HEAD/src/sys/arch/macppc/compile/GENERIC
 318 .Ed
 319 .Ss "After bootstrap"
 320 Once the
 321 .Nx Ns Tn /macppc
 322 kernel is booted normally
 323 it initializes itself and proceeds to start the system.
 324 An automatic consistency check of the file systems takes place,
 325 and unless this fails, the system comes up to multi-user operation.
 326 .Pp
 327 The proper way to shut the system down is with the
 328 .Xr shutdown 8
 329 command.
 330 .Pp
 331 If the system crashes, it will enter the kernel debugger,
 332 .Xr ddb 4 ,
 333 if it is configured in the kernel.
 334 If the crash occurred during initialization and the debugger is
 335 not present or is exited, the kernel will halt the system.
 336 .Pp
 337 If the crash occurred during normal operation and the debugger
 338 is not present or is exited, the system will attempt a dump to the
 339 configured dump device (which will be automatically recovered with
 340 .Xr savecore 8
 341 during the next bootstrap cycle), and after the dump is complete (successful
 342 or not) the kernel will attempt a reboot.
 343 .Sh FILES
 344 .Bl -tag -width /usr/mdec/bootxx_cd9660 -compact
 345 .It Pa /boot
 346 .Nx
 347 secondary bootstrap program (Open Firmware 1.x and 2.x)
 348 .It Pa /netbsd
 349 default
 350 .Nx
 351 system kernel
 352 .It Pa /usr/mdec/bootxx
 353 .Nx
 354 primary bootstrap program (Open Firmware 1.x and 2.x) a.k.a.
 355 .Dq "partition zero"
 356 bootloader
 357 .It Pa /usr/mdec/ofwboot
 358 .Nx
 359 secondary bootstrap program (Open Firmware 1.x and 2.x)
 360 .It Pa /usr/mdec/ofwboot.xcf
 361 primary bootstrap for netboot and
 362 .Dq cd9660
 363 .Pq Tn ISO 9660 ,
 364 .Dq MS-DOS ,
 365 .Dq HFS ,
 366 and
 367 .Dq HFS+
 368 file systems.
 369 .El
 370 .Sh SEE ALSO
 371 .Xr ddb 4 ,
 372 .Xr intro 4 ,
 373 .Xr diskless 8 ,
 374 .Xr halt 8 ,
 375 .Xr init 8 ,
 376 .Xr installboot 8 ,
 377 .Xr ofwboot 8 ,
 378 .Xr rc 8 ,
 379 .Xr reboot 8 ,
 380 .Xr savecore 8 ,
 381 .Xr shutdown 8
 382 .Pp
 383 .Lk http://www.NetBSD.org/ports/macppc/faq.html
 384 .br
 385 .Lk http://www.NetBSD.org/docs/network/netboot/
 386 .Sh STANDARDS
 387 .St -ieee1275-94
 388 .Lk http://playground.sun.com/1275/home.html
 389 .Sh BUGS
 390 The device names used by
 391 .Nx Ns Tn /macppc
 392 and Open Firmware often have no relation to each other.
 393 .Pp
 394 Apple Computer's Open Firmware implementation is easily confused.
 395 It is best to reboot your computer
 396 after a failed boot attempt,
 397 .Ic halt ,
 398 or
 399 .Ic "shutdown -h" .
 400 Use the Open Firmware
 401 .Ic reset-all
 402 command.
 403 .Pp
 404 Apple Computer's Open Firmware implementation is notoriously bad.
 405 Thorough instructions for installing and booting
 406 .Nx
 407 are in the install notes
 408 .Pq Pa INSTALL.html
 409 included with every release of
 410 .Nx .