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>

1 files changed, 103 insertions, 0 deletions

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/*