Skip to content

GitLab

Unverified Commit 848f00ce authored by Soby Mathew's avatar Soby Mathew Committed by GitHub
Browse files

Merge pull request #1598 from soby-mathew/sm/docs_update_deprecate_1 

docs: update for removal of deprecated interfaces.
parents 3ccfcd6e 509af92e
Show whitespace changes
Inline Side-by-side
docs/firmware-design.rst
View file @ 848f00ce
......@@ -1618,80 +1618,10 @@ Additionally, if the platform memory layout implies some image overlaying like
on FVP, BL31 and TSP need to know the limit address that their PROGBITS
sections must not overstep. The platform code must provide those.
When LOAD\_IMAGE\_V2 is disabled, TF-A provides a mechanism to verify at boot
time that the memory to load a new image is free to prevent overwriting a
previously loaded image. For this mechanism to work, the platform must specify
the memory available in the system as regions, where each region consists of
base address, total size and the free area within it (as defined in the
``meminfo_t`` structure). TF-A retrieves these memory regions by calling the
corresponding platform API:
- ``meminfo_t *bl1_plat_sec_mem_layout(void)``
- ``meminfo_t *bl2_plat_sec_mem_layout(void)``
- ``void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)``
- ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)``
- ``void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)``
For example, in the case of BL1 loading BL2, ``bl1_plat_sec_mem_layout()`` will
return the region defined by the platform where BL1 intends to load BL2. The
``load_image()`` function will check that the memory where BL2 will be loaded is
within the specified region and marked as free.
The actual number of regions and their base addresses and sizes is platform
specific. The platform may return the same region or define a different one for
each API. However, the overlap verification mechanism applies only to a single
region. Hence, it is the platform responsibility to guarantee that different
regions do not overlap, or that if they do, the overlapping images are not
accessed at the same time. This could be used, for example, to load temporary
images (e.g. certificates) or firmware images prior to being transfered to its
corresponding processor (e.g. the SCP BL2 image).
To reduce fragmentation and simplify the tracking of free memory, all the free
memory within a region is always located in one single buffer defined by its
base address and size. TF-A implements a top/bottom load approach:
after a new image is loaded, it checks how much memory remains free above and
below the image. The smallest area is marked as unavailable, while the larger
area becomes the new free memory buffer. Platforms should take this behaviour
into account when defining the base address for each of the images. For example,
if an image is loaded near the middle of the region, small changes in image size
could cause a flip between a top load and a bottom load, which may result in an
unexpected memory layout.
The following diagram is an example of an image loaded in the bottom part of
the memory region. The region is initially free (nothing has been loaded yet):
::
Memory region
+----------+
| |
| | <<<<<<<<<<<<< Free
| |
|----------| +------------+
| image | <<<<<<<<<<<<< | image |
|----------| +------------+
| xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable
+----------+
And the following diagram is an example of an image loaded in the top part:
::
Memory region
+----------+
| xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable
|----------| +------------+
| image | <<<<<<<<<<<<< | image |
|----------| +------------+
| |
| | <<<<<<<<<<<<< Free
| |
+----------+
When LOAD\_IMAGE\_V2 is enabled, TF-A does not provide any mechanism to verify
at boot time that the memory to load a new image is free to prevent overwriting
a previously loaded image. The platform must specify the memory available in
the system for all the relevant BL images to be loaded.
TF-A does not provide any mechanism to verify at boot time that the memory
to load a new image is free to prevent overwriting a previously loaded image.
The platform must specify the memory available in the system for all the
relevant BL images to be loaded.
For example, in the case of BL1 loading BL2, ``bl1_plat_sec_mem_layout()`` will
return the region defined by the platform where BL1 intends to load BL2. The
......@@ -1742,43 +1672,6 @@ The following list describes the memory layout on the Arm development platforms:
When BL32 (for AArch64) is loaded into Trusted SRAM, it is loaded below
BL31.
When LOAD\_IMAGE\_V2 is disabled the memory regions for the overlap detection
mechanism at boot time are defined as follows (shown per API):
- ``meminfo_t *bl1_plat_sec_mem_layout(void)``
This region corresponds to the whole Trusted SRAM except for the shared
memory at the base. This region is initially free. At boot time, BL1 will
mark the BL1(rw) section within this region as occupied. The BL1(rw) section
is placed at the top of Trusted SRAM.
- ``meminfo_t *bl2_plat_sec_mem_layout(void)``
This region corresponds to the whole Trusted SRAM as defined by
``bl1_plat_sec_mem_layout()``, but with the BL1(rw) section marked as
occupied. This memory region is used to check that BL2 and BL31 do not
overlap with each other. BL2\_BASE and BL1\_RW\_BASE are carefully chosen so
that the memory for BL31 is top loaded above BL2.
- ``void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)``
This region is an exact copy of the region defined by
``bl2_plat_sec_mem_layout()``. Being a disconnected copy means that all the
changes made to this region by the TF-A will not be propagated. This
approach is valid because the SCP BL2 image is loaded temporarily while it
is being transferred to the SCP, so this memory is reused afterwards.
- ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)``
This region depends on the location of the BL32 image. Currently, Arm
platforms support three different locations (detailed below): Trusted SRAM,
Trusted DRAM and the TZC-Secured DRAM.
- ``void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)``
This region corresponds to the Non-Secure DDR-DRAM, excluding the
TZC-Secured area.
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.
......
docs/porting-guide.rst
View file @ 848f00ce
......@@ -997,8 +997,8 @@ Function : plat\_get\_bl\_image\_load\_info()
Return : bl_load_info_t *
This function returns pointer to the list of images that the platform has
populated to load. This function is currently invoked in BL2 to load the
BL3xx images, when LOAD\_IMAGE\_V2 is enabled.
populated to load. This function is invoked in BL2 to load the
BL3xx images.
Function : plat\_get\_next\_bl\_params()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -1010,8 +1010,8 @@ Function : plat\_get\_next\_bl\_params()
This function returns a pointer to the shared memory that the platform has
kept aside to pass TF-A related information that next BL image needs. This
function is currently invoked in BL2 to pass this information to the next BL
image, when LOAD\_IMAGE\_V2 is enabled.
function is invoked in BL2 to pass this information to the next BL
image.
Function : plat\_get\_stack\_protector\_canary()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -1040,8 +1040,8 @@ Function : plat\_flush\_next\_bl\_params()
Return : void
This function flushes to main memory all the image params that are passed to
next image. This function is currently invoked in BL2 to flush this information
to the next BL image, when LOAD\_IMAGE\_V2 is enabled.
next image. This function is invoked in BL2 to flush this information
to the next BL image.
Function : plat\_log\_get\_prefix()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -1108,15 +1108,9 @@ warm boot. For each CPU, BL1 is responsible for the following tasks:
meminfo.total_base = Base address of secure RAM visible to BL2
meminfo.total_size = Size of secure RAM visible to BL2
meminfo.free_base = Base address of secure RAM available for
allocation to BL2
meminfo.free_size = Size of secure RAM available for allocation to BL2
By default, BL1 places this ``meminfo`` structure at the beginning of the
free memory available for its use. Since BL1 cannot allocate memory
dynamically at the moment, its free memory will be available for BL2's use
as-is. However, this means that BL2 must read the ``meminfo`` structure
before it starts using its free memory (this is discussed in Section 3.2).
By default, BL1 places this ``meminfo`` structure at the end of secure
memory visible to BL2.
It is possible for the platform to decide where it wants to place the
``meminfo`` structure for BL2 or restrict the amount of memory visible to
......@@ -1346,66 +1340,33 @@ Boot Loader Stage 2 (BL2)
The BL2 stage is executed only by the primary CPU, which is determined in BL1
using the ``platform_is_primary_cpu()`` function. BL1 passed control to BL2 at
``BL2_BASE``. BL2 executes in Secure EL1 and is responsible for:
#. (Optional) Loading the SCP\_BL2 binary image (if present) from platform
provided non-volatile storage. To load the SCP\_BL2 image, BL2 makes use of
the ``meminfo`` returned by the ``bl2_plat_get_scp_bl2_meminfo()`` function.
The platform also defines the address in memory where SCP\_BL2 is loaded
through the optional constant ``SCP_BL2_BASE``. BL2 uses this information
to determine if there is enough memory to load the SCP\_BL2 image.
Subsequent handling of the SCP\_BL2 image is platform-specific and is
implemented in the ``bl2_plat_handle_scp_bl2()`` function.
If ``SCP_BL2_BASE`` is not defined then this step is not performed.
#. Loading the BL31 binary image into secure RAM from non-volatile storage. To
load the BL31 image, BL2 makes use of the ``meminfo`` structure passed to it
by BL1. This structure allows BL2 to calculate how much secure RAM is
available for its use. The platform also defines the address in secure RAM
where BL31 is loaded through the constant ``BL31_BASE``. BL2 uses this
information to determine if there is enough memory to load the BL31 image.
#. (Optional) Loading the BL32 binary image (if present) from platform
provided non-volatile storage. To load the BL32 image, BL2 makes use of
the ``meminfo`` returned by the ``bl2_plat_get_bl32_meminfo()`` function.
The platform also defines the address in memory where BL32 is loaded
through the optional constant ``BL32_BASE``. BL2 uses this information
to determine if there is enough memory to load the BL32 image.
If ``BL32_BASE`` is not defined then this and the next step is not performed.
#. (Optional) Arranging to pass control to the BL32 image (if present) that
has been pre-loaded at ``BL32_BASE``. BL2 populates an ``entry_point_info``
structure in memory provided by the platform with information about how
BL31 should pass control to the BL32 image.
#. (Optional) Loading the normal world BL33 binary image (if not loaded by
other means) into non-secure DRAM from platform storage and arranging for
BL31 to pass control to this image. This address is determined using the
``plat_get_ns_image_entrypoint()`` function described below.
#. BL2 populates an ``entry_point_info`` structure in memory provided by the
platform with information about how BL31 should pass control to the
other BL images.
``BL2_BASE``. BL2 executes in Secure EL1 and and invokes
``plat_get_bl_image_load_info()`` to retrieve the list of images to load from
non-volatile storage to secure/non-secure RAM. After all the images are loaded
then BL2 invokes ``plat_get_next_bl_params()`` to get the list of executable
images to be passed to the next BL image.
The following functions must be implemented by the platform port to enable BL2
to perform the above tasks.
Function : bl2\_early\_platform\_setup() [mandatory]
Function : bl2\_early\_platform\_setup2() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : meminfo *
Argument : u_register_t, u_register_t, u_register_t, u_register_t
Return : void
This function executes with the MMU and data caches disabled. It is only called
by the primary CPU. The arguments to this function is the address of the
``meminfo`` structure populated by BL1.
by the primary CPU. The 4 arguments are passed by BL1 to BL2 and these arguments
are platform specific.
On Arm standard platforms, the arguments received are :
The platform may copy the contents of the ``meminfo`` structure into a private
variable as the original memory may be subsequently overwritten by BL2. The
copied structure is made available to all BL2 code through the
``bl2_plat_sec_mem_layout()`` function.
arg0 - Points to load address of HW_CONFIG if present
arg1 - ``meminfo`` structure populated by BL1. The platform copies
the contents of ``meminfo`` as it may be subsequently overwritten by BL2.
On Arm standard platforms, this function also:
......@@ -1451,24 +1412,6 @@ In Arm standard platforms, this function performs security setup, including
configuration of the TrustZone controller to allow non-secure masters access
to most of DRAM. Part of DRAM is reserved for secure world use.
Function : bl2\_plat\_sec\_mem\_layout() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : void
Return : meminfo *
This function should only be called on the cold boot path. It may execute with
the MMU and data caches enabled if the platform port does the necessary
initialization in ``bl2_plat_arch_setup()``. It is only called by the primary CPU.
The purpose of this function is to return a pointer to a ``meminfo`` structure
populated with the extents of secure RAM available for BL2 to use. See
``bl2_early_platform_setup()`` above.
Following functions are optionally used only when LOAD\_IMAGE\_V2 is enabled.
Function : bl2\_plat\_handle\_pre\_image\_load() [optional]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -1479,7 +1422,7 @@ Function : bl2\_plat\_handle\_pre\_image\_load() [optional]
This function can be used by the platforms to update/use image information
for given ``image_id``. This function is currently invoked in BL2 before
loading each image, when LOAD\_IMAGE\_V2 is enabled.
loading each image.
Function : bl2\_plat\_handle\_post\_image\_load() [optional]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -1491,183 +1434,7 @@ Function : bl2\_plat\_handle\_post\_image\_load() [optional]
This function can be used by the platforms to update/use image information
for given ``image_id``. This function is currently invoked in BL2 after
loading each image, when LOAD\_IMAGE\_V2 is enabled.
Following functions are required only when LOAD\_IMAGE\_V2 is disabled.
Function : bl2\_plat\_get\_scp\_bl2\_meminfo() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : meminfo *
Return : void
This function is used to get the memory limits where BL2 can load the
SCP\_BL2 image. The meminfo provided by this is used by load\_image() to
validate whether the SCP\_BL2 image can be loaded within the given
memory from the given base.
Function : bl2\_plat\_handle\_scp\_bl2() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : image_info *
Return : int
This function is called after loading SCP\_BL2 image and it is used to perform
any platform-specific actions required to handle the SCP firmware. Typically it
transfers the image into SCP memory using a platform-specific protocol and waits
until SCP executes it and signals to the Application Processor (AP) for BL2
execution to continue.
This function returns 0 on success, a negative error code otherwise.
Function : bl2\_plat\_get\_bl31\_params() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : void
Return : bl31_params *
BL2 platform code needs to return a pointer to a ``bl31_params`` structure it
will use for passing information to BL31. The ``bl31_params`` structure carries
the following information.
- Header describing the version information for interpreting the bl31\_param
structure
- Information about executing the BL33 image in the ``bl33_ep_info`` field
- Information about executing the BL32 image in the ``bl32_ep_info`` field
- Information about the type and extents of BL31 image in the
``bl31_image_info`` field
- Information about the type and extents of BL32 image in the
``bl32_image_info`` field
- Information about the type and extents of BL33 image in the
``bl33_image_info`` field
The memory pointed by this structure and its sub-structures should be
accessible from BL31 initialisation code. BL31 might choose to copy the
necessary content, or maintain the structures until BL33 is initialised.
Funtion : bl2\_plat\_get\_bl31\_ep\_info() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : void
Return : entry_point_info *
BL2 platform code returns a pointer which is used to populate the entry point
information for BL31 entry point. The location pointed by it should be
accessible from BL1 while processing the synchronous exception to run to BL31.
In Arm standard platforms this is allocated inside a bl2\_to\_bl31\_params\_mem
structure in BL2 memory.
Function : bl2\_plat\_set\_bl31\_ep\_info() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : image_info *, entry_point_info *
Return : void
In the normal boot flow, this function is called after loading BL31 image and
it can be used to overwrite the entry point set by loader and also set the
security state and SPSR which represents the entry point system state for BL31.
When booting an EL3 payload instead, this function is called after populating
its entry point address and can be used for the same purpose for the payload
image. It receives a null pointer as its first argument in this case.
Function : bl2\_plat\_set\_bl32\_ep\_info() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : image_info *, entry_point_info *
Return : void
This function is called after loading BL32 image and it can be used to
overwrite the entry point set by loader and also set the security state
and SPSR which represents the entry point system state for BL32.
Function : bl2\_plat\_set\_bl33\_ep\_info() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : image_info *, entry_point_info *
Return : void
This function is called after loading BL33 image and it can be used to
overwrite the entry point set by loader and also set the security state
and SPSR which represents the entry point system state for BL33.
In the preloaded BL33 alternative boot flow, this function is called after
populating its entry point address. It is passed a null pointer as its first
argument in this case.
Function : bl2\_plat\_get\_bl32\_meminfo() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : meminfo *
Return : void
This function is used to get the memory limits where BL2 can load the
BL32 image. The meminfo provided by this is used by load\_image() to
validate whether the BL32 image can be loaded with in the given
memory from the given base.
Function : bl2\_plat\_get\_bl33\_meminfo() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : meminfo *
Return : void
This function is used to get the memory limits where BL2 can load the
BL33 image. The meminfo provided by this is used by load\_image() to
validate whether the BL33 image can be loaded with in the given
memory from the given base.
This function isn't needed if either ``PRELOADED_BL33_BASE`` or ``EL3_PAYLOAD_BASE``
build options are used.
Function : bl2\_plat\_flush\_bl31\_params() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : void
Return : void
Once BL2 has populated all the structures that needs to be read by BL1
and BL31 including the bl31\_params structures and its sub-structures,
the bl31\_ep\_info structure and any platform specific data. It flushes
all these data to the main memory so that it is available when we jump to
later Bootloader stages with MMU off
Function : plat\_get\_ns\_image\_entrypoint() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : void
Return : uintptr_t
As previously described, BL2 is responsible for arranging for control to be
passed to a normal world BL image through BL31. This function returns the
entrypoint of that image, which BL31 uses to jump to it.
BL2 is responsible for loading the normal world BL33 image (e.g. UEFI).
This function isn't needed if either ``PRELOADED_BL33_BASE`` or ``EL3_PAYLOAD_BASE``
build options are used.
loading each image.
Function : bl2\_plat\_preload\_setup [optional]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -1870,8 +1637,8 @@ CPUs. BL31 executes at EL3 and is responsible for:
should make no assumptions about the system state when it receives control.
#. Passing control to a normal world BL image, pre-loaded at a platform-
specific address by BL2. BL31 uses the ``entry_point_info`` structure that BL2
populated in memory to do this.
specific address by BL2. On ARM platforms, BL31 uses the ``bl_params`` list
populated by BL2 in memory to do this.
#. Providing runtime firmware services. Currently, BL31 only implements a
subset of the Power State Coordination Interface (PSCI) API as a runtime
......@@ -1881,8 +1648,8 @@ CPUs. BL31 executes at EL3 and is responsible for:
#. Optionally passing control to the BL32 image, pre-loaded at a platform-
specific address by BL2. BL31 exports a set of apis that allow runtime
services to specify the security state in which the next image should be
executed and run the corresponding image. BL31 uses the ``entry_point_info``
structure populated by BL2 to do this.
executed and run the corresponding image. On ARM platforms, BL31 uses the
``bl_params`` list populated by BL2 in memory to do this.
If BL31 is a reset vector, It also needs to handle the reset as specified in
section 2.2 before the tasks described above.
......@@ -1890,28 +1657,32 @@ section 2.2 before the tasks described above.
The following functions must be implemented by the platform port to enable BL31
to perform the above tasks.
Function : bl31\_early\_platform\_setup() [mandatory]
Function : bl31\_early\_platform\_setup2() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
Argument : bl31_params *, void *
Argument : u_register_t, u_register_t, u_register_t, u_register_t
Return : void
This function executes with the MMU and data caches disabled. It is only called
by the primary CPU. The arguments to this function are:
by the primary CPU. BL2 can pass 4 arguments to BL31 and these arguments are
platform specific.
In Arm standard platforms, the arguments received are :
arg0 - The pointer to the head of `bl_params_t` list
which is list of executable images following BL31,
arg1 - Points to load address of SOC_FW_CONFIG if present
- The address of the ``bl31_params`` structure populated by BL2.
- An opaque pointer that the platform may use as needed.
arg2 - Points to load address of HW_CONFIG if present
The platform can copy the contents of the ``bl31_params`` structure and its
sub-structures into private variables if the original memory may be
subsequently overwritten by BL31 and similarly the ``void *`` pointing
to the platform data also needs to be saved.
arg3 - A special value to verify platform parameters from BL2 to BL31. Not
used in release builds.
In Arm standard platforms, BL2 passes a pointer to a ``bl31_params`` structure
in BL2 memory. BL31 copies the information in this pointer to internal data
structures. It also performs the following:
The function runs through the `bl_param_t` list and extracts the entry point
information for BL32 and BL33. It also performs the following:
- Initialize a UART (PL011 console), which enables access to the ``printf``
family of functions in BL31.
......
docs/user-guide.rst
View file @ 848f00ce
......@@ -1312,7 +1312,7 @@ section for more info on selecting the right FDT to use.
::
make ARCH=aarch64 PLAT=juno LOAD_IMAGE_V2=1 JUNO_AARCH32_EL3_RUNTIME=1 \
make ARCH=aarch64 PLAT=juno JUNO_AARCH32_EL3_RUNTIME=1 \
BL33=<path-to-juno32-oe-uboot>/SOFTWARE/bl33-uboot.bin \
SCP_BL2=<path-to-juno32-oe-uboot>/SOFTWARE/scp_bl2.bin \
BL32=<path-to-bl32>/bl32.bin all fip
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment