1 files changed, 197 insertions, 0 deletions
diff --git a/qemu/roms/ipxe/src/arch/i386/README.i386 b/qemu/roms/ipxe/src/arch/i386/README.i386
new file mode 100644
index 000000000..b9b79cc4b
--- /dev/null
+++ b/qemu/roms/ipxe/src/arch/i386/README.i386
@@ -0,0 +1,197 @@
+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().