Documentation: Add new sphinxs docs

This is a rewrite of the Documentation in reStructuredText format using
Sphinx as build system, see http://sphinx-doc.org/.

The documentation is built into static html pages with 'make docs'.
The pages can be found under Documentation/html after building.

Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>

23 files changed, 811 insertions, 0 deletions

diff --git a/Documentation/boards/cirrus-logic.rst b/Documentation/boards/cirrus-logic.rst
new file mode 100644
index 0000000000..95a961e244
--- /dev/null
+++ b/Documentation/boards/cirrus-logic.rst
@@ -0,0 +1,9 @@
+Cirrus Logic edb9xxx
+====================
+
+.. toctree::
+  :glob:
+  :numbered:
+  :maxdepth: 1
+
+  edb9xxx/*
diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9301.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9301.rst
new file mode 100644
index 0000000000..78c2d30c79
--- /dev/null
+++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9301.rst
@@ -0,0 +1,10 @@
+Cirrus Logic EP9301
+===================
+
+This boards is based on a Cirrus Logic EP9301 CPU. The board is shipped with:
+
+  * 16MiB NOR type Flash Memory
+  * 32MiB synchronous dynamic RAM on CS3
+  * 128kiB serial EEPROM
+  * MII 10/100 Ethernet PHY
+  * Stereo audio codec
diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9302.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9302.rst
new file mode 100644
index 0000000000..43dfb83da4
--- /dev/null
+++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9302.rst
@@ -0,0 +1,10 @@
+Cirrus Logic EDB9302
+====================
+
+This board is based on a Cirrus Logic EP9302 CPU. The board is shipped with:
+
+  * 16MiB NOR type Flash Memory
+  * 32MiB synchronous dynamic RAM on CS3
+  * 128kiB serial EEPROM
+  * MII 10/100 Ethernet PHY
+  * Stereo audio codec
diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9302a.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9302a.rst
new file mode 100644
index 0000000000..7283536ea1
--- /dev/null
+++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9302a.rst
@@ -0,0 +1,10 @@
+Cirrus Logic EDB9302A
+=====================
+
+This board is based on a Cirrus Logic EP9302 CPU. The board is shipped with:
+
+  * 16MiB NOR type Flash Memory
+  * 32MiB synchronous dynamic RAM on CS0
+  * 512kiB serial EEPROM
+  * MII 10/100 Ethernet PHY
+  * Stereo audio codec
diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9307.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9307.rst
new file mode 100644
index 0000000000..9006f2c9ce
--- /dev/null
+++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9307.rst
@@ -0,0 +1,13 @@
+Cirrus Logic EDB9307
+====================
+
+This board is based on a Cirrus Logic EP9307 CPU. The board is shipped with:
+
+  * 32MiB NOR type Flash Memory
+  * 64MiB synchronous dynamic RAM on CS3
+  * 512kiB asynchronous SRAM
+  * 128kiB serial EEPROM
+  * MII 10/100 Ethernet PHY
+  * Stereo audio codec
+  * Real-Time Clock
+  * IR receiver
diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9307a.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9307a.rst
new file mode 100644
index 0000000000..ba3763c386
--- /dev/null
+++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9307a.rst
@@ -0,0 +1,13 @@
+Cirrus Logic EDB9307A
+=====================
+
+This board is based on a Cirrus Logic EP9307 CPU. The board is shipped with:
+
+  * 32MiB NOR type Flash Memory
+  * 64MiB synchronous dynamic RAM on CS0
+  * 512kiB serial EEPROM
+  * MII 10/100 Ethernet PHY
+  * Stereo audio codec
+  * Real-Time Clock
+  * IR receiver
+
diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9312.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9312.rst
new file mode 100644
index 0000000000..16ad7fbbf9
--- /dev/null
+++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9312.rst
@@ -0,0 +1,13 @@
+Cirrus Logic EDB9312
+====================
+
+This board is based on a Cirrus Logic EP9312 CPU. The board is shipped with:
+
+  * 32MiB NOR type Flash Memory
+  * 64MiB synchronous dynamic RAM on CS3
+  * 512kiB asynchronous SRAM
+  * 128kiB serial EEPROM
+  * MII 10/100 Ethernet PHY
+  * Stereo audio codec
+  * Real-Time Clock
+  * IR receiver
diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9315.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9315.rst
new file mode 100644
index 0000000000..5adb96696b
--- /dev/null
+++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9315.rst
@@ -0,0 +1,13 @@
+Cirrus Logic EDB9315
+====================
+
+This board is based on a Cirrus Logic EP9315 CPU. The board is shipped with:
+
+  * 32MiB NOR type Flash Memory
+  * 64MiB synchronous dynamic RAM on CS3
+  * 512kiB asynchronous SRAM
+  * 128kiB serial EEPROM
+  * MII 10/100 Ethernet PHY
+  * Stereo audio codec
+  * Real-Time Clock
+  * IR receiver
diff --git a/Documentation/boards/edb9xxx/cirrus_logic_edb9315a.rst b/Documentation/boards/edb9xxx/cirrus_logic_edb9315a.rst
new file mode 100644
index 0000000000..c44f873859
--- /dev/null
+++ b/Documentation/boards/edb9xxx/cirrus_logic_edb9315a.rst
@@ -0,0 +1,12 @@
+Cirrus Logic EDB9315A
+=====================
+
+This board is based on a Cirrus Logic EP9315 CPU. The board is shipped with:
+
+  * 32MiB NOR type Flash Memory
+  * 64MiB synchronous dynamic RAM on CS0
+  * 128kiB serial EEPROM
+  * MII 10/100 Ethernet PHY
+  * Stereo audio codec
+  * Real-Time Clock
+  * IR receiver
diff --git a/Documentation/boards/imx.rst b/Documentation/boards/imx.rst
new file mode 100644
index 0000000000..c6b208728e
--- /dev/null
+++ b/Documentation/boards/imx.rst
@@ -0,0 +1,103 @@
+Freescale i.MX
+==============
+
+Freescale i.MX is traditionally very good supported under barebox.
+Depending on the SoC there are different Boot Modes supported. Older
+SoCs up to i.MX31 only support the external Boot Mode. Newer SoCs
+can be configured for internal or external Boot Mode with the internal
+boot mode being the more popular mode. The i.MX23 and i.MX28, also
+known as i.MXs, are special. These SoCs have a completely different
+boot mechanism.
+
+Internal Boot Mode
+------------------
+
+The Internal Boot Mode is supported on:
+
+* i.MX25
+* i.MX35
+* i.MX51
+* i.MX53
+* i.MX6
+
+With the Internal Boot Mode the images contain a header which describes
+where the binary shall be loaded and started. Also these headers contain
+a so called DCD table which consists of register/value pairs. These are
+executed by the Boot ROM and are used to configure the SDRAM. In barebox
+the i.MX images are generated with the ``scripts/imx/imx-image`` tool.
+Normally it's not necessary to call this tool manually, it is executed
+automatically at the end of the build process.
+
+The images generated by the build process can be directly written to an
+SD card::
+
+  # with Multi Image support:
+  cat images/barebox-freescale-imx51-babbage.img > /dev/sdd
+  # otherwise:
+  cat barebox-flash-image > /dev/sdd
+
+This will overwrite the partition table on the card. It can be preserved
+with::
+
+  dd if=images/barebox-freescale-imx51-babbage.img of=/dev/sdd bs=512 skip=1 seek=1
+
+The images can also always be started second stage::
+
+  bootm /mnt/tftp/barebox-freescale-imx51-babbage.img
+
+USB Boot
+^^^^^^^^
+
+Most boards can be explicitly configured for USB Boot Mode or fall back
+to USB Boot when no other medium can be found. The barebox repository
+contains a USB upload tool. As it depends on the libusb development headers
+it is not built by default. Enable it explicitly in ``make menuconfig``
+and install the libusb development package. On Debian this can be done
+with ``apt-get install libusb-dev``. After compilation the tool can be used
+with only the image name as argument::
+
+  scripts/imx/imx-usb-loader images/barebox-freescale-imx51-babbage.img
+
+External Boot Mode
+------------------
+
+The External Boot Mode is supported by the older i.MX SoCs:
+
+* i.MX1
+* i.MX21
+* i.MX27
+* i.MX31
+
+(It may be supported on newer SoCs aswell, but it is not widely used there)
+
+The External Boot Mode only supports booting from NOR and NAND flash. On NOR
+flash the binary is started directly on its physical address in memory. Booting
+from NAND flash is more complicated. The NAND flash controller copies the first
+2kb of the image to the NAND Controllers internal SRAM. This initial binary
+portion is then has to:
+
+* Set up the SDRAM
+* Copy the initial binary to SDRAM to make the internal SRAM in the NAND flash
+  controller free for use for the controller
+* Copy the whole barebox image to SDRAM
+* Start the image
+
+It is possible to write the image directly to NAND. However, since NAND flash
+can have bad blocks which must be skipped during writing the image and also
+by the initial loader, it is recommended to use the :ref:`command_barebox_update`
+command for writing to NAND flash.
+
+i.MX boards
+-----------
+
+Not supported all boards have a description here. Many newer boards also do
+not have individual defconfig files, they are covered by ``imx_v7_defconfig``
+or ``imx_defconfig`` instead.
+
+.. toctree::
+  :glob:
+  :numbered:
+  :maxdepth: 1
+
+  imx/*
+  mxs/*
diff --git a/Documentation/boards/imx/Garz-Fricke-Cupid.rst b/Documentation/boards/imx/Garz-Fricke-Cupid.rst
new file mode 100644
index 0000000000..1328810bd3
--- /dev/null
+++ b/Documentation/boards/imx/Garz-Fricke-Cupid.rst
@@ -0,0 +1,9 @@
+Garz+Fricke Cupid
+=================
+
+This CPU card is based on a Freescale i.MX35 CPU. The card is shipped with:
+
+  * 256MiB Nand flash
+  * 128MiB synchronous dynamic RAM
+
+see http://www.garz-fricke.com/cupid-core_de.html for more information
diff --git a/Documentation/boards/imx/Phytec-phyCORE-i.MX31.rst b/Documentation/boards/imx/Phytec-phyCORE-i.MX31.rst
new file mode 100644
index 0000000000..527c49045f
--- /dev/null
+++ b/Documentation/boards/imx/Phytec-phyCORE-i.MX31.rst
@@ -0,0 +1,38 @@
+Phytec phyCORE-i.MX31 CPU module PCM-037
+========================================
+
+The CPU module
+--------------
+
+http://www.phytec.eu/europe/products/modules-overview/phycore/produktdetails/p/phycore-imx31-2.html
+
+This CPU card is based on a Freescale i.MX31 CPU. The card in configuration -0000REU is shipped with:
+
+  * 128 MiB synchronous dynamic RAM (DDR type)
+  * 64 MiB NAND flash
+  * 32 MiB NOR flash
+  * 512 kiB SRAM
+  * 4kiB EEPROM
+  * MMU, FPU
+  * Serial, Ethernet, USB (OTG), I2C, SPI, MMC/SD/SDIO, PCMCIA/CF, RTC
+
+Supported baseboards
+--------------------
+
+Supported baseboards are:
+  * Silica / Phytec PCM-970 via phyMAP-i.MX31, PMA-001
+
+How to get barebox for 'Phytec's phyCORE-i.MX31'
+------------------------------------------------
+
+Using the default configuration::
+
+  make ARCH=arm pcm037_defconfig
+
+Build the binary image::
+
+  make ARCH=arm CROSS_COMPILE=armv5compiler
+
+**NOTE** Replace ''armv5compiler'' with your ARM v5 cross compiler, e.g.: ''arm-1136jfs-linux-gnueabi-''
+
+The resulting binary image to be flashed will be barebox.bin, whereas the file named just barebox is an ELF executable for ARM.
diff --git a/Documentation/boards/imx/eukrea_cpuimx27.rst b/Documentation/boards/imx/eukrea_cpuimx27.rst
new file mode 100644
index 0000000000..c5ab4b94b7
--- /dev/null
+++ b/Documentation/boards/imx/eukrea_cpuimx27.rst
@@ -0,0 +1,11 @@
+Eukrea CPUIMX27
+===============
+
+This CPU card is based on a Freescale i.MX27 CPU. The card is shipped with:
+
+  * up to 64MiB NOR type Flash Memory
+  * up to 256MiB synchronous dynamic RAM
+  * up to 512MiB NAND type Flash Memory
+  * MII 10/100 ethernet PHY
+  * optional 16554 Quad UART on CS3
+
diff --git a/Documentation/boards/imx/synertronixx_scb9328.rst b/Documentation/boards/imx/synertronixx_scb9328.rst
new file mode 100644
index 0000000000..229b3d0a1e
--- /dev/null
+++ b/Documentation/boards/imx/synertronixx_scb9328.rst
@@ -0,0 +1,12 @@
+Synertronixx scb9328
+====================
+
+See http://www.synertronixx.de/produkte/scb9328/scb9328.htm
+
+This CPU card is based on a Freescale i.MX1 CPU. The card is shipped with:
+
+  * 16MiB NOR type Flash Memory
+  * 16MiB synchronous dynamic RAM
+  * DM9000 network controller
+
+It's the first i.MX board sha has ever ported Linux to.
diff --git a/Documentation/boards/mxs/Chumby-Falconwing.rst b/Documentation/boards/mxs/Chumby-Falconwing.rst
new file mode 100644
index 0000000000..73e4c302f0
--- /dev/null
+++ b/Documentation/boards/mxs/Chumby-Falconwing.rst
@@ -0,0 +1,46 @@
+chumbyone Chumby Industrie's Falconwing
+=======================================
+
+This device is also known as "chumby one" (http://www.chumby.com/)
+
+This CPU card is based on a Freescale i.MX23 CPU. The card is shipped with:
+
+  * 64 MiB synchronous dynamic RAM (DDR type)
+
+Memory layout when @b barebox is running:
+
+  * 0x40000000 start of SDRAM
+  * 0x40000100 start of kernel's boot parameters
+    * below malloc area: stack area
+    * below barebox: malloc area
+  * 0x42000000 start of @b barebox
+
+How to get the bootloader binary image
+--------------------------------------
+
+Using the default configuration::
+
+  make ARCH=arm chumbyone_defconfig
+
+Build the bootloader binary image::
+
+  make ARCH=arm CROSS_COMPILE=armv5compiler
+
+NOTE replace the armv5compiler with your ARM v5 cross compiler.
+
+How to prepare an MCI card to boot the "chumby one" with barebox
+----------------------------------------------------------------
+
+  * Create four primary partitions on the MCI card
+    * the first one for the bootlets (about 256 kiB)
+    * the second one for the persistant environment (size is up to you, at least 256k)
+    * the third one for the kernel (2 MiB ... 4 MiB in size)
+    * the 4th one for the root filesystem which can fill the rest of the available space
+
+  * Mark the first partition with the partition ID "53" and copy the bootlets into this partition (currently not part of @b barebox!).
+
+  * Copy the default @b barebox environment into the second partition (no filesystem required).
+
+  * Copy the kernel into the third partition (no filesystem required).
+
+  * Create the root filesystem in the 4th partition. You may copy an image into this partition or you can do it in the classic way: mkfs on it, mount it and copy all required data and programs into it.
diff --git a/Documentation/boards/mxs/Freescale-i.MX23-evk.rst b/Documentation/boards/mxs/Freescale-i.MX23-evk.rst
new file mode 100644
index 0000000000..b03508c0bb
--- /dev/null
+++ b/Documentation/boards/mxs/Freescale-i.MX23-evk.rst
@@ -0,0 +1,28 @@
+Freescale i.MX23 evaluation kit
+===============================
+
+This CPU card is based on an i.MX23 CPU. The card is shipped with:
+
+  * 32 MiB synchronous dynamic RAM (mobile DDR type)
+  * ENC28j60 based network (over SPI)
+
+Memory layout when @b barebox is running:
+
+  * 0x40000000 start of SDRAM
+  * 0x40000100 start of kernel's boot parameters
+    * below malloc area: stack area
+    * below barebox: malloc area
+  * 0x41000000 start of @b barebox
+
+How to get the bootloader binary image
+--------------------------------------
+
+Using the default configuration::
+
+  make ARCH=arm imx23evk_defconfig
+
+Build the bootloader binary image::
+
+  make ARCH=arm CROSS_COMPILE=armv5compiler
+
+**NOTE** replace the armv5compiler with your ARM v5 cross compiler.
diff --git a/Documentation/boards/mxs/KaRo-TX28.rst b/Documentation/boards/mxs/KaRo-TX28.rst
new file mode 100644
index 0000000000..a6c308c7e6
--- /dev/null
+++ b/Documentation/boards/mxs/KaRo-TX28.rst
@@ -0,0 +1,48 @@
+KARO TX28 CPU module
+====================
+
+The CPU module
+--------------
+
+http://www.karo-electronics.de/
+
+This CPU card is based on a Freescale i.MX28 CPU. The card is shipped with:
+
+  * 128 MiB synchronous dynamic RAM (DDR2 type), 200 MHz support
+  * 128 MiB NAND K9F1G08U0A (3.3V type)
+  * PCA9554 GPIO expander
+  * DS1339 RTC
+  * LAN8710 Phy
+
+Supported baseboards
+--------------------
+
+Supported baseboards are:
+  * KARO's Starterkit 5
+
+How to get barebox for 'KARO's Starterkit 5'
+--------------------------------------------
+
+Using the default configuration::
+
+  make ARCH=arm tx28stk5_defconfig
+
+Build the binary image::
+
+  make ARCH=arm CROSS_COMPILE=armv5compiler
+
+**NOTE** replace the armv5compiler with your ARM v5 cross compiler.
+
+**NOTE** To use the result, you also need the following resources from Freescale:
+  * the 'bootlets' archive
+  * the 'elftosb2' encryption tool
+  * in the case you want to start @b barebox from an attached SD card the 'sdimage' tool from Freescale's 'uuc' archive.
+
+Memory layout when barebox is running
+-------------------------------------
+
+  * 0x40000000 start of SDRAM
+  * 0x40000100 start of kernel's boot parameters
+    * below malloc area: stack area
+    * below barebox: malloc area
+  * 0x47000000 start of @b barebox
diff --git a/Documentation/boards/omap.rst b/Documentation/boards/omap.rst
new file mode 100644
index 0000000000..63caf66f5a
--- /dev/null
+++ b/Documentation/boards/omap.rst
@@ -0,0 +1,40 @@
+Texas Instruments OMAP/AM335x
+=============================
+
+Texas Intruments OMAP SoCs have a two staged boot process. The first stage is
+known as Xload which only loads the second stage bootloader. barebox can act as
+both the first and the second stage loader. To build as a first stage loader
+build the \*_xload_defconfig for your board, for second stage build the normal
+\*_defconfig for your board.
+
+bootstrapping a panda board
+---------------------------
+
+The Panda board boots from SD card. The OMAP Boot ROM code loads a file named
+'MLO' on a bootable FAT partition on this card. There are several howtos and
+scripts on the net which describe how to prepare such a card (it needs a
+special partitioning). The same procedure can be used for barebox. With such a
+card (assumed to be at /dev/sdc) the following can be used to build and install
+barebox::
+
+  # mount -t fat /dev/sdc1 /mnt
+  # make panda_xload_defconfig
+  # make
+  # cp barebox.bin.ift /mnt/MLO
+  # make panda_defconfig
+  # make
+  # cp barebox.bin /mnt/barebox.bin
+  # umount /mnt
+
+Bootstrapping a Beagle board is the same with the corresponding Beagle board defconfigs
+
+Networking
+----------
+
+The Beagle board does not have ethernet, but a USB ethernet dongle can be used
+for networking. the Panda board has an integrated USB ethernet converter which
+exactly behaves like an external dongle. Barebox does not automatically detect
+USB devices as this would have bad effects on boot time when USB is not needed.
+So you have to use the [[commands:usb|usb]] command to trigger USB detection.
+After this a network device should be present which can be used with the normal
+[[commands:dhcp|dhcp]] and [[commands:tftp|tftp]] commands.
diff --git a/Documentation/boards/s3c/Digi-a9m2440.rst b/Documentation/boards/s3c/Digi-a9m2440.rst
new file mode 100644
index 0000000000..4ed8ae4101
--- /dev/null
+++ b/Documentation/boards/s3c/Digi-a9m2440.rst
@@ -0,0 +1,67 @@
+DIGI a9m2440
+============
+
+This CPU card is based on a Samsung S3C2440 CPU. The card is shipped with:
+
+  * S3C2440\@400 MHz or 533 MHz (ARM920T/ARMv4T)
+  * 16.9344 MHz crystal reference
+  * SDRAM 32/64/128 MiB
+     * Samsung K4M563233E-EE1H (one or two devices for 32 MiB or 64 MiB)
+       * 2M x 32bit x 4 Banks Mobile SDRAM
+       * CL2\@100 MHz (CAS/RAS delay 19ns)
+       * 105 MHz max
+       * column address size is 9 bits
+       *  Row cycle time: 69ns
+     * Samsung K4M513233C-DG75 (one or two devices for 64 MiB or 128 MiB)
+       * 4M x 32bit x 4 Banks Mobile SDRAM
+       * CL2\@100MHz (CAS/RAS delay 18ns)
+       * 111 MHz max
+       * column address size is 9 bits
+       * Row cycle time: 63ns
+     * 64ms refresh period (4k)
+     * 90 pin FBGA
+     * 32 bit data bits
+     * Extended temperature range (-25°C...85°C)
+  * NAND Flash 32/64/128 MiB
+     * Samsung KM29U512T (NAND01GW3A0AN6)
+       * 64 MiB 3,3V 8-bit
+       * ID: 0xEC, 0x76, 0x??, 0xBD
+     * Samsung KM29U256T
+       * 32 MiB 3,3V 8-bit
+       * ID: 0xEC, 0x75, 0x??, 0xBD
+     * ST Micro
+       * 128 MiB 3,3V 8-bit
+       * ID: 0x20, 0x79
+     * 30ns/40ns/20ns
+  * I2C interface, 100 KHz and 400 KHz
+     * Real Time Clock
+       * Dallas DS1337
+       * address 0x68
+     * EEPROM
+       * ST M24LC64
+       * address 0x50
+       * 16bit addressing
+  * LCD interface
+  * Touch Screen interface
+  * Camera interface
+  * I2S interface
+  * AC97 Audio-CODEC interface
+  * SD card interface
+  * 3 serial RS232 interfaces
+  * Host and device USB interface, USB1.1 compliant
+  * Ethernet interface
+    * 10Mbps, Cirrus Logic, CS8900A (on the CPU card)
+  * SPI interface
+  * JTAG interface
+
+How to get the binary image:
+
+Using the default configuration::
+
+  make ARCH=arm a9m2440_defconfig
+
+Build the binary image::
+
+  make ARCH=arm CROSS_COMPILE=armv4compiler
+
+**NOTE** replace the armv4compiler with your ARM v4 cross compiler.
diff --git a/Documentation/boards/samsung.rst b/Documentation/boards/samsung.rst
new file mode 100644
index 0000000000..d75224f780
--- /dev/null
+++ b/Documentation/boards/samsung.rst
@@ -0,0 +1,9 @@
+Samsung S3C/S5P
+===============
+
+.. toctree::
+  :glob:
+  :numbered:
+  :maxdepth: 1
+
+  s3c/*
diff --git a/Documentation/boards/sandbox.rst b/Documentation/boards/sandbox.rst
new file mode 100644
index 0000000000..4601aedbc0
--- /dev/null
+++ b/Documentation/boards/sandbox.rst
@@ -0,0 +1,67 @@
+Sandbox
+=======
+
+barebox can be run as a simulator on your host to check and debug new non
+hardware related features.
+
+Build barebox for simulation
+----------------------------
+
+the barebox sand box can be built with the host compiler::
+
+  ARCH=sandbox make sandbox_defconfig
+  ARCH=sandbox make
+
+Run sandbox
+-----------
+
+::
+
+  $ barebox [\<OPTIONS\>]
+
+Options can be::
+
+  -m, --malloc=\<size\>
+
+Start sandbox with a specified malloc-space \<size\> in bytes.
+
+::
+
+  -i \<file\>
+
+Map a \<file\> to barebox. This option can be given multiple times. The \<file\>s
+will show up as /dev/fd0 ... /dev/fdx in the barebox simulator.
+
+::
+
+  -e \<file\>
+
+Map \<file\> to barebox. With this option \<file\>s are mapped as /dev/env0 ...
+/dev/envx and thus are used as default environment. A clean file generated
+with dd will do to get started with an empty environment
+
+::
+
+  -O \<file\>
+
+Register \<file\> as a console capable of doing stdout. \<file\> can be a
+regular file or a fifo.
+
+::
+
+  -I \<file\>
+
+Register \<file\> as a console capable of doing stdin. \<file\> can be a regular
+file or a fifo.
+
+::
+
+  -x, --xres \<res\>
+
+Specify SDL width
+
+::
+
+  -y, --yres \<res\>
+
+Specify SDL height
diff --git a/Documentation/boards/tegra.rst b/Documentation/boards/tegra.rst
new file mode 100644
index 0000000000..f28c506a69
--- /dev/null
+++ b/Documentation/boards/tegra.rst
@@ -0,0 +1,102 @@
+.. highlight:: console
+
+Nvidia Tegra
+============
+
+Building
+--------
+
+All currently supported Tegra boards are integrated in a single
+multi-image build (:ref:`multi_image`). Building is as easy as typing:
+
+.. code-block:: sh
+
+  make ARCH=arm tegra_v7_defconfig
+  make ARCH=arm CROSS_COMPILE=arm-v7-compiler-
+
+**NOTE** replace the arm-v7-compiler- with your ARM v7 cross compiler.
+
+Tegra images are specific to the bootsource. The build will generate images for
+all combinations of bootsources and supported boards. You can find the
+completed images in the ``images/`` subdirectory.
+
+The naming scheme consists of the triplet tegracodename-boardname-bootsource
+
+Kickstarting a board using USB
+------------------------------
+
+The tool needed to transfer and start a bootloader image to any Tegra board
+using the USB boot mode is called TegraRCM. Most likely this isn't available
+from your distributions repositories. You can get and install it by running the
+following commands:
+
+.. code-block:: sh
+
+  git clone https://github.com/NVIDIA/tegrarcm.git
+  cd tegrarcm
+  ./autogen.sh
+  make
+  sudo make install
+
+Connect the board to your host via the USB OTG port.
+The next step is to bring the device into USB boot mode. On developer boards
+this could normally be done by holding down a force recovery button (or setting
+some jumper) while resetting the board. On other devices you are on your own
+finding out how to achieve this.
+
+The tegrarcm tool has 3 basic options:
+
+.. code-block:: none
+
+  --bct        : the BCT file needed for basic hardware init,
+                 this can be found in the respective board directory
+  --bootloader : the actual barebox image
+                 use the -usbloader image
+  --loadaddr   : start address of the barebox image
+                 use 0x00108000 for Tegra20 aka Tegra2 devices
+                 use 0x80108000 for all other Tegra devices
+
+An example command line for the NVIDIA Beaver board looks like this:
+
+.. code-block:: sh
+
+  tegrarcm --bct arch/arm/boards/nvidia-beaver/beaver-2gb-emmc.bct \
+           --bootloader images/barebox-tegra30-nvidia-beaver-usbloader.img \
+           --loadaddr 0x80108000
+
+You should now see barebox coming up on the serial console.
+
+Writing barebox to the primary boot device
+------------------------------------------
+
+**NOTE** This may change in the near future to work with the standard
+barebox update mechanism (:ref:`update`).
+
+Copy the image corresponding to the primary boot device for your board to a
+SD-card and plug it into your board.
+
+Within the barebox shell use the standard mount and cp commands to copy the
+image to the boot device.
+
+On the NVIDIA Beaver board this looks like this:
+
+.. code-block:: sh
+
+  barebox@NVIDIA Tegra30 Beaver evaluation board:/ mount -a
+  mci0: detected SD card version 2.0
+  mci0: registered disk0
+  mci1: detected MMC card version 4.65
+  mci1: registered disk1.boot0
+  mci1: registered disk1.boot1
+  mci1: registered disk1
+  ext4 ext40: EXT2 rev 1, inode_size 128
+  ext4 ext41: EXT2 rev 1, inode_size 256
+  ext4 ext42: EXT2 rev 1, inode_size 256
+  none on / type ramfs
+  none on /dev type devfs
+  /dev/disk0.0 on /mnt/disk0.0 type ext4
+  /dev/disk0.1 on /mnt/disk0.1 type ext4
+  /dev/disk1.1 on /mnt/disk1.1 type ext4
+  barebox@NVIDIA Tegra30 Beaver evaluation board:/ cp /mnt/disk0.0/barebox-tegra30-nvidia-beaver-emmc.img /dev/disk1.boot0
+
+That's it: barebox should come up after resetting the board.
diff --git a/Documentation/boards/x86.rst b/Documentation/boards/x86.rst
new file mode 100644
index 0000000000..5d38955001
--- /dev/null
+++ b/Documentation/boards/x86.rst
@@ -0,0 +1,128 @@
+x86
+===
+
+Features
+--------
+
+barebox can act as a bootloader for PC based systems. In this case a special
+binary layout will be created to be able to store it on some media the PC
+BIOS can boot from. It can boot Linux kernels stored also on the same boot
+media and be configured at runtime, with the possibility to store the changed
+configuration on the boot media.
+
+Restrictions
+------------
+
+Due to some BIOS and barebox restrictions the boot media must be
+prepared in some special way:
+
+  * barebox must be stored in the MBR (Master Boot Record) of the boot media. Currently its not possible to store and boot it in one of the partition sectors  to use it as a second stage loader). This is no eternal restriction. It only needs further effort to add this feature.
+  * barebox currently cannot run a chained boot loader. Also, this is no external restriction, only further effort needed.
+  * barebox comes with limited filesystem support. There is currently no support for the most common and popular filesystems used in the \*NIX world. This restricts locations where to store a kernel and other runtime information
+  * barebox must be stored to the first n sectors of the boot media. To ensure this does not collide with partitions on the boot media, the first partition must start at a sector behind the ones barebox occupies.
+  * barebox handles its runtime configuration in a special way: It stores it in a binary way into some reserved sectors ("persistant storage").
+
+Boot Preparations
+-----------------
+
+To store the barebox image to a boot media, it comes with the tool
+setupmbr in the directory  scripts/setupmbr/ . To be able to use it on
+the boot media of your choice, some preparations are required.
+
+Keep Sectors free
+-----------------
+
+Build the barebox image and check its size. At least this amount of
+sectors must be kept free after the MBR prior the first partition. Do this
+simple calulation::
+
+	sectors = (\<size of barebox image\> + 511) / 512
+
+To be able to store the runtime configuration, further free sectors are
+required. Its up to you and your requirements, how large this persistant
+storage must be. If you need 16 kiB for this purpose, you need to keep
+additional 32 sectors free.
+
+For this example we are reserving 300 sectors for the barebox image and
+additionaly 32 sectors for the persistant storage. So, the first partition on
+the boot media must start at sector 333 or later.
+
+Run the  fdisk tool to setup such a partition table::
+
+
+  [jb@host]~> fdisk /dev/sda
+  Command (m for help): p
+  
+  Disk /dev/sda: 20.7 MB, 212680704 bytes
+  16 heads, 63 sectors/track, 406 cylinders
+  Units = cylinders of 1008 * 512 = 516096 bytes
+  
+  Device Boot      Start         End      Blocks   Id  System
+
+Change the used units to  sectors for easier handling.
+
+::
+
+  Command (m for help): u
+  Changing display/entry units to sectors
+  
+  Command (m for help): p
+
+  Disk /dev/sda: 20.7 MB, 212680704 bytes
+  16 heads, 63 sectors/track, 406 cylinders, total 409248 sectors
+  Units = sectors of 1 * 512 = 512 bytes
+  
+  Device Boot      Start         End      Blocks   Id  System
+
+Now its possible to create the first partition with the required offset::
+
+  Command (m for help): n
+  Command action
+     e   extended
+     p   primary partition (1-4)
+  p
+  Partition number (1-4): 1
+  First sector (63-409247, default 63): 333
+  Last sector or +size or +sizeM or +sizeK (333-409247, default 409247): +18M
+  Command (m for help): p
+  
+  Disk /dev/sda: 20.7 MB, 212680704 bytes
+  16 heads, 63 sectors/track, 406 cylinders, total 409248 sectors
+  Units = sectors of 1 * 512 = 512 bytes
+  
+          Device Boot      Start         End      Blocks   Id  System
+  /dev/sda                   333       35489       17578+  83  Linux
+
+That's all. Do whatever is required now with the new partition (formatting
+and populating the root filesystem for example) to make it useful.
+
+In the next step, barebox gets installed to this boot media::
+
+  [jb@host]~> scripts/setupmbr/setupmbr -s 32 -m ./barebox -d /dev/sda
+
+This command writes the barebox image file './barebox' onto the device
+ /dev/sda.
+
+The  -s option will keep the persistant storage sectors free and untouched
+and set flags in the MBR to forward its existance, size and location to
+barebox at runtime.  setupmbr also does not change the partition table.
+
+The barebox image gets stored on the boot media like this::
+
+  sector 0   1             33                              333
+         |---|-------------|--------------- ~~~ ------------|--------------
+        MBR    persistant              barebox                 first
+                storage               main image              partition
+
+If the  -s option is omitted, the "persistant storage" part simply does
+not exist::
+
+  sector 0   1                              333
+         |---|--------------- ~~~ ------------|--------------
+        MBR               barebox                 first
+                         main image              partition
+
+**NOTE** The  setupmbr tool is also working on real image file than on device
+      nodes only. So, there is no restriction what kind of file will be
+      modified.
+