arch/x86/mach-x86.dox

/* This document is intended to provide the developer with information
 * how to integrate a new CPU (MACH) into this part of the barebox tree
 */

/** @page dev_x86_mach barebox on x86 at runtime

@section mach_x86_memory_layout barebox's memory layout (BIOS based)

@a barebox uses the following memory layout at runtime when it still depends
on some kind of BIOS function:

@verbatim
     Addresses
------------------------

 seg:off     flat

xxxx:xxxx 0x01xxxxxx    end of  barebox's malloc area
    .        .
xxxx:xxxx 0x01000000    start of barebox's malloc area
    .          .
    .          .        (used while loading a Linux kernel of type 'bzImage')
    .          .
xxxx:xxxx 0x00100000    start of extended memory and  malloc area
    .          .
    .          .	(the big hole)
    .          .
9000:ffff 0x0009ffff    end of expected real mode memory
    .          .
    .          .        (used while loading a Linux kernel of type 'bzImage')
    .          .
9000:0000 0x00090000    end of used lower real mode memory
    .          .
    .          .
    .          .        Flat mode stack (about 32 kiB)
    .          .        bss
    .          .        Data
    .          .        Text
0000:7e00 0x00007e00	Real and flat mode barebox code
0000:7c00 0x00007c00	MBR initial boot loader code
0000:7a00 0x00007a00	location of the indirect sector (while booting only)
			below: real mode stack
@endverbatim

@note The start address of 0x0000:7c000 is a fixed one, defined by the BIOS.
So, for a BIOS based @a barebox this address can't be changed.

While the @a barebox code is runnung in flat mode, all interrupts are disabled.
But in the CPU only. All other interrupt settings are still valid. This is
required to be able to call real mode code from inside @a barebox flat mode
code. Thats why not the PIC is touched nor the IDT.

@todo Add some notes about drive numbers used by the BIOS. They may change
if one change orders in the BIOS setup. Drive orders and numbers may be
different at BIOS runtime and Linux runtime! But these numbers are required
at BIOS runtime for booting and the persistant environment storage.

@attention Currently there is a 4 GiB limit for the disk sizes!

@section mach_x86_image_layout barebox's image layout

@a barebox's binary image layout

@verbatim
  Offset     Content

 0x?????
    .        32 bit barebox code
    .
    .        16 bit bootstrap code, BIOS calling code
 0x00400
 0x003ff
    .        indirect sector
 0x00200
 0x001ff
    .        MBR
 0x00000
@endverbatim

The "indirect sector" is a free area in the image where the sector information
gets stored when this image will be written to a boot media. This information
is required to load all parts of the image from the boot media at runtime.

The image gets installed in two ways onto the boot media, depending on the
need for a persistant storage.

@subsection mach_x86_drive_layout_wops barebox's boot media layout without persistant storage

In this case @a barebox's persistant storage is anywhere:

@verbatim
  Sector     Content
---------------------------
    X        start of first partition
    .
    ?        end of the binary image
    .        32 bit barebox code
    2        16 bit bootstrap code, BIOS calling code
    1        indirect sector
    0        MBR, Partition table, boot code
@endverbatim

@subsection mach_x86_drive_layout_wps barebox's boot media layout with persistant storage

@a barebox's persistant storage is part of the boot media (more
space required in front of the first partition) and interferes with the
boot loader image itself:

@verbatim
  Sector     Content
---------------------------
    X        start of first partition
    .
    n+?      end of the binary image
    .        32 bit barebox code
    n+2      16 bit bootstrap code, BIOS calling code
    n+1      indirect sector
    n        end of persistant environment storage
    .
    1        start of persistant environment storage
    0        MBR, Partition table, boot code
@endverbatim

The information where the persistant storage is located is also stored into
the MBR at specific locations by @p setupmbr. The @a barebox runtime will use
it to load and store all environment relevant data.

*/