[PATCH 4/9] Linux loader: add initial documentation

[Eero Tamminen <oak@xxxxxxxxxxxxxx>]

---
 doc/hatari.1          | 11 +++++++
 doc/lilo.cfg          | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/release-notes.txt |  1 +
 3 files changed, 95 insertions(+)
 create mode 100644 doc/lilo.cfg

diff --git a/doc/hatari.1 b/doc/hatari.1
index 061b4b2f..0aebb66f 100644
--- a/doc/hatari.1
+++ b/doc/hatari.1
@@ -495,6 +495,17 @@ Specify which exceptions invoke debugger, see
 .B \-\-debug\-except help
 for available (comma separated) exception flags.
 .TP
+.B \-\-lilo <string>
+Boot m68k Linux using kernel, ramdisk, and kernel arguments specified
+in the Hatari configuration file [LILO] section. Hatari documentation
+folder contains an example "lilo.cfg" config file for this. String
+given to the \-\-lilo option is appended to the kernel command line.
+.br
+NOTE: This is Hatari (and Linux kernel) developer option to test Linux
+booting.  Unless you know how your kernel is configured, and the state
+of specific kernel and Hatari features, don't expect m68k Linux to
+boot up succesfully.
+.TP
 .B \-\-bios\-intercept <bool>
 Enable/Disable XBios command parsing. XBios(11) Dbmsg call can be used
 to invoke Hatari debugger. XBios(20) printscreen calls produce also
diff --git a/doc/lilo.cfg b/doc/lilo.cfg
new file mode 100644
index 00000000..b4b1732f
--- /dev/null
+++ b/doc/lilo.cfg
@@ -0,0 +1,83 @@
+# 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
+
+[LILO]
+
+# Kernel file name, see:
+#   https://en.wikipedia.org/wiki/Vmlinux
+Kernel = vmlinuz
+
+# Initial ramdisk (initramfs since 2.6 kernels), see:
+#   https://en.wikipedia.org/wiki/Initial_ramdisk
+#   https://wiki.debian.org/initramfs
+#   https://wiki.ubuntu.com/Initramfs
+Ramdisk = initrd.img
+
+# 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
+#
+# Few common arguments:
+# - loglevel=<1-15>, default=7, quiet=4
+# - root=<device>, root file system device:
+#   /dev/ram    -- ramdisk (specified above)
+#   /dev/fd0    -- "--disk-a <image>"
+#   /dev/fd1    -- "--disk-b <image>"
+#   /dev/hda<n> -- "--ide-master <image>"
+#   /dev/hdb<n> -- "--ide-slave <image>"
+#   /dev/sda<n> -- "--scsi 0=<image>"
+#   /dev/sdb<n> -- "--scsi 1=<image>"
+# - 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
+#
+# 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)
+# - stram_pool=<size>, bytes set aside for ST-RAM allocs (default=1MB)
+
+Args = root=/dev/ram video=atafb:sthigh
+
+# Load kernel (and ramdisk) to TT-RAM if there's enough of it
+# - Note: some kernel versions work only from TT-RAM, some only from ST-RAM!
+LoadToFastRam = TRUE
+
+# Whether to exit emulator when Linux resets on reboots
+# - automatically disabled unless Hatari "--natfeats on" option is used
+HaltOnReboot = TRUE
diff --git a/doc/release-notes.txt b/doc/release-notes.txt
index 3747ba5e..3d4ed14d 100644
--- a/doc/release-notes.txt
+++ b/doc/release-notes.txt
@@ -7,6 +7,7 @@
  -------------------
 
 Emulator:
+- Add --lilo linux loading debug option
 - Fix: when autostarting programs without pre-existing INF file,
   enable blitter also with EmuTOS
 
-- 
2.11.0


--------------A9B4B3CBBE16AB6BBACAF517
Content-Type: text/x-patch;
 name="0003-Linux-loader-integrate-lilo.c-to-Hatari-and-add-lilo.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename*0="0003-Linux-loader-integrate-lilo.c-to-Hatari-and-add-lilo.pa";
 filename*1="tch"