[PATCH 9/9] Linux loader: documentation updates

[Eero Tamminen <oak@xxxxxxxxxxxxxx>]

- Split build and Hatari running instructions from lilo.cfg
  to a separate document and expand it significantly
- List which kernel config options are related to
  each kernel command line option in lilo.cfg
---
 doc/lilo.cfg                  |  88 +++++++++-----------
 doc/m68k-linux-for-hatari.txt | 186 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 225 insertions(+), 49 deletions(-)
 create mode 100644 doc/m68k-linux-for-hatari.txt

diff --git a/doc/lilo.cfg b/doc/lilo.cfg
index 25236d55..314f197a 100644
--- a/doc/lilo.cfg
+++ b/doc/lilo.cfg
@@ -1,78 +1,68 @@
 # These config options are identical to ones used by the Aranym emulator.
 # Edit them to suit your kernel before using this config!!!
 #
-# Kernel build (Debian):
-#   apt install gcc-m68k-linux-gnu
-#   git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-#             git://git.kernel.org/pub/scm/linux/kernel/git/geert/linux-m68k.git
-#             (-> "git checkout m68k-v5.0")
-#   ARCH=m68k CROSS_COMPILE=m68k-linux-gnu- make menuconfig
-#   <disable modules and add anything needed as builtin>
-#   ARCH=m68k CROSS_COMPILE=m68k-linux-gnu- make vmlinux
-#
-# Kernel/initrd notes:
-# - Current (v4.x+) Linux kernels don't work with TT, only with Falcon
-# - Typical ramdisks are so large that they need to be loaded to TT-RAM
-# - Normal Linux builds require MMU and 030 or better
-#   (only uCLinux would work on ST/STE i.e. without MMU)
-# - Bootup works faster if kernel and ramdisk are uncompressed
-#   (as uncompression would happen in emulated code)
-#
-# Hatari notes:
-# - Suitable Hatari command lines look like this:
-#     hatari --trace nvram --log-level debug --machine falcon --dsp dummy \
-#      --mmu on --fpu 68882 -s 14 --ttram 64 --addr24 off  -c lilo.cfg \
-#      --lilo "debug=par" --printer /dev/stderr
+# Documentation on how to build m68k Linux kernel, ramdisk and rootfs
+# for use with Hatari are in the m68k-linux-for-hatari.txt file, along
+# with notes about suitable Hatari options for them.
 
 [LILO]
 
-# Kernel file name, see:
+# Kernel file name:
 #   https://en.wikipedia.org/wiki/Vmlinux
 Kernel = vmlinuz
 
-# Initial ramdisk (initramfs since 2.6 kernels), see:
+# Initial ramdisk (initramfs since 2.6 kernels):
+#   https://www.kernel.org/doc/Documentation/filesystems/ramfs-rootfs-initramfs.txt
 #   https://en.wikipedia.org/wiki/Initial_ramdisk
 #   https://wiki.debian.org/initramfs
 #   https://wiki.ubuntu.com/Initramfs
-Ramdisk = initrd.img
+# Relevant if kernel needs to load modules or do other things
+# (e.g. uncrypting) to mount actual root file system
+Ramdisk =
 
 # Kernel command line arguments, see:
 #   https://www.kernel.org/doc/Documentation/m68k/kernel-options.txt
-# Ramdisk options (older/manual alternative for initrd):
-#   https://www.kernel.org/doc/Documentation/blockdev/ramdisk.txt
-# For example, 16MB ext2 FS can be created from dir/ contents with:
-#     /sbin/mke2fs -t ext2 -L NAME -d dir/ ext2.img 16M
+# Specifying partition or partitiontable:
+#   https://www.kernel.org/doc/Documentation/block/cmdline-partition.txt
+#   (CONFIG_BLK_CMDLINE_PARSER, CONFIG_CMDLINE_PARTITION,
+#    CONFIG_ATARI_PARTITION, CONFIG_MSDOS_PARTITION)
 #
 # Few common arguments:
