Change in coreboot[master]: [WIP]Documentation: Improve x86_64

[Patrick Rudolph (Code Review)]

Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/56017 )

Change subject: [WIP]Documentation: Improve x86_64
......................................................................

[WIP]Documentation: Improve x86_64

Change-Id: Ia5ba51be629a8c878aad64d3297176457cf8e855
Signed-off-by: Patrick Rudolph 
---
A Documentation/arch/x86/x86_64.md
1 file changed, 72 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/17/56017/1

diff --git a/Documentation/arch/x86/x86_64.md b/Documentation/arch/x86/x86_64.md
new file mode 100644
index 0000000..021ad7c
--- /dev/null
+++ b/Documentation/arch/x86/x86_64.md
@@ -0,0 +1,72 @@
+# x86_64 architecture documentation
+
+This section contains documentation about coreboot's experimental
+x86_64 support. In coreboot every stage (when enabled) is build for
+x86_64, contrary to UEFIs implementation that only some stages in x86_64.
+On UEFI the PEI phase, which is x86_32, brings up DRAM and installs
+page tables for the x86_64 DXE and BDS phases.
+
+The differences can be explained as following:
+
+## Supported boards
+* QEMU x86 boards
+* Intel Sandy Bridge boards
+
+## Reference implementation
+The reference implementation is
+* [QEMU i440fx](../../mainboard/emulation/qemu-i440fx.md)
+* [QEMU Q35](../../mainboard/emulation/qemu-q35.md)
+
+## Hardware requirements for x86_64 support
+* The CPU supports long mode (x86_64)
+* The BIOS region is large enough to contain the page tables
+  (24 KiB minimum) besides the coreboot code itself.
+* The BIOS region of the SPI flash is memory mapped at reset
+
+## Current software constrains for x86_64 support
+* 0-4GiB are identity mapped using 2MiB-pages as WB
+* Memory above 4GiB isn't accessible
+* page tables reside in memory mapped ROM
+* x86 payloads are loaded below 4GiB in physical memory and are jumped
+  to in *protected mode*
+* The high dword of pointers is always zero
+* All memory returned by malloc must be below 4GiB in physical memory
+* All code that is to be run must be below 4GiB in physical memory
+* The compiler supports generating code for the *large memory model*
+  (-mcmodel=large).
+
+## Page tables
+Page tables are generated by a tool in `util/pgtblgen/pgtblgen`. It writes
+the page tables to a file which is then included into the CBFS as file called
+`pagetables`.
+
+To generate the static page tables it must know the physical address where to
+place the file. The pagetable must be placed in flash that is memory mapped at
+reset and thus can be read in bootblock's assembly code without additional
+setup.
+
+The page tables contains the following structure:
+* PML4E pointing to PDPE
+* PDPE with *$n* entries each pointing to PDE
+* *$n* PDEs with 512 entries each
+
+At the moment *$n* is 4, which results in identity mapping the lower 4 GiB.
+
+## Pros / Cons
+
+* x86_64 code is bigger than the x86_32 code as it uses 64bit absolute addressing.
+  It cannot use 32bit addressing as the memory model
+
+## TODO
+1. Identity map memory above 4GiB in ramstage
+   - This requires a complete memory map to be present in postcar stage
+2. Fine grained page tables for SMM:
+   * Must not have execute and write permissions for the same page.
+   * Must allow only that TSEG pages can be marked executable
+   * Must reside in SMRAM
+3. Support 64bit PCI BARs above 4GiB
+4. Place and run code above 4GiB
+
+## Porting other boards
+* Fix compilation errors
+* Test libgfxinit / VGA Option ROMs / FSP