From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.3 required=3.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_SANE_2 autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id AF48AC48BDE for ; Sun, 7 Jul 2019 19:59:59 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 4B62C2053B for ; Sun, 7 Jul 2019 19:59:59 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=hansenpartnership.com header.i=@hansenpartnership.com header.b="gLdyV2zM"; dkim=fail reason="signature verification failed" (1024-bit key) header.d=hansenpartnership.com header.i=@hansenpartnership.com header.b="gLdyV2zM" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727328AbfGGT77 (ORCPT ); Sun, 7 Jul 2019 15:59:59 -0400 Received: from bedivere.hansenpartnership.com ([66.63.167.143]:39130 "EHLO bedivere.hansenpartnership.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726605AbfGGT76 (ORCPT ); Sun, 7 Jul 2019 15:59:58 -0400 Received: from localhost (localhost [127.0.0.1]) by bedivere.hansenpartnership.com (Postfix) with ESMTP id 87B718EE1CB for ; Sun, 7 Jul 2019 12:59:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=hansenpartnership.com; s=20151216; t=1562529598; bh=O3FG3WWocq8oLgygKRkfIWnvN+tIyWr32Eghn+eTIXM=; h=Subject:From:To:Date:From; b=gLdyV2zMQDqmM1iIeuTKEUMZ07B+Q2KrKxdDWASPrI6RPmLYhQDJNDXI4fjSBR6vx KRFqNgxcPP7fEbEhxzq8LL1sz+6UUxAjnDsnrQhCw0jSc9ChlsYk2JXV0HEYs9Wio1 BCNE4b1KV+cXV1N90UIyEjzl2V8f+VYPlwKsbvl8= Received: from bedivere.hansenpartnership.com ([127.0.0.1]) by localhost (bedivere.hansenpartnership.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id ssRzSU4dfMjY for ; Sun, 7 Jul 2019 12:59:58 -0700 (PDT) Received: from jarvis.lan (unknown [50.35.68.20]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by bedivere.hansenpartnership.com (Postfix) with ESMTPSA id 2A5F98EE1B2 for ; Sun, 7 Jul 2019 12:59:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=hansenpartnership.com; s=20151216; t=1562529598; bh=O3FG3WWocq8oLgygKRkfIWnvN+tIyWr32Eghn+eTIXM=; h=Subject:From:To:Date:From; b=gLdyV2zMQDqmM1iIeuTKEUMZ07B+Q2KrKxdDWASPrI6RPmLYhQDJNDXI4fjSBR6vx KRFqNgxcPP7fEbEhxzq8LL1sz+6UUxAjnDsnrQhCw0jSc9ChlsYk2JXV0HEYs9Wio1 BCNE4b1KV+cXV1N90UIyEjzl2V8f+VYPlwKsbvl8= Message-ID: <1562529597.3216.18.camel@HansenPartnership.com> Subject: [PATCH v2] Update palo documentation From: James Bottomley To: Parisc List Date: Sun, 07 Jul 2019 12:59:57 -0700 Content-Type: text/plain; charset="UTF-8" X-Mailer: Evolution 3.26.6 Mime-Version: 1.0 Content-Transfer-Encoding: 7bit Sender: linux-parisc-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-parisc@vger.kernel.org Now that we support ext4 and palo within the boot label, update the documentation to reflect this. Also beef up the man page with examples and remove reference to palo in the gnu info system because it doesn't exist. Signed-off-by: James Bottomley --- v2: remove references to setting the console --- Makefile | 8 ++++--- README.html | 44 +++++++++++++++++++---------------- palo.8 | 72 ++++++++++++++++++++++++++++++++++++++++++---------------- palo.help2man | 46 +++++++++++++++++++++++++++++++++++++ palo/usage.txt | 8 +++---- 5 files changed, 132 insertions(+), 46 deletions(-) create mode 100644 palo.help2man diff --git a/Makefile b/Makefile index 8c76693..a372617 100644 --- a/Makefile +++ b/Makefile @@ -66,7 +66,7 @@ CMDLINE = 0/vmlinux HOME=/ TERM=linux $(ROOT) $(EISAIRQ) $(CONSOLE) HELP2MAN := $(shell command -v help2man 2> /dev/null) all: makepalo README palo.conf - + README: README.html lynx -dump README.html > README @@ -106,10 +106,12 @@ distclean: cd ipl && $(MAKE) distclean cd palo && $(MAKE) distclean -palo.8.gz: palo/palo palo/usage.txt ifdef HELP2MAN - help2man ./palo/palo > palo.8 +palo.8: palo/palo palo/usage.txt palo.help2man + help2man --no-info -i palo.help2man ./palo/palo > palo.8 endif + +palo.8.gz: palo.8 gzip -9 < palo.8 > palo.8.gz changelog.gz: debian/changelog diff --git a/README.html b/README.html index 0711890..784c86e 100644 --- a/README.html +++ b/README.html @@ -26,7 +26,7 @@ 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. +you'll call kernels and ramdisks on an ext2/3/4 partition.

Creating and Maintaining Bootable Disks

Partitioned media usually refers to disks, in this case disks partitioned @@ -35,14 +35,20 @@ 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 fdisk or something to (re)partition the disk. When + you are finished, the disk may need to 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/3/4 partition within the first 2Gb where you'll store your + Linux kernel. + +
  • If fdisk created the first partition at sector 2048, + which is usual for modern fdisk, you don't need a F0 partition, so + set all partition types to 82 swap or 83 linux and palo will place + the boot loader inside the disk label. You still need a /boot + partition <2GB from the beginning of the disk formatted as + ext2/3/4 where you keep your boot kernels and initial ramdisks.

  • Use mke2fs and mkswap as usual. @@ -67,16 +73,16 @@ 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 + a kernel from an ext2/3/4 partition instead. I like to have a kernel + there just in case the ext2/3/4 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 + number, 5, is the partition number of your ext2/3/4 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. + your kernel executable within your ext2/3/4 partition. The special partition number "0" is used to load the "recovery" kernel which you placed into the "F0" partition with -k. @@ -90,7 +96,7 @@ and running palo.

    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 +kernel in your ext2/3/4 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. @@ -143,7 +149,7 @@ 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 +contiguously (except when booting from ext2/3/4), and the ISO file system works well for this too.

    When you run palo, it locates the boot loader and kernel @@ -308,10 +314,10 @@ 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. +

    On partitioned media, palo can load a kernel from any +ext2/3/4-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

    diff --git a/palo.8 b/palo.8 index 7362621..c3a4e53 100644 --- a/palo.8 +++ b/palo.8 @@ -1,12 +1,12 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.5. -.TH PALO "1" "January 2018" "palo version 2.00" "User Commands" +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.10. +.TH PALO "1" "July 2019" "palo version 2.01" "User Commands" .SH NAME -palo \- manual page for palo version 2.00 +palo \- manual page for palo version 2.01 .SH SYNOPSIS .B palo [\fI\,options\/\fR] .SH DESCRIPTION -palo version 2.00 +palo version 2.01 .TP \-?, \fB\-\-help\fR Print this information @@ -83,10 +83,10 @@ Provide more verbose information when running palo \fB\-e\fR, \fB\-\-format\-as\fR=\fI\,type\/\fR .IP This is only for partitioned media. Format the palo -partition as an ext2 (type == 2) or ext3 (type == 3) -partition. With this option, you cannot specify any -parameters, kernels or ramdisks to be loaded into -the palo partition +partition as an ext2 (type == 2), ext3 (type == 3) or +ext4 (type == 4) partition. With this option, you +cannot specify any parameters, kernels or ramdisks to +be loaded into the palo partition .PP \&'palo' with no arguments whatsoever is equivalent to 'palo \fB\-f\fR \fI\,/etc/palo\/\fP.conf'. .PP @@ -94,15 +94,47 @@ When more than one of \fB\-I\fR, \fB\-U\fR, \fB\-s\fR and \fB\-C\fR are used, on last one is effective. .PP http://www.parisc\-linux.org \- Wed, 17 Jan 2018 15:15:40 +0100 -.SH "SEE ALSO" -The full documentation for -.B palo -is maintained as a Texinfo manual. If the -.B info -and -.B palo -programs are properly installed at your site, the command -.IP -.B info palo -.PP -should give you access to the complete manual. + +palo is the installation and management tool for the parisc +bootloader, called iplboot. The size required for the iplboot binary +is 256kb. Older MS-DOS label disks begin the first partition at +sector 63 and there is no room for iplboot within the disk label, so +you must create a palo partition of type F0 to hold iplboot. If your +disk was formatted more recently it should have a newer MS-DOS label +where the first partition begins at sector 2048 meaning there is room +for iplboot within the disk label and a palo (F0) partition is not +required. + +If you have a palo partition (type F0), it must occur within the first +2GB of the beginning of the disk. If you choose to have a palo +partition, you may store both the kernel and the initrd in this +partition, meaning you have to update it every time you update the +kernel, or you may choose to have a /boot partition, which must be +formatted as an ext2/3/4 filesystem, from which palo will load +kernels. This /boot partition also must be within the first 2GB of +the beginning of the disk. If you have no palo partition, and palo is +installed inside the disk label, you must have a /boot partition +because the disk label is still too small to contain a kernel and a +ramdisk. + +Palo allows you to specify a kernel command line, which is stored in +the firstboot partition. The format should be kernel first followed +by an optional initrd= and then the rest of the kernel parameters. +The format of the kernel and initial ramdisk files is /. It is recommended, but not required, that +both the kernel and the initial ramdisk be in the root directory of +the filesystem. +.SH EXAMPLES + +Create a Bootable disk on sda for the first time by installing palo + + $ palo -c "1/vmlinux initrd=1/initrd.img" -I /dev/sda + +Update the bootloader command line without re-installing it + + $ palo -c "1/vmlinux.new initrd=1/initrd.img.new" -U /dev/sda + +Format the palo partition as ext4 and install iplboot within that +partition using ext4 badblocks [requires a palo (type F0) partition]: + + $ palo palo -c "1/vmlinux initrd=1/initrd.img" --format-as=4 -I /dev/sda diff --git a/palo.help2man b/palo.help2man new file mode 100644 index 0000000..6c49bd5 --- /dev/null +++ b/palo.help2man @@ -0,0 +1,46 @@ +[>description] + +palo is the installation and management tool for the parisc +bootloader, called iplboot. The size required for the iplboot binary +is 256kb. Older MS-DOS label disks begin the first partition at +sector 63 and there is no room for iplboot within the disk label, so +you must create a palo partition of type F0 to hold iplboot. If your +disk was formatted more recently it should have a newer MS-DOS label +where the first partition begins at sector 2048 meaning there is room +for iplboot within the disk label and a palo (F0) partition is not +required. + +If you have a palo partition (type F0), it must occur within the first +2GB of the beginning of the disk. If you choose to have a palo +partition, you may store both the kernel and the initrd in this +partition, meaning you have to update it every time you update the +kernel, or you may choose to have a /boot partition, which must be +formatted as an ext2/3/4 filesystem, from which palo will load +kernels. This /boot partition also must be within the first 2GB of +the beginning of the disk. If you have no palo partition, and palo is +installed inside the disk label, you must have a /boot partition +because the disk label is still too small to contain a kernel and a +ramdisk. + +Palo allows you to specify a kernel command line, which is stored in +the firstboot partition. The format should be kernel first followed +by an optional initrd= and then the rest of the kernel parameters. +The format of the kernel and initial ramdisk files is /. It is recommended, but not required, that +both the kernel and the initial ramdisk be in the root directory of +the filesystem. + +[examples] + +Create a Bootable disk on sda for the first time by installing palo + + $ palo -c "1/vmlinux initrd=1/initrd.img" -I /dev/sda + +Update the bootloader command line without re-installing it + + $ palo -c "1/vmlinux.new initrd=1/initrd.img.new" -U /dev/sda + +Format the palo partition as ext4 and install iplboot within that +partition using ext4 badblocks [requires a palo (type F0) partition]: + + $ palo palo -c "1/vmlinux initrd=1/initrd.img" --format-as=4 -I /dev/sda diff --git a/palo/usage.txt b/palo/usage.txt index 893316a..e3b9302 100644 --- a/palo/usage.txt +++ b/palo/usage.txt @@ -49,10 +49,10 @@ Usage: palo [options] Provide more verbose information when running palo -e, --format-as=type This is only for partitioned media. Format the palo - partition as an ext2 (type == 2) or ext3 (type == 3) - partition. With this option, you cannot specify any - parameters, kernels or ramdisks to be loaded into - the palo partition + partition as an ext2 (type == 2), ext3 (type == 3) or + ext4 (type == 4) partition. With this option, you + cannot specify any parameters, kernels or ramdisks to + be loaded into the palo partition 'palo' with no arguments whatsoever is equivalent to 'palo -f /etc/palo.conf'. -- 2.16.4