Merge branch 'for-next/misc'

4 files changed, 124 insertions, 17 deletions

diff --git a/Documentation/user/booting-linux.rst b/Documentation/user/booting-linux.rst
index f26299efd9..66f64ece08 100644
--- a/Documentation/user/booting-linux.rst
+++ b/Documentation/user/booting-linux.rst
@@ -229,10 +229,10 @@ time.
 Network boot
 ------------
 
-With the following steps barebox can start the Kernel and root filesystem
-over network, a standard development case.
+With the following steps, barebox can start the kernel and root filesystem
+over the network, a standard development case.
 
-Configure network: edit ``/env/network/eth0``. For a standard dhcp setup
+Configure network: edit ``/env/network/eth0``. For a standard DHCP setup
 the following is enough:
 
 .. code-block:: sh
@@ -242,8 +242,11 @@ the following is enough:
   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:
+The optional setting ``serverip`` specifies the IP address of your TFTP and NFS
+server, and is only necessary if it differs from the server IP offered by the
+DHCP server (i.e., the field ``siaddr`` in the DHCP ACK Reply).
+
+A static IP setup can look like this:
 
 .. code-block:: sh
 
@@ -255,27 +258,43 @@ A static ip setup can look like this:
   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.
+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``::
+By default, barebox uses the variables ``global.user`` and ``global.hostname``
+to retrieve its kernel image over TFTP, which makes it possible to use multiple
+boards for multiple users with one single server.
+You can adjust those variables in ``/env/config``::
 
   global.user=sha
   global.hostname=efikasb
 
-Copy the kernel (and devicetree if needed) to the base dir of the TFTP server::
+Copy the kernel (and devicetree if needed) to the root directory of your TFTP
+server, and name them accordingly; for example::
 
   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 paths or names are not suitable they can be adjusted in
+(In this example, the directory ``/tftpboot`` represents the root directory of
+the TFTP server.
+That directory depends on the configuration of your TFTP server, some servers
+may also use ``/srv/tftp`` instead.)
+
+barebox will pass ``nfsroot=/home/${global.user}/nfsroot/${global.hostname}`` to
+the kernel.
+This causes the kernel to mount its root filesystem from a NFS server, which is
+detected through the DHCP reply.
+To choose a different server, simply prepend its IP address to the mount path,
+e.g. ``nfsroot=192.168.23.5:/home/...``.
+In any case, make sure that the specified mountpoint is exported by your NFS
+server.
+
+For more information about booting with ``nfsroot``, see
+`Documentation/filesystems/nfs/nfsroot.txt <https://github.com/torvalds/linux/blob/master/Documentation/filesystems/nfs/nfsroot.txt>`__
+in the Linux kernel documentation.
+
+If the preconfigured paths or names are not suitable, they can be adjusted in
 ``/env/boot/net``:
 
 .. code-block:: sh
@@ -294,3 +313,6 @@ If the paths or names are not suitable they can be adjusted in
   nfsroot="/home/${global.user}/nfsroot/${global.hostname}"
   bootargs-ip
   global.linux.bootargs.dyn.root="root=/dev/nfs nfsroot=$nfsroot,v3,tcp"
+
+``boot net`` will then retrieve the kernel (and also the device tree and
+initramfs, if used) over TFTP and boot it.
diff --git a/Documentation/user/random.rst b/Documentation/user/random.rst
new file mode 100644
index 0000000000..95dad72e55
--- /dev/null
+++ b/Documentation/user/random.rst
@@ -0,0 +1,63 @@
+Random Number Generator support
+===============================
+
+Barebox provides two types of RNG sources - PRNG and HWRNG:
+
+- "A pseudorandom number generator (PRNG), also known as a deterministic random
+  bit generator (DRBG),[1] is an algorithm for generating a sequence of numbers
+  whose properties approximate the properties of sequences of random numbers.
+  The PRNG-generated sequence is not truly random, because it is completely
+  determined by a relatively small set of initial values, called the PRNG's seed
+  (which may include truly random values). Although sequences that are closer to
+  truly random can be generated using hardware random number generators."
+  Pseudorandom number generator. https://en.wikipedia.org/wiki/Pseudorandom_number_generator (2017.05.08).
+  The PRNG used by Barebox is LCG (linear congruential generator) non cryptographically
+  secure, so please use with caution.
+
+- The HWRNG framework is software that makes use of a special hardware feature on
+  your CPU, SoC or motherboard. It can‘t provide any guarantee about cryptographic
+  security of used HW. Please refer to vendor documentation and/or RNG certification.
+
+API
+^^^
+
+.. code-block:: c
+
+        /* seed the PRNG. */
+        void srand(unsigned int seed);
+
+        /* Fill the buffer with PRNG bits. */
+        void get_random_bytes(void *buf, int len);
+
+        /* Fill the buffer with bits provided by HWRNG.
+         * This function may fail with a message “error: no HWRNG available!”
+         * in case HWRNG is not available or HW got some runtime error.
+         * If barebox is compiled with CONFIG_ALLOW_PRNG_FALLBACK,
+         * then get_crypto_bytes() will print “warning: falling back to Pseudo RNG source!”
+         * and use PRNG instead of returning error.
+         */
+        int get_crypto_bytes(void *buf, int len);
+
+User interface
+^^^^^^^^^^^^^^
+
+- /dev/hwrng0
+  provides access to first available HWRNG. To examine this source you can use:
+
+.. code-block:: sh
+
+  md -s /dev/hwrng0
+
+- /dev/prng
+  provides access to PRNG. To examine this source you can use:
+
+.. code-block:: sh
+
+  md -s /dev/prng
+
+To seed PRNG from user space the :ref:`command_seed` is provided. For example:
+
+.. code-block:: sh
+
+  seed 12345
+  md -s /dev/prng
diff --git a/Documentation/user/usb.rst b/Documentation/user/usb.rst
index bbcb045cee..ec219cfbe4 100644
--- a/Documentation/user/usb.rst
+++ b/Documentation/user/usb.rst
@@ -216,3 +216,24 @@ mode. Once a specific mode has been selected it can't be changed later anymore.
   musb-hdrc: setup fifo_mode 4
   musb-hdrc: 28/31 max ep, 16384/16384 memory
   barebox:/
+
+USB Gadget autostart Support
+----------------------------
+
+Barebox can be configured to start usbgadget automatically by using global variables,
+instead of creating boot script. This can be useful if autostart policy should be
+chosen at boot time from other driver or script.
+To get usbgadget autostart support barebox has to be compiled with
+CONFIG_USB_GADGET_AUTOSTART enabled.
+
+USB Gadget autostart Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``global.usbgadget.autostart``
+  Boolean flag. If set to 1, usbgadget will be started automatically on boot and
+  enable USB OTG mode. (Default 0).
+``global.usbgadget.acm``
+  Boolean flag. If set to 1, CDC ACM function will be created.
+  See :ref:`command_usbgadget` -a. (Default 0).
+``global.usbgadget.fastboot_function``
+  Function description for fastboot. See :ref:`command_usbgadget` -A [desc].
diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index 435649f353..791c8e0979 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -33,6 +33,7 @@ Contents:
    reset-reason
    system-reset
    state
+   random
 
 * :ref:`search`
 * :ref:`genindex`