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>

docs/change-log.rst

@@ -1186,7 +1186,8 @@ New features
 -  Migrated to use SPDX[0] license identifiers to make software license
    auditing simpler.
 
-   *NOTE:* Files that have been imported by FreeBSD have not been modified.
+   .. note::
+      Files that have been imported by FreeBSD have not been modified.
 
    [0]: https://spdx.org/
 
@@ -2205,7 +2206,8 @@ New features
    be used on the AEMv8 and Cortex-A57-A53 Base FVPs, as well as the Foundation
    FVP.
 
-   NOTE: The software will not work on Version 1.0 of the Foundation FVP.
+   .. note::
+      The software will not work on Version 1.0 of the Foundation FVP.
 
 -  Enabled third party contributions. Added a new contributing.md containing
    instructions for how to contribute and updated copyright text in all files
@@ -2236,15 +2238,18 @@ New features
    FIP from NOR flash, although some support for image loading using semi-
    hosting is retained.
 
-   NOTE: Building a FIP by default is a non-backwards-compatible change.
+   .. note::
+      Building a FIP by default is a non-backwards-compatible change.
 
-   NOTE: Generic BL2 code now loads a BL3-3 (non-trusted firmware) image into
-   DRAM instead of expecting this to be pre-loaded at known location. This is
-   also a non-backwards-compatible change.
+   .. note::
+      Generic BL2 code now loads a BL3-3 (non-trusted firmware) image into
+      DRAM instead of expecting this to be pre-loaded at known location. This is
+      also a non-backwards-compatible change.
 
-   NOTE: Some non-trusted firmware (e.g. UEFI) will need to be rebuilt so that
-   it knows the new location to execute from and no longer needs to copy
-   particular code modules to DRAM itself.
+   .. note::
+      Some non-trusted firmware (e.g. UEFI) will need to be rebuilt so that
+      it knows the new location to execute from and no longer needs to copy
+      particular code modules to DRAM itself.
 
 -  Reworked BL2 to BL3-1 handover interface. A new composite structure
    (bl31_args) holds the superset of information that needs to be passed from
@@ -2270,8 +2275,11 @@ New features
    Dispatcher (TSPD), which is loaded as an EL3 runtime service. The TSPD
    implements Secure Monitor functionality such as world switching and
    EL1 context management, and is responsible for communication with the TSP.
-   NOTE: The TSPD does not yet contain support for secure world interrupts.
-   NOTE: The TSP/TSPD is not built by default.
+
+   .. note::
+      The TSPD does not yet contain support for secure world interrupts.
+   .. note::
+      The TSP/TSPD is not built by default.
 
 Issues resolved since last release
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/components/exception-handling.rst

@@ -193,7 +193,7 @@ priority assignment:
    6 and 5), the platform can partition into 4 secure priority ranges: ``0x0``,
    ``0x20``, ``0x40``, and ``0x60``. See `Interrupt handling example`_.
 
-Note:
+.. note::
 
    The Arm GIC architecture requires that a GIC implementation that supports two
    security states must implement at least 32 priority levels; i.e., at least 5
@@ -215,7 +215,7 @@ priority level descriptors. Each entry in the array is of type
 ``ehf_pri_desc_t``, and declares a priority level, and shall be populated by the
 ``EHF_PRI_DESC()`` macro.
 
-Note:
+.. warning::
 
    The macro ``EHF_PRI_DESC()`` installs the descriptors in the array at a
    computed index, and not necessarily where the macro is placed in the array.

docs/design/auth-framework.rst

@@ -953,9 +953,11 @@ sources in the build for the various algorithms. Setting the variable to
 `rsa+ecdsa` enables support for both rsa and ecdsa algorithms in the mbedTLS
 library.
 
-Note: If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can
-be defined in the platform Makefile. It will make mbed TLS use an implementation
-of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%).
+.. note::
+   If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can
+   be defined in the platform Makefile. It will make mbed TLS use an
+   implementation of SHA-256 with smaller memory footprint (~1.5 KB less) but
+   slower (~30%).
 
 --------------
 

docs/design/firmware-design.rst

@@ -1141,8 +1141,10 @@ returning through EL3 and running the non-trusted firmware (BL33):
    ``bl31_register_bl32_init()`` which provides a SPD-defined mechanism to
    invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32
    entrypoint.
-   NOTE: The Test SPD service included with TF-A provides one implementation
-   of such a mechanism.
+
+   .. note::
+      The Test SPD service included with TF-A provides one implementation
+      of such a mechanism.
 
    On completion BL32 returns control to BL31 via a SMC, and on receipt the
    SPD service handler invokes the synchronous call return mechanism to return
@@ -1675,8 +1677,9 @@ The location of the BL32 image will result in different memory maps. This is
 illustrated for both FVP and Juno in the following diagrams, using the TSP as
 an example.
 
-Note: Loading the BL32 image in TZC secured DRAM doesn't change the memory
-layout of the other images in Trusted SRAM.
+.. note::
+   Loading the BL32 image in TZC secured DRAM doesn't change the memory
+   layout of the other images in Trusted SRAM.
 
 CONFIG section in memory layouts shown below contains:
 
@@ -2215,8 +2218,9 @@ The default memory layout for each BL image is as follows:
        |       Code        |
        +-------------------+ BLx_BASE
 
-Note: The 2KB alignment for the exception vectors is an architectural
-requirement.
+.. note::
+   The 2KB alignment for the exception vectors is an architectural
+   requirement.
 
 The read-write data start on a new memory page so that they can be mapped with
 read-write permissions, whereas the code and read-only data below are configured

docs/design/interrupt-framework-design.rst

@@ -416,8 +416,9 @@ runtime.
 Test secure payload dispatcher behavior
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Note:** where this document discusses ``TSP_NS_INTR_ASYNC_PREEMPT`` as being
-``1``, the same results also apply when ``EL3_EXCEPTION_HANDLING`` is ``1``.
+.. note::
+   Where this document discusses ``TSP_NS_INTR_ASYNC_PREEMPT`` as being
+   ``1``, the same results also apply when ``EL3_EXCEPTION_HANDLING`` is ``1``.
 
 The TSPD only handles Secure-EL1 interrupts and is provided with the following
 routing model at build time.

docs/design/reset-design.rst

@@ -23,10 +23,11 @@ configuration, some of these steps might be unnecessary. The following sections
 guide the platform integrator by indicating which build options exclude which
 steps, depending on the capability of the platform.
 
-Note: If BL31 is used as the TF-A entry point instead of BL1, the diagram
-above is still relevant, as all these operations will occur in BL31 in
-this case. Please refer to section 6 "Using BL31 entrypoint as the reset
-address" for more information.
+.. note::
+   If BL31 is used as the TF-A entry point instead of BL1, the diagram
+   above is still relevant, as all these operations will occur in BL31 in
+   this case. Please refer to section 6 "Using BL31 entrypoint as the reset
+   address" for more information.
 
 Programmable CPU reset address
 ------------------------------

docs/design/trusted-board-boot.rst

@@ -141,8 +141,9 @@ if any of the steps fail.
    compared with the hash of the ROTPK read from the trusted root-key storage
    registers. If they match, the BL2 hash is read from the certificate.
 
-   Note: the matching operation is platform specific and is currently
-   unimplemented on the Arm development platforms.
+   .. note::
+      The matching operation is platform specific and is currently
+      unimplemented on the Arm development platforms.
 
 -  BL1 loads the BL2 image. Its hash is calculated and compared with the hash
    read from the certificate. Control is transferred to the BL2 image if all

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

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
 -------------------------------------------

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/index.rst

@@ -153,7 +153,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.5 Build 33, unless otherwise stated.
+.. note::
+   The FVP models used are Version 11.5 Build 33, unless otherwise stated.
 
 -  ``FVP_Base_AEMv8A-AEMv8A``
 -  ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502``
@@ -190,7 +191,8 @@ 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.
+.. note::
+   The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities.
 
 The Foundation FVP can be downloaded free of charge. The Base FVPs can be
 licensed from Arm. See the `Arm FVP website`_.

docs/plat/rpi3.rst

@@ -270,11 +270,12 @@ The following build options are supported:
   BL32_EXTRA1=tee-pager_v2.bin  BL32_EXTRA2=tee-pageable_v2.bin``
   to put the binaries into the FIP.
 
-  Note: If OP-TEE is used it may be needed to add the following options to the
-  Linux command line so that the USB driver doesn't use FIQs:
-  ``dwc_otg.fiq_enable=0 dwc_otg.fiq_fsm_enable=0 dwc_otg.nak_holdoff=0``.
-  This will unfortunately reduce the performance of the USB driver. It is needed
-  when using Raspbian, for example.
+  .. warning::
+     If OP-TEE is used it may be needed to add the following options to the
+     Linux command line so that the USB driver doesn't use FIQs:
+     ``dwc_otg.fiq_enable=0 dwc_otg.fiq_fsm_enable=0 dwc_otg.nak_holdoff=0``.
+     This will unfortunately reduce the performance of the USB driver. It is
+     needed when using Raspbian, for example.
 
 - ``TRUSTED_BOARD_BOOT``: This port supports TBB. Set this option to 1 to enable
   it. In order to use TBB, you might want to set ``GENERATE_COT=1`` to let the

docs/process/coding-guidelines.rst

@@ -7,8 +7,9 @@ and provide feedback.
 
 Some of the guidelines may also apply to other codebases.
 
-**Note:** the existing TF codebase does not necessarily comply with all the
-below guidelines but the intent is for it to do so eventually.
+.. note::
+   The existing TF codebase does not necessarily comply with all the
+   below guidelines but the intent is for it to do so eventually.
 
 Checkpatch overrides
 --------------------

license.rst

@@ -27,8 +27,8 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 --------------
 
-Note:
-Individual files contain the following tag instead of the full license text.
+.. note::
+   Individual files contain the following tag instead of the full license text.
 
 ::