Provide pre-built README file to avoid dependency on lynx.

2 files changed, 289 insertions, 1 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..a50b39e
--- /dev/null
+++ b/README
@@ -0,0 +1,288 @@
+                       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.
diff --git a/debian/control b/debian/control
index a31c4d5..b4fb777 100644
--- a/debian/control
+++ b/debian/control
@@ -3,7 +3,7 @@ Section: admin
 Priority: optional
 Maintainer: Helge Deller <deller@gmx.de>
 Uploaders:
-Build-Depends: debhelper (>= 9), lynx
+Build-Depends: debhelper (>= 9)
 Standards-Version: 3.9.5
 Homepage: http://git.kernel.org/cgit/linux/kernel/git/deller/palo.git
 Vcs-Browser: http://git.kernel.org/cgit/linux/kernel/git/deller/palo.git