doc: arch: Convert README.x86 to reST

Convert plain text documentation to reStructuredText format and add
it to Sphinx TOC tree. No essential content change.

Signed-off-by: Bin Meng <bmeng.cn@gmail.com>

2 files changed, 729 insertions, 0 deletions

diff --git a/doc/arch/index.rst b/doc/arch/index.rst
index 1aeb7a1..f24b4a3 100644
--- a/doc/arch/index.rst
+++ b/doc/arch/index.rst
@@ -7,3 +7,4 @@ Architecture-specific doc
    :maxdepth: 2
 
    mips
+   x86
diff --git a/doc/arch/x86.rst b/doc/arch/x86.rst
new file mode 100644
index 0000000..2eb524c
--- /dev/null
+++ b/doc/arch/x86.rst
@@ -0,0 +1,728 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2014, Simon Glass <sjg@chromium.org>
+.. Copyright (C) 2014, Bin Meng <bmeng.cn@gmail.com>
+
+x86
+===
+
+This document describes the information about U-Boot running on x86 targets,
+including supported boards, build instructions, todo list, etc.
+
+Status
+------
+U-Boot supports running as a `coreboot`_ payload on x86. So far only Link
+(Chromebook Pixel) and `QEMU`_ x86 targets have been tested, but it should
+work with minimal adjustments on other x86 boards since coreboot deals with
+most of the low-level details.
+
+U-Boot is a main bootloader on Intel Edison board.
+
+U-Boot also supports booting directly from x86 reset vector, without coreboot.
+In this case, known as bare mode, from the fact that it runs on the
+'bare metal', U-Boot acts like a BIOS replacement. The following platforms
+are supported:
+
+   - Bayley Bay CRB
+   - Cherry Hill CRB
+   - Congatec QEVAL 2.0 & conga-QA3/E3845
+   - Cougar Canyon 2 CRB
+   - Crown Bay CRB
+   - Galileo
+   - Link (Chromebook Pixel)
+   - Minnowboard MAX
+   - Samus (Chromebook Pixel 2015)
+   - QEMU x86 (32-bit & 64-bit)
+
+As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit
+Linux kernel as part of a FIT image. It also supports a compressed zImage.
+U-Boot supports loading an x86 VxWorks kernel. Please check README.vxworks
+for more details.
+
+Build Instructions for U-Boot as BIOS replacement (bare mode)
+-------------------------------------------------------------
+Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a
+little bit tricky, as generally it requires several binary blobs which are not
+shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build is
+not turned on by default in the U-Boot source tree. Firstly, you need turn it
+on by enabling the ROM build either via an environment variable::
+
+   $ export BUILD_ROM=y
+
+or via configuration::
+
+   CONFIG_BUILD_ROM=y
+
+Both tell the Makefile to build u-boot.rom as a target.
+
+CPU Microcode
+-------------
+Modern CPUs usually require a special bit stream called `microcode`_ to be
+loaded on the processor after power up in order to function properly. U-Boot
+has already integrated these as hex dumps in the source tree.
+
+SMP Support
+-----------
+On a multicore system, U-Boot is executed on the bootstrap processor (BSP).
+Additional application processors (AP) can be brought up by U-Boot. In order to
+have an SMP kernel to discover all of the available processors, U-Boot needs to
+prepare configuration tables which contain the multi-CPUs information before
+loading the OS kernel. Currently U-Boot supports generating two types of tables
+for SMP, called Simple Firmware Interface (`SFI`_) and Multi-Processor (`MP`_)
+tables. The writing of these two tables are controlled by two Kconfig
+options GENERATE_SFI_TABLE and GENERATE_MP_TABLE.
+
+Driver Model
+------------
+x86 has been converted to use driver model for serial, GPIO, SPI, SPI flash,
+keyboard, real-time clock, USB. Video is in progress.
+
+Device Tree
+-----------
+x86 uses device tree to configure the board thus requires CONFIG_OF_CONTROL to
+be turned on. Not every device on the board is configured via device tree, but
+more and more devices will be added as time goes by. Check out the directory
+arch/x86/dts/ for these device tree source files.
+
+Useful Commands
+---------------
+In keeping with the U-Boot philosophy of providing functions to check and
+adjust internal settings, there are several x86-specific commands that may be
+useful:
+
+fsp
+  Display information about Intel Firmware Support Package (FSP).
+  This is only available on platforms which use FSP, mostly Atom.
+iod
+  Display I/O memory
+iow
+  Write I/O memory
+mtrr
+  List and set the Memory Type Range Registers (MTRR). These are used to
+  tell the CPU whether memory is cacheable and if so the cache write
+  mode to use. U-Boot sets up some reasonable values but you can
+  adjust then with this command.
+
+Booting Ubuntu
+--------------
+As an example of how to set up your boot flow with U-Boot, here are
+instructions for starting Ubuntu from U-Boot. These instructions have been
+tested on Minnowboard MAX with a SATA drive but are equally applicable on
+other platforms and other media. There are really only four steps and it's a
+very simple script, but a more detailed explanation is provided here for
+completeness.
+
+Note: It is possible to set up U-Boot to boot automatically using syslinux.
+It could also use the grub.cfg file (/efi/ubuntu/grub.cfg) to obtain the
+GUID. If you figure these out, please post patches to this README.
+
+Firstly, you will need Ubuntu installed on an available disk. It should be
+possible to make U-Boot start a USB start-up disk but for now let's assume
+that you used another boot loader to install Ubuntu.
+
+Use the U-Boot command line to find the UUID of the partition you want to
+boot. For example our disk is SCSI device 0::
+
+   => part list scsi 0
+
+   Partition Map for SCSI device 0  --   Partition Type: EFI
+
+      Part	Start LBA	End LBA		Name
+        Attributes
+        Type GUID
+        Partition GUID
+      1	0x00000800	0x001007ff	""
+        attrs:	0x0000000000000000
+        type:	c12a7328-f81f-11d2-ba4b-00a0c93ec93b
+        guid:	9d02e8e4-4d59-408f-a9b0-fd497bc9291c
+      2	0x00100800	0x037d8fff	""
+        attrs:	0x0000000000000000
+        type:	0fc63daf-8483-4772-8e79-3d69d8477de4
+        guid:	965c59ee-1822-4326-90d2-b02446050059
+      3	0x037d9000	0x03ba27ff	""
+        attrs:	0x0000000000000000
+        type:	0657fd6d-a4ab-43c4-84e5-0933c84b4f4f
+        guid:	2c4282bd-1e82-4bcf-a5ff-51dedbf39f17
+      =>
+
+This shows that your SCSI disk has three partitions. The really long hex
+strings are called Globally Unique Identifiers (GUIDs). You can look up the
+'type' ones `here`_. On this disk the first partition is for EFI and is in
+VFAT format (DOS/Windows)::
+
+   => fatls scsi 0:1
+               efi/
+
+   0 file(s), 1 dir(s)
+
+
+Partition 2 is 'Linux filesystem data' so that will be our root disk. It is
+in ext2 format::
+
+   => ext2ls scsi 0:2
+   <DIR>       4096 .
+   <DIR>       4096 ..
+   <DIR>      16384 lost+found
+   <DIR>       4096 boot
+   <DIR>      12288 etc
+   <DIR>       4096 media
+   <DIR>       4096 bin
+   <DIR>       4096 dev
+   <DIR>       4096 home
+   <DIR>       4096 lib
+   <DIR>       4096 lib64
+   <DIR>       4096 mnt
+   <DIR>       4096 opt
+   <DIR>       4096 proc
+   <DIR>       4096 root
+   <DIR>       4096 run
+   <DIR>      12288 sbin
+   <DIR>       4096 srv
+   <DIR>       4096 sys
+   <DIR>       4096 tmp
+   <DIR>       4096 usr
+   <DIR>       4096 var
+   <SYM>         33 initrd.img
+   <SYM>         30 vmlinuz
+   <DIR>       4096 cdrom
+   <SYM>         33 initrd.img.old
+   =>
+
+and if you look in the /boot directory you will see the kernel::
+
+   => ext2ls scsi 0:2 /boot
+   <DIR>       4096 .
+   <DIR>       4096 ..
+   <DIR>       4096 efi
+   <DIR>       4096 grub
+            3381262 System.map-3.13.0-32-generic
+            1162712 abi-3.13.0-32-generic
+             165611 config-3.13.0-32-generic
+             176500 memtest86+.bin
+             178176 memtest86+.elf
+             178680 memtest86+_multiboot.bin
+            5798112 vmlinuz-3.13.0-32-generic
+             165762 config-3.13.0-58-generic
+            1165129 abi-3.13.0-58-generic
+            5823136 vmlinuz-3.13.0-58-generic
+           19215259 initrd.img-3.13.0-58-generic
+            3391763 System.map-3.13.0-58-generic
+            5825048 vmlinuz-3.13.0-58-generic.efi.signed
+           28304443 initrd.img-3.13.0-32-generic
+   =>
+
+The 'vmlinuz' files contain a packaged Linux kernel. The format is a kind of
+self-extracting compressed file mixed with some 'setup' configuration data.
+Despite its size (uncompressed it is >10MB) this only includes a basic set of
+device drivers, enough to boot on most hardware types.
+
+The 'initrd' files contain a RAM disk. This is something that can be loaded
+into RAM and will appear to Linux like a disk. Ubuntu uses this to hold lots
+of drivers for whatever hardware you might have. It is loaded before the
+real root disk is accessed.
+
+The numbers after the end of each file are the version. Here it is Linux
+version 3.13. You can find the source code for this in the Linux tree with
+the tag v3.13. The '.0' allows for additional Linux releases to fix problems,
+but normally this is not needed. The '-58' is used by Ubuntu. Each time they
+release a new kernel they increment this number. New Ubuntu versions might
+include kernel patches to fix reported bugs. Stable kernels can exist for
+some years so this number can get quite high.
+
+The '.efi.signed' kernel is signed for EFI's secure boot. U-Boot has its own
+secure boot mechanism - see `this`_ & `that`_. It cannot read .efi files
+at present.
+
+To boot Ubuntu from U-Boot the steps are as follows:
+
+1. Set up the boot arguments. Use the GUID for the partition you want to boot::
+
+   => setenv bootargs root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro
+
+Here root= tells Linux the location of its root disk. The disk is specified
+by its GUID, using '/dev/disk/by-partuuid/', a Linux path to a 'directory'
+containing all the GUIDs Linux has found. When it starts up, there will be a
+file in that directory with this name in it. It is also possible to use a
+device name here, see later.
+
+2. Load the kernel. Since it is an ext2/4 filesystem we can do::
+
+   => ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic
+
+The address 30000000 is arbitrary, but there seem to be problems with using
+small addresses (sometimes Linux cannot find the ramdisk). This is 48MB into
+the start of RAM (which is at 0 on x86).
+
+3. Load the ramdisk (to 64MB)::
+
+   => ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic
+
+4. Start up the kernel. We need to know the size of the ramdisk, but can use
+   a variable for that. U-Boot sets 'filesize' to the size of the last file it
+   loaded::
+
+   => zboot 03000000 0 04000000 ${filesize}
+
+Type 'help zboot' if you want to see what the arguments are. U-Boot on x86 is
+quite verbose when it boots a kernel. You should see these messages from
+U-Boot::
+
+   Valid Boot Flag
+   Setup Size = 0x00004400
+   Magic signature found
+   Using boot protocol version 2.0c
+   Linux kernel version 3.13.0-58-generic (buildd@allspice) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015
+   Building boot_params at 0x00090000
+   Loading bzImage at address 100000 (5805728 bytes)
+   Magic signature found
+   Initial RAM disk at linear address 0x04000000, size 19215259 bytes
+   Kernel command line: "root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro"
+
+   Starting kernel ...
+
+U-Boot prints out some bootstage timing. This is more useful if you put the
+above commands into a script since then it will be faster::
+
+   Timer summary in microseconds:
+          Mark    Elapsed  Stage
+             0          0  reset
+       241,535    241,535  board_init_r
+     2,421,611  2,180,076  id=64
+     2,421,790        179  id=65
+     2,428,215      6,425  main_loop
+    48,860,584 46,432,369  start_kernel
+
+   Accumulated time:
+                  240,329  ahci
+                1,422,704  vesa display
+
+Now the kernel actually starts (if you want to examine kernel boot up message on
+the serial console, append "console=ttyS0,115200" to the kernel command line)::
+
+   [    0.000000] Initializing cgroup subsys cpuset
+   [    0.000000] Initializing cgroup subsys cpu
+   [    0.000000] Initializing cgroup subsys cpuacct
+   [    0.000000] Linux version 3.13.0-58-generic (buildd@allspice) (gcc version 4.8.2 (Ubuntu 4.8.2-19ubuntu1) ) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015 (Ubuntu 3.13.0-58.97-generic 3.13.11-ckt22)
+   [    0.000000] Command line: root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro console=ttyS0,115200
+
+It continues for a long time. Along the way you will see it pick up your
+ramdisk::
+
+   [    0.000000] RAMDISK: [mem 0x04000000-0x05253fff]
+   ...
+   [    0.788540] Trying to unpack rootfs image as initramfs...
+   [    1.540111] Freeing initrd memory: 18768K (ffff880004000000 - ffff880005254000)
+   ...
+
+Later it actually starts using it::
+
+   Begin: Running /scripts/local-premount ... done.
+
+You should also see your boot disk turn up::
+
+   [    4.357243] scsi 1:0:0:0: Direct-Access     ATA      ADATA SP310      5.2  PQ: 0 ANSI: 5
+   [    4.366860] sd 1:0:0:0: [sda] 62533296 512-byte logical blocks: (32.0 GB/29.8 GiB)
+   [    4.375677] sd 1:0:0:0: Attached scsi generic sg0 type 0
+   [    4.381859] sd 1:0:0:0: [sda] Write Protect is off
+   [    4.387452] sd 1:0:0:0: [sda] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA
+   [    4.399535]  sda: sda1 sda2 sda3
+
+Linux has found the three partitions (sda1-3). Mercifully it doesn't print out
+the GUIDs. In step 1 above we could have used::
+
+   setenv bootargs root=/dev/sda2 ro
+
+instead of the GUID. However if you add another drive to your board the
+numbering may change whereas the GUIDs will not. So if your boot partition
+becomes sdb2, it will still boot. For embedded systems where you just want to
+boot the first disk, you have that option.
+
+The last thing you will see on the console is mention of plymouth (which
+displays the Ubuntu start-up screen) and a lot of 'Starting' messages::
+
+   * Starting Mount filesystems on boot                                   [ OK ]
+
+After a pause you should see a login screen on your display and you are done.
+
+If you want to put this in a script you can use something like this::
+
+   setenv bootargs root=UUID=b2aaf743-0418-4d90-94cc-3e6108d7d968 ro
+   setenv boot zboot 03000000 0 04000000 \${filesize}
+   setenv bootcmd "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; run boot"
+   saveenv
+
+The \ is to tell the shell not to evaluate ${filesize} as part of the setenv
+command.
+
+You can also bake this behaviour into your build by hard-coding the
+environment variables if you add this to minnowmax.h:
+
+.. code-block:: c
+
+	#undef CONFIG_BOOTCOMMAND
+	#define CONFIG_BOOTCOMMAND	\
+		"ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; " \
+		"ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; " \
+		"run boot"
+
+	#undef CONFIG_EXTRA_ENV_SETTINGS
+	#define CONFIG_EXTRA_ENV_SETTINGS "boot=zboot 03000000 0 04000000 ${filesize}"
+
+and change CONFIG_BOOTARGS value in configs/minnowmax_defconfig to::
+
+   CONFIG_BOOTARGS="root=/dev/sda2 ro"
+
+Test with SeaBIOS
+-----------------
+`SeaBIOS`_ is an open source implementation of a 16-bit x86 BIOS. It can run
+in an emulator or natively on x86 hardware with the use of U-Boot. With its
+help, we can boot some OSes that require 16-bit BIOS services like Windows/DOS.
+
+As U-Boot, we have to manually create a table where SeaBIOS gets various system
+information (eg: E820) from. The table unfortunately has to follow the coreboot
+table format as SeaBIOS currently supports booting as a coreboot payload.
+
+To support loading SeaBIOS, U-Boot should be built with CONFIG_SEABIOS on.
+Booting SeaBIOS is done via U-Boot's bootelf command, like below::
+
+   => tftp bios.bin.elf;bootelf
+   Using e1000#0 device
+   TFTP from server 10.10.0.100; our IP address is 10.10.0.108
+   ...
+   Bytes transferred = 122124 (1dd0c hex)
+   ## Starting application at 0x000ff06e ...
+   SeaBIOS (version rel-1.9.0)
+   ...
+
+bios.bin.elf is the SeaBIOS image built from SeaBIOS source tree.
+Make sure it is built as follows::
+
+   $ make menuconfig
+
+Inside the "General Features" menu, select "Build for coreboot" as the
+"Build Target". Inside the "Debugging" menu, turn on "Serial port debugging"
+so that we can see something as soon as SeaBIOS boots. Leave other options
+as in their default state. Then::
+
+   $ make
+   ...
+   Total size: 121888  Fixed: 66496  Free: 9184 (used 93.0% of 128KiB rom)
+   Creating out/bios.bin.elf
+
+Currently this is tested on QEMU x86 target with U-Boot chain-loading SeaBIOS
+to install/boot a Windows XP OS (below for example command to install Windows).
+
+.. code-block:: none
+
+   # Create a 10G disk.img as the virtual hard disk
+   $ qemu-img create -f qcow2 disk.img 10G
+
+   # Install a Windows XP OS from an ISO image 'winxp.iso'
+   $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -cdrom winxp.iso -smp 2 -m 512
+
+   # Boot a Windows XP OS installed on the virutal hard disk
+   $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -smp 2 -m 512
+
+This is also tested on Intel Crown Bay board with a PCIe graphics card, booting
+SeaBIOS then chain-loading a GRUB on a USB drive, then Linux kernel finally.
+
+If you are using Intel Integrated Graphics Device (IGD) as the primary display
+device on your board, SeaBIOS needs to be patched manually to get its VGA ROM
+loaded and run by SeaBIOS. SeaBIOS locates VGA ROM via the PCI expansion ROM
+register, but IGD device does not have its VGA ROM mapped by this register.
+Its VGA ROM is packaged as part of u-boot.rom at a configurable flash address
+which is unknown to SeaBIOS. An example patch is needed for SeaBIOS below:
+
+.. code-block:: none
+
+   diff --git a/src/optionroms.c b/src/optionroms.c
+   index 65f7fe0..c7b6f5e 100644
+   --- a/src/optionroms.c
+   +++ b/src/optionroms.c
+   @@ -324,6 +324,8 @@ init_pcirom(struct pci_device *pci, int isvga, u64 *sources)
+            rom = deploy_romfile(file);
+        else if (RunPCIroms > 1 || (RunPCIroms == 1 && isvga))
+            rom = map_pcirom(pci);
+   +    if (pci->bdf == pci_to_bdf(0, 2, 0))
+   +        rom = (struct rom_header *)0xfff90000;
+        if (! rom)
+            // No ROM present.
+            return;
+
+Note: the patch above expects IGD device is at PCI b.d.f 0.2.0 and its VGA ROM
+is at 0xfff90000 which corresponds to CONFIG_VGA_BIOS_ADDR on Minnowboard MAX.
+Change these two accordingly if this is not the case on your board.
+
+Development Flow
+----------------
+These notes are for those who want to port U-Boot to a new x86 platform.
+
+Since x86 CPUs boot from SPI flash, a SPI flash emulator is a good investment.
+The Dediprog em100 can be used on Linux.
+
+The em100 tool is available here: http://review.coreboot.org/p/em100.git
+
+On Minnowboard Max the following command line can be used::
+
+   sudo em100 -s -p LOW -d u-boot.rom -c W25Q64DW -r
+
+A suitable clip for connecting over the SPI flash chip is here:
+http://www.dediprog.com/pd/programmer-accessories/EM-TC-8.
+
+This allows you to override the SPI flash contents for development purposes.
+Typically you can write to the em100 in around 1200ms, considerably faster
+than programming the real flash device each time. The only important
+limitation of the em100 is that it only supports SPI bus speeds up to 20MHz.
+This means that images must be set to boot with that speed. This is an
+Intel-specific feature - e.g. tools/ifttool has an option to set the SPI
+speed in the SPI descriptor region.
+
+If your chip/board uses an Intel Firmware Support Package (FSP) it is fairly
+easy to fit it in. You can follow the Minnowboard Max implementation, for
+example. Hopefully you will just need to create new files similar to those
+in arch/x86/cpu/baytrail which provide Bay Trail support.
+
+If you are not using an FSP you have more freedom and more responsibility.
+The ivybridge support works this way, although it still uses a ROM for
+graphics and still has binary blobs containing Intel code. You should aim to
+support all important peripherals on your platform including video and storage.
+Use the device tree for configuration where possible.
+
+For the microcode you can create a suitable device tree file using the
+microcode tool::
+
+   ./tools/microcode-tool -d microcode.dat -m <model> create
+
+or if you only have header files and not the full Intel microcode.dat database::
+
+   ./tools/microcode-tool -H BAY_TRAIL_FSP_KIT/Microcode/M0130673322.h \
+    -H BAY_TRAIL_FSP_KIT/Microcode/M0130679901.h -m all create
+
+These are written to arch/x86/dts/microcode/ by default.
+
+Note that it is possible to just add the micrcode for your CPU if you know its
+model. U-Boot prints this information when it starts::
+
+   CPU: x86_64, vendor Intel, device 30673h
+
+so here we can use the M0130673322 file.
+
+If you platform can display POST codes on two little 7-segment displays on
+the board, then you can use post_code() calls from C or assembler to monitor
+boot progress. This can be good for debugging.
+
+If not, you can try to get serial working as early as possible. The early
+debug serial port may be useful here. See setup_internal_uart() for an example.
+
+During the U-Boot porting, one of the important steps is to write correct PIRQ
+routing information in the board device tree. Without it, device drivers in the
+Linux kernel won't function correctly due to interrupt is not working. Please
+refer to U-Boot `doc <doc/device-tree-bindings/misc/intel,irq-router.txt>`_ for
+the device tree bindings of Intel interrupt router. Here we have more details
+on the intel,pirq-routing property below.
+
+.. code-block:: none
+
+	intel,pirq-routing = <
+		PCI_BDF(0, 2, 0) INTA PIRQA
+		...
+	>;
+
+As you see each entry has 3 cells. For the first one, we need describe all pci
+devices mounted on the board. For SoC devices, normally there is a chapter on
+the chipset datasheet which lists all the available PCI devices. For example on
+Bay Trail, this is chapter 4.3 (PCI configuration space). For the second one, we
+can get the interrupt pin either from datasheet or hardware via U-Boot shell.
+The reliable source is the hardware as sometimes chipset datasheet is not 100%
+up-to-date. Type 'pci header' plus the device's pci bus/device/function number
+from U-Boot shell below::
+
+  => pci header 0.1e.1
+    vendor ID =			0x8086
+    device ID =			0x0f08
+    ...
+    interrupt line =		0x09
+    interrupt pin =		0x04
+    ...
+
+It shows this PCI device is using INTD pin as it reports 4 in the interrupt pin
+register. Repeat this until you get interrupt pins for all the devices. The last
+cell is the PIRQ line which a particular interrupt pin is mapped to. On Intel
+chipset, the power-up default mapping is INTA/B/C/D maps to PIRQA/B/C/D. This
+can be changed by registers in LPC bridge. So far Intel FSP does not touch those
+registers so we can write down the PIRQ according to the default mapping rule.
+
+Once we get the PIRQ routing information in the device tree, the interrupt
+allocation and assignment will be done by U-Boot automatically. Now you can
+enable CONFIG_GENERATE_PIRQ_TABLE for testing Linux kernel using i8259 PIC and
+CONFIG_GENERATE_MP_TABLE for testing Linux kernel using local APIC and I/O APIC.
+
+This script might be useful. If you feed it the output of 'pci long' from
+U-Boot then it will generate a device tree fragment with the interrupt
+configuration for each device (note it needs gawk 4.0.0)::
+
+   $ cat console_output |awk '/PCI/ {device=$4} /interrupt line/ {line=$4} \
+	/interrupt pin/ {pin = $4; if (pin != "0x00" && pin != "0xff") \
+	{patsplit(device, bdf, "[0-9a-f]+"); \
+	printf "PCI_BDF(%d, %d, %d) INT%c PIRQ%c\n", strtonum("0x" bdf[1]), \
+	strtonum("0x" bdf[2]), bdf[3], strtonum(pin) + 64, 64 + strtonum(pin)}}'
+
+Example output::
+
+   PCI_BDF(0, 2, 0) INTA PIRQA
+   PCI_BDF(0, 3, 0) INTA PIRQA
+   ...
+
+Porting Hints
+-------------
+
+Quark-specific considerations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To port U-Boot to other boards based on the Intel Quark SoC, a few things need
+to be taken care of. The first important part is the Memory Reference Code (MRC)
+parameters. Quark MRC supports memory-down configuration only. All these MRC
+parameters are supplied via the board device tree. To get started, first copy
+the MRC section of arch/x86/dts/galileo.dts to your board's device tree, then
+change these values by consulting board manuals or your hardware vendor.
+Available MRC parameter values are listed in include/dt-bindings/mrc/quark.h.
+The other tricky part is with PCIe. Quark SoC integrates two PCIe root ports,
+but by default they are held in reset after power on. In U-Boot, PCIe
+initialization is properly handled as per Quark's firmware writer guide.
+In your board support codes, you need provide two routines to aid PCIe
+initialization, which are board_assert_perst() and board_deassert_perst().
+The two routines need implement a board-specific mechanism to assert/deassert
+PCIe PERST# pin. Care must be taken that in those routines that any APIs that
+may trigger PCI enumeration process are strictly forbidden, as any access to
+PCIe root port's configuration registers will cause system hang while it is
+held in reset. For more details, check how they are implemented by the Intel
+Galileo board support codes in board/intel/galileo/galileo.c.
+
+coreboot
+^^^^^^^^
+
+See scripts/coreboot.sed which can assist with porting coreboot code into
+U-Boot drivers. It will not resolve all build errors, but will perform common
+transformations. Remember to add attribution to coreboot for new files added
+to U-Boot. This should go at the top of each file and list the coreboot
+filename where the code originated.
+
+Debugging ACPI issues with Windows
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Windows might cache system information and only detect ACPI changes if you
+modify the ACPI table versions. So tweak them liberally when debugging ACPI
+issues with Windows.
+
+ACPI Support Status
+-------------------
+Advanced Configuration and Power Interface (`ACPI`_) aims to establish
+industry-standard interfaces enabling OS-directed configuration, power
+management, and thermal management of mobile, desktop, and server platforms.
+
+Linux can boot without ACPI with "acpi=off" command line parameter, but
+with ACPI the kernel gains the capabilities to handle power management.
+For Windows, ACPI is a must-have firmware feature since Windows Vista.
+CONFIG_GENERATE_ACPI_TABLE is the config option to turn on ACPI support in
+U-Boot. This requires Intel ACPI compiler to be installed on your host to
+compile ACPI DSDT table written in ASL format to AML format. You can get
+the compiler via "apt-get install iasl" if you are on Ubuntu or download
+the source from https://www.acpica.org/downloads to compile one by yourself.
+
+Current ACPI support in U-Boot is basically complete. More optional features
+can be added in the future. The status as of today is:
+
+ * Support generating RSDT, XSDT, FACS, FADT, MADT, MCFG tables.
+ * Support one static DSDT table only, compiled by Intel ACPI compiler.
+ * Support S0/S3/S4/S5, reboot and shutdown from OS.
+ * Support booting a pre-installed Ubuntu distribution via 'zboot' command.
+ * Support installing and booting Ubuntu 14.04 (or above) from U-Boot with
+   the help of SeaBIOS using legacy interface (non-UEFI mode).
+ * Support installing and booting Windows 8.1/10 from U-Boot with the help
+   of SeaBIOS using legacy interface (non-UEFI mode).
+ * Support ACPI interrupts with SCI only.
+
+Features that are optional:
+
+ * Dynamic AML bytecodes insertion at run-time. We may need this to support
+   SSDT table generation and DSDT fix up.
+ * SMI support. Since U-Boot is a modern bootloader, we don't want to bring
+   those legacy stuff into U-Boot. ACPI spec allows a system that does not
+   support SMI (a legacy-free system).
+
+ACPI was initially enabled on BayTrail based boards. Testing was done by booting
+a pre-installed Ubuntu 14.04 from a SATA drive. Installing Ubuntu 14.04 and
+Windows 8.1/10 to a SATA drive and booting from there is also tested. Most
+devices seem to work correctly and the board can respond a reboot/shutdown
+command from the OS.
+
+For other platform boards, ACPI support status can be checked by examining their
+board defconfig files to see if CONFIG_GENERATE_ACPI_TABLE is set to y.
+
+The S3 sleeping state is a low wake latency sleeping state defined by ACPI
+spec where all system context is lost except system memory. To test S3 resume
+with a Linux kernel, simply run "echo mem > /sys/power/state" and kernel will
+put the board to S3 state where the power is off. So when the power button is
+pressed again, U-Boot runs as it does in cold boot and detects the sleeping
+state via ACPI register to see if it is S3, if yes it means we are waking up.
+U-Boot is responsible for restoring the machine state as it is before sleep.
+When everything is done, U-Boot finds out the wakeup vector provided by OSes
+and jump there. To determine whether ACPI S3 resume is supported, check to
+see if CONFIG_HAVE_ACPI_RESUME is set for that specific board.
+
+Note for testing S3 resume with Windows, correct graphics driver must be
+installed for your platform, otherwise you won't find "Sleep" option in
+the "Power" submenu from the Windows start menu.
+
+EFI Support
+-----------
+U-Boot supports booting as a 32-bit or 64-bit EFI payload, e.g. with UEFI.
+This is enabled with CONFIG_EFI_STUB to boot from both 32-bit and 64-bit
+UEFI BIOS. U-Boot can also run as an EFI application, with CONFIG_EFI_APP.
+The CONFIG_EFI_LOADER option, where U-Boot provides an EFI environment to
+the kernel (i.e. replaces UEFI completely but provides the same EFI run-time
+services) is supported too. For example, we can even use 'bootefi' command
+to load a 'u-boot-payload.efi', see below test logs on QEMU.
+
+.. code-block:: none
+
+  => load ide 0 3000000 u-boot-payload.efi
+  489787 bytes read in 138 ms (3.4 MiB/s)
+  => bootefi 3000000
+  Scanning disk ide.blk#0...
+  Found 2 disks
+  WARNING: booting without device tree
+  ## Starting EFI application at 03000000 ...
+  U-Boot EFI Payload
+
+
+  U-Boot 2018.07-rc2 (Jun 23 2018 - 17:12:58 +0800)
+
+  CPU: x86_64, vendor AMD, device 663h
+  DRAM:  2 GiB
+  MMC:
+  Video: 1024x768x32
+  Model: EFI x86 Payload
+  Net:   e1000: 52:54:00:12:34:56
+
+  Warning: e1000#0 using MAC address from ROM
+  eth0: e1000#0
+  No controllers found
+  Hit any key to stop autoboot:  0
+
+See README.u-boot_on_efi and README.uefi for details of EFI support in U-Boot.
+
+TODO List
+---------
+- Audio
+- Chrome OS verified boot
+
+.. _coreboot: http://www.coreboot.org
+.. _QEMU: http://www.qemu.org
+.. _microcode: http://en.wikipedia.org/wiki/Microcode
+.. _SFI: http://simplefirmware.org
+.. _MP: http://www.intel.com/design/archives/processors/pro/docs/242016.htm
+.. _here: https://en.wikipedia.org/wiki/GUID_Partition_Table
+.. _this: http://events.linuxfoundation.org/sites/events/files/slides/chromeos_and_diy_vboot_0.pdf
+.. _that: http://events.linuxfoundation.org/sites/events/files/slides/elce-2014.pdf
+.. _SeaBIOS: http://www.seabios.org/SeaBIOS
+.. _ACPI: http://www.acpi.info