Linux/68k Atari Bootstrap version 3.2 ------------------------------------- Date: Feb 16, 1998 Linux/68k version: 2.1.85 Author: Roman.Hodek@informatik.uni-erlangen.de (Roman Hodek) 1) Introduction =============== This document describes the options available for the Atari bootstrap (``ataboot''). This bootstrap program (program name BOOTSTRA.TTP or ATABOOT.TTP, depending on your taste :-) is used to boot the Linux/68k kernel from TOS. It can be started either from the desktop, by simply double-clicking on it, or from a shell. If you start it in the desktop, you'll be prompted for a command line. You can then either enter some options (unfortunately, the space is rather limited...), or rely on the default arguments feature described in section 3. ataboot in many versions is available on ftp.uni-erlangen.de:/pub/Linux/680x0/vx.y/boot where vx.y is a kernel version (with the patchlevel omitted). There are usually two version, one with BOOTP and one without (see section 5 on how to include BOOTP support if compiling yourself). FAQ: How can I compile my own bootstrap? A: Unfortunately, that's not too easy :-( ataboot is a TOS program (obviously), so it must be compiled with a TOS compiler. On the other hand, it needs several files from include/{linux,asm}, so it needs the kernel source tree. And that isn't easy to unpack under TOS, because of its size and long file names. The best solution seems to be using a cross compiler, i.e. a compiler that runs under Linux but produces TOS programs. Such cross compilers (running under m68k-linux or i486-linux) are available at ftp.uni-erlangen.de, under /pub/Linux/680x0/tools. 2) Options ========== ataboot itself knows several options that modify its behaviour. These are: -? Display help information -d Enable debugging. This will print some additional data before lauching the kernel, and will also wait for a key being pressed. -k Sets the name of the kernel image to boot. Default is "vmlinux". The name is first tried with ".gz" appended, to find a compressed kernel. If such a file isn't found, the plain name is tried. Specials if is supported: If the name is exactly "vmlinux", the name sent to the BOOTP server is "" (empty string), which means use the default kernel. A prefix "local:" before the name means to skip BOOTP, and load a local disk file (name with prefix stripped). -r Gives the name of a ramdisk image to pass to the kernel. Default is not to use any ramdisk. You probably will also need the argument "root=/dev/ram" to let the kernel recognize the ramdisk as its boot device. With BOOTP, a "local:" prefix is supported as above. -s ("to ST-RAM") Load kernel into ST-RAM, even if there is TT-RAM (which would be preferred normally). Note that -s is ignored on a Medusa, the kernel is always loaded to ST-RAM there (it's the same kind of memory, no speed difference). -t ("ignore TT-RAM") Ignore any TT-RAM found, tell kernel only about ST-RAM. (Mainly for testing purposes, or if you have problems under Linux with your TT-RAM). -S ("force ST-RAM size") Pretend that the ST-RAM has size . is a number in decimal, a "0" prefix means octal, and "0x" hexadecimal. You can append either "k" or "m" (case-insensitive) to denote kBytes or MBytes, resp. Making ST-RAM smaller than it really is can make sense if you have lots of TT-RAM (min. 16 MB, better > 32 MB). Then using too much ST-RAM would only slow down the machine. But remind that some amount of ST-RAM is always needed for DMA buffer (video, floppy, ...). ataboot knows this, and if should be smaller than 256k, it announces 256k of ST-RAM nevertheless. If is bigger than the physical amount of ST-RAM you have, the kernel will crash... -T ("force TT-RAM size") Is the same as -S for TT-RAM, just no forcing of at least 256k is done. As above, the kernel will probably crash is is greater than how much TT-RAM you really have. -m : ("memory block") Tell the kernel about an additional memory block that isn't ST-RAM or TT-RAM, or isn't autodetected (could happen for some Falcon memory boards that aren't explictly supported. Magnum and BlowUp FX are.) If the memory you announce isn't really present, a bad crash will happen. is the (physical) start address of the memory block, as above "0" means octal notation, and "0x" hexadecimal. can be as above, i.e. with a "k" or "m" postfix. -n ("no BOOTP") If ataboot supports BOOTP, you can turn off its use with this option. ataboot will search for local disk files for kernel and ramdisk. (Usually a remote image has preference.) After these option understood by bootp, you can append further options that are passed to the kernel. See the file kernel-options.txt in this directory for a description of these. Just note: Kernel options *must follow* the bootstrap options, mixing both is not possible! 3) Default Arguments (bootargs) =============================== You'll see that most of the time, you'll be using ever the same arguments to bootstrap (kernel name, root device, maybe a video= option.) Since all these together can get quite long, there's an abbreviation to save typing. You can put a set of default options into a file "bootargs" in the same directory where the ataboot program is. In this file you can write down your default options just as you would have typed them on the command line. Just one exception: You can use newlines as separators, to make the file more readable (no over-long lines necessary). Newlines count simply as whitespace. The "bootargs" file is used whenever there are no options given to ataboot. (Really no options, not even a "-d" or the like...) E.g., if you just press RETURN in the desktop's dialog that lets you enter a command line. 4) Bootinfo Version =================== ataboot needs to pass some information to the kernel (machine type, memory configuration, command line, ...). These informations are stored in a structure called "boot info". Now different versions of kernels can need/use different infos from this bootinfo. In the past, we often had problems because ataboot's and the kernels view of the bootinfo strcuture were different. To fix this, a version number for the bootinfo has been introduced. The initial version used since around 1.2.13 was 1.0. (Seems we've added this versioning at a time where no more dramatic changes were needed... :-) Starting with 2.1 kernels, the bootinfo's internal structure has been changed totally, with the main advantage that no more incompabilities between the bootstrapper and the kernel are possible anymore. This format has been given version 2.0, and it probably is the highest major version ever given to a bootinfo. (As stated, the new format should be general enough to avoid any mismatches.) Why I'm telling you all this? Well, 2.0 kernels still use bootinfo 1.x, whereas 2.1 kernels use 2.x bootinfo. So you basically can't boot a 2.0 kernel with a bootstrap from a 2.1 source, and vice versa. But all new bootstraps for 2.1.x kernels have a compability mode that allows to also boot a kernel with 1.0 bootinfo (i.e., 2.0.x, or even older). If you really want, you can omit that compat mode, by undefining BOOTINFO_COMPAT_1_0 (see next section). If there should be any unexpected problems with bootinfo versions, ataboot should tell you about it. The above should give you an idea what's going on. For the rest, ask an guru... As a note, there exist now 3 bootinfo versions in all: 1.0: The original bootinfo, used by 2.0.x kernels and all older ones, since bootinfo versioning has been introduced. The bootinfo is simply a structure with some defined fields. 2.0: Used by 2.1 kernel up to 2.1.72. The bootinfo now consists of named tags with values, and the kernel picks the infos it needs. Unknown tags are ignored so they're no problem. 2.1: There's a new tag for Atari special machine type (Medusa, Hades, Afterburner040). That version came with ataboot-3.1 and kernel 2.1.79. With the new tag, the kernel needs not test for the machine type a second time, and it needs that tag. This means that you need an ataboot >= 3.1 for such kernels, but can still boot older kernels with the new ataboot. ataboot should abort if you try to boot a new kernel with a too-old bootstrap (therefore the updated minor version.) 5) Compile Time Options ======================= ataboot has --in addition to the command line options described above-- also some compile time options. These are selected in the Makefile (variable ATARI_BOOTOPTS), or on make's command line, e.g. like this: make ATARI_BOOTOPTS='-DBOOTINFO_COMPAT_1_0 -DAOUT_KERNEL' The options currently available are: - BOOTINFO_COMPAT_1_0: Support bootinfo version 1.0, in addition to current 2.0. This is necessary to be able to boot 2.0.x kernels with a 3.0 ataboot. - AOUT_KERNEL: Support kernels in a.out executable format. By now, such kernels should have become rather seldom, and can't even be built anymore since 2.1.x. It's unprobable that you need it... - USE_BOOTP: Include support for the BOOTP and TFTP protocols, to read the kernel (and ramdisk) image from a boot server (instead from disk). This comes *very* handy if you use another machine to cross-compile Linux/68k kernels :-) If USE_BOOTP is defined, also some Ethernet low-level drivers should be selected by defining ETHLL_* macros. The only such driver is current ETHLL_LANCE, for Lance-based boards (RieblCard, PAM VME). The default configuration is -DBOOTINFO_COMPAT_1_0 only, others are off. Support for BOOTP/TFTP can be selected by adding "USE_BOOTP=yes" on the make command line: make USE_BOOTP=yes