From: Juergen Beisert <jbe@pengutronix.de>
To: barebox@lists.infradead.org
Subject: [PATCHv2 03/14] Adding x86 usage documentation to the tree
Date: Tue, 12 Jan 2010 11:15:37 +0100 [thread overview]
Message-ID: <20100112102054.163194713@pengutronix.de> (raw)
In-Reply-To: <20100112101534.868276907@pengutronix.de>
[-- Attachment #1: add_x86_documentation.diff --]
[-- Type: text/plain, Size: 6236 bytes --]
Adding x86 usage documentation to the tree
Signed-off-by: Juergen Beisert <jbe@pengutronix.de>
---
Documentation/developers_manual.dox | 1
Documentation/users_manual.dox | 1
arch/architecture.dox | 1
arch/x86/mach-x86.dox | 128 ++++++++++++++++++++++++++++++++++++
4 files changed, 131 insertions(+)
Index: barebox-2009.12.0/arch/x86/mach-x86.dox
===================================================================
--- /dev/null
+++ barebox-2009.12.0/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.
+
+*/
Index: barebox-2009.12.0/arch/architecture.dox
===================================================================
--- barebox-2009.12.0.orig/arch/architecture.dox
+++ barebox-2009.12.0/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
*/
Index: barebox-2009.12.0/Documentation/users_manual.dox
===================================================================
--- barebox-2009.12.0.orig/Documentation/users_manual.dox
+++ barebox-2009.12.0/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
*/
Index: barebox-2009.12.0/Documentation/developers_manual.dox
===================================================================
--- barebox-2009.12.0.orig/Documentation/developers_manual.dox
+++ barebox-2009.12.0/Documentation/developers_manual.dox
@@ -20,5 +20,6 @@ This part of the documentation is intend
@li @subpage barebox_simul
@li @subpage io_access_functions
@li @subpage mcfv4e_MCDlib
+@li @subpage x86_runtime
*/
--
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
next prev parent reply other threads:[~2010-01-12 10:21 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-01-12 10:15 [PATCHv2 00/14] Bring in basic x86 support into 'barebox' Juergen Beisert
2010-01-12 10:15 ` [PATCHv2 01/14] Add a tool to activate barebox as a boot loader on x86 architectures Juergen Beisert
2010-01-12 10:15 ` [PATCHv2 02/14] Consider real and protected mode in the dump file Juergen Beisert
2010-01-12 10:15 ` Juergen Beisert [this message]
2010-01-12 10:15 ` [PATCHv2 04/14] Adding required architecture header files Juergen Beisert
2010-01-12 10:15 ` [PATCHv2 05/14] Bring in the first x86 specific code Juergen Beisert
2010-01-12 10:15 ` [PATCHv2 06/14] Add some generic functions to make x86 work Juergen Beisert
2010-01-12 10:15 ` [PATCHv2 07/14] Add functions to be able to boot with BIOSs help Juergen Beisert
2010-01-12 10:15 ` [PATCHv2 08/14] Add a generic PC platform Juergen Beisert
2010-01-12 10:15 ` [PATCHv2 09/14] Bring in the time reference for the x86 platforms Juergen Beisert
2010-01-12 10:15 ` [PATCHv2 10/14] Start to add ATA support to barebox Juergen Beisert
2010-01-12 10:15 ` [PATCHv2 11/14] Add the main disk driver Juergen Beisert
2010-01-12 10:15 ` [PATCHv2 12/14] Add a low level disk drive access driver Juergen Beisert
2010-01-12 10:15 ` [PATCHv2 13/14] Add a special command to load and start a bzImage on x86 Juergen Beisert
2010-01-12 10:15 ` [PATCHv2 14/14] Add the whole x86 architecture to the build system Juergen Beisert
2010-01-14 9:29 ` [PATCHv2 00/14] Bring in basic x86 support into 'barebox' Sascha Hauer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20100112102054.163194713@pengutronix.de \
--to=jbe@pengutronix.de \
--cc=barebox@lists.infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox