diff options
Diffstat (limited to 'gpxe/src/arch/i386/README.i386')
| -rw-r--r-- | gpxe/src/arch/i386/README.i386 | 197 |
1 files changed, 0 insertions, 197 deletions
diff --git a/gpxe/src/arch/i386/README.i386 b/gpxe/src/arch/i386/README.i386 deleted file mode 100644 index b9b79cc4..00000000 --- a/gpxe/src/arch/i386/README.i386 +++ /dev/null @@ -1,197 +0,0 @@ -Etherboot/NILO i386 initialisation path and external call interface -=================================================================== - -1. Background - -GCC compiles 32-bit code. It is capable of producing -position-independent code, but the resulting binary is about 25% -bigger than the corresponding fixed-position code. Since one main use -of Etherboot is as firmware to be burned into an EPROM, code size must -be kept as small as possible. - -This means that we want to compile fixed-position code with GCC, and -link it to have a predetermined start address. The problem then is -that we must know the address that the code will be loaded to when it -runs. There are several ways to solve this: - -1. Pick an address, link the code with this start address, then make - sure that the code gets loaded at that location. This is - problematic, because we may pick an address that we later end up - wanting to use to load the operating system that we're booting. - -2. Pick an address, link the code with this start address, then set up - virtual addressing so that the virtual addresses match the - link-time addresses regardless of the real physical address that - the code is loaded to. This enables us to relocate Etherboot to - the top of high memory, where it will be out of the way of any - loading operating system. - -3. Link the code with a text start address of zero and a data start - address also of zero. Use 16-bit real mode and the - quasi-position-independence it gives you via segment addressing. - Doing this requires that we generate 16-bit code, rather than - 32-bit code, and restricts us to a maximum of 64kB in each segment. - -There are other possible approaches (e.g. including a relocation table -and code that performs standard dynamic relocation), but the three -options listed above are probably the best available. - -Etherboot can be invoked in a variety of ways (ROM, floppy, as a PXE -NBP, etc). Several of these ways involve control being passed to -Etherboot with the CPU in 16-bit real mode. Some will involve the CPU -being in 32-bit protected mode, and there's an outside chance that -some may involve the CPU being in 16-bit protected mode. We will -almost certainly have to effect a CPU mode change in order to reach -the mode we want to be in to execute the C code. - -Additionally, Etherboot may wish to call external routines, such as -BIOS interrupts, which must be called in 16-bit real mode. When -providing a PXE API, Etherboot must provide a mechanism for external -code to call it from 16-bit real mode. - -Not all i386 builds of Etherboot will want to make real-mode calls. -For example, when built for LinuxBIOS rather than the standard PCBIOS, -no real-mode calls are necessary. - -For the ultimate in PXE compatibility, we may want to build Etherboot -to run permanently in real mode. - -There is a wide variety of potential combinations of mode switches -that we may wish to implement. There are additional complications, -such as the inability to access a high-memory stack when running in -real mode. - -2. Transition libraries - -To handle all these various combinations of mode switches, we have -several "transition" libraries in Etherboot. We also have the concept -of an "internal" and an "external" environment. The internal -environment is the environment within which we can execute C code. -The external environment is the environment of whatever external code -we're trying to interface to, such as the system BIOS or a PXE NBP. - -As well as having a separate addressing scheme, the internal -environment also has a separate stack. - -The transition libraries are: - -a) librm - -librm handles transitions between an external 16-bit real-mode -environment and an internal 32-bit protected-mode environment with -virtual addresses. - -b) libkir - -libkir handles transitions between an external 16-bit real-mode (or -16:16 or 16:32 protected-mode) environment and an internal 16-bit -real-mode (or 16:16 protected-mode) environment. - -c) libpm - -libpm handles transitions between an external 32-bit protected-mode -environment with flat physical addresses and an internal 32-bit -protected-mode environment with virtual addresses. - -The transition libraries handle the transitions required when -Etherboot is started up for the first time, the transitions required -to execute any external code, and the transitions required when -Etherboot exits (if it exits). When Etherboot provides a PXE API, -they also handle the transitions required when a PXE client makes a -PXE API call to Etherboot. - -Etherboot may use multiple transition libraries. For example, an -Etherboot ELF image does not require librm for its initial transitions -from prefix to runtime, but may require librm for calling external -real-mode functions. - -3. Setup and initialisation - -Etherboot is conceptually divided into the prefix, the decompressor, -and the runtime image. (For non-compressed images, the decompressor -is a no-op.) The complete image comprises all three parts and is -distinct from the runtime image, which exclude the prefix and the -decompressor. - -The prefix does several tasks: - - Load the complete image into memory. (For example, the floppy - prefix issues BIOS calls to load the remainder of the complete image - from the floppy disk into RAM, and the ISA ROM prefix copies the ROM - contents into RAM for faster access.) - - Call the decompressor, if the runtime image is compressed. This - decompresses the runtime image. - - Call the runtime image's setup() routine. This is a routine - implemented in assembly code which sets up the internal environment - so that C code can execute. - - Call the runtime image's arch_initialise() routine. This is a - routine implemented in C which does some basic startup tasks, such - as initialising the console device, obtaining a memory map and - relocating the runtime image to high memory. - - Call the runtime image's arch_main() routine. This records the exit - mechanism requested by the prefix and calls main(). (The prefix - needs to register an exit mechanism because by the time main() - returns, the memory occupied by the prefix has most likely been - overwritten.) - -When acting as a PXE ROM, the ROM prefix contains an UNDI loader -routine in addition to its usual code. The UNDI loader performs a -similar sequence of steps: - - Load the complete image into memory. - - Call the decompressor. - - Call the runtime image's setup() routine. - - Call the runtime image's arch_initialise() routine. - - Call the runtime image's install_pxe_stack() routine. - - Return to caller. - -The runtime image's setup() routine will perform the following steps: - - Switch to the internal environment using an appropriate transition - library. This will record the parameters of the external - environment. - - Set up the internal environment: load a stack, and set up a GDT for - virtual addressing if virtual addressing is to be used. - - Switch back to the external environment using the transition - library. This will record the parameters of the internal - environment. - -Once the setup() routine has returned, the internal environment has been -set up ready for C code to run. The prefix can call C routines using -a function from the transition library. - -The runtime image's arch_initialise() routine will perform the -following steps: - - Zero the bss - - Initialise the console device(s) and print a welcome message. - - Obtain a memory map via the INT 15,E820 BIOS call or suitable - fallback mechanism. [not done if libkir is being used] - - Relocate the runtime image to the top of high memory. [not done if - libkir is being used] - - Install librm to base memory. [done only if librm is being used] - - Call initialise(). - - Return to the prefix, setting registers to indicate to the prefix - the new location of the transition library, if applicable. Which - registers these are is specific to the transition library being - used. - -Once the arch_initialise() routine has returned, the prefix will -probably call arch_main(). |