-# - loglevel=<1-15>, default=7, quiet=4
+# - console=<device> -- device for interactive console
+#   tty -- onscreen virtual terminal (CONFIG_VT_CONSOLE)
 # - root=<device>, root file system device:
-#   /dev/ram    -- ramdisk (specified above)
-#   /dev/fd0    -- "--disk-a <image>"
+#   /dev/ram    -- ramdisk (CONFIG_BLK_DEV_RAM)
+#   /dev/fd0    -- "--disk-a <image>" (CONFIG_ATARI_FLOPPY)
 #   /dev/fd1    -- "--disk-b <image>"
-#   /dev/hda<n> -- "--ide-master <image>"
+#   /dev/hda<n> -- "--ide-master <image>" (CONFIG_BLK_DEV_FALCON_IDE)
 #   /dev/hdb<n> -- "--ide-slave <image>"
-#   /dev/sda<n> -- "--scsi 0=<image>"
+#   /dev/sda<n> -- "--scsi 0=<image>" (CONFIG_ATARI_SCSI)
 #   /dev/sdb<n> -- "--scsi 1=<image>"
-# - devtmpfs.mount=1, mount devtmpfs at /dev after kernel mounts
+# - ro/rw -- whether to mount rootfs read-only or writable
+# - scsi_mod.scan=sync -- disable async SCSI scanning (CONFIG_SCSI_SCAN_ASYNC)
+# - devtmpfs.mount=1 -- mount devtmpfs at /dev after kernel mounts
 #   root filesystem. Does not affect initramfs based mounting
-# - console=<device>, not needed as it defaults to "tty0"
-# - earlyprintk --  if enabled in kernel config, early boot debug output
+#   (CONFIG_DEVTMPFS_MOUNT)
+# - loglevel=<1-15> -- debug output logging: default=7, quiet=4
 #
 # Atari specific arguments:
-# - video=<fbdev>:<mode>, "atafb" for Atari framebuffer, with mode one of:
-#   stlow stmid sthigh (for all machines)
-#   ttlow ttmid tthigh (TT-only)
-#   vga2 vga4 vga16 vga256 falh2 falh16 (Falcon-only)
-# - debug=<output>, kernel boot messages output option, where output is one of:
-#   par -- parallel port (recommended, "--printer /dev/stderr" shows messages)
-#   midi -- MIDI port ("--midi-out /dev/stderr" shows messages, if also MIDI-in)
-#   ser1 -- ST-MFP Modem1 serial port ("--rs232-out serial.txt", if also RS232-in)
-#   ser2 -- SCC Modem2 serial port ("--scc-b-out serial.txt")
-#   ser -- "ser2" on Falcon, "ser1" on other machines
-#   nfcon -- if NatFeats enabled in kernel config ("--natfeats on" shows messages)
+# - video=atafb:<mode> -- Atari framebuffer / VT, with mode one of:
+#   - stlow, stmid, sthigh -- all machines
+#   - ttlow, ttmid, tthigh -- TT-only
+#   - vga2, vga4, vga16, vga256, falh2, falh16 -- Falcon-only
+#   (CONFIG_FB_ATARI)
+# - external:<spec> -- Hatari VDI mode, see m68k/kernel-options.txt
+#   (CONFIG_FB_SIMPLE)
+# - debug=<output> -- select kernel debug boot messages output:
+#   - par   -- parallel port, "--printer /dev/stderr" shows messages
+#   - midi  -- MIDI, "--midi-out /dev/stderr" shows messages, if also MIDI-in enabled
+#   - ser1  -- ST-MFP, "--rs232-out serial-out.txt", if also RS232-in enabled
+#   - ser2  -- SCC, "--scc-b-out serial-out.txt"
+#   - ser   -- "ser2" on Falcon, "ser1" on other machines
+#   - nfcon -- NatFeats STDERR (CONFIG_NFCON), "--natfeats on" shows messages
 # - stram_pool=<size>, bytes set aside for ST-RAM allocs (default=1MB)
 
-Args = root=/dev/ram video=atafb:sthigh
+Args = video=atafb:sthigh
 
 # Whether to load kernel to TT-RAM when there's enough of it
 # (some kernel versions work only from TT-RAM, some only from ST-RAM!)
diff --git a/doc/m68k-linux-for-hatari.txt b/doc/m68k-linux-for-hatari.txt
new file mode 100644
index 00000000..ef356ae8
--- /dev/null
+++ b/doc/m68k-linux-for-hatari.txt
@@ -0,0 +1,186 @@
+Contents:
+
+1. Introduction
+2. Building m68k kernel
+3. Building initrd
+4. Building root file system
+4.1 As EXT2 HD image (from BusyBox)
+4.2 As FAT HD/floppy image (from klibc utils)
+5. Running Hatari
+6. Notes
+
+
+1. Introduction
+---------------
+
+Here are instructions on building m68k:
+- kernel
+- ramdisk
+- root file system
+
+That will work in Hatari, with given options.
+
+Instructions are for Debian (and derivatives like Ubuntu)
+as that still supports m68k in ports:
+	http://ftp.ports.debian.org/debian-ports/pool-m68k/main/
+
+
+2. Building m68k kernel
+-----------------------
+
+1. Install compiler:
+   $ apt install gcc-m68k-linux-gnu
+
+2. Get v5.0 m68k kernel sources (without history):
+   $Â git clone --depth 1 --branch m68k-v5.0 \
+     git://git.kernel.org/pub/scm/linux/kernel/git/geert/linux-m68k.git
+
+3. Get Hatari compatible configuration:
+   $Â cd linux-m68k
+   $Â cp /path/to/hatari/tools/linux/kernel.config .config
+
+4. Fine-tune kernel config for your requirements:
+   $Â ARCH=m68k CROSS_COMPILE=m68k-linux-gnu- make menuconfig
+
+4. Compile configured kernel:
+   $Â ARCH=m68k CROSS_COMPILE=m68k-linux-gnu- make vmlinux
+
+
+3. Building initrd
+------------------
+
+NOTE: this is unnecessary with kernel having modules built-in.
+It's needed only if you change provided kernel config to be
+modular instead.
+
+<collect kernel modules etc things needed to mount rootfs>
+$Â cd /to/initrd/dir/
+$Â find | cpio -R 0:0 -H newc --create | lzop -9 > ../initrd.img
+
+
+4. Building root file system
+----------------------------
+
+This is same for both examples below, and assumes there's no
+pre-existing disk/ -directory (if there is, clean it first).
+
+1. Create directories for content:
+   $ mkdir -p disk
+   $Â cd disk
+   $Â mkdir dev etc proc run sys tmp
+
+2. Add minimal init script for mounting virtual file systems
+   before starting shell:
+   $ cp -a /path/to/hatari/tools/linux/init.sh init
+
+
+4.1 As EXT2 HD image (from BusyBox)
+-----------------------------------
+
+This builds a minimal 8MB EXT2 hard disk image with BusyBox.
+
+BusyBox is a multi-call binary, which performs the same job as more
+than one utility program, based on the (symlink) name with which it is
+invoked. For more info, see "man busybox" after creating the image.
+
+3. Fetch statically linked m68k BusyBox and extract it:
+   $Â wget http://ftp.ports.debian.org/debian-ports/pool-m68k/main/b/busybox/busybox-static_1.30.1-2_m68k.deb
+   $Â ar x busybox-static_1.30.1-2_m68k.deb
+   $Â tar xvf data.tar.xz ./bin/busybox
+
+4. Add symlinks for BusyBox tools:
+   $Â sudo apt install busybox
+   $ /path/to/hatari/tools/linux/symlink-busybox.sh
+
+5. Directory content cleanup:
+   $Â rm *.*
+   $Â cd ..
+
+6. Make HD image out of it:
+   $ /sbin/mkfs.ext2 -t ext2 -L NAME -d disk/ bb-rootfs.img 8M
+
+
+4.2 As FAT HD/floppy image (from klibc utils)
+--------------------------------------
+
+This builds image with VFAT file system.  All the utilities are real
+binaries instead of symlinks, so FAT file system is enough for them
+(VFAT long file names are needed for the klibc library name).
+
+3. Fetch klibc library and utilities:
+   $Â wget http://ftp.ports.debian.org/debian-ports/pool-m68k/main/k/klibc/libklibc_2.0.6-1_m68k.deb
+   $Â wget http://ftp.ports.debian.org/debian-ports/pool-m68k/main/k/klibc/klibc-utils_2.0.6-1_m68k.deb
+
+4. Extract them:
+   $ ar x libklibc_2.0.6-1_m68k.deb
+   $Â tar xvf data.tar.xz
+   $ ar x klibc-utils_2.0.6-1_m68k.deb
+   $Â tar xvf data.tar.xz
+
+5. Move to utils to bin/ and clean directory:
+   $ mv usr/lib/klibc/bin/ .
+   $Â rm -r *.* usr
+   $ cd ..
+
+6. Make HD image with one FAT partition out of the directory contents:
+   $ atari-hd-image 8 -vfat klibc-rootfs.img NAME disk/
+
+7. Make floppy out of it:
+   $Â zip2st disk/ klibc-rootfs.st
+
+NOTE: atari-hd-image will include (DOS) partition table to the image,
+so you need to give the first partion (hda1) as root, instead of the
+whole disk (hda).
+
+
+5. Running Hatari
+-----------------
+
+1. Set suitable options in lilo.cfg
+
+2. Start Hatari:
+    $ hatari --trace nvram --log-level debug \
+      --fast-forward on --fastfdc on --timer-d on \
+      --machine falcon --dsp dummy --fpu 68882 \
+      --mmu on -s 14 --ttram 64 --addr24 off \
+      -c lilo.cfg --natfeats on \
+
+2a) Busybox HD rootfs options:
+      --ide-master bb-rootfs.img \
+      --lilo "debug=nfcon root=/dev/hda ro init=/init"
+
+2b) Klibc utils HD rootfs options:
+      --ide-master klibc-rootfs.img \
+      --lilo "debug=nfcon root=/dev/hda1 ro init=/init"
+
+2c) Klibc utils floppy rootfs options:
+      --disk-a klibc-rootfs.st \
+      --lilo "debug=nfcon root=/dev/fd0 ro init=/init"
+
+
+6. Notes
+--------
+
+- Current (v4.x+) Linux kernels don't work with TT, only with Falcon
+
+- Typical ramdisks are so large that they need to be loaded to TT-RAM,
+  so building non-modular kernel that includes all relevant features
+  and using using rootfs directly saves some memory
+
+- Normal Linux builds require 030 or better with MMU and FPU (only
+  uCLinux would work on ST/STE i.e. on 68000 without MMU)
+
+- Bootup works faster if kernel is uncompressed (as uncompression
+  would happen in emulated code)
+
+- However, ramdisk can't be uncompressed beforehand, because then it's
+  interpreted to be microcode part before the actual initramfs.  Just
+  use smaller initramfs
+
+- LZO provides faster decompression speed, gzip/deflate better
+  compression ratio.  Both are enabled in included kernel.config.
+  Kernel offers also compression algoritms that have better
+  compression ratio, but they're significantly slower
+
+- Put "init=" last on kernel command line, otherwise kernel may give
+  arguments after it also as to init
-- 
2.11.0


--------------A9B4B3CBBE16AB6BBACAF517
Content-Type: text/x-patch;
 name="0008-Linux-loader-add-files-for-building-m68k-kernel-and-.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename*0="0008-Linux-loader-add-files-for-building-m68k-kernel-and-.pa";
 filename*1="tch"