This document describes the "new" booting procedure which all version 2.4.18 and later kernels use. The legacy "struct" method must not be used.

This document contains information from a wide variety of sources (see the Bibliography) and authors, you are encouraged to consult these sources for more information before asking questions of the Maintainers, or on the ARM Linux mailing lists. Most of these areas have been covered repeatedly in the past and you are likely to be ignored if you haven't done at least basic research.

Additionally it should be noted that provided the guidance in this document is followed, there should be no need for an implementor to understand every nuance of the assembler that starts the kernel. Experience has shown on numerous occasions that most booting problems are unlikely to be related to this code, said code is also quite tricky and unlikely to give any insight into the problem.

Before embarking on writing a new bootloader a developer should consider if one of the existing loaders is appropriate. There are examples of loaders in most areas, from simple GPL loaders to full blown commercial offerings. A short list is provided here but the documents in the Bibliography offer more solutions.

ARM Linux cannot be started on a machine without a small amount of machine specific code to initialise the system. ARM Linux requires the bootloader code to do very little, although several bootloaders do provide extensive additional functionality. The minimal requirements are:

It is usually expected that the bootloader will initialise a serial or video console for the kernel in addition to these basic tasks. Indeed a serial port is almost considered mandatory in most system configurations.

Each of these steps will be examined in the following sections.

The bootloader is expected to find and initialise all RAM that the kernel will use for volatile data storage in the system. It performs this in a machine dependent manner. It may use internal algorithms to automatically locate and size all RAM, or it may use knowledge of the RAM in the machine, or any other method the bootloader designer sees fit.

In all cases it should be noted that all setup is performed by the bootloader. The kernel should have no knowledge of the setup or configuration of the RAM within a system other than that provided by the bootloader. The use of machine_fixup() within the kernel is most definitely not the correct place for this. There is a clear distinction between the bootloaders responsibility and the kernel in this area.

The physical memory layout is passed to the kernel using the ATAG_MEM parameter. Memory does not necessarily have to be completely contiguous, although the minimum number of fragments is preferred. Multiple ATAG_MEM blocks allow for several memory regions. The kernel will coalesce blocks passed to it if they are contiguous physical regions.

The bootloader may also manipulate the memory with the kernels command line, using the 'mem=' parameter, the options for this parameter are fully documented in linux/Documentation/kernel-parameters.txt

The kernel command line 'mem=' has the syntax mem=<size>[KM][,@<phys_offset>] which allows the size and physical memory location for a memory area to be defined. This allows for specifying multiple discontigous memory blocks at differing offsets by providing the mem= parameter multiple times.

Kernel images generated by the kernel build process are either uncompressed "Image" files or compressed zImage files.

The uncompressed Image files are generally not used, as they do not contain a readily identifiable magic number. The compressed zImage format is almost universally used in preference.

The zImage has several benefits in addition to the magic number. Typically, the decompression of the image is faster than reading from some external media. The integrity of the image can be assured, as any errors will result in a failed decompress. The kernel has knowledge of its internal structure and state, which allows for better results than a generic external compression method.

The zImage has a magic number and some useful information near its beginning.

The start and end offsets can be used to determine the length of the compressed image (size = end - start). This is used by several bootloaders to determine if any data is appended to the kernel image. This data is typically used for an initial RAM disk (initrd). The start address is usually 0 as the zImage code is position independent.

The zImage code is Position Independent Code (PIC) so may be loaded anywhere within the available address space. The maximum kernel size after decompression is 4Megabytes. This is a hard limit and would include the initrd if a bootpImage target was used.

Despite the ability to place zImage anywhere within memory, convention has it that it is loaded at the base of physical RAM plus an offset of 0x8000 (32K). This leaves space for the parameter block usually placed at offset 0x100, zero page exception vectors and page tables. This convention is very common.

An initial RAM disk is a common requirement on many systems. It provides a way to have a root filesystem available without access to other drivers or configurations. Full details can be obtained from linux/Documentation/initrd.txt

There are two methods available on ARM Linux to obtain an initial RAM disk. The first is a special build target bootpImage which takes an initial RAM disk at build time and appends it to a zImage. This method has the benefit that it needs no bootloader intervention, but requires the kernel build process to have knowledge of the physical address to place the ramdisk (using the INITRD_PHYS definition). The hard size limit for the uncompressed kernel and initrd of 4Megabytes applies. Because of these limitations this target is rarely used in practice.

The second and much more widely used method is for the bootloader to place a given initial ramdisk image, obtained from whatever media, into memory at a set location. This location is passed to the kernel using ATAG_INITRD2 and ATAG_RAMDISK.

Conventionally the initrd is placed 8Megabytes from the base of physical memory. Wherever it is placed there must be sufficient memory after boot to decompress the initial ramdisk into a real ramdisk i.e. enough memory for zImage + decompressed zImage + initrd + uncompressed ramdisk. The compressed initial ramdisk memory will be freed after the decompression has happened. Limitations to the position of the ramdisk are:

A console is highly recommended as a method to see what actions the kernel is performing when initialising a system. This can be any input output device with a suitable driver, the most common cases are a video framebuffer driver or a serial driver. Systems that ARM Linux runs on tend to almost always provide a serial console port.

The bootloader should initialise and enable one serial port on the target.This includes enabling any hardware power management etc., to use the port. This allows the kernel serial driver to automatically detect which serial port it should use for the kernel console (generally used for debugging purposes, or communication with the target.)

As an alternative, the bootloader can pass the relevant 'console=' option to the kernel, via the command line parameter specifying the port, and serial format options as described in linux/Documentation/kernel-parameters.txt

The bootloader must pass parameters to the kernel to describe the setup it has performed, the size and shape of memory in the system and, optionally, numerous other values.

The tagged list should conform to the following constraints

Each tag in the list consists of a header containing two unsigned 32 bit values, the size of the tag (in 32 bit, 4 byte words) and the tag value

struct atag_header {
        u32 size; /* legth of tag in words including this header */
        u32 tag;  /* tag value */
};

Each tag header is followed by data associated with that tag, excepting ATAG_NONE which has no data and ATAG_CORE where the data is optional. The size of the data is determined by the size field in header, the minimum size is 2 as the headers size is included in this value. The ATAG_NONE is unique in that its size field is set to zero.

A tag may contain additional data after the mandated structures provided the size is adjusted to cover the extra information, this allows for future expansion and for a bootloader to extend the data provided to the kernel. For example a bootloader may provide additional serial number information in an ATAG_SERIAL which could them be interpreted by a modified kernel.

The order of the tags in the parameter list is unimportant, they may appear as many times as required although interpretation of duplicate tags is tag dependant.

The data for each individual tag is described in the Appendix A, Tag Reference section.

For implementation purposes a structure can be defined for a tag

struct atag {
        struct atag_header hdr;
        union {
                struct atag_core         core;
                struct atag_mem          mem;
                struct atag_videotext    videotext;
                struct atag_ramdisk      ramdisk;
                struct atag_initrd2      initrd2;
                struct atag_serialnr     serialnr;
                struct atag_revision     revision;
                struct atag_videolfb     videolfb;
                struct atag_cmdline      cmdline;
        } u;
};

Once these structures have been defined an implementation needs to create the list this can be implemented with code similar to

#define tag_next(t)     ((struct tag *)((u32 *)(t) + (t)->hdr.size))
#define tag_size(type)  ((sizeof(struct tag_header) + sizeof(struct type)) >> 2)
static struct atag *params; /* used to point at the current tag */

static void
setup_core_tag(void * address,long pagesize)
{
    params = (struct tag *)address;         /* Initialise parameters to start at given address */

    params->hdr.tag = ATAG_CORE;            /* start with the core tag */
    params->hdr.size = tag_size(atag_core); /* size the tag */

    params->u.core.flags = 1;               /* ensure read-only */
    params->u.core.pagesize = pagesize;     /* systems pagesize (4k) */
    params->u.core.rootdev = 0;             /* zero root device (typicaly overidden from commandline )*/

    params = tag_next(params);              /* move pointer to next tag */
}

static void
setup_mem_tag(u32_t start, u32_t len)
{
    params->hdr.tag = ATAG_MEM;             /* Memory tag */
    params->hdr.size = tag_size(atag_mem);  /* size tag */

    params->u.mem.start = start;            /* Start of memory area (physical address) */
    params->u.mem.size = len;               /* Length of area */

    params = tag_next(params);              /* move pointer to next tag */
}

static void
setup_end_tag(void)
{
    params->hdr.tag = ATAG_NONE;            /* Empty tag ends list */
    params->hdr.size = 0;                   /* zero length */
}


static void
setup_tags(void)
{
    setup_core_tag(0x100, 4096);            /* standard core tag 4k pagesize */
    setup_mem_tag(0x10000000, 0x400000);    /* 64Mb at 0x10000000 */
    setup_mem_tag(0x18000000, 0x400000);    /* 64Mb at 0x18000000 */
    setup_end_tag(void);                    /* end of tags */
}

While this code fragment is complete it illustrates the absolute minimal requirements for a parameter set and is intended to demonstrate the concepts expressed earlier in this section. A real bootloader would probably pass additional values and would probably probe for the memory actually in a system rather than using fixed values. A more complete example can be found in Appendix B, Complete example

The only additional information the bootloader needs to provide is the machine type, this is a simple number unique for each ARM system often referred to as a MACH_TYPE.

The machine type number is obtained via the ARM Linux website Machine Registry. A machine type should be obtained as early in a projects life as possible, it has a number of ramifications for the kernel port itself (machine definitions etc.) and changing definitions afterwards may lead to a number of undesirable issues. These values are represented by a list of defines within the kernel source (linux/arch/arm/tools/mach-types)

The boot loader must obtain the machine type value by some method. Whether this is a hard coded value or an algorithm that looks at the connected hardware. Implementation is completely system specific and is beyond the scope of this document.

Once the bootloader has performed all the other steps it must start execution of the kernel with the correct values in the CPU registers.

The entry requirements are:

The bootloader is expected to call the kernel image by jumping directly to the first instruction of the kernel image.