diff --git a/docs/firmware-update.rst b/docs/firmware-update.rst
new file mode 100644
index 0000000..829341d
--- /dev/null
+++ b/docs/firmware-update.rst
@@ -0,0 +1,412 @@
+ARM Trusted Firmware - Firmware Update Design Guide
+===================================================
+
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
+--------------
+
+Introduction
+------------
+
+This document describes the design of the Firmware Update (FWU) feature, which
+enables authenticated firmware to update firmware images from external
+interfaces such as USB, UART, SD-eMMC, NAND, NOR or Ethernet to SoC Non-Volatile
+memories such as NAND Flash, LPPDR2-NVM or any memory determined by the
+platform. This feature functions even when the current firmware in the system
+is corrupt or missing; it therefore may be used as a recovery mode. It may also
+be complemented by other, higher level firmware update software.
+
+FWU implements a specific part of the Trusted Board Boot Requirements (TBBR)
+specification, ARM DEN0006C-1. It should be used in conjunction with the
+`Trusted Board Boot`_ design document, which describes the image authentication
+parts of the Trusted Firmware (TF) TBBR implementation.
+
+Scope
+~~~~~
+
+This document describes the secure world FWU design. It is beyond its scope to
+describe how normal world FWU images should operate. To implement normal world
+FWU images, please refer to the "Non-Trusted Firmware Updater" requirements in
+the TBBR.
+
+FWU Overview
+------------
+
+The FWU boot flow is primarily mediated by BL1. Since BL1 executes in ROM, and
+it is usually desirable to minimize the amount of ROM code, the design allows
+some parts of FWU to be implemented in other secure and normal world images.
+Platform code may choose which parts are implemented in which images but the
+general expectation is:
+
+-  BL1 handles:
+
+   -  Detection and initiation of the FWU boot flow.
+   -  Copying images from non-secure to secure memory
+   -  FWU image authentication
+   -  Context switching between the normal and secure world during the FWU
+      process.
+
+-  Other secure world FWU images handle platform initialization required by
+   the FWU process.
+-  Normal world FWU images handle loading of firmware images from external
+   interfaces to non-secure memory.
+
+The primary requirements of the FWU feature are:
+
+#. Export a BL1 SMC interface to interoperate with other FWU images executing
+   at other Exception Levels.
+#. Export a platform interface to provide FWU common code with the information
+   it needs, and to enable platform specific FWU functionality. See the
+   `Porting Guide`_ for details of this interface.
+
+TF uses abbreviated image terminology for FWU images like for other TF images.
+An overview of this terminology can be found `here`_.
+
+The following diagram shows the FWU boot flow for ARM development platforms.
+ARM CSS platforms like Juno have a System Control Processor (SCP), and these
+use all defined FWU images. Other platforms may use a subset of these.
+
+|Flow Diagram|
+
+Image Identification
+--------------------
+
+Each FWU image and certificate is identified by a unique ID, defined by the
+platform, which BL1 uses to fetch an image descriptor (``image_desc_t``) via a
+call to ``bl1_plat_get_image_desc()``. The same ID is also used to prepare the
+Chain of Trust (Refer to the `Authentication Framework Design`_
+for more information).
+
+The image descriptor includes the following information:
+
+-  Executable or non-executable image. This indicates whether the normal world
+   is permitted to request execution of a secure world FWU image (after
+   authentication). Secure world certificates and non-AP images are examples
+   of non-executable images.
+-  Secure or non-secure image. This indicates whether the image is
+   authenticated/executed in secure or non-secure memory.
+-  Image base address and size.
+-  Image entry point configuration (an ``entry_point_info_t``).
+-  FWU image state.
+
+BL1 uses the FWU image descriptors to:
+
+-  Validate the arguments of FWU SMCs
+-  Manage the state of the FWU process
+-  Initialize the execution state of the next FWU image.
+
+FWU State Machine
+-----------------
+
+BL1 maintains state for each FWU image during FWU execution. FWU images at lower
+Exception Levels raise SMCs to invoke FWU functionality in BL1, which causes
+BL1 to update its FWU image state. The BL1 image states and valid state
+transitions are shown in the diagram below. Note that secure images have a more
+complex state machine than non-secure images.
+
+|FWU state machine|
+
+The following is a brief description of the supported states:
+
+-  RESET: This is the initial state of every image at the start of FWU.
+   Authentication failure also leads to this state. A secure
+   image may yield to this state if it has completed execution.
+   It can also be reached by using ``FWU_SMC_IMAGE_RESET``.
+
+-  COPYING: This is the state of a secure image while BL1 is copying it
+   in blocks from non-secure to secure memory.
+
+-  COPIED: This is the state of a secure image when BL1 has completed
+   copying it to secure memory.
+
+-  AUTHENTICATED: This is the state of an image when BL1 has successfully
+   authenticated it.
+
+-  EXECUTED: This is the state of a secure, executable image when BL1 has
+   passed execution control to it.
+
+-  INTERRUPTED: This is the state of a secure, executable image after it has
+   requested BL1 to resume normal world execution.
+
+BL1 SMC Interface
+-----------------
+
+BL1\_SMC\_CALL\_COUNT
+~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Arguments:
+        uint32_t function ID : 0x0
+
+    Return:
+        uint32_t
+
+This SMC returns the number of SMCs supported by BL1.
+
+BL1\_SMC\_UID
+~~~~~~~~~~~~~
+
+::
+
+    Arguments:
+        uint32_t function ID : 0x1
+
+    Return:
+        UUID : 32 bits in each of w0-w3 (or r0-r3 for AArch32 callers)
+
+This SMC returns the 128-bit `Universally Unique Identifier`_ for the
+BL1 SMC service.
+
+BL1\_SMC\_VERSION
+~~~~~~~~~~~~~~~~~
+
+::
+
+    Argument:
+        uint32_t function ID : 0x3
+
+    Return:
+        uint32_t : Bits [31:16] Major Version
+                   Bits [15:0] Minor Version
+
+This SMC returns the current version of the BL1 SMC service.
+
+BL1\_SMC\_RUN\_IMAGE
+~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Arguments:
+        uint32_t           function ID : 0x4
+        entry_point_info_t *ep_info
+
+    Return:
+        void
+
+    Pre-conditions:
+        if (normal world caller) synchronous exception
+        if (ep_info not EL3) synchronous exception
+
+This SMC passes execution control to an EL3 image described by the provided
+``entry_point_info_t`` structure. In the normal TF boot flow, BL2 invokes this SMC
+for BL1 to pass execution control to BL31.
+
+FWU\_SMC\_IMAGE\_COPY
+~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Arguments:
+        uint32_t     function ID : 0x10
+        unsigned int image_id
+        uintptr_t    image_addr
+        unsigned int block_size
+        unsigned int image_size
+
+    Return:
+        int : 0 (Success)
+            : -ENOMEM
+            : -EPERM
+
+    Pre-conditions:
+        if (image_id is invalid) return -EPERM
+        if (image_id is non-secure image) return -EPERM
+        if (image_id state is not (RESET or COPYING)) return -EPERM
+        if (secure world caller) return -EPERM
+        if (image_addr + block_size overflows) return -ENOMEM
+        if (image destination address + image_size overflows) return -ENOMEM
+        if (source block is in secure memory) return -ENOMEM
+        if (source block is not mapped into BL1) return -ENOMEM
+        if (image_size > free secure memory) return -ENOMEM
+        if (image overlaps another image) return -EPERM
+
+This SMC copies the secure image indicated by ``image_id`` from non-secure memory
+to secure memory for later authentication. The image may be copied in a single
+block or multiple blocks. In either case, the total size of the image must be
+provided in ``image_size`` when invoking this SMC for the first time for each
+image; it is ignored in subsequent calls (if any) for the same image.
+
+The ``image_addr`` and ``block_size`` specify the source memory block to copy from.
+The destination address is provided by the platform code.
+
+If ``block_size`` is greater than the amount of remaining bytes to copy for this
+image then the former is truncated to the latter. The copy operation is then
+considered as complete and the FWU state machine transitions to the "COPIED"
+state. If there is still more to copy, the FWU state machine stays in or
+transitions to the COPYING state (depending on the previous state).
+
+When using multiple blocks, the source blocks do not necessarily need to be in
+contiguous memory.
+
+Once the SMC is handled, BL1 returns from exception to the normal world caller.
+
+FWU\_SMC\_IMAGE\_AUTH
+~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Arguments:
+        uint32_t     function ID : 0x11
+        unsigned int image_id
+        uintptr_t    image_addr
+        unsigned int image_size
+
+    Return:
+        int : 0 (Success)
+            : -ENOMEM
+            : -EPERM
+            : -EAUTH
+
+    Pre-conditions:
+        if (image_id is invalid) return -EPERM
+        if (secure world caller)
+            if (image_id state is not RESET) return -EPERM
+            if (image_addr/image_size is not mappped into BL1) return -ENOMEM
+        else // normal world caller
+            if (image_id is secure image)
+                if (image_id state is not COPIED) return -EPERM
+            else // image_id is non-secure image
+                if (image_id state is not RESET) return -EPERM
+                if (image_addr/image_size is in secure memory) return -ENOMEM
+                if (image_addr/image_size not mappped into BL1) return -ENOMEM
+
+This SMC authenticates the image specified by ``image_id``. If the image is in the
+RESET state, BL1 authenticates the image in place using the provided
+``image_addr`` and ``image_size``. If the image is a secure image in the COPIED
+state, BL1 authenticates the image from the secure memory that BL1 previously
+copied the image into.
+
+BL1 returns from exception to the caller. If authentication succeeds then BL1
+sets the image state to AUTHENTICATED. If authentication fails then BL1 returns
+the -EAUTH error and sets the image state back to RESET.
+
+FWU\_SMC\_IMAGE\_EXECUTE
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Arguments:
+        uint32_t     function ID : 0x12
+        unsigned int image_id
+
+    Return:
+        int : 0 (Success)
+            : -EPERM
+
+    Pre-conditions:
+        if (image_id is invalid) return -EPERM
+        if (secure world caller) return -EPERM
+        if (image_id is non-secure image) return -EPERM
+        if (image_id is non-executable image) return -EPERM
+        if (image_id state is not AUTHENTICATED) return -EPERM
+
+This SMC initiates execution of a previously authenticated image specified by
+``image_id``, in the other security world to the caller. The current
+implementation only supports normal world callers initiating execution of a
+secure world image.
+
+BL1 saves the normal world caller's context, sets the secure image state to
+EXECUTED, and returns from exception to the secure image.
+
+FWU\_SMC\_IMAGE\_RESUME
+~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Arguments:
+        uint32_t   function ID : 0x13
+        register_t image_param
+
+    Return:
+        register_t : image_param (Success)
+                   : -EPERM
+
+    Pre-conditions:
+        if (normal world caller and no INTERRUPTED secure image) return -EPERM
+
+This SMC resumes execution in the other security world while there is a secure
+image in the EXECUTED/INTERRUPTED state.
+
+For normal world callers, BL1 sets the previously interrupted secure image state
+to EXECUTED. For secure world callers, BL1 sets the previously executing secure
+image state to INTERRUPTED. In either case, BL1 saves the calling world's
+context, restores the resuming world's context and returns from exception into
+the resuming world. If the call is successful then the caller provided
+``image_param`` is returned to the resumed world, otherwise an error code is
+returned to the caller.
+
+FWU\_SMC\_SEC\_IMAGE\_DONE
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Arguments:
+        uint32_t function ID : 0x14
+
+    Return:
+        int : 0 (Success)
+            : -EPERM
+
+    Pre-conditions:
+        if (normal world caller) return -EPERM
+
+This SMC indicates completion of a previously executing secure image.
+
+BL1 sets the previously executing secure image state to the RESET state,
+restores the normal world context and returns from exception into the normal
+world.
+
+FWU\_SMC\_UPDATE\_DONE
+~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Arguments:
+        uint32_t   function ID : 0x15
+        register_t client_cookie
+
+    Return:
+        N/A
+
+This SMC completes the firmware update process. BL1 calls the platform specific
+function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie`` as
+a ``void *``. The SMC does not return.
+
+FWU\_SMC\_IMAGE\_RESET
+~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Arguments:
+        uint32_t     function ID : 0x16
+        unsigned int image_id
+
+    Return:
+        int : 0 (Success)
+            : -EPERM
+
+    Pre-conditions:
+        if (secure world caller) return -EPERM
+        if (image in EXECUTED) return -EPERM
+
+This SMC sets the state of an image to RESET and zeroes the memory used by it.
+
+This is only allowed if the image is not being executed.
+
+--------------
+
+*Copyright (c) 2015-2017, ARM Limited and Contributors. All rights reserved.*
+
+.. _Trusted Board Boot: ./trusted-board-boot.rst
+.. _Porting Guide: ./porting-guide.rst
+.. _here: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
+.. _Authentication Framework Design: ./auth-framework.rst
+.. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt
+
+.. |Flow Diagram| image:: diagrams/fwu_flow.png?raw=true
+.. |FWU state machine| image:: diagrams/fwu_states.png?raw=true