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, 267 insertions, 0 deletions

diff --git a/Documentation/user/booting-linux.rst b/Documentation/user/booting-linux.rst
new file mode 100644
index 0000000000..561a850ce3
--- /dev/null
+++ b/Documentation/user/booting-linux.rst
@@ -0,0 +1,267 @@
+.. _booting_linux:
+
+Booting Linux
+=============
+
+Introduction
+------------
+
+The basic boot command in barebox is :ref:`command_bootm`. This command
+can be used directly, but there is also a :ref:`command_boot` command
+which offers additional features like a boot sequence which tries to
+boot different entries until one succeeds.
+
+The bootm command
+-----------------
+
+The :ref:`command_bootm` command is the basic boot command. Depending on the
+architecture the bootm command handles different image types. On ARM the
+following images are supported:
+
+* ARM Linux zImage
+* U-Boot uImage
+* barebox images
+
+The images can either be passed directly to the bootm command as argument or
+in the ``global.bootm.image`` variable:
+
+.. code-block:: sh
+
+  bootm /path/to/zImage
+
+  # same as:
+
+  global.bootm.image=/path/to/zImage
+  bootm
+
+When barebox has an internal devicetree it is passed to the kernel. You can
+specify an alternative devicetree with the ``-o DTS`` option or the ``global.bootm.oftree``
+variable:
+
+.. code-block:: sh
+
+  bootm -o /path/to/dtb /path/to/zImage
+
+  # same as:
+
+  global.bootm.oftree=/path/to/dtb
+  global.bootm.image=/path/to/zImage
+  bootm
+
+**NOTE** It may happen that barebox is probed from the devicetree, but you have
+want to start a Kernel without passing a devicetree. In this case call ``oftree -f``
+to free the internal devicetree before calling ``bootm``
+
+Passing Kernel Arguments
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Depending on the barebox configuration (``CONFIG_FLEXIBLE_BOOTARGS``) there
+are to ways to pass bootargs to the Kernel. With ``CONFIG_FLEXIBLE_BOOTARGS``
+disabled the bootm command takes the bootargs from the ``bootargs`` environment
+variable. With ``CONFIG_FLEXIBLE_BOOTARGS`` enabled the bootargs are composed
+from different :ref:`global_device` variables. All variables beginning with
+``global.bootargs.`` will be concatenated to the bootargs:
+
+.. code-block:: sh
+
+  global linux.bootargs.base="console=ttyO0,115200"
+  global linux.bootargs.debug="earlyprintk ignore_loglevel"
+
+  bootm zImage
+
+  ...
+
+  Kernel command line: console=ttymxc0,115200n8 earlyprintk ignore_loglevel
+
+Additionally all variables starting with ``global.linux.mtdparts.`` are concatenated
+to a ``mtdparts=`` parameter to the kernel. This makes it possible to consistently
+partition devices with the :ref:`command_addpart` command and pass the same string as used
+with addpart to the Kernel:
+
+.. code-block:: sh
+
+  norparts="512k(bootloader),512k(env),4M(kernel),-(root)"
+  nandparts="1M(bootloader),1M(env),4M(kernel),-(root)"
+
+  global linux.mtdparts.nor0="physmap-flash.0:$norparts"
+  global linux.mtdparts.nand0="mxc_nand:$nandparts"
+
+  addpart /dev/nor0 $norparts
+  addpart /dev/nand0 $nandparts
+
+  ...
+
+  bootm zImage
+
+  ...
+
+  Kernel command line: mtdparts=physmap-flash.0:512k(bootloader),512k(env),4M(kernel),-(root);
+			mxc_nand:1M(bootloader),1M(env),4M(kernel),-(root)
+
+
+The boot command
+----------------
+
+The :ref:`command_boot` command offers additional convenience for the :ref:`command_bootm`
+command. It works with :ref:`boot_entries` and :ref:`bootloader_spec` entries. Boot entries
+are located under /env/boot/ and are scripts which setup the bootm variables so that the
+``boot`` command can run ``bootm`` without further arguments.
+
+.. _boot_entries:
+
+Boot entries
+^^^^^^^^^^^^
+
+A simple boot entry in ``/env/boot/mmc`` could look like this:
+
+.. code-block:: sh
+
+  #!/bin/sh
+
+  global.bootm.image=/mnt/mmc1/zImage
+  global.bootm.oftree=/env/oftree
+
+  global linux.bootargs.dyn.root="root=PARTUUID=deadbeef:01"
+
+This takes the kernel from ``/mnt/mmc1/zImage`` (which could be an
+:ref:`automount` path registered earlier). The devicetree will be used from
+``/env/oftree``. The Kernel gets the command line
+``root=PARTUUID=deadbeef:01``. Note the ``.dyn`` in the bootargs variable name.
+boot entries should always add Kernel command line parameters to variables with
+``.dyn`` in it. These will be cleared before booting different boot entries.
+This is done so that following boot entries do not leak command line
+parameters from the previous boot entries.
+
+This entry can be booted with ``boot mmc``. It can also be made the default by
+setting the ``global.boot.default`` variable to ``mmc`` and then calling
+``boot`` without arguments.
+
+.. _bootloader_spec:
+
+Bootloader Spec
+^^^^^^^^^^^^^^^
+
+barebox supports booting according to the bootloader spec:
+
+http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
+
+It follows another philosophy than the :ref:`boot_entries`. With Boot Entries
+booting is completely configured in the bootloader. Bootloader Spec Entries
+on the other hand the boot entries are on a boot medium. This gives a boot medium
+the possibility to describe where a Kernel is and what parameters it needs.
+
+All Bootloader Spec Entries are in a partition on the boot medium under ``/loader/entries/*.conf``.
+In the Bootloader Spec a boot medium has a dedicated partition to use for
+boot entries. barebox is less strict, it accepts Bootloader Spec Entries on
+every partition barebox can read.
+
+A Bootloader Spec Entry consists of key value pairs::
+
+  /loader/entries/6a9857a393724b7a981ebb5b8495b9ea-3.8.0-2.fc19.x86_64.conf:
+
+  title      Fedora 19 (Rawhide)
+  version    3.8.0-2.fc19.x86_64
+  machine-id 6a9857a393724b7a981ebb5b8495b9ea
+  options    root=UUID=6d3376e4-fc93-4509-95ec-a21d68011da2
+  linux      /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux
+  initrd     /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd
+
+All pathes are absolute pathes in the partition. Bootloader Spec Entries can
+be created manually, but there also is the ``scripts/kernel-install`` tool to
+create/list/modify entries directly on a MMC/SD card or other media. To use
+it create a SD card / USB memory stick with a /boot partition with type 0xea.
+The partition can be formatted with FAT or EXT4 filesystem. If you wish to write
+to it from barebox later you must use FAT. The following creates a Bootloader
+Spec Entry on a SD card:
+
+.. code-block:: sh
+
+  scripts/kernel-install --device=/dev/mmcblk0 -a \
+                --machine-id=11ab7c89d02c4f66a4e2474ea25b2b84 --kernel-version="3.15" \
+                --kernel=/home/sha/linux/arch/arm/boot/zImage --add-root-option \
+                --root=/dev/mmcblk0p1 -o "console=ttymxc0,115200"
+
+The entry can be listed with the -l option:
+
+.. code-block:: sh
+
+  scripts/kernel-install --device=/dev/mmcblk0 -l
+
+  Entry 0:
+        title:      Linux-3.15
+        version:    3.15
+        machine_id: 11ab7c89d02c4f66a4e2474ea25b2b84
+        options:    console=ttymxc0,115200 root=PARTUUID=0007CB20-01
+        linux:      11ab7c89d02c4f66a4e2474ea25b2b84.15/linux
+
+When on barebox the SD card shows up as ``mmc`` then this entry can be booted with
+``boot mmc1`` or with setting ``global.boot.default`` to ``mmc1``.
+
+network boot
+------------
+
+With the following steps barebox can start the Kernel and root filesystem
+over network, a standard development case.
+
+Configure network: edit ``/env/network/eth0``. For a standard dhcp setup
+the following is enough:
+
+.. code-block:: sh
+
+  #!/bin/sh
+
+  ip=dhcp
+  serverip=192.168.23.45
+
+serverip is only necessary if it differs from the serverip offered from the dhcp server.
+A static ip setup can look like this:
+
+.. code-block:: sh
+
+  #!/bin/sh
+
+  ip=static
+  ipaddr=192.168.2.10
+  netmask=255.255.0.0
+  gateway=192.168.2.1
+  serverip=192.168.2.1
+
+Note that barebox will pass the same ip settings to the kernel, i.e. it passes
+``ip=$ipaddr:$serverip:$gateway:$netmask::eth0:`` for a static ip setup and
+``ip=dhcp`` for a dynamic dhcp setup.
+
+Adjust ``global.user`` and maybe ``global.hostname`` in ``/env/config``::
+
+  global.user=sha
+  global.hostname=efikasb
+
+Copy the kernel (and devicetree if needed) to the base dir of the TFTP server::
+
+  cp zImage /tftpboot/sha-linux-efikasb
+  cp myboard.dtb /tftpboot/sha-oftree-efikasb
+
+barebox will pass ``nfsroot=/home/${global.user}/nfsroot/${global.hostname}``
+This may be a link to another location on the NFS server. Make sure that the
+link target is exported from the server.
+
+``boot net`` will then start the Kernel.
+
+If the pathes or names are not suitable they can be adjusted in
+``/env/boot/net``:
+
+.. code-block:: sh
+
+  #!/bin/sh
+
+  path="/mnt/tftp"
+
+  global.bootm.image="${path}/${global.user}-linux-${global.hostname}"
+
+  oftree="${path}/${global.user}-oftree-${global.hostname}"
+  if [ -f "${oftree}" ]; then
+         global.bootm.oftree="$oftree"
+  fi
+
+  nfsroot="/home/${global.user}/nfsroot/${global.hostname}"
+  bootargs-ip
+  global.linux.bootargs.dyn.root="root=/dev/nfs nfsroot=$nfsroot,v3,tcp"