Seth Woolley's Man Viewer

bootstrap(8) - bootstrap - Disk boot process for PowerMac GNU/Linux - man 8 bootstrap

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

BOOTSTRAP(8)                System Manager's Manual               BOOTSTRAP(8)



NAME
       bootstrap - Disk boot process for PowerMac GNU/Linux

DESCRIPTION
       This  man(1,5,7)  page  describes  the bootstrap process for both OldWorld and
       NewWorld PowerMacs.  OldWorld PowerMacs all have a hardware  MacOS  ROM
       and the case is beige in(1,8) color.  NewWorld PowerMacs do not have a hard-
       ware MacOS ROM, and are in(1,8) colored, translucent cases.  All G3s in(1,8) col-
       ored  cases  are  NewWorld, as are all G4s and later.  This man(1,5,7) page is
       divided into three sections, OLDWORLD, NEWWORLD, and IBM.  Please  read(2,n,1 builtins)
       the section appropriate to your hardware.

OLDWORLD
       The  process  of  booting  PowerMac/Linux  from a disk starts with Open
       Firmware loading the boot block from the first  bootable  partition  of
       the  boot  disk  into memory.  The user specifies which device is to be
       the boot disk by setting the boot-device environment  variable  to  the
       Open  Firmware  name  of  the boot disk, or by giving it as an explicit
       argument to the Open Firmware boot command.  OldWorld  PowerMacs  typi-
       cally do not require bootstrap partitions like NewWorld PowerMacs do.

       Open  Firmware  then  transfers  control  to  the first-stage bootstrap
       (first.b), located at the beginning of the boot block.  The boot  block
       also contains the list of block numbers for the second-stage bootstrap.
       First.b reads these blocks into memory, thus loading  the  second-stage
       bootstrap.

       The  task of the second-stage bootstrap (second.b) is to load(7,n) the Linux
       kernel into memory and pass it any arguments given by the  user.   Sec-
       ond.b  can  also be used for loading other programs, such as diagnostic
       programs or other operating systems, as long as they are present as  an
       ELF binary in(1,8) an ext2 filesystem.

       Second.b gets(3,n) two string(3,n) values from Open Firmware, called bootpath and
       bootargs.  Bootpath is the Open Firmware name of the boot  disk  (i.e.,
       the  device  that  the first-stage bootstrap was loaded from).  If Open
       Firmware auto-booted, or if(3,n) the boot command was  given  without  argu-
       ments,  then  bootpath  and bootargs are set(7,n,1 builtins) to the values of the boot-
       device and boot-file variables, respectively.  If the boot command  was
       given  with arguments, the first argument becomes bootpath and any sub-
       sequent arguments are saved in(1,8) bootargs.

       Second.b uses the Open Firmware input and output devices  for  communi-
       cating with the user.  By default, the modem port is used for both, but
       this can be changed by setting the Open Firmware input-device and  out-
       put-device variables.

       Second.b  starts by printing a message to indicate that it has started,
       and then reads the configuration file.  By default,  the  configuration
       file(1,n)  is /etc/quik.conf(5) on the same partition as the boot block, but
       this can be overridden with quik(8).  The configuration file(1,n) must be on
       the  same disk as the boot block.  The format of the configuration file(1,n)
       is described in(1,8) quik.conf(5).

       Then second.b prints its boot: prompt and waits for the user to type  a
       command line.  Normally the configuration file(1,n) specifies a timeout(1,3x,3x cbreak), and
       if(3,n) the user does not type anything within that period of time(1,2,n), second.b
       proceeds  using the bootargs value as the command line.  If the timeout(1,3x,3x cbreak)
       value is 0, second.b will always use the bootargs value, ignoring  any-
       thing  the user types.  This can be useful when a modem is connected to
       the modem port.

       Having obtained a command line, second.b takes the first  word  (white-
       space-separated)  as  the  name  of the program to load.  Any remaining
       words on the line become arguments to be passed to the program when  it
       is  loaded.   If  the command line is empty, second.b uses the value of
       the default keyword in(1,8) the configuration file(1,n),  or  failing  that,  the
       first program specified in(1,8) the configuration file.

       The configuration file(1,n) can specify several alternative programs to load(7,n)
       (referred to as images in(1,8) the configuration file(1,n)  syntax),  along  with
       shorthand  labels for them and extra arguments to be prepended to those
       specified by the user.  The program name given in(1,8) the command line  can
       be  either  an  explicit  path  name  or a shorthand label.  If it is a
       shorthand label, the configuration file(1,n) gives  the  corresponding  path
       name.

       Path names are of the form

              [device:][partno]/filepath

       where device is the Open Firmware name of the disk, partno is the (dec-
       imal) number of the partition on that disk, and filepath is the path to
       the  file(1,n)  in(1,8)  the  ext2 filesystem on that partition.  The default for
       device is bootpath, and the default for partno is  the  first  bootable
       partition  on  device.   Alternatively,  the  /filepath  section can be
       replaced by a span of 512-byte blocks to load(7,n) using the syntax  [start-
       end] where start and end are decimal block numbers.

       Second.b  will attempt to open(2,3,n) the file(1,n) identified by the path name and
       load(7,n) it into memory as an ELF binary.  If the file(1,n) cannot be found,  or
       if(3,n)  it  is  not an ELF binary, second.b will print an error(8,n) message and
       print its boot: prompt again.  In this case there  is  no  timeout(1,3x,3x cbreak)  and
       second.b does not use the bootargs value.

       Once  second.b has loaded the program into memory, it transfers control
       to it, passing it the list of arguments.

NEWWORLD
       The process of booting so called NewWorld PowerMacs  from  disk  starts
       with OpenFirmware first attempting to execute the file(1,n) specified in(1,8) the
       boot-device variable.  Unlike older versions of OpenFirmware  the  New-
       World version(1,3,5) will not attempt to read(2,n,1 builtins) a boot sector.  By default Open-
       Firmware attempts to load(7,n) a file(1,n) with  HFS  file(1,n)  type  "tbxi"  in(1,8)  the
       "blessed"  directory  from  each partition of each disk OpenFirmware is
       aware of, the first partition/disk that is  found  to  be  bootable  is
       booted immediately.

       Ybin(8)  configures a bootstrap partition to pass all of OpenFirmware's
       tests to determine if(3,n) the partition is considered  to  be  bootable  or
       not.   The boot script is given file(1,n) type "tbxi" and the root directory
       is marked as "blessed", the blessing is important because  OpenFirmware
       will  immediately  consider  a  partition unbootable if(3,n) no directory is
       marked as blessed (you can still manually  execute  a  loader  such  as
       yaboot(5,8)(8)  with  OpenFirmware  even  without a blessed directory but it
       will not happen automatically).

       The MacOS System Folder is always marked as blessed, this  is  required
       for  MacOS  as well as OpenFirmware.  The MacOS System Folder also con-
       tains its own boot loader which has the  tbxi  file(1,n)  type,  this  makes
       installing yaboot(5,8)(8) onto a MacOS partition is difficult.  The only way
       to install yaboot(5,8)(8) on a MacOS  boot  partition  is  to  modify  Open-
       Firmware  to  boot  the  CHRP script directly.  Given this it is highly
       recommended  that  you  create  a  dedicated  bootstrap  partition  for
       yaboot(5,8)(8).

       Since OpenFirmware boots the first partition it finds to be bootable it
       is important that the bootstrap partition be first on the  disk  before
       any  MacOS  partition, otherwise MacOS will be booted instead of a dual
       boot menu(3x,n,n tk_menuSetFocus) used with yaboot(5,8)(8).

       The bootstrap partition should also NOT be mountable by MacOS, the rea-
       son  is MacOS will (almost always) closely inspect any blessed directo-
       ries to make sure its real MacOS, if(3,n) it is not satisfied that the  con-
       tents are a real copy of MacOS it will unbless the directory, resulting
       in(1,8) OpenFirmware no longer considering it bootable.   The  best  way  to
       protect against this is to create the bootstrap partition with the par-
       tition type "Apple_Bootstrap" which OpenFirmware accepts as a valid HFS
       partition,  but  MacOS  will ignore and refuse to mount.  The bootstrap
       partition need not be any larger then 800K.  800K is the  minimum  size
       of  an  HFS  filesystem, and is much more then enough for this purpose.
       You need not, and should not keep kernels on this partition,  yaboot(5,8)(8)
       will  load(7,n)  them  from your ext2fs root partition just fine, as well as
       from any HFS or HFS+ partitions  (yaboot(5,8)(8)  uses  OpenFirmware's  HFS+
       filesystem support).

       To create the bootstrap partition, use GNU parted(8) or mac-fdisk(8) to
       create a partiton of type "Apple_Bootstrap".  This is documented better
       in(1,8)   mac-fdisks-basics   (http://penguinppc.org/usr/ybin/doc/mac-fdisk-
       basics.shtml).

       The bootstrap need not and should  not  be  mounted  anywhere  on  your
       filesystem,  especially not on top of /boot.  Yaboot(8) is able to load(7,n)
       the kernels from the ext2fs root partition so that is where they should
       be kept.

       OpenFirmware  maintains a hierarchy of all the hardware it is aware of.
       To access(2,5) or specify a boot device you must use the OpenFirmware  path.
       For  example:  the  path  to a SCSI hard disk partition might look(1,8,3 Search::Dict) like
       this: /pci@80000000/pci-bridge@d/ADPT,2930CU@2/@2:2 . The  first  part,
       pci@80000000,  shows that the target device is accessed through the PCI
       bus.  The next part is the PCI bridge, the next is the name of the SCSI
       host(1,5)  adapter installed (this name is provided by a BootROM on the card
       itself), and after that is the SCSI ID number.  The colon delimits  the
       device  from  partition  specification,  so the last 2 means the second
       partition of this device.  After the partition number  we  can  specify
       pathnames to files in(1,8) two ways: lazy and absolute. The "," delimits the
       OpenFirmware path from the location of the bootfile.  ",\\:tbxi" speci-
       fies  the file(1,n) that has a HFS file(1,n) type of "tbxi" in(1,8) the blessed direc-
       tory.  If there is not blessed directory this will fail.  The second is
       to  specify a absolute pathname to an arbitrary file(1,n) on the disk, exam-
       ple: 2:,yaboot(5,8) would load(7,n) the file(1,n) named(5,8) "yaboot(5,8)" in(1,8) the root directory
       of  the filesystem.  It is possible to load(7,n) files in(1,8) subdirectories but
       OpenFirmware does not always do this reliably, and any special  charac-
       ters such as an embedded space must be expressed like %20 (for a space)
       the directory separator used by OpenFirmware is the backslash \.  Exam-
       ple:  2:,\boot\yaboot.  Determining  the  OpenFirmware  path to a given
       device is unfortunately not a trivial task.  If you are using the built
       in(1,8) ATA hard disk you can use the alias "hd:".

       Ybin also includes a utility ofpath(8) which can in(1,8) most cases find the
       OpenFirmware device path from a unix device node (ie /dev/hda2).

       In addition to binary executables OpenFirmware can also execute a  CHRP
       script.   This is somewhat similar to a shell script.  A CHRP script is
       useful to create simple boot menus, among other things.   CHRP  scripts
       are  divided  into  sections in(1,8) a way similar to HTML.  Here is a basic
       example of a CHRP script used as a wrapper to  yaboot(5,8)(8)  (since  Open-
       Firmware  will  only  load(7,n)  a  file(1,n)  with  type  "tbxi" if(3,n) it is a CHRP
       script).

              <CHRP-BOOT>
              <COMPATIBLE>
              MacRISC
              </COMPATIBLE>
              <DESCRIPTION>
              GNU/Linux PowerPC bootloader
              </DESCRIPTION>
              <BOOT-SCRIPT>
              boot hd:,\\yaboot(5,8)
              </BOOT-SCRIPT>
              </CHRP-BOOT>

       The COMPATIBLE section defines what machines this script is  compatible
       with,  if(3,n)  the  machine name encoded into the ROM does not match one of
       these entries OpenFirmware will print out  a  lot  of  incomprehensible
       junk  and fail to load(7,n) the script.  The DESCRIPTION is ignored by Open-
       Firmware as far as I know.  The BOOT-SCRIPT section is where  arbitrary
       OpenFirmware  Forth commands may go.  They are executed the same way as
       you would enter them on the  OpenFirmware  command  line.   The  entire
       script  is wrapped with the CHRP-BOOT tags so that such a script may be
       attached as a header to a binary file.  Much more complicated and elab-
       orate  CHRP  scripts  are possible but that is beyond the scope of this
       document.

       Ybin as of version(1,3,5) 0.17 includes a more robust script that is automati-
       cally   configured   with  the  correct  OpenFirmware  paths  based  on
       /etc/yaboot.conf.  This new script need not and should not be edited by
       the user.

       If  you  have  G4  hardware  then  your OpenFirmware may already have a
       graphical boot selector built in. This  selector  can  be  accessed  by
       holding down the option key when booting the machine.  You should see a
       screen with buttons for each bootable partition.  The  current  version(1,3,5)
       (as of ybin(8) 0.13) of ofboot includes a badge icon, the button with a
       penguin icon is your bootstrap partition.  If you decide  to  use  this
       built in(1,8) selector you really do not need to use a CHRP script that pro-
       vides a boot menu. Thanks to Nicholas Humfrey for  creating  the  Badge
       icon.

IBM
       IBM  hardware such as the RS/6000 require msdos style partition tables.
       In order to boot from the disk they require a type 0x41 PReP Boot boot-
       strap   partition  large  enough  to  hold  the  bootloader  (typically
       yaboot(5,8)(8)).  The bootloader is copied onto the raw(3x,7,8,3x cbreak) partition  as  there
       is no filesystem.  This is done either with dd(1) or mkofboot(8).

BUGS
       OpenFirmware

AUTHORS
       ybin,  and  the  NEWWORLD, and IBM sections of this man(1,5,7) page written by
       Ethan Benson <erbenson@alaska.net>

       The OLDWORLD section of this man(1,5,7) page was taken from the quik(8)  pack-
       age, which was written by Paul Mackerras.

       yaboot(5,8)   was  written  by  Benjamin  Herrenschmidt  <benh@kernel.crash-
       ing.org>.

SEE ALSO
       dd(1),  mkofboot(8),  ofpath(8),  quik(8),   quik.conf(5),   yaboot(5,8)(8),
       ybin(8).



GNU/Linux PowerPC                28 April 2001                    BOOTSTRAP(8)

References for this manual (incoming links)