
                       palo PA-Risc/Linux Boot Loader

                               Building palo

    If you are self hosted on PA-RISC/LInux you should already have palo
    on your system. Assuming you have apt configured you can always run
    "apt-get update; apt-get install palo" to obtain the latest released
    version.

    If you need to build palo yourself, especially if you are
    cross-compiling on x86, skip to the end of this document.

                            Kernel Command Line

   Palo's  boot  loader parses the kernel command line to determine which
   kernel  to  boot and optionally which ramdisk to load. Given a command
   line:  '0/vmlinux ... initrd=0/ramdisk ...',  palo uses '0/vmlinux' as
   the  kernel  file  and '0/ramdisk' as the ramdisk file. Both names are
   composed  of  a  partition  number followed by a file path name within
   that partition. Partition number '0' is magic and refers to the kernel
   (ramdisk)  you  placed  on  the boot medium with '-k' ('-r'). The path
   name  on  the '0' partition is ignored, '0/vmlinux' and '0/xyzzy' work
   identically,  but  it's  a good idea to be consistent with what you'll
   call kernels and ramdisks on an ext2 partition.

                  Creating and Maintaining Bootable Disks

   Partitioned  media  usually  refers  to  disks,  in  this  case  disks
   partitioned  by  fdisk  or  a  similar  program. Normally your disk is
   properly  initialized  when you install PA-RISC Linux, but if you need
   to do it by hand here are some clues:
     * Use  fdisk  or  something  to (re)partition the disk. When you are
       finished, the disk must have a partition of type "F0" somewhere in
       the  first  2Gb.  This  is  where  the boot loader and an optional
       kernel  and ramdisk will be stored, so make it big enough for that
       --  at  least  4Mb  (I  like  8-16Mb).  There must also be an ext2
       partition  within  the  first  2Gb  where  you'll store your Linux
       kernel.
     * Use mke2fs and mkswap as usual.
     * Mount  the  partition,  copy your kernel and any other interesting
       files to it, unmount.
     * Use palo to make the disk bootable:
        $ palo \
             -c "5/vmlinux HOME=/ TERM=linux console=tty" \
             -k path/to/vmlinux \
             -I /dev/your-disk

      On a self-hosted system, you can accomplish the same thing by placing
      the following into /etc/palo.conf:
   --commandline=5/vmlinux HOME=/ TERM=linux console=tty
   --recoverykernel=/boot/vmlinux
   --init-partitioned=/dev/your-disk

   and running palo.

       -k path/to/vmlinux designates a kernel to be stored along with the
       boot  loader in the "F0" partition. You can omit this if you want,
       since  you'll  usually  be booting a kernel from an ext2 partition
       instead.  I  like to have a kernel there just in case the ext2 one
       is lost for some reason. I call it a recovery kernel.
       -c 5/vmlinux must be changed for your situation. The number, 5, is
       the  partition number of your ext2 partition as reported by fdisk,
       the  same  number  you  use  when you mounted the partition (e.g.,
       "mount  /dev/sdb5  /mnt").  "/vmlinux"  is the path to your kernel
       executable  within  your  ext2  partition.  The  special partition
       number  "0" is used to load the "recovery" kernel which you placed
       into the "F0" partition with -k.
       -I   /dev/your-disk   tells  palo  to  initialize  the  palo  boot
       parameters  on  the  drive  rather  than  preserving  any existing
       parameters.
       Use 'palo -?' or 'palo --help' for more information.

   You now have a partitioned bootable disk, try it!

   There  is  no need to run palo when you change the kernel in your ext2
   partition  because  it  is located dynamically by the palo boot loader
   when  you boot. However there are probably some tasks which will again
   require palo.

   Once  you have a partitioned bootable disk, palo can be used to change
   the  default  command  line  or kernel or boot loader. The most common
   task is probably changing the "recovery" kernel:

    The update (-U) feature is currently disabled, perhaps permanently.
    The usual method for maintaining your disk is to edit /etc/palo.conf
    and rerun palo.

        ./palo -k path/to/vmlinux -U /dev/your-disk

   or command line:
        ./palo -c "new command line" -U /dev/your-disk

   Which  will  normally  be done in a self-hosted environment by editing
   /etc/palo.conf  and  re-running  palo. Hopefully you won't need to use
   palo very often.

                     Creating ISO9660 Bootable CD-ROMs

   Bootable CDs are often used for installation. In short the process is:
    1. Master your CD image but don't burn it. The image MUST contain the
       kernel(s), iplboot, and ramdisk file (if used).
    2. Run palo to make the image bootable:
        ./palo  -k path/to/vmlinux \
                -b iplboot \
                -c '0/vmlinux ....' \
                -C your-iso-image
       -C   tells   palo   to  prepare  a  CD-ROM  image.  'iplboot'  and
       'path/to/vmlinux'  must  be exactly the same files (same contents)
       you  previously  copied  into  the future root file system or palo
       will  fail.  I usually point those paths at the exact files in the
       directory from which I mastered the CD just to be sure.
    3. Burn the CD and boot it.

   CD-ROM support at the moment is a bit of a hack. Here's how it works.

   palo  currently  treats  CD-ROM  as an unpartitioned sequential medium
   like tape or bootp. Unlike other unpartitioned media, there is no room
   to  store  the  kernel  and bootloader (iplboot) near the start of the
   (ISO-standard)  medium,  so  palo requires you to put those files into
   the  ISO  file  system.  HP  boot  firmware  requires  the boot loader
   (iplboot)  to be a multiple of 2k in length and be stored contiguously
   on a 2k boundary. Luckily the ISO file system meets all these criteria
   except  for  the  mod-2k length, which is achieved by padding iplboot.
   The  palo  bootloader  (iplboot)  requires  requires  the kernel to be
   stored  contiguously (except when booting from ext2), and the ISO file
   system works well for this too.

   When  you  run palo, it locates the boot loader and kernel (optionally
   ramdisk)  files  in  the ISO file system by doing a raw search through
   the  ISO image. That's why the files in the ISO file system, and those
   named on the palo command line must be identical. Once found, pointers
   to  those  files  are  stored  in  the  appropriate places in the boot
   headers.

   Ideally  palo  and  the boot loader would both understand the ISO file
   system,  but  that'll  take  more  investment  than  I'm interested in
   supplying.  If  anyone  pursues  this,  note  that  I've had good luck
   leveraging code from aboot, one of the Alpha boot loaders. I recommend
   starting with the ISO code from aboot-0.6 or later.

   It  may  be  possible  to  place  a MS-DOS partition table on a CD-ROM
   therefore having an "F0" partition as on a hard disk, but I don't feel
   confident this would be understandable by, say, a Windows box.

                            Some Newer Features

   During  installation  testing several annoyances were discovered which
   have been partly addressed by two new features:
    1. HP  machines  can  use either a serial or a graphics boot console.
       Palo  now  figures  out  which  one  you  are  using  and adds the
       appropriate  "console=" to the end of the boot command line. It is
       only  added  if  you  don't  already  have "console=" in your boot
       command line.
    2. It  would be nice to have a single bootable image, especially when
       using  CD-ROM. This requires proper console selection (see #1) and
       booting a 32-bit or 64-bit kernel as appropriate for the hardware.
       Palo  can  now place both a 32 and 64-bit kernel on sequential (or
       CD-ROM)  media.  Simply  use  the  -k (or --recoverykernel) option
       twice,  once  for  each  kernel. The palo boot loader examines the
       kernel  name, which on sequential&CD-ROM is often "0/vmlinux", and
       if  it  ends  in  "32"  or  "64"  palo boots the requested kernel.
       However  if  the name does not end in "32" or "64", palo chooses a
       kernel  based  upon  a recommendation by firmware, which is almost
       always  the right thing. (Note that a 32-bit kernel will be chosen
       to a 64-bit one on hardware which can boot both. Change the kernel
       name to 0/vmlinux64 if you want to force a 64-bit kernel.)

                               Original Goals

     * #1 support target is PA/Linux on a disk by itself (another disk(s)
       may contain a standard HP-UX installation)
     * #2 support target is PA/Linux with kernel on sequential media such
       as tape or tftp/bootp (or CD-ROM??????)
     * #3  support  target  is  PA/Linux kernel on HP-UX disk with second
       disk  for PA/Linux file system. (NOTE this is currently impossible
       with the ELF32 compiler **This is now a non-goal** )
     * Not  a  support  target:  dual-boot  HP-UX/Linux systems with both
       Linux and HP-UX file systems on a single disk
     * Possibility:  write mnttab into palo so you can boot with "normal"
       path   names   on  that  machine.  If  palo  knew  where  to  find
       /etc/mnttab...

                                  Features

   PA/Linux partitioned hard disks:
     * can be read/written by current Linux boxes, expecially x86
     * can be read/written by IA-64 Linux boxes
     * are tolerated by IA-32 and IA-64 non-Linux boxes
     * are not understood by the HP-UX secondary boot loader
     * require no new disk partitioning tools

                                Terminology

   palo  is  two  programs,  a  boot  loader,  which  is loaded by the HP
   firmware  into  memory  and  then  executed, and boot media management
   tool,  which initializes and updates bootable media such as disks. The
   palo  boot  loader  is  stored  in  a file called iplboot. "IPL" is HP
   jargon  for  Initial Program Loader. It's mostly called "the palo boot
   loader" in this document.

   The boot media management tool is called palo, just as on x86 the LILO
   boot  media  management  tool is called lilo, though it's worth noting
   that  palo  doesn't usually need to be used every time you build a new
   kernel, as lilo does.

                             Basic Media Format

   Bootable PA/Linux disks combine a standard MS-DOS partition table with
   the  data  required  for  HP  firmware  to locate its boot loader, all
   within  the  first 512-byte "sector" of the disk. Here is the detailed
   layout  of  the  first  512 bytes of the disk. Only these bytes can be
   depended  upon! The term "IPL" means Initial Program Loader e.g., boot
   loader in HP-ese.
        Offset (hex)            Contents        Why

        0                       0x80            These two bytes denote
        1                       0x00            a LIF volume to HP firmware

        f0-f3                   IPL_ADDR        disk offset to beginning
                                                of boot "IPL" loader.  Must
                                                not be zero.  Must be a
                                                multiple of 2kbytes.
                                                Big endian.

        f4-f7                   IPL_SIZE        Size of boot loader in bytes.
                                                Must be a multiple of 2kbytes.
                                                Big endian.

        f8-f11                  IPL_ENTRY       Offset from the beginning
                                                of the boot loader to its
                                                entry point.  This really
                                                better be a multiple of 4bytes.
                                                Big endian.

        1b0-1ff                 P-TABLE         DOS partition table, managed
                                                by fdisk.

   Information about the kernel, command line, and ramdisk, is sandwiched
   between  the  LIF  magic  number  and  the  IPL_ADDR. Check out struct
   firstblock  in  common.h  for  the  details.  The boot program must be
   located  within  the  first  2  Gb of the boot medium (a limitation of
   older machines, which might not be permanent).

   palo works with both un-partitioned (usually sequential) media such as
   tapes,  and  partitioned  (usually random-access) media such as disks.
   The  media format for un-partitioned media is described first since it
   is  a  subset  of  the  format for partitioned media. In the remaining
   discussion, the term sequential is synonymous with un-partitioned, and
   random-access  is  synonymous with partitioned media. This restriction
   is not present in the palo software however.

   On  unpartitioned  media,  the  partition  table shown in the previous
   figure  is  unused  and set to values which will not be mistaken for a
   partition table. The boot loader program is stored starting at 2kbytes
   from  the  beginning  of the medium and is followed by the kernel file
   and optional ramdisk file.

   On  partitioned  media,  which  is  usually random-access, for example
   disks,  the  boot  loader  program must be stored in an area protected
   from  disk  management  software,  and  often cannot be located at the
   first  2kbyte  boundary  as on sequential media. palo therefore places
   the  boot  loader,  and  optionally a kernel and ramdisk, in a special
   partition,  created  by fdisk, of type F0. HP-UX firmware requires the
   boot program to be stored on the boot medium starting on a multiple of
   2kbytes,  whereas  the  F0  partition might start on a 512-byte sector
   boundary. The boot program starts within the F0 partition on the first
   2k  boundary,  which  may  be  up  to  3 sectors from the start of the
   partition.

   The  format  of  the boot loader, kernel, and ramdisk are identical to
   the  sequential  case  except that some padding is added in order that
   somewhat  larger  kernels  and boot loaders can be added later without
   re-writing  the  rest of the F0 partition (this feature may not yet be
   supported by palo however).

   On  partitioned  media, palo can load a kernel from any ext2-formatted
   partition  which  falls within the first 2G of the medium, in addition
   to  having  a  "sequential"  kernel,  perhaps  best seen as a recovery
   kernel, within the F0 partition.

                            Really Building palo

   In  the source directory type 'make'. On x86 you will need the PA-RISC
   cross compilers installed and in your $PATH.

   You  can  use  "make  DESTDIR=/ install" to install palo in the normal
   location.  On x86 the cross compilers are usually in "/opt/palinux" so
   I   use  "make  DESTDIR=/opt/palinux  install".  Note  that  the  palo
   executable  goes into "DESTDIR/sbin" which you may want to add to your
   $PATH.

   Palo can also be built in the normal way as a Debian package though it
   cannot be cross-compiled as a Debian package.

                $Id: README.html,v 1.8.4.1 2001/06/14 01:33:38 bame Exp $
