From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from metis.ext.pengutronix.de ([2001:6f8:1178:4:290:27ff:fe1d:cc33]) by bombadil.infradead.org with esmtps (Exim 4.69 #1 (Red Hat Linux)) id 1NUdrz-0007Gk-6G for barebox@lists.infradead.org; Tue, 12 Jan 2010 10:21:05 +0000 Received: from octopus.hi.pengutronix.de ([2001:6f8:1178:2:215:17ff:fe12:23b0]) by metis.ext.pengutronix.de with esmtp (Exim 4.69) (envelope-from ) id 1NUdrq-0006Vo-BB for barebox@lists.infradead.org; Tue, 12 Jan 2010 11:20:54 +0100 Received: from jbe by octopus.hi.pengutronix.de with local (Exim 4.69) (envelope-from ) id 1NUdrq-0006yW-8p for barebox@lists.infradead.org; Tue, 12 Jan 2010 11:20:54 +0100 Message-Id: <20100112102054.163194713@pengutronix.de> References: <20100112101534.868276907@pengutronix.de> Date: Tue, 12 Jan 2010 11:15:37 +0100 From: Juergen Beisert Content-Disposition: inline; filename=add_x86_documentation.diff List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Sender: barebox-bounces@lists.infradead.org Errors-To: barebox-bounces+u.kleine-koenig=pengutronix.de@lists.infradead.org Subject: [PATCHv2 03/14] Adding x86 usage documentation to the tree To: barebox@lists.infradead.org Adding x86 usage documentation to the tree Signed-off-by: Juergen Beisert --- 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