summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Documentation/developers_manual.dox1
-rw-r--r--Documentation/users_manual.dox1
-rw-r--r--arch/architecture.dox1
-rw-r--r--arch/x86/mach-x86.dox128
4 files changed, 131 insertions, 0 deletions
diff --git a/Documentation/developers_manual.dox b/Documentation/developers_manual.dox
index 2f7d3605ef..620905eaa7 100644
--- a/Documentation/developers_manual.dox
+++ b/Documentation/developers_manual.dox
@@ -20,5 +20,6 @@ This part of the documentation is intended for developers of @a barebox.
@li @subpage barebox_simul
@li @subpage io_access_functions
@li @subpage mcfv4e_MCDlib
+@li @subpage x86_runtime
*/
diff --git a/Documentation/users_manual.dox b/Documentation/users_manual.dox
index e4ba9d00e3..5467bee475 100644
--- a/Documentation/users_manual.dox
+++ b/Documentation/users_manual.dox
@@ -10,5 +10,6 @@ work easier.
@li @subpage readline_parser
@li @subpage command_reference
@li @subpage partitions
+@li @subpage x86_bootloader
*/
diff --git a/arch/architecture.dox b/arch/architecture.dox
index 669c028435..ea00dcdc89 100644
--- a/arch/architecture.dox
+++ b/arch/architecture.dox
@@ -88,6 +88,7 @@ TODO
@li @subpage dev_bf_mach
@li @subpage dev_ppc_mach
@li @subpage dev_m68k_mach
+@li @subpage dev_x86_mach
*/
diff --git a/arch/x86/mach-x86.dox b/arch/x86/mach-x86.dox
new file mode 100644
index 0000000000..fc5b85a081
--- /dev/null
+++ b/arch/x86/mach-x86.dox
@@ -0,0 +1,128 @@
+/* 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 x86_runtime 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.
+
+*/