doc: Use proper note and warning annotations

The documentation contains plenty of notes and warnings. Enable
special rendering of these blocks by converting the note prefix
into a .. note:: annotation.

Change-Id: I34e26ca6bf313d335672ab6c2645741900338822
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

3 files changed, 111 insertions, 77 deletions

diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 5be8c152..94ec9323 100644
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -331,7 +331,9 @@ must also be defined:
 
    SCP_BL2U image identifier, used by BL1 to fetch an image descriptor
    corresponding to SCP_BL2U.
-   NOTE: TF-A does not provide source code for this image.
+
+   .. note::
+      TF-A does not provide source code for this image.
 
 If the Non-Secure Firmware Updater ROM, NS_BL1U is used, the following must
 also be defined:
@@ -340,7 +342,9 @@ also be defined:
 
    Defines the base address in non-secure ROM where NS_BL1U executes.
    Must be aligned on a page-size boundary.
-   NOTE: TF-A does not provide source code for this image.
+
+   .. note::
+      TF-A does not provide source code for this image.
 
 -  **#define : NS_BL1U_IMAGE_ID**
 
@@ -354,7 +358,9 @@ be defined:
 
    Defines the base address in non-secure memory where NS_BL2U executes.
    Must be aligned on a page-size boundary.
-   NOTE: TF-A does not provide source code for this image.
+
+   .. note::
+      TF-A does not provide source code for this image.
 
 -  **#define : NS_BL2U_IMAGE_ID**
 
@@ -1000,8 +1006,9 @@ situation from which it cannot recover. This function must not return,
 and must be implemented in assembly because it may be called before the C
 environment is initialized.
 
-Note: The address from where it was called is stored in x30 (Link Register).
-The default implementation simply spins.
+.. note::
+   The address from where it was called is stored in x30 (Link Register).
+   The default implementation simply spins.
 
 Function : plat_get_bl_image_load_info()
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1042,9 +1049,10 @@ value will weaken the protection as the attacker could easily write the right
 value as part of the attack most of the time. Therefore, it should return a
 true random number.
 
-Note: For the protection to be effective, the global data need to be placed at
-a lower address than the stack bases. Failure to do so would allow an attacker
-to overwrite the canary as part of the stack buffer overflow attack.
+.. warning::
+   For the protection to be effective, the global data need to be placed at
+   a lower address than the stack bases. Failure to do so would allow an
+   attacker to overwrite the canary as part of the stack buffer overflow attack.
 
 Function : plat_flush_next_bl_params()
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2564,10 +2572,12 @@ makefiles in order to benefit from them. By default, they will cause the crash
 output to be routed over the normal console infrastructure and get printed on
 consoles configured to output in crash state. ``console_set_scope()`` can be
 used to control whether a console is used for crash output.
-NOTE: Platforms are responsible for making sure that they only mark consoles for
-use in the crash scope that are able to support this, i.e. that are written in
-assembly and conform with the register clobber rules for putc() (x0-x2, x16-x17)
-and flush() (x0-x3, x16-x17) crash callbacks.
+
+.. note::
+   Platforms are responsible for making sure that they only mark consoles for
+   use in the crash scope that are able to support this, i.e. that are written
+   in assembly and conform with the register clobber rules for putc()
+   (x0-x2, x16-x17) and flush() (x0-x3, x16-x17) crash callbacks.
 
 In some cases (such as debugging very early crashes that happen before the
 normal boot console can be set up), platforms may want to control crash output
diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst
index 51e9d3fa..03212af1 100644
--- a/docs/getting_started/rt-svc-writers-guide.rst
+++ b/docs/getting_started/rt-svc-writers-guide.rst
@@ -260,8 +260,9 @@ The ``cookie`` parameter to the handler is reserved for future use and can be
 ignored. The ``handle`` is returned by the SMC handler - completion of the
 handler function must always be via one of the ``SMC_RETn()`` macros.
 
-NOTE: The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow
-all of the above requirements yet.
+.. note::
+   The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow
+   all of the above requirements yet.
 
 Services that contain multiple sub-services
 -------------------------------------------
diff --git a/docs/getting_started/user-guide.rst b/docs/getting_started/user-guide.rst
index 42040275..60654644 100644
--- a/docs/getting_started/user-guide.rst
+++ b/docs/getting_started/user-guide.rst
@@ -96,9 +96,10 @@ targets which both utilise the `checkpatch.pl` script that ships with the Linux
 source tree. The project also defines certain *checkpatch* options in the
 ``.checkpatch.conf`` file in the top-level directory.
 
-**Note:** Checkpatch errors will gate upstream merging of pull requests.
-Checkpatch warnings will not gate merging but should be reviewed and fixed if
-possible.
+.. note::
+   Checkpatch errors will gate upstream merging of pull requests.
+   Checkpatch warnings will not gate merging but should be reviewed and fixed if
+   possible.
 
 To check the entire source tree, you must first download copies of
 ``checkpatch.pl``, ``spelling.txt`` and ``const_structs.checkpatch`` available
@@ -718,8 +719,9 @@ Common build options
    of certificates in the FIP and FWU_FIP depends upon the value of the
    ``GENERATE_COT`` option.
 
-   Note: This option depends on ``CREATE_KEYS`` to be enabled. If the keys
-   already exist in disk, they will be overwritten without further notice.
+   .. warning::
+      This option depends on ``CREATE_KEYS`` to be enabled. If the keys
+      already exist in disk, they will be overwritten without further notice.
 
 -  ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
    specifies the file that contains the Trusted World private key in PEM
@@ -739,8 +741,9 @@ Common build options
    interrupts to TSP allowing it to save its context and hand over
    synchronously to EL3 via an SMC.
 
-   Note: when ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT``
-   must also be set to ``1``.
+   .. note::
+      When ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT``
+      must also be set to ``1``.
 
 -  ``USE_ARM_LINK``: This flag determines whether to enable support for ARM
    linker. When the ``LINKER`` build variable points to the armlink linker,
@@ -948,9 +951,10 @@ version to 2 is recommended for DS-5 versions older than 5.16.
 When debugging logic problems it might also be useful to disable all compiler
 optimizations by using ``-O0``.
 
-NOTE: Using ``-O0`` could cause output images to be larger and base addresses
-might need to be recalculated (see the **Memory layout on Arm development
-platforms** section in the `Firmware Design`_).
+.. warning::
+   Using ``-O0`` could cause output images to be larger and base addresses
+   might need to be recalculated (see the **Memory layout on Arm development
+   platforms** section in the `Firmware Design`_).
 
 Extra debug options can be passed to the build system by setting ``CFLAGS`` or
 ``LDFLAGS``:
@@ -1205,12 +1209,14 @@ images with support for these features:
        NS_BL2U=<path-to>/<ns_bl2u_image>                               \
        all fip fwu_fip
 
-   Note: The BL2U image will be built by default and added to the FWU_FIP.
-   The user may override this by adding ``BL2U=<path-to>/<bl2u_image>``
-   to the command line above.
+   .. note::
+      The BL2U image will be built by default and added to the FWU_FIP.
+      The user may override this by adding ``BL2U=<path-to>/<bl2u_image>``
+      to the command line above.
 
-   Note: Building and installing the non-secure and SCP FWU images (NS_BL1U,
-   NS_BL2U and SCP_BL2U) is outside the scope of this document.
+   .. note::
+      Building and installing the non-secure and SCP FWU images (NS_BL1U,
+      NS_BL2U and SCP_BL2U) is outside the scope of this document.
 
    The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries.
    Both the FIP and FWU_FIP will include the certificates corresponding to the
@@ -1252,21 +1258,26 @@ This section provides Juno and FVP specific instructions to build Trusted
 Firmware, obtain the additional required firmware, and pack it all together in
 a single FIP binary. It assumes that a `Linaro Release`_ has been installed.
 
-Note: Pre-built binaries for AArch32 are available from Linaro Release 16.12
-onwards. Before that release, pre-built binaries are only available for AArch64.
+.. note::
+   Pre-built binaries for AArch32 are available from Linaro Release 16.12
+   onwards. Before that release, pre-built binaries are only available for
+   AArch64.
 
-Note: Follow the full instructions for one platform before switching to a
-different one. Mixing instructions for different platforms may result in
-corrupted binaries.
+.. warning::
+   Follow the full instructions for one platform before switching to a
+   different one. Mixing instructions for different platforms may result in
+   corrupted binaries.
 
-Note: The uboot image downloaded by the Linaro workspace script does not always
-match the uboot image packaged as BL33 in the corresponding fip file. It is
-recommended to use the version that is packaged in the fip file using the
-instructions below.
+.. warning::
+   The uboot image downloaded by the Linaro workspace script does not always
+   match the uboot image packaged as BL33 in the corresponding fip file. It is
+   recommended to use the version that is packaged in the fip file using the
+   instructions below.
 
-Note: For the FVP, the kernel FDT is packaged in FIP during build and loaded
-by the firmware at runtime. See `Obtaining the Flattened Device Trees`_
-section for more info on selecting the right FDT to use.
+.. note::
+   For the FVP, the kernel FDT is packaged in FIP during build and loaded
+   by the firmware at runtime. See `Obtaining the Flattened Device Trees`_
+   section for more info on selecting the right FDT to use.
 
 #. Clean the working directory
 
@@ -1291,12 +1302,14 @@ section for more info on selecting the right FDT to use.
    current working directory. The SCP_BL2 image corresponds to
    ``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``.
 
-   Note: The fiptool will complain if the images to be unpacked already
-   exist in the current directory. If that is the case, either delete those
-   files or use the ``--force`` option to overwrite.
+   .. note::
+      The fiptool will complain if the images to be unpacked already
+      exist in the current directory. If that is the case, either delete those
+      files or use the ``--force`` option to overwrite.
 
-   Note: For AArch32, the instructions below assume that nt-fw.bin is a normal
-   world boot loader that supports AArch32.
+   .. note::
+      For AArch32, the instructions below assume that nt-fw.bin is a
+      normal world boot loader that supports AArch32.
 
 #. Build TF-A images and create a new FIP for FVP
 
@@ -1662,7 +1675,8 @@ The latest version of the AArch64 build of TF-A has been tested on the following
 Arm FVPs without shifted affinities, and that do not support threaded CPU cores
 (64-bit host machine only).
 
-The FVP models used are Version 11.6 Build 45, unless otherwise stated.
+.. note::
+   The FVP models used are Version 11.6 Build 45, unless otherwise stated.
 
 -  ``FVP_Base_AEMv8A-AEMv8A``
 -  ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502``
@@ -1699,30 +1713,36 @@ Arm FVPs without shifted affinities, and that do not support threaded CPU cores
 -  ``FVP_Base_AEMv8A-AEMv8A``
 -  ``FVP_Base_Cortex-A32x4``
 
-NOTE: The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which
-is not compatible with legacy GIC configurations. Therefore this FVP does not
-support these legacy GIC configurations.
-
-NOTE: The build numbers quoted above are those reported by launching the FVP
-with the ``--version`` parameter.
-
-NOTE: Linaro provides a ramdisk image in prebuilt FVP configurations and full
-file systems that can be downloaded separately. To run an FVP with a virtio
-file system image an additional FVP configuration option
-``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be
-used.
-
-NOTE: The software will not work on Version 1.0 of the Foundation FVP.
-The commands below would report an ``unhandled argument`` error in this case.
-
-NOTE: FVPs can be launched with ``--cadi-server`` option such that a
-CADI-compliant debugger (for example, Arm DS-5) can connect to and control its
-execution.
-
-NOTE: Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202
-the internal synchronisation timings changed compared to older versions of the
-models. The models can be launched with ``-Q 100`` option if they are required
-to match the run time characteristics of the older versions.
+.. note::
+   The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which
+   is not compatible with legacy GIC configurations. Therefore this FVP does not
+   support these legacy GIC configurations.
+
+.. note::
+   The build numbers quoted above are those reported by launching the FVP
+   with the ``--version`` parameter.
+
+.. note::
+   Linaro provides a ramdisk image in prebuilt FVP configurations and full
+   file systems that can be downloaded separately. To run an FVP with a virtio
+   file system image an additional FVP configuration option
+   ``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be
+   used.
+
+.. note::
+   The software will not work on Version 1.0 of the Foundation FVP.
+   The commands below would report an ``unhandled argument`` error in this case.
+
+.. note::
+   FVPs can be launched with ``--cadi-server`` option such that a
+   CADI-compliant debugger (for example, Arm DS-5) can connect to and control
+   its execution.
+
+.. warning::
+   Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202
+   the internal synchronisation timings changed compared to older versions of
+   the models. The models can be launched with ``-Q 100`` option if they are
+   required to match the run time characteristics of the older versions.
 
 The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be
 downloaded for free from `Arm's website`_.
@@ -1743,8 +1763,9 @@ be found in the TF-A source directory under ``fdts/``. The Foundation FVP has
 a subset of the Base FVP components. For example, the Foundation FVP lacks
 CLCD and MMC support, and has only one CPU cluster.
 
-Note: It is not recommended to use the FDTs built along the kernel because not
-all FDTs are available from there.
+.. note::
+   It is not recommended to use the FDTs built along the kernel because not
+   all FDTs are available from there.
 
 The dynamic configuration capability is enabled in the firmware for FVPs.
 This means that the firmware can authenticate and load the FDT if present in
@@ -1851,8 +1872,9 @@ with 8 CPUs using the AArch64 build of TF-A.
     --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
     --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
 
-Note: The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires a
-specific DTS for all the CPUs to be loaded.
+.. note::
+   The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires
+   a specific DTS for all the CPUs to be loaded.
 
 Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2010,8 +2032,9 @@ with 8 CPUs using the AArch32 build of TF-A.
     --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000  \
     --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
 
-Note: The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``.
-It should match the address programmed into the RVBAR register as well.
+.. note::
+   The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``.
+   It should match the address programmed into the RVBAR register as well.
 
 Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~