summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/README.x8678
-rw-r--r--doc/device-tree-bindings/gpio/intel,x86-pinctrl.txt31
-rw-r--r--doc/device-tree-bindings/misc/intel,irq-router.txt50
3 files changed, 142 insertions, 17 deletions
diff --git a/doc/README.x86 b/doc/README.x86
index ef13fb45f4c..c19f4a03ba0 100644
--- a/doc/README.x86
+++ b/doc/README.x86
@@ -14,12 +14,13 @@ including supported boards, build instructions, todo list, etc.
Status
------
U-Boot supports running as a coreboot [1] payload on x86. So far only Link
-(Chromebook Pixel) has been tested, but it should work with minimal adjustments
-on other x86 boards since coreboot deals with most of the low-level details.
+(Chromebook Pixel) and QEMU [2] 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 also supports booting directly from x86 reset vector without coreboot,
-aka raw support or bare support. Currently Link, Intel Crown Bay, Intel
-Minnowboard Max and Intel Galileo support running U-Boot 'bare metal'.
+aka raw support or bare support. Currently Link, QEMU x86 targets and all
+Intel boards support running U-Boot 'bare metal'.
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.
@@ -32,15 +33,15 @@ on other architectures, like below:
$ make coreboot-x86_defconfig
$ make all
-Note this default configuration will build a U-Boot payload for the Link board.
+Note this default configuration will build a U-Boot payload for the QEMU board.
To build a coreboot payload against another board, you can change the build
configuration during the 'make menuconfig' process.
x86 architecture --->
...
- (chromebook_link) Board configuration file
- (chromebook_link) Board Device Tree Source (dts) file
- (0x19200000) Board specific Cache-As-RAM (CAR) address
+ (qemu-x86) Board configuration file
+ (qemu-x86_i440fx) Board Device Tree Source (dts) file
+ (0x01920000) Board specific Cache-As-RAM (CAR) address
(0x4000) Board specific Cache-As-RAM (CAR) size
Change the 'Board configuration file' and 'Board Device Tree Source (dts) file'
@@ -78,7 +79,7 @@ Find the following files:
* ./northbridge/intel/sandybridge/systemagent-r6.bin
The 3rd one should be renamed to mrc.bin.
-As for the video ROM, you can get it here [2].
+As for the video ROM, you can get it here [3].
Make sure all these binary blobs are put in the board directory.
Now you can build U-Boot and obtain u-boot.rom:
@@ -88,8 +89,8 @@ $ make all
Intel Crown Bay specific instructions:
-U-Boot support of Intel Crown Bay board [3] relies on a binary blob called
-Firmware Support Package [4] to perform all the necessary initialization steps
+U-Boot support of Intel Crown Bay board [4] relies on a binary blob called
+Firmware Support Package [5] to perform all the necessary initialization steps
as documented in the BIOS Writer Guide, including initialization of the CPU,
memory controller, chipset and certain bus interfaces.
@@ -178,6 +179,21 @@ Now you can build U-Boot and obtain u-boot.rom
$ make galileo_defconfig
$ make all
+QEMU x86 target instructions:
+
+To build u-boot.rom for QEMU x86 targets, just simply run
+
+$ make qemu-x86_defconfig
+$ make all
+
+Note this default configuration will build a U-Boot for the QEMU x86 i440FX
+board. To build a U-Boot against QEMU x86 Q35 board, you can change the build
+configuration during the 'make menuconfig' process like below:
+
+Device Tree Control --->
+ ...
+ (qemu-x86_q35) Default Device Tree for DT control
+
Test with coreboot
------------------
For testing U-Boot as the coreboot payload, there are things that need be paid
@@ -207,10 +223,38 @@ At present it seems that for Minnowboard Max, coreboot does not pass through
the video information correctly (it always says the resolution is 0x0). This
works correctly for link though.
+Test with QEMU
+--------------
+QEMU is a fancy emulator that can enable us to test U-Boot without access to
+a real x86 board. Please make sure your QEMU version is 2.3.0 or above test
+U-Boot. To launch QEMU with u-boot.rom, call QEMU as follows:
+
+$ qemu-system-i386 -nographic -bios path/to/u-boot.rom
+
+This will instantiate an emulated x86 board with i440FX and PIIX chipset. QEMU
+also supports emulating an x86 board with Q35 and ICH9 based chipset, which is
+also supported by U-Boot. To instantiate such a machine, call QEMU with:
+
+$ qemu-system-i386 -nographic -bios path/to/u-boot.rom -M q35
+
+Note by default QEMU instantiated boards only have 128 MiB system memory. But
+it is enough to have U-Boot boot and function correctly. You can increase the
+system memory by pass '-m' parameter to QEMU if you want more memory:
+
+$ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024
+
+This creates a board with 1 GiB system memory. Currently U-Boot for QEMU only
+supports 3 GiB maximum system memory and reserves the last 1 GiB address space
+for PCI device memory-mapped I/O and other stuff, so the maximum value of '-m'
+would be 3072.
+
+QEMU emulates a graphic card which U-Boot supports. Removing '-nographic' will
+show QEMU's VGA console window. Note this will disable QEMU's serial output.
+If you want to check both consoles, use '-serial stdio'.
CPU Microcode
-------------
-Modern CPUs usually require a special bit stream called microcode [5] to be
+Modern CPUs usually require a special bit stream called microcode [6] 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.
@@ -227,7 +271,6 @@ 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:
@@ -314,7 +357,8 @@ TODO List
References
----------
[1] http://www.coreboot.org
-[2] http://www.coreboot.org/~stepan/pci8086,0166.rom
-[3] http://www.intel.com/content/www/us/en/embedded/design-tools/evaluation-platforms/atom-e660-eg20t-development-kit.html
-[4] http://www.intel.com/fsp
-[5] http://en.wikipedia.org/wiki/Microcode
+[2] http://www.qemu.org
+[3] http://www.coreboot.org/~stepan/pci8086,0166.rom
+[4] http://www.intel.com/content/www/us/en/embedded/design-tools/evaluation-platforms/atom-e660-eg20t-development-kit.html
+[5] http://www.intel.com/fsp
+[6] http://en.wikipedia.org/wiki/Microcode
diff --git a/doc/device-tree-bindings/gpio/intel,x86-pinctrl.txt b/doc/device-tree-bindings/gpio/intel,x86-pinctrl.txt
new file mode 100644
index 00000000000..45ab1afc395
--- /dev/null
+++ b/doc/device-tree-bindings/gpio/intel,x86-pinctrl.txt
@@ -0,0 +1,31 @@
+Intel x86 PINCTRL/GPIO controller
+
+Pin-muxing on x86 can be described with a node for the PINCTRL master
+node and a set of child nodes for each pin on the SoC.
+
+The PINCTRL master node requires the following properties:
+- compatible : "intel,x86-pinctrl"
+
+Pin nodes must be children of the pinctrl master node and can
+contain the following properties:
+- pad-offset - (required) offset in the IOBASE for the pin to configured.
+- gpio-offset - (required) offset in the GPIOBASE for the pin to configured and
+ also the bit shift in this register.
+- mode-gpio - (optional) standalone property to force the pin into GPIO mode.
+- mode-func - (optional) function number to assign to the pin. if 'mode-gpio'
+ is set, this property will be ignored.
+in case of 'mode-gpio' property set:
+- output-value - (optional) this set the default output value of the GPIO.
+- direction - (optional) this set the direction of the gpio.
+- pull-str - (optional) this set the pull strength of the pin.
+- pull-assign - (optional) this set the pull assignement (up/down) of the pin.
+
+Example:
+
+pin_usb_host_en0@0 {
+ gpio-offset = <0x80 8>;
+ pad-offset = <0x260>;
+ mode-gpio;
+ output-value = <1>;
+ direction = <PIN_OUTPUT>;
+};
diff --git a/doc/device-tree-bindings/misc/intel,irq-router.txt b/doc/device-tree-bindings/misc/intel,irq-router.txt
new file mode 100644
index 00000000000..598b4b1c2f5
--- /dev/null
+++ b/doc/device-tree-bindings/misc/intel,irq-router.txt
@@ -0,0 +1,50 @@
+Intel Interrupt Router Device Binding
+=====================================
+
+The device tree node which describes the operation of the Intel Interrupt Router
+device is as follows:
+
+Required properties :
+- reg : Specifies the interrupt router's PCI configuration space address as
+ defined by the Open Firmware spec.
+- compatible = "intel,irq-router"
+- intel,pirq-config : Specifies the IRQ routing register programming mechanism.
+ Valid values are:
+ "pci": IRQ routing is controlled by PCI configuration registers
+ "ibase": IRQ routing is in the memory-mapped IBASE register block
+- intel,ibase-offset : IBASE register offset in the interrupt router's PCI
+ configuration space, required only if intel,pirq-config = "ibase".
+- intel,pirq-link : Specifies the PIRQ link information with two cells. The
+ first cell is the register offset that controls the first PIRQ link routing.
+ The second cell is the total number of PIRQ links the router supports.
+- intel,pirq-mask : Specifies the IRQ mask reprenting the 16 IRQs in 8259 PIC.
+ Bit N is 1 means IRQ N is available to be routed.
+- intel,pirq-routing : Specifies all PCI devices' IRQ routing information,
+ encoded as 3 cells a group for a device. The first cell is the device's PCI
+ bus number, device number and function number encoding with PCI_BDF() macro.
+ The second cell is the PCI interrupt pin used by this device. The last cell
+ is which PIRQ line the PCI interrupt pin is routed to.
+
+
+Example
+-------
+
+#include <dt-bindings/interrupt-router/intel-irq.h>
+
+ irq-router@1f,0 {
+ reg = <0x0000f800 0 0 0 0>;
+ compatible = "intel,irq-router";
+ intel,pirq-config = "pci";
+ intel,pirq-link = <0x60 8>;
+ intel,pirq-mask = <0xdef8>;
+ intel,pirq-routing = <
+ PCI_BDF(0, 2, 0) INTA PIRQA
+ PCI_BDF(0, 3, 0) INTA PIRQB
+ PCI_BDF(0, 8, 0) INTA PIRQC
+ PCI_BDF(0, 8, 1) INTB PIRQD
+ PCI_BDF(1, 6, 0) INTA PIRQE
+ PCI_BDF(1, 6, 1) INTB PIRQF
+ PCI_BDF(1, 6, 2) INTC PIRQG
+ PCI_BDF(1, 6, 3) INTD PIRQH
+ >;
+ };