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>

19 files changed, 1460 insertions, 0 deletions

diff --git a/Documentation/user/automount.rst b/Documentation/user/automount.rst
new file mode 100644
index 0000000000..d13eaf19af
--- /dev/null
+++ b/Documentation/user/automount.rst
@@ -0,0 +1,34 @@
+.. _automount:
+
+Automount
+=========
+
+barebox supports automatically mounting filesystems when a path is first
+accessed. This is handled with the :ref:`command_automount` command. With automounting
+it is possible to separate the configuration of a board from actually using
+filesystems. The filesystems (and the devices they are on) are only probed
+when necessary, so barebox does not lose time probing unused devices.
+
+Typical usage is for accessing the TFTP server. To set up an automount for a
+TFTP server, the following is required::
+
+  mkdir -p /mnt/tftp
+  automount /mnt/tftp 'ifup eth0 && mount -t tftp $eth0.serverip /mnt/tftp'
+
+This creates an automountpoint on /mnt/tftp. Whenever this directory is accessed,
+the command ``ifup eth0 && mount -t tftp $eth0.serverip /mnt/tftp`` is executed.
+It will bring up the network device using :ref:`command_ifup` and mount a TFTP filesystem
+using :ref:`command_mount`.
+
+Usually the above automount command is executed from an init script in /env/init/automount.
+With the above, files on the TFTP server can be accessed without configuration::
+
+  cp /mnt/tftp/linuximage /image
+
+This automatically detects a USB mass storage device and mounts the first
+partition to /mnt/fat::
+
+  mkdir -p /mnt/fat
+  automount -d /mnt/fat 'usb && [ -e /dev/disk0.0 ] && mount /dev/disk0.0 /mnt/fat'
+
+To see a list of currently registered automountpoints use ``automount -l``.
diff --git a/Documentation/user/barebox.rst b/Documentation/user/barebox.rst
new file mode 100644
index 0000000000..9eb34af874
--- /dev/null
+++ b/Documentation/user/barebox.rst
@@ -0,0 +1,178 @@
+barebox
+=======
+
+Getting barebox
+---------------
+
+barebox is released on a monthly basis. The version numbers use the format
+YYYY.MM.N, so 2014.06.0 is the monthly release for June 2014. Stable releases
+are done as needed to fix critical problems and are indicated by incrementing
+the suffix (for example 2014.06.1).
+
+All releases can be downloaded from:
+
+http://www.barebox.org/download/
+
+Development versions of barebox are accessible via git. A local repository clone
+can be created using git::
+
+  git clone git://git.pengutronix.de/git/barebox.git
+  Cloning into 'barebox'...
+  remote: Counting objects: 113356, done.
+  remote: Compressing objects: 100% (25177/25177), done.
+  remote: Total 113356 (delta 87910), reused 111155 (delta 85935)
+  Receiving objects: 100% (113356/113356), 33.13 MiB | 183.00 KiB/s, done.
+  Resolving deltas: 100% (87910/87910), done.
+  Checking connectivity... done.
+  Checking out files: 100% (5651/5651), done.
+
+A web interface to the repository is available at
+http://git.pengutronix.de/?p=barebox.git.
+
+.. _configuration:
+
+Configuration
+-------------
+
+barebox uses Kconfig from the Linux Kernel as a configuration tool.
+All configuration is accessible via the 'make' command. Before running
+it you have to specify your architecture with the ARCH environment
+variable and the cross compiler with the CROSS_COMPILE environment
+variable. ARCH has to be one of:
+
+* arm
+* blackfin
+* mips
+* nios2
+* openrisc
+* ppc
+* sandbox
+* x86
+
+CROSS_COMPILE should be the prefix of your cross compiler. This can
+either contain the full path or, if the cross compiler binary is
+in your $PATH, just the prefix.
+
+Either export ARCH and CROSS_COMPILE once before working on barebox::
+
+  export ARCH=arm
+  export CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf-
+  make ...
+
+or add them before each 'make' command::
+
+  ARCH=arm CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf- make ...
+
+For readability, ARCH/CROSS_COMPILE are skipped from the following examples.
+
+Configuring for a board
+^^^^^^^^^^^^^^^^^^^^^^^
+
+All configuration files can be found under arch/$ARCH/configs/. For an
+overview type::
+
+  make help
+
+  ...
+  Architecture specific targets (mips):
+    No architecture specific help defined for mips
+
+    loongson-ls1b_defconfig  - Build for loongson-ls1b
+    ritmix-rzx50_defconfig   - Build for ritmix-rzx50
+    tplink-mr3020_defconfig  - Build for tplink-mr3020
+    dlink-dir-320_defconfig  - Build for dlink-dir-320
+    qemu-malta_defconfig     - Build for qemu-malta
+
+barebox supports building for multiple boards with a single config. If you
+can't find your board in the list, it may be supported by one of the multi-board
+configs. As an example, this is the case for tegra_v7_defconfig and imx_v7_defconfig.
+Select your config with ``make <yourboard>_defconfig``::
+
+  make imx_v7_defconfig
+
+The configuration can be further customized with one of the configuration frontends
+with the most popular being ``menuconfig``::
+
+  make menuconfig
+
+Compilation
+-----------
+
+After barebox has been :ref:`configured <configuration>` it can be compiled::
+
+  make
+
+The resulting binary varies depending on the board barebox is compiled for.
+Without :ref:`multi_image` support the 'barebox-flash-image' link will point
+to the binary for flashing/uploading to the board. With :ref:`multi_image` support
+the compilation process will finish with a list of images built under images/::
+
+  images built:
+  barebox-freescale-imx51-babbage.img
+  barebox-genesi-efikasb.img
+  barebox-freescale-imx53-loco.img
+  barebox-freescale-imx53-loco-r.img
+  barebox-freescale-imx53-vmx53.img
+  barebox-tq-mba53-512mib.img
+  barebox-tq-mba53-1gib.img
+  barebox-datamodul-edm-qmx6.img
+  barebox-guf-santaro.img
+  barebox-gk802.img
+
+Starting barebox
+-----------------
+
+Bringing barebox to a board for the first time is highly board specific, see your
+board documentation for initial bringup.
+
+barebox binaries are, where possible, designed to be startable second stage from another
+bootloader. For example, if you have U-Boot running on your board, you can start barebox
+with U-Boot's 'go' command::
+
+  U-Boot: tftp $load_addr barebox.bin
+  U-Boot: go $load_addr
+
+With barebox already running on your board, this can be used to chainload another barebox::
+
+  bootm /mntf/tftp/barebox.bin
+
+At least ``barebox.bin`` (with :ref:`pbl` support enabled ``arch/$ARCH/pbl/zbarebox.bin``)
+should be startable second stage. The flash binary (``barebox-flash-image``) may or may not
+be startable second stage as it may have SoC specific headers which prevent running second
+stage.
+
+First Steps
+-----------
+
+This is a typical barebox startup log::
+
+  barebox 2014.06.0-00232-g689dc27-dirty #406 Wed Jun 18 00:25:17 CEST 2014
+
+
+  Board: Genesi Efika MX Smartbook
+  detected i.MX51 revision 3.0
+  mc13xxx-spi mc13892@00: Found MC13892 ID: 0x0045d0 [Rev: 2.0a]
+  m25p80 m25p800: sst25vf032b (4096 Kbytes)
+  ata0: registered /dev/ata0
+  imx-esdhc 70004000.esdhc: registered as 70004000.esdhc
+  imx-esdhc 70008000.esdhc: registered as 70008000.esdhc
+  imx-ipuv3 40000000.ipu: IPUv3EX probed
+  netconsole: registered as cs2
+  malloc space: 0xabe00000 -> 0xafdfffff (size 64 MiB)
+  mmc1: detected SD card version 2.0
+  mmc1: registered mmc1
+  barebox-environment environment-sd.7: setting default environment path to /dev/mmc1.barebox-environment
+  running /env/bin/init...
+
+  Hit any key to stop autoboot:  3
+
+  barebox@Genesi Efika MX Smartbook:/
+
+Without intervention, barebox will continue booting after 3 seconds. If interrupted
+by pressing a key, you will find yourself on the :ref:`shell <hush>`.
+
+On the shell type ``help`` for a list of supported commands. ``help <command>`` shows
+the usage for a particular command. barebox has tab completion which will complete
+your command. Arguments to commands are also completed depending on the command. If
+a command expects a file argument only files will be offered as completion. Other
+commands will only complete devices or devicetree nodes.
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"
diff --git a/Documentation/user/defaultenv-2.rst b/Documentation/user/defaultenv-2.rst
new file mode 100644
index 0000000000..fc3723ec6f
--- /dev/null
+++ b/Documentation/user/defaultenv-2.rst
@@ -0,0 +1,113 @@
+Default environment version 2
+=============================
+
+barebox has its environment files under /env/. Most of the runtime configuration
+takes place under /env/. The environment is comparable to a tar archive which is
+unpacked from a storage medium during startup. If for whatever reason the environment
+cannot be loaded from a storage medium, a compiled-in default environment is used
+instead.
+
+The environment is not automatically stored on the storage medium when a file
+under /env/ is changed, instead this has to be done manually using the
+:ref:`command_saveenv` command.
+
+There are two sets of generic environment files which can be used. The older one
+should not be used for new boards and is not described here. New boards should use
+defaultenv-2 instead.
+
+The default environment is composed from different directories during compilation::
+
+  defaultenv/defaultenv-2-base   -> base files
+  defaultenv/defaultenv-2-dfu    -> overlay for DFU
+  defaultenv/defaultenv-2-menu   -> overlay for menus
+  arch/$ARCH/boards/<board>/env  -> board specific overlay
+
+The content of the above directories is applied one after another. If the
+same file exists in a later overlay, it will overwrite the preceding one.
+
+/env/bin/init
+-------------
+
+This script is executed by the barebox startup code after initialization.
+In the defaultenv-2 it will add some global variables and executes the scripts
+in /env/init/. It is also responsible for printing the boot timeout prompt.
+Be careful with changes to this script: since it is executed before any user
+intervention, it might lock the system.
+
+/env/init/
+----------
+
+/env/init/ is the place for startup scripts. The scripts in this directory
+will be executed in alphabetical order by the /env/bin/init script.
+
+/env/boot/
+----------
+
+/env/boot/ contains boot entry scripts. the :ref:`command_boot` command treats
+the files in this directory as possible boot targets. See :ref:`booting_linux`
+for more details.
+
+/env/config
+-----------
+
+This file contains some basic configuration settings. It can be edited using
+the :ref:`command_edit` command. Typical content:
+
+.. code-block:: sh
+
+  #!/bin/sh
+
+  # change network settings in /env/network/eth0
+  # change mtd partition settings and automountpoints in /env/init/*
+
+  #global.hostname=
+
+  # set to false if you do not want to have colors
+  #global.allow_color=true
+
+  # user (used for network filenames)
+  #global.user=none
+
+  # timeout in seconds before the default boot entry is started
+  #global.autoboot_timeout=3
+
+  # list of boot entries. These are executed in order until one
+  # succeeds. An entry can be:
+  # - a filename in /env/boot/
+  # - a full path to a directory. All files in this directory are
+  #   treated as boot files and executed in alphabetical order
+  #global.boot.default=net
+
+  # base bootargs
+  #global.linux.bootargs.base="console=ttyS0,115200"
+
+When changing this file remember to do a ``saveenv`` to make the change
+persistent. Also it may be necessary to manually ``source /env/config`` before
+the changes take effect.
+
+/env/network/
+-------------
+
+This contains the configuration files for the network interfaces. Typically
+there will be a file ``eth0`` with a content like this:
+
+.. code-block:: sh
+
+  #!/bin/sh
+
+  # ip setting (static/dhcp)
+  ip=dhcp
+  global.dhcp.vendor_id=barebox-${global.hostname}
+
+  # static setup used if ip=static
+  ipaddr=
+  netmask=
+  gateway=
+  serverip=
+
+  # MAC address if needed
+  #ethaddr=xx:xx:xx:xx:xx:xx
+
+  # put code to discover eth0 (i.e. 'usb') to /env/network/eth0-discover
+
+  exit 0
diff --git a/Documentation/user/devicetree.rst b/Documentation/user/devicetree.rst
new file mode 100644
index 0000000000..856ff6a05b
--- /dev/null
+++ b/Documentation/user/devicetree.rst
@@ -0,0 +1,84 @@
+.. _devicetree:
+
+Devicetree support
+==================
+
+Flattened Device Tree (FDT) is a data structure for describing the hardware on
+a system. On an increasing number of boards both barebox and the Linux Kernel can
+probe their devices directly from devicetrees. barebox needs the devicetree compiled
+into the binary. The Kernel usually does not have a devicetree compiled in, instead
+the Kernel expects to be passed a devicetree from the bootloader.
+
+From a bootloader's point of view, using devicetrees has the advantage that the
+same devicetree is used to probe both the Kernel and the Bootloader; this
+drastically reduces porting effort since the devicetree has to be written only
+once (and with luck somebody has already written a devicetree for the Kernel).
+Probing barebox from devicetree is highly recommended for new projects.
+
+.. _internal_devicetree:
+
+The internal devicetree
+-----------------------
+
+The devicetree barebox has been probed from plays a special role. It is referred to
+as the :ref:`internal_devicetree`. The barebox devicetree commands work on this
+devicetree. The devicetree source (DTS) files are kept in sync with the Kernel DTS
+files. As the FDT files are meant to be backward compatible, it should always be possible
+to start a Kernel with the barebox internal devicetree. However, since the barebox
+devicetree may not be complete or contain bugs it is always possible to start the
+Kernel with another devicetree than barebox has been started with.
+If a device has been probed from the devicetree then using the :ref:`command_devinfo`
+command on it will show the corresponding devicetree node:
+
+.. code-block:: sh
+
+  barebox@Phytec pcm970:/ devinfo 10002000.wdog
+  Resources:
+    num: 0
+    name: /soc/aipi@10000000/wdog@10002000
+    start: 0x10002000
+    size: 0x00001000
+  Driver: imx-watchdog
+  Bus: platform
+  Device node: /soc/aipi@10000000/wdog@10002000
+  wdog@10002000 {
+          compatible = "fsl,imx27-wdt", "fsl,imx21-wdt";
+          reg = <0x10002000 0x1000>;
+          interrupts = <0x1b>;
+          clocks = <0x1 0x4a>;
+  };
+
+Devicetree commands
+-------------------
+
+barebox has commands to show and manipulate devicetrees. These commands always
+work on the internal devicetree. It is possible to add/remove nodes using the
+:ref:`command_of_node` command and to add/change/remove properties using the
+:ref:`command_of_property` command. To dump devicetrees on the console use the
+:ref:`command_of_dump` command.
+
+.. code-block:: sh
+
+  # dump the whole devicetree
+  of_dump
+
+  # dump node of_dump /soc/nand@d8000000/
+  of_dump /soc/nand@d8000000/
+
+  # create a new node
+  of_node -c /chosen/mynode
+
+  # add a property to it
+  of_property -s /chosen/mynode/ myproperty myvalue
+
+It is important to know that these commands always work on the internal
+devicetree. If you modify the internal devicetree to influence the behaviour of
+a Kernel booted later, make sure that you start the kernel with the internal
+devicetree (i.e. don't pass a devicetree to the :ref:`command_bootm` command). If you
+wish to use another devicetree than the internal devicetree for starting the Kernel,
+you can exchange the internal devicetree during runtime:
+
+.. code-block:: sh
+
+   oftree -f
+   oftree -l /new/dtb
diff --git a/Documentation/user/driver-model.rst b/Documentation/user/driver-model.rst
new file mode 100644
index 0000000000..2ec55f1385
--- /dev/null
+++ b/Documentation/user/driver-model.rst
@@ -0,0 +1,91 @@
+Driver model
+============
+
+barebox has a driver model. This matches the devices on a board with their
+corresponding drivers. From a users point of view this is mostly visible in the
+:ref:`command_devinfo` and :ref:`command_drvinfo` command. Without arguments
+the :ref:`command_devinfo` command will show a hierarchical list of devices
+found on the board. As this may be instantiated from the :ref:`devicetree`
+there may be devices listed for which no driver is available. The
+:ref:`command_drvinfo` command shows a list of drivers together with the
+devices they handle.
+
+:ref:`command_devinfo` also shows a list of device files a device has registered::
+
+ `-- 70008000.esdhc
+    `-- mmc1
+       `-- 0x00000000-0x1d9bfffff (   7.4 GiB): /dev/mmc1
+       `-- 0x00100000-0x040fffff (    64 MiB): /dev/mmc1.0
+       `-- 0x04100000-0x240fffff (   512 MiB): /dev/mmc1.1
+       `-- 0x24100000-0xe40fffff (     3 GiB): /dev/mmc1.2
+       `-- 0xe4100000-0x1640fffff (     2 GiB): /dev/mmc1.3
+       `-- 0x00080000-0x000fffff (   512 KiB): /dev/mmc1.barebox-environment
+
+In this case the /dev/mmc1\* are handled by the mmc1 device. It must be noted
+that it's desirable that devices (mmc1) have the same name as the device files (/dev/mmc1\*),
+but this doesn't always have to be the case.
+
+Device detection
+----------------
+
+Some devices like USB or MMC may take a longer time to probe. Probing USB
+devices should not delay booting when USB may not even be used. This case is
+handled with device detection. The user visible interface to device detection
+is the :ref:`command_detect` command. ``detect -l`` shows a list of detectable
+devices::
+
+  barebox@Genesi Efika MX Smartbook:/ detect -l
+  70004000.esdhc
+  70008000.esdhc
+  73f80000.usb
+  73f80200.usb
+  73f80400.usb
+  83fe0000.pata
+  ata0
+  mmc0
+  mmc1
+  miibus0
+
+A particular device can be detected with ``detect <devname>``::
+
+  barebox@Genesi Efika MX Smartbook:/ detect 73f80200.usb
+  Found SMSC USB331x ULPI transceiver (0x0424:0x0006).
+  Bus 002 Device 004: ID 13d3:3273 802.11 n WLAN
+  mdio_bus: miibus0: probed
+  eth0: got preset MAC address: 00:1c:49:01:03:4b
+  Bus 002 Device 005: ID 0b95:7720 ZoWii
+  Bus 002 Device 002: ID 0424:2514
+  Bus 002 Device 001: ID 0000:0000 EHCI Host Controller
+
+For detecting all devices ``detect -a`` can be used.
+
+Device parameters
+-----------------
+
+Devices can have parameters which can be used to configure devices or to provide
+additional information for a device. The parameters can be listed with the
+:ref:`command_devinfo` command. A ``devinfo <devicename>`` will print the parameters
+of a device::
+
+  barebox@Genesi Efika MX Smartbook:/ devinfo eth0
+  Parameters:
+    ipaddr: 192.168.23.197
+    serverip: 192.168.23.1
+    gateway: 192.168.23.1
+    netmask: 255.255.0.0
+    ethaddr: 00:1c:49:01:03:4b
+
+The parameters can be used as shell variables::
+
+  eth0.ipaddr=192.168.23.15
+  echo "my current ip is: $eth0.ipaddr"
+
+device variables may have a type, so assigning wrong values may fail::
+
+  barebox@Genesi Efika MX Smartbook:/ eth0.ipaddr="This is not an IP"
+  set parameter: Invalid argument
+  barebox@Genesi Efika MX Smartbook:/ echo $?
+  1
+
+**HINT** barebox has tab completion for variables. Typing ``eth0.<TAB><TAB>``
+will show the parameters for eth0.
diff --git a/Documentation/user/framebuffer.rst b/Documentation/user/framebuffer.rst
new file mode 100644
index 0000000000..0065e7b42f
--- /dev/null
+++ b/Documentation/user/framebuffer.rst
@@ -0,0 +1,43 @@
+Framebuffer support
+===================
+
+barebox has support for framebuffer devices. Currently there is no console support
+for framebuffers, so framebuffer usage is limited to splash screens only. barebox
+supports BMP and PNG graphics using the :ref:`command_splash` command. barebox
+currently has no support for backlights, so unless there is a board specific enable
+hook for enabling a display it must be done manually with a script. Since barebox
+has nothing useful to show on the framebuffer it doesn't enable it during startup.
+A framebuffer can be enabled with the ``enable`` parameter of the framebuffer device:
+
+.. code-block:: sh
+
+  fb0.enable=1
+
+Some framebuffer devices support different resolutions. These can be configured
+with the ``mode_name`` parameter. See a list of supported modes using ``devinfo fb0``.
+A mode can only be changed when the framebuffer is disabled.
+
+A typical script to enable the framebuffer could look like this:
+
+.. code-block:: sh
+
+  #!/bin/sh
+
+  SPLASH=/path/to/mysplash.png
+
+  if [ ! -f $SPLASH ]; then
+      exit 0
+  fi
+
+  # first show splash
+  splash /path/to/mysplash.png
+
+  # enable framebuffer
+  fb0.enable=1
+
+  # wait for signals to become stable
+  msleep 100
+
+  # finally enable backlight
+  gpio_direction_output 42 1
+
diff --git a/Documentation/user/hush.rst b/Documentation/user/hush.rst
new file mode 100644
index 0000000000..4a1b84bad1
--- /dev/null
+++ b/Documentation/user/hush.rst
@@ -0,0 +1,52 @@
+.. index:: hush shell
+
+.. _hush:
+
+hush shell
+==========
+
+barebox has an integrated shell: hush. This is a simple shell which
+is enough for writing simple shell scripts. Usage of the shell for
+scripts should not be overstrained. Often a command written in C is
+more flexible and also more robust than a complicated shell script.
+
+hush features
+-------------
+
+variables::
+
+	a="Hello user"
+	echo $a
+	Hello user
+
+conditional execution ``if`` / ``elif`` / ``else`` / ``fi``::
+
+	if [ ${foo} = ${bar} ]; then
+		echo "foo equals bar"
+	else
+		echo "foo and bar differ"
+	fi
+
+``for`` loops::
+
+	for i in a b c; do
+		echo $i
+	done
+
+``while`` loops::
+
+	while true; do
+		echo "endless loop"
+	done
+
+wildcard globbing::
+
+	ls d*
+	echo ???
+
+There is no support in hush for input/output redirection or pipes.
+Some commands work around this limitation with additional arguments. for
+example the :ref:`command_echo` command has the ``-a FILE`` option for appending
+a file and the ``-o FILE`` option for overwriting a file. The readline
+command requires a variable name as argument in which the line will be
+stored.
diff --git a/Documentation/user/introduction.rst b/Documentation/user/introduction.rst
new file mode 100644
index 0000000000..8eb586044a
--- /dev/null
+++ b/Documentation/user/introduction.rst
@@ -0,0 +1,27 @@
+Introduction
+============
+
+This is the barebox user manual. It describes how to configure, compile
+and run barebox on Embedded Systems.
+
+barebox (just barebox, not *the* barebox) is a bootloader designed for
+Embedded Systems. It runs on a variety of ARM, MIPS, PowerPC based SoCs.
+barebox aims to be a versatile and flexible bootloader, not only for
+booting Embedded Linux Systems but also for initial hardware bringup and
+development. barebox is highly configurable to be suitable as a full featured
+development binary to a lean production system. Just like busybox is the swiss
+army knife for Embedded Linux, barebox is the swiss army knife for bare metal,
+hence the name.
+
+Feedback
+--------
+
+For sending patches, asking for help and giving general feedback you are
+always welcome to write a mail to the barebox mailing list. Most of the
+discussion of barebox takes place here:
+
+http://lists.infradead.org/mailman/listinfo/barebox/
+
+There's also an IRC channel:
+
+IRC: #barebox (Freenode)
diff --git a/Documentation/user/memory-areas.rst b/Documentation/user/memory-areas.rst
new file mode 100644
index 0000000000..dd1db9e8cd
--- /dev/null
+++ b/Documentation/user/memory-areas.rst
@@ -0,0 +1,27 @@
+memory areas
+============
+
+Several barebox commands like :ref:`command_md`, erase or crc work on an area
+of memory. Areas have the following form::
+
+  <start>-<end>
+
+or::
+
+  <start>+<count>
+
+start, end and count are interpreted as decimal values if not prefixed with 0x.
+Additionally these can be postfixed with K, M or G for kilobyte, megabyte or
+gigabyte.
+
+Examples
+--------
+
+Display a hexdump from 0x80000000 to 0x80001000 (inclusive)::
+
+  md 0x80000000-0x80001000
+
+Display 1 kilobyte of memory starting at 0x80000000::
+
+  md 0x80000000+1k
+
diff --git a/Documentation/user/multi-image.rst b/Documentation/user/multi-image.rst
new file mode 100644
index 0000000000..727b98fe5a
--- /dev/null
+++ b/Documentation/user/multi-image.rst
@@ -0,0 +1,54 @@
+.. _multi_image:
+
+Multi Image Support
+===================
+
+Traditionally a single configuration only works for a single board. Sometimes
+even variants of a single board like different amount of memory require a new
+config. This has the effect that the number of defconfig files increases dramatically.
+All the configs have to be kept in sync manually. Multi Image Support solves this
+problem.
+
+With Multi Image Support binaries for multiple boards can be generated from a single
+config. A single board can only support compilation with or without Multi Image Support.
+Multi Image Support exposes several user visible changes:
+
+* In ``make menuconfig`` it becomes possible to select multiple boards instead of
+  only one.
+* The ``barebox-flash-image`` link is no longer generated since there is no single
+  binary to use anymore.
+* images are generated under images/. The build process shows all images generated
+  at the end of the build.
+
+Technical background
+--------------------
+
+With Multi Image Support enabled, the main barebox binary (barebox.bin) will be
+shared across different boards. For board specific code this means that it has
+to test whether it actually runs on the board it is designed for. Typically board
+specific code has this:
+
+.. code-block:: c
+
+	static int efikamx_init(void)
+	{
+		if (!of_machine_is_compatible("genesi,imx51-sb"))
+			return 0;
+
+		... board specific code ...
+	}
+	device_initcall(efikamx_init);
+
+Multi Image Support always uses :ref:`PBL <pbl>` to generate compressed images.
+A board specific PBL image is prepended to the common barebox binary. The PBL
+image contains the devicetree which is passed to the common barebox binary to
+let the common binary determine the board type.
+
+The board specific PBL images are generated from a single set of object files
+using the linker. The basic trick here is that the PBL objects have multiple
+entry points, specified with the ENTRY_POINT macro. For each PBL binary
+generated a different entry point is selected using the ``-e`` option to ld.
+The linker will throw away all unused entry points and only keep the functions
+used by a particular entry point.
+
+The Multi Image PBL files can be disassembled with ``make <entry-function-name.pbl.S``
diff --git a/Documentation/user/networking.rst b/Documentation/user/networking.rst
new file mode 100644
index 0000000000..23b0e4640b
--- /dev/null
+++ b/Documentation/user/networking.rst
@@ -0,0 +1,81 @@
+networking
+==========
+
+barebox has IPv4 networking support. Several protocols such as
+:ref:`command_dhcp`, :ref:`filesystems_nfs`, :ref:`command_tftp` are
+supported.
+
+Network configuration
+---------------------
+
+The first step for networking is configuring the network device. The network
+device is usually ``eth0``. The current configuration can be viewed with the
+:ref:`command_devinfo` command:
+
+.. code-block:: sh
+
+  barebox@Genesi Efika MX Smartbook:/ devinfo eth0
+  Parameters:
+    ipaddr: 192.168.23.197
+    serverip: 192.168.23.1
+    gateway: 192.168.23.1
+    netmask: 255.255.0.0
+    ethaddr: 00:1c:49:01:03:4b
+
+The configuration can be changed on the command line with:
+
+.. code-block:: sh
+
+  eth0.ipaddr=172.0.0.10
+
+The :ref:`command_dhcp` command will change the settings based on the answer
+from the DHCP server.
+
+This low level configuration of the network interface is often not necessary. Normally
+the network settings should be edited in ``/env/network/eth0``, then the network interface
+can be brought up using the :ref:`command_ifup` command.
+
+Network filesystems
+-------------------
+
+barebox supports NFS and TFTP as filesystem implementations. See :ref:`filesystems_nfs`
+and :ref:`filesystems_tftp` for more information. After the network device has been
+brought up a network filesystem can be mounted with:
+
+.. code-block:: sh
+
+  mount -t tftp 192.168.2.1 /mnt
+
+or
+
+.. code-block:: sh
+
+  mount -t nfs 192.168.2.1:/export none /mnt
+
+**NOTE** This can often be hidden behind the :ref:`command_automount` command to make
+mounting transparent to the user.
+
+Network console
+---------------
+
+barebox has a udp based network console. If enabled in the config, you will see
+something like this during startup:
+
+  registered netconsole as cs1
+
+By default the network console is disabled during runtime to prevent security
+risks. It can be enabled using:
+
+.. code-block:: sh
+
+  cs1.ip=192.168.23.2
+  cs1.active=ioe
+
+This will send udp packets to 192.168.23.2 on port 6666. On 192.168.23.2 the
+scripts/netconsole script can be used to control barebox:
+
+.. code-block:: sh
+
+  scripts/netconsole <board IP> 6666
+
+The netconsole can be used just like any other console.
diff --git a/Documentation/user/pbl.rst b/Documentation/user/pbl.rst
new file mode 100644
index 0000000000..a08d6c9d77
--- /dev/null
+++ b/Documentation/user/pbl.rst
@@ -0,0 +1,31 @@
+.. _pbl:
+
+PreBootLoader images (PBL)
+==========================
+
+Traditionally barebox generates a raw uncompressed binary. PBL is an effort to
+create self extracting compressed images instead. This helps on some boards
+where storage space is sparse. Another usecase of PBL is on SoCs on which the
+ROM code loads the initial bootloader to (limited) SRAM. With self extracting
+binaries, more binary space becomes available.
+
+PBL is available for ARM and MIPS. It can be enabled in ``make menuconfig`` with
+the ``[*] Pre-Bootloader image`` option.
+
+The user visible difference is that with PBL support ``barebox.bin`` is no longer
+the final binary image, but instead ``arch/$ARCH/pbl/zbarebox.bin``. Use the
+``barebox-flash-image`` link which always points to the correct image.
+
+Technical background
+--------------------
+
+Normal object files are added to the make system using ``obj-y += file.o``.
+With PBL the build system recurses into the source directories a second
+time, this time all files specified with ``pbl-y += file.o`` are compiled.
+This way source code can be shared between regular barebox and PBL. A special
+case is ``lwl-y += file.o`` which expands to ``obj-y`` when PBL is disabled
+and to ``pbl-y`` when PBL is enabled.
+
+**HINT** For getting an overview over the binaries, disassemble barebox.bin
+(``make barebox.S``) with or without PBL support and also disassemble the
+PBL (``make arch/$ARCH/pbl/zbarebox.S``)
diff --git a/Documentation/user/system-setup.rst b/Documentation/user/system-setup.rst
new file mode 100644
index 0000000000..35d61475f3
--- /dev/null
+++ b/Documentation/user/system-setup.rst
@@ -0,0 +1,64 @@
+System Setup
+============
+
+Serial Console Access
+---------------------
+
+As most current development machines don't have serial ports, the usual setup
+is to use a USB-Serial-Converter. Some evaluation boards have such a converter
+on board. After connecting, these usually show up on your host as
+``/dev/ttyUSB#`` or ``/dev/ttyACM#`` (check ``dmesg`` to find out).
+
+On Debian systems, the device node will be accessible to the ``dialout`` group,
+so adding your user to that group (``adduser <user> dialout``) removes the need
+for root privileges.
+
+Using the "screen" program
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The terminal manager ``screen`` can also be used as a simple terminal emulator::
+
+  screen /dev/ttyUSB0 115200
+
+To exit from ``screen``, press ``<CTRL-A> <K> <y>``.
+
+Using the "microcom" program
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A good alternative terminal program is microcom. On Debian it can be installed
+with ``apt-get install microcom``, on other distributions it can be installed
+from source:
+
+http://git.pengutronix.de/?p=tools/microcom;a=summary
+
+Usage is simple::
+
+  microcom -p /dev/ttyUSB0
+
+Network Access
+--------------
+
+Having network connectivity between your host and your target will save you a
+lot of time otherwise spent on writing SD cards or using JTAG. The main
+protocols used with barebox are DHCP, TFTP and NFS.
+
+Configuration of dnsmasq for DHCP and TFTP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``dnsmasq`` program can be configured as a DHCP and TFTP server in addition
+to its original DNS functionality::
+
+  sudo ip addr add 192.168.23.1/24 dev <interface>
+  sudo ip link set <interface> up
+  sudo /usr/sbin/dnsmasq --interface=<interface> --no-daemon --log-queries \
+    --enable-tftp --tftp-root=<absolute-path-to-your-images>/ \
+    --dhcp-range=192.168.23.240,192.168.23.250
+
+Configuration of a TFTP Server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Configuration of a BOOTP / DHCP Server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Configuring a NFS Server
+^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Documentation/user/ubi.rst b/Documentation/user/ubi.rst
new file mode 100644
index 0000000000..a2e386fdc9
--- /dev/null
+++ b/Documentation/user/ubi.rst
@@ -0,0 +1,138 @@
+UBI/UBIFS support
+=================
+
+barebox has both UBI and UBIFS support. For handling UBI barebox has commands similar to
+the Linux commands :ref:`command_ubiformat`, :ref:`command_ubiattach`, :ref:`command_ubidetach`,
+:ref:`command_ubimkvol` and :ref:`command_ubirmvol`.
+
+The following examples assume we work on the first UBI device. Replace ``ubi0`` with
+the appropriate number when you have multiple UBI devices.
+
+The first step for preparing a pristine Flash for UBI is to :ref:`command_ubiformat` the
+device:
+
+.. code-block:: sh
+
+  ubiformat /dev/nand0.root
+
+If you intend to use a device with UBI you should always use ``ubiformat`` instead of plain
+:ref:`command_erase`. ``ubiformat`` will make sure the erasecounters are preserved and also
+:ref:`ubi_fastmap` won't work when a flash is erased with ``erase``
+
+NOTE: When using the :ref:`ubi_fastmap` feature make sure that the UBI is attached and detached
+once after using ``ubiformat``. This makes sure the Fastmap is written.
+
+After a device has been formatted it can be attached with :ref:`command_ubiattach`.
+
+.. code-block:: sh
+
+  ubiattach /dev/nand0.root
+
+This will create the controlling node ``/dev/ubi0`` and also register all volumes present
+on the device as ``/dev/ubi0.<volname>``. When freshly formatted there won't be any volumes
+present. A volume can be created with:
+
+.. code-block:: sh
+
+  ubimkvol /dev/ubi0 root 0
+
+The first parameter is the controlling node. The second parameter is the name of the volume.
+In this case the volume can be found under ``/dev/ubi.root``. The third parameter contains
+the size. A size of zero means that all available space shall be used.
+
+The next step is to write a UBIFS image to the volume. The image must be created on a host using
+the ``mkfs.ubifs`` command. ``mkfs.ubifs`` requires several arguments for describing the
+flash layout. Values for these arguments can be retrieved from a ``devinfo ubi`` under barebox:
+
+.. code-block:: sh
+
+  barebox@Phytec pcm970:/ devinfo ubi0
+  Parameters:
+    peb_size: 16384
+    leb_size: 15360
+    vid_header_offset: 512
+    min_io_size: 512
+    sub_page_size: 512
+    good_peb_count: 3796
+    bad_peb_count: 4
+    max_erase_counter: 0
+    mean_erase_counter: 0
+    available_pebs: 3713
+    reserved_pebs: 83
+
+To build a UBIFS image for this device the following command is suitable:
+
+.. code-block:: sh
+
+  mkfs.ubifs --min-io-size=512 --leb-size=15360 --max-leb-cnt=4096 -r rootdir \
+	/tftpboot/root.ubifs
+
+The ``--max-leb-cnt`` parameter specifies the maximum number of logical erase blocks
+the UBIFS image can ever have. For this particular device a number of 3713 would be
+enough. If the image shall be used for multiple boards the maximim peb count of all
+boards must be used.
+
+The UBIFS image can be transferred to the board for example with TFTP:
+
+.. code-block:: sh
+
+  cp /mnt/tftp/root.ubifs /dev/ubi0.root
+
+Finally it can be mounted using the :ref:`command_mount` command:
+
+.. code-block:: sh
+
+  mkdir -p /mnt/ubi
+  mount -t ubifs /dev/ubi0.root /mnt/ubi
+
+The second time the UBIFS is mounted the above can be simplified to:
+
+.. code-block:: sh
+
+  ubiattach /dev/nand0.root
+  mount -t ubifs /dev/ubi0.root /mnt/ubi
+
+Mounting the UBIFS can also be made transparent with the automount command.
+With this helper script in ``/env/bin/automount-ubi:``:
+
+.. code-block:: sh
+
+  #!/bin/sh
+
+  if [ ! -e /dev/ubi0 ]; then
+	ubiattach /dev/nand0 || exit 1
+  fi
+
+  mount -t ubifs /dev/ubi0.root $automount_path
+
+
+The command ``automount -d /mnt/ubi/ '/env/bin/automount-ubi'`` will automatically
+attach the UBI device and mount the UBIFS image to ``/mnt/ubi`` whenever ``/mnt/ubi``
+is first accessed. The automount command can be added to ``/env/init/automount`` to
+execute it during startup.
+
+.. _ubi_fastmap:
+
+UBI Fastmap
+-----------
+
+When attaching UBI to a flash device the UBI code has to scan all eraseblocks on the
+flash. Since this can take some time the Fastmap feature has been introduced. It has
+been merged in Linux 3.7. barebox has support for the Fastmap feature, but to use
+it some care must be taken. The Fastmap feature reduces scanning time by adding
+informations to one of the first blocks of a flash. For technical details see
+http://www.linux-mtd.infradead.org/doc/ubi.html#L_fastmap. Since the Fastmap can
+only live near the beginning of a flash the Fastmap code relies on finding a free
+eraseblock there. The above example command make that sure, but Fastmap is incompatible
+with creating a UBI image on a host and directly flashing the UBI image to the
+raw NAND/NOR device. In this case the Fastmap code will not find a free eraseblock
+and the following message will occur during ``ubidetach``:
+
+.. code-block:: sh
+
+  UBI error: ubi_update_fastmap: could not find any anchor PEB
+  UBI warning: ubi_update_fastmap: Unable to write new fastmap, err=-28
+
+The Fastmap is first written after a ``ubidetach``, so it's important to attach/detach
+a UBI volume after using ``ubiformat``.
+
diff --git a/Documentation/user/updating.rst b/Documentation/user/updating.rst
new file mode 100644
index 0000000000..0503e7dc72
--- /dev/null
+++ b/Documentation/user/updating.rst
@@ -0,0 +1,29 @@
+
+.. _update:
+
+Updating barebox
+================
+
+Updating barebox is potentially a dangerous task. When the update fails,
+the board may not start anymore and must be recovered. barebox has a special
+command to make updating barebox easier and safer: :ref:`command_barebox_update`.
+A board can register an update handler to the update command. The handler can
+do additional checks before trying an update, e.g. it's possible
+to check whether the new image actually is a barebox image.
+
+Updating barebox can be as easy as::
+
+  barebox_update /path/to/new/barebox.img
+
+Multiple handlers can be registered to the update mechanism. Usually the device
+barebox has been started from is registered as default (marked with a ``*``)::
+
+  barebox@Genesi Efika MX Smartbook:/ barebox_update -l
+  registered update handlers:
+  * mmc         -> /dev/mmc1
+    spinor	-> /dev/m25p0
+
+:ref:`command_barebox_update` requires board support, so it may not be
+available for your board. It is recommended to implement it, but you can also
+update barebox manually using :ref:`command_erase` and :ref:`command_cp`
+commands. The exact commands are board specific.
diff --git a/Documentation/user/usb.rst b/Documentation/user/usb.rst
new file mode 100644
index 0000000000..9bbfccac5f
--- /dev/null
+++ b/Documentation/user/usb.rst
@@ -0,0 +1,65 @@
+USB support
+===========
+
+USB host support
+----------------
+
+barebox has support for USB host and USB device mode. USB devices
+take a long time to probe, so they are not probed automatically. Probing
+has to be triggered using the :ref:`command_usb` or :ref:`command_detect` command.
+USB devices in barebox are not hotpluggable. It is expected that USB
+devices are not disconnected while barebox is running.
+
+USB Networking
+^^^^^^^^^^^^^^
+
+barebox supports ASIX compatible devices and the SMSC95xx. After
+detection the device shows up as eth0 and can be used like a regular network
+device.
+
+To use a USB network device together with the :ref:`command_ifup` command, add the
+following to /env/network/eth0-discover:
+
+.. code-block:: sh
+
+  #!/bin/sh
+
+  usb
+
+USB mass storage
+^^^^^^^^^^^^^^^^
+
+barebox supports USB mass storage devices. After probing them with the :ref:`command_usb`
+they show up as ``/dev/diskx`` and can be used like any other device.
+
+USB device support
+------------------
+
+DFU
+^^^
+
+USB Device Firmware Upgrade (DFU) is an official USB device class specification of the USB
+Implementers Forum. It provides a vendor independent way to update the firmware of embedded
+devices. The current specification is version 1.1 and can be downloaded here:
+http://www.usb.org/developers/devclass_docs/DFU_1.1.pdf
+
+On barebox side the update is handled with the :ref:`command_dfu` command. It is passes a list
+of partitions to provide to the host. The partition list has the form ``<file>(<name>)<flags>``.
+``file`` is the path to the device or regular file which shall be updated. ``name`` is the
+name under which the partition shall be provided to the host. For the possible ``flags`` see
+:ref:`command_dfu`. A typical ``dfu`` command could look like this:
+
+.. code-block:: sh
+
+  dfu "/dev/nand0.barebox.bb(barebox)sr,/dev/nand0.kernel.bb(kernel)r,/dev/nand0.root.bb(root)r"
+
+On the host the tool `dfu-util <http://dfu-util.gnumonks.org/>`_ can be used to update the
+partitions. It is available for the most distributions. To update the Kernel for the above
+example the following can be used:
+
+.. code-block:: sh
+
+  dfu-util -D arch/arm/boot/zImage -a kernel
+
+The dfu-util command automatically finds dfu capable devices. If there are multiple devices
+found it has to be specified with the ``-d``/``-p`` options.
diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
new file mode 100644
index 0000000000..4e2a2509f2
--- /dev/null
+++ b/Documentation/user/user-manual.rst
@@ -0,0 +1,33 @@
+.. highlight:: console
+
+barebox user manual
+===================
+
+Contents:
+
+.. toctree::
+   :numbered:
+   :maxdepth: 2
+
+   introduction
+   system-setup
+   barebox
+   networking
+   automount
+   memory-areas
+   driver-model
+   hush
+   defaultenv-2
+   variables
+   updating
+   devicetree
+   pbl
+   multi-image
+   framebuffer
+   usb
+   ubi
+   booting-linux
+
+* :ref:`search`
+* :ref:`genindex`
+
diff --git a/Documentation/user/variables.rst b/Documentation/user/variables.rst
new file mode 100644
index 0000000000..04e179114e
--- /dev/null
+++ b/Documentation/user/variables.rst
@@ -0,0 +1,49 @@
+Configuration variables
+=======================
+
+.. _global_device:
+
+The ``global`` device
+---------------------
+
+The ``global`` device is a special purpose device. It only exists as a
+storage for global variables. Some global variables are created internally
+in barebox (see :ref:`magicvars`). Additional variables can be created with
+the :ref:`command_global` command::
+
+  global myvar
+
+This creates the ``global.myvar`` variable which now can be used like any
+other variable. You can also directly assign a value during creation::
+
+  global myvar1=foobar
+
+**NOTE** creating a variable with ``global myvar1=foobar`` looks very similar
+to assigning a value with ``global.myvar1=foobar``, but the latter fails when
+a variable has not been created before.
+
+.. _magicvars:
+
+Magic variables
+---------------
+
+Some variables have special meanings and influence the behaviour
+of barebox. Most but not all of them are consolidated in the :ref:`global_device`
+Since it's hard to remember which variables these are and if the current
+barebox has support for them the :ref:`command_magicvar` command can print a list
+of all variables with special meaning along with a short description::
+
+  barebox@Genesi Efika MX Smartbook:/ magicvar
+  OPTARG                           optarg for hush builtin getopt
+  PATH                             colon separated list of pathes to search for executables
+  PS1                              hush prompt
+  armlinux_architecture            ARM machine ID
+  armlinux_system_rev              ARM system revision
+  armlinux_system_serial           ARM system serial
+  automount_path                   mountpath passed to automount scripts
+  bootargs                         Linux Kernel parameters
+  bootsource                       The source barebox has been booted from
+  bootsource_instance              The instance of the source barebox has been booted from
+  global.boot.default              default boot order
+  ...
+