I know this is a long entry - but I wanted to capture most of the related requirements, some proposed specification and some commentary on what happens on the FVP. Please provide some feedback if this does not meet your needs or if you have suggestions for implementation as we plan to start implementing this proposal piece by piece over the coming few weeks. We will probably break bits out of the long text into separate/sub issues.

Entrypoint definitions

1. Reset Handler

A function residing at the CPU reset vector RVBAR_EL3. The function must be capable of determining the cold/warm boot and primary/secondary status of the CPU, and invoking the appropriate follow on function:

cold-boot initialization on the primary CPU
cold boot 'holding' or power-off on the secondary CPUs
warm boot to a previously configured function on any CPU
2. Cold boot Initialization

A function which must be called exactly once by the primary CPU before any other code in the image is run, excepting a possible Reset Handler described above.

3. Warm boot Initalization

A function (or functions) that initialize a CPU following a software programmed or interrupt triggered warm power-on. It is assumed that the cold boot initialization is complete.

BL3-1 interface requirements

1. BL3-1 base address entrypoint

The BL3-1 base address entrypoint should default to being the BL3-1 Cold boot Initialization function.
It must be possible for a platform to configure the BL3-1 base address entrypoint to be a Reset Handler.
2. BL3-1 Cold boot Initialization

This is only called by the primary CPU, if this is called by any other CPU the firmware will abort.

Required CPU state

On entry to the cold boot initialization function the calling primary CPU must be AArch64 EL3, little-endian data access, and all interrupt sources masked:

PSTATE.EL = 3
PSTATE.RW = 1
PSTATE.DAIF = 0xf
CTLR_EL3.EE = 0

X0 and X1 can be used to pass information from the Trusted Boot Firmware to the platform code in BL3-1:

X0 : Reserved for common Trusted Firmware information
X1 : Platform specific information

BL3-1 zero-init sections (e.g. .bss) must not contain valid data on entry, these will be zero filled prior to invoking platform setup code.

Use of the X0 and X1 parameters

The parameters are platform specific and passed from the Cold boot Initialization function to bl31_early_platform_setup().

The convention is that X0 conveys information regarding the BL3-1, BL3-2 and BL3-3 images from the Secure Boot software and X1 can be used for other platform specific purpose. This convention allows platforms which use Trusted Firmware's BL1 and BL2 images to transfer additional platform specific information from Secure Boot without conflicting with future evolution of the Trusted Firmware use of X0.

More details on the use of these parameters and proposed specification for X0 follows below.

Platform specific functionality required during initialization

BL3-1 common initialization code depends on platform specific CPU, MMU and core SoC initialization, which must be provided via bl31 platform APIs.

Platform specific data required during initialization

BL3-1 common and SPD initialization code depends on image, entrypoint and memory information about BL3-3 and BL3-2, which is provided via bl31 platform APIs. This information is required until the start of execution of BL3-3.

This information can be provided in a platform defined manner, e.g. compiled into the platform code in BL3-1, or provided in a platform defined memory location by the Trusted Boot firmware, or passed from the Trusted Boot Firmware via the Cold boot Initialization parameters. This data is not referenced by common or SPD code prior to caches being enabled, however if platform code uses this data with caches disabled, the platform must ensure that the data is flushed into main memory before initializing BL3-1.

MMU & Caches

The common code does not depend on caches and MMU being enabled or disabled on entry to this function. If disabled on entry, these should be enabled during bl31_plat_arch_setup().

Coherency

The coherency status of the CPU and SoC interconnect is platform specific on entry. If not coherent on entry, coherency should be enabled prior to MMU and caches being enabled during bl31_plat_arch_setup().

3. BL3-1 Warm boot Initialization

When requesting a CPU power-on, or suspending a running CPU, Trusted Firmware provides the platform power management code with a Warm boot Initialization entry-point, to be invoked by the CPU immediately after the Reset Handler. On entry to the Warm boot Initialization function the calling CPU must be in AArch64 EL3, little-endian data access and all interrupt sources masked:

PSTATE.EL = 3
PSTATE.RW = 1
PSTATE.DAIF = 0xf
SCTLR_EL3.EE = 0

The PSCI implementation will initialize the processor state and ensure that the platform power management code is then invoked as required to initialize all necessary system, cluster and CPU resources.

4. BL3-1 compatibility with independent Trusted Boot Firmware

Future changes to the BL3-1 interface must be done in a backwards compatible way. This ensures that adoption of updated Trusted Firmware code will not break systems that use alternative Trusted Boot Firmware (e.g. not BL2 from Trusted Firmware), and should allow such Boot firmware to be enhanced/updated to exploit the new functionality independently.

Related Requirements and commentary

Specification: Common data structures

Initialization of BL3-1, and the setup for execution of BL3-2 and BL3-3 requires that information about these images and their entrypoint context (address, mode, parameters, etc) is provided to the common BL3-1 software or to any SPD built into BL3-1. If Trusted Firmware BL2 is being used, this will transfer this information in a structured way to the BL3-1 Cold boot Initialization function in parameter X0.

In order to best support the use of independent Trusted Boot Firmware, but enable each of these data structures to evolve independently in future we should avoid making these structures rigid, and avoid hard-wiring the precise type of the structure into the BL3-1 code.

For example, the initial image information, based on the current .bin images, would just contain a base address and image size. A future extension to that structure to support .elf images could additionally provide the extent of the RAM required or offsets and extents of the important image sections (read-only, read-write, coherent). The BL3-1 code for using this structure should be able to recognize and interpret either the basic .bin info or make use of the extended .elf info.

The proposal is to make these structures typed, versioned and sized - providing flexibility in how these are constructed and then passed between boot loader stages.

/*******************************************************************************
 * The param_header structure provides common fields for the extensible
 * interface to BL31. These are used to allow future evolution of this interface
 * without demanding immediate changes in ports of the firmware.
 ******************************************************************************/

typedef struct {
    uint16_t type_ver;  /* type[15:8]/version[7:0] of this structure */
    uint16_t size;      /* size of this structure in bytes */
    uint32_t attr;      /* attributes: unused bits SBZ */
} param_header;

/*******************************************************************************
 * The entrypoint structure identifies the execution mode, physical PC value,
 * argument parameters (X0-X3), and security state for an image entrypoint.
 *
 * The security state is indicated using bit 0 of the header attributes.
 ******************************************************************************/

typedef struct {
    param_header h;

    uintptr_t pc;       /* entrypoint address */
    uint32_t spsr;      /* entrypoint processor state */
    unsigned long X[4]; /* register value arguments */
} entrypoint_v1;

#define PARAM_EP_V1     0x0101
#define PARAM_EP_NS_MASK    0x1

/*******************************************************************************
 * The image_info structure provides information from the image loader that can
 * be used by the firmware to manage the available trusted RAM. More advanced
 * firmware image formats can provide additional information that enables
 * optimization or greater flexibility in the common firmware code
 ******************************************************************************/

 typedef struct {
    param_header h;

    uintptr_t image_base;   /* physical address of base of image */
    uint32_t image_size;    /* bytes read from image file */
} image_info_binary;

#define PARAM_IMAGE_BINARY  0x0201

/*******************************************************************************
 * This structure represents the super-set of common information that can be
 * passed to BL3-1 during cold boot (e.g. while passing control to it from BL2).
 * If used, a pointer to a structure of this type should be passed in X0 to
 * BL3-1's cold-boot entrypoint.
 * 
 * Use of this structure and the X0 parameter is not mandatory: the BL3-1
 * platform code can use other mechanisms to provide the necessary information
 * about BL3-2 and BL3-3 to the common and SPD code.
 *
 * BL3-1 image information is mandatory if this structure is used. If either of
 * the optional BL3-2 and BL3-3 image information is not provided, this is
 * indicated by the respective image_info pointers being `0`.
 ******************************************************************************/

typedef struct {
    param_header h;

    image_info_binary* bl31_image;
    image_info_binary* bl32_image;
    entrypoint_v1* bl32_ep;
    image_info_binary* bl33_image;
    entrypoint_v1* bl33_ep;
} bl31_param_v1;

#define PARAM_BL31_V1       0x0301

Requirement: BL3-2 and BL3-3 entrypoint setup

The common BL2 code must ensure that platform specific code in BL2 is able to set or update the BL3-3 and BL3-2 entrypoint information after these images have been loaded.

The common BL3-1 code must ensure that the SPD code (if present) is able to set or update the BL3-2 entrypoint information before this is used to execute the image.

It must be possible for all aspects of the entrypoint to be specified: register width, exception level, processing mode, ISA, PC and initial parameters (X0-X3)

Detailed specification of these APIs will be provided later during implementation and added to the porting guide.

Specification: Control transfer from BL2 to BL3-1 via BL1

[This is incompatible with the current SMC convention, which uses registers for the entrypoint context. However, unlike the BL2/BL3-1 interface it is expected that users of BL1 will also be using a matching version of BL2 so this break should have no impact]

If BL1 is being used to transfer control to BL3-1, this implements an SMC call for use by BL2 (or any replacement) which has the following parameters:

Register	Usage
`X0`	`RUN_IMAGE = 0xC0000000` : SMC function number used for the BL2 -> BL1 -> BL3-1 transition
`X1`	physical address of an `entrypoint_v1` structure for BL3-1. This will include the `PC`, `SPSR`, `X0` and `X1` values for the BL3-1 initialization function.

Hi Andrew,

Sorry delayed reply – but thanks for doing this. It looks good and extensible. So as long as we get the processor into the right state the main change to run from our BL2 will be moving from:

(*BL31_image_entry)(RUN_IMAGE, NULL, NULL, &(struct bl31_args from bl_common.h), NULL);

(*BL31_image_entry)(&(struct bl31_param_v1), &(optional plat specific struct));

and of course filling in the different args struct…

All fine, Thanks, James

(trying to email back – may go in GitHub – if not added you to cc)

From: Andrew Thoelke [mailto:notifications@github.com] Sent: 09 April 2014 23:36 To: ARM-software/tf-issues Subject: [tf-issues] RFC: Proposed requirements and specification for BL3-1 initialization (#133)

Entrypoint definitions

Reset Handler

A function residing at the CPU reset vector RVBAR_EL3. The function must be capable of determining the cold/warm boot and primary/secondary status of the CPU, and invoking the appropriate follow on function:

cold-boot initialization on the primary CPU
cold boot 'holding' or power-off on the secondary CPUs
warm boot to a previously configured function on any CPU
1. Cold boot Initialization

A function which must be called exactly once by the primary CPU before any other code in the image is run, excepting a possible Reset Handler described above.

Warm boot Initalization

A function (or functions) that initialize a CPU following a software programmed or interrupt triggered warm power-on. It is assumed that the cold boot initialization is complete.

BL3-1 interface requirements

BL3-1 base address entrypoint

· The BL3-1 base address entrypoint should default to being the BL3-1 Cold boot Initialization function.

· It must be possible for a platform to configure the BL3-1 base address entrypoint to be a Reset Handler.

BL3-1 Cold boot Initialization

This is only called by the primary CPU, if this is called by any other CPU the firmware will abort.

Required CPU state

On entry to the cold boot initialization function the calling primary CPU must be AArch64 EL3, little-endian data access, and all interrupt sources masked:

PSTATE.EL = 3

PSTATE.RW = 1

PSTATE.DAIF = 0xf

CTLR_EL3.EE = 0

X0 and X1 can be used to pass information from the Trusted Boot Firmware to the platform code in BL3-1:

X0 : Reserved for common Trusted Firmware information

X1 : Platform specific information

BL3-1 zero-init sections (e.g. .bss) must not contain valid data on entry, these will be zero filled prior to invoking platform setup code.

Use of the X0 and X1 parameters

The parameters are platform specific and passed from the Cold boot Initialization function to bl31_early_platform_setup().

The convention is that X0 conveys information regarding the BL3-1, BL3-2 and BL3-3 images from the Secure Boot software and X1 can be used for other platform specific purpose. This convention allows platforms which use Trusted Firmware's BL1 and BL2 images to transfer additional platform specific information from Secure Boot without conflicting with future evolution of the Trusted Firmware use of X0.

More details on the use of these parameters and proposed specification for X0 follows below.

Platform specific functionality required during initialization

BL3-1 common initialization code depends on platform specific CPU, MMU and core SoC initialization, which must be provided via bl31 platform APIs.

Platform specific data required during initialization

MMU & Caches

The common code does not depend on caches and MMU being enabled or disabled on entry to this function. If disabled on entry, these should be enabled during bl31_plat_arch_setup().

Coherency

BL3-1 Warm boot Initialization

PSTATE.EL = 3

PSTATE.RW = 1

PSTATE.DAIF = 0xf

SCTLR_EL3.EE = 0

BL3-1 compatibility with independent Trusted Boot Firmware

Related Requirements and commentary Specification: Common data structures

For example, the initial image information, based on the current .bin images, would just contain a base address and image size. A future extension to that structure to support .elf images could additionally provide the extent of the RAM required or offsets and extents of the important image sections (read-only, read-write, coherent). The BL3-1 code for using this structure should be able to recognize and interpret either the basic .bin info or make use of the extended .elf info.

The proposal is to make these structures typed, versioned and sized - providing flexibility in how these are constructed and then passed between boot loader stages.

/***

The param_header structure provides common fields for the extensible
interface to BL31. These are used to allow future evolution of this interface
without demanding immediate changes in ports of the firmware.

**/

typedef struct {

uint16_t type_ver;  /* type[15:8]/version[7:0] of this structure */

uint16_t size;      /* size of this structure in bytes */

uint32_t attr;      /* attributes: unused bits SBZ */

} param_header;

/***

The entrypoint structure identifies the execution mode, physical PC value,
argument parameters (X0-X3), and security state for an image entrypoint.

*
The security state is indicated using bit 0 of the header attributes.

**/

typedef struct {

param_header h;

uintptr_t pc;       /* entrypoint address */

uint32_t spsr;      /* entrypoint processor state */

unsigned long X[4]; /* register value arguments */

} entrypoint_v1;

define PARAM_EP_V1 0x0101

define PARAM_EP_NS_MASK 0x1

/***

The image_info structure provides information from the image loader that can
be used by the firmware to manage the available trusted RAM. More advanced
firmware image formats can provide additional information that enables
optimization or greater flexibility in the common firmware code

**/

typedef struct {

param_header h;

uintptr_t image_base; /* physical address of base of image */

uint32_t image_size; /* bytes read from image file */

} image_info_binary;

define PARAM_IMAGE_BINARY 0x0201

/***

This structure represents the super-set of common information that can be
passed to BL3-1 during cold boot (e.g. while passing control to it from BL2).
If used, a pointer to a structure of this type should be passed in X0 to
BL3-1's cold-boot entrypoint.

*
Use of this structure and the X0 parameter is not mandatory: the BL3-1
platform code can use other mechanisms to provide the necessary information
about BL3-2 and BL3-3 to the common and SPD code.

*
BL3-1 image information is mandatory if this structure is used. If either of
the optional BL3-2 and BL3-3 image information is not provided, this is
indicated by the respective image_info pointers being 0.

**/

typedef struct {

param_header h;

image_info_binary* bl31_image;

image_info_binary* bl32_image;

entrypoint_v1* bl32_ep;

image_info_binary* bl33_image;

entrypoint_v1* bl33_ep;

} bl31_param_v1;

define PARAM_BL31_V1 0x0301

Requirement: BL3-2 and BL3-3 entrypoint setup

The common BL2 code must ensure that platform specific code in BL2 is able to set or update the BL3-3 and BL3-2 entrypoint information after these images have been loaded.

The common BL3-1 code must ensure that the SPD code (if present) is able to set or update the BL3-2 entrypoint information before this is used to execute the image.

It must be possible for all aspects of the entrypoint to be specified: register width, exception level, processing mode, ISA, PC and initial parameters (X0-X3)

Detailed specification of these APIs will be provided later during implementation and added to the porting guide.

Specification: Control transfer from BL2 to BL3-1 via BL1

If BL1 is being used to transfer control to BL3-1, this implements an SMC call for use by BL2 (or any replacement) which has the following parameters: Register

Usage

RUN_IMAGE = 0xC0000000 : SMC function number used for the BL2 -> BL1 -> BL3-1 transition

physical address of an entrypoint_v1 structure for BL3-1. This will include the PC, SPSR, X0 and X1 values for the BL3-1 initialization function.

— Reply to this email directly or view it on GitHubhttps://github.com/ARM-software/tf-issues/issues/133.

ARM-software / tf-issues

RFC: Proposed requirements and specification for BL3-1 initialization #133

Entrypoint definitions

1. Reset Handler

2. Cold boot Initialization

3. Warm boot Initalization

BL3-1 interface requirements

1. BL3-1 base address entrypoint

2. BL3-1 Cold boot Initialization

Required CPU state

Use of the X0 and X1 parameters

Platform specific functionality required during initialization

Platform specific data required during initialization

MMU & Caches

Coherency

3. BL3-1 Warm boot Initialization

4. BL3-1 compatibility with independent Trusted Boot Firmware

Related Requirements and commentary

Specification: Common data structures

Requirement: BL3-2 and BL3-3 entrypoint setup

Specification: Control transfer from BL2 to BL3-1 via BL1

define PARAM_EP_V1 0x0101

define PARAM_EP_NS_MASK 0x1

define PARAM_IMAGE_BINARY 0x0201

define PARAM_BL31_V1 0x0301