Processor Boot Management TISCI Description

Introduction

This chapter provides information about the messaging APIs for the processor boot control. APIs are divided into the following two sets:

  • Book keeping APIs - Meant to control access to allow a reasonable usage scenario of processors.
  • Processor Control APIs - Meant to be the actual Processor Core controls.

Book Keeping APIs:

TISCI Message ID Message Name
0xC000 TISCI_MSG_PROC_REQUEST.
0xC001 TISCI_MSG_PROC_RELEASE.
0xC005 TISCI_MSG_PROC_HANDOVER.

Processor Control APIs:

TISCI Message ID Message Name
0xC100 TISCI_MSG_PROC_SET_CONFIG
0xC101 TISCI_MSG_PROC_SET_CONTROL
0xC120 TISCI_MSG_PROC_AUTH_BOOT
0xC400 TISCI_MSG_PROC_GET_STATUS
0xC401 TISCI_MSG_PROC_WAIT_STATUS

The APIs use the overall concepts explained in the following sections.

ID definition

To help identify the various entities invovled, the following IDs are involved:

  • HOST_ID is the concept of identifying processing entities (SoC specific)
  • PROC_ID is the specific hardware processor instance involved (SoC specific)

Access control definition

Access control is enforced via the Book keeping APIs. The basic definition of access is as follows:

  • We identify a requester (just like rest of TISCI) using Host ID (or plain Host).
  • By default, we permit all processors to be controlled by any other Host (no policing).
  • Board configuration provides: per PROC_ID, a limited list of “permitted host IDs” which are permitted to control a processor. BUT with the following conditions:
    • Only one host can control a processor at a time
    • A host(with control) can hand over control of a processor to another host in the permitted list.
    • “recovery master” host id is identified in board cfg and this host can override the ownership already established.

In addition, ONLY a secure host can request for an authenticated image access.

API access control will be as follows:

  • request_processor: Only one host can get control from access list. However, “recovery master” host can override previously allocated master.
  • handover_processor: Only the host with current control of the processor.
  • release_processor: Only the host with current control of the processor.
  • set_processor_config: Only the host with current control of the processor.
  • get_processor_config: Any host within the access control list.
  • set_processor_control: Only the host with current control of the processor.
  • get_processor_control: Any host within the access control list.
  • authenticate_and_start_image: Only a secure host with current control of the processor.
  • set_processor_suspend_ready: Only the host with current control of processor can report that the processor is ready to suspend
  • get_processor_wake_reason: Any host within the access control list.

Sequencing of APIs

The boot APIs must be used in correct sequence with the device and clock APIs to be operational. This sequence would be specific to the processor involved.

Rationale: by encoding the sequence of processor boot along with boot configuration API will complicate management of processors, since the operational requirements are extremely varied. Some processors need the boot configuration done, clocked, and specific MMU/RAT configuration be done prior to be released from reset. Many of the operations may require interaction with specific processor internals that is hard to make generic and usecase independent.

Example usage of APIs

Example 1: Boot a processor from one core and let it self manage:

  1. Boot host: (optionally) PM apis to control clock and hold processor in reset. This might be necessary for some processors to get the boot vector registers to be accessible in the first place.
  2. Boot host: request_processor
  3. Boot host: set_processor_config -> set bootvector
  4. Alternatively call authenticate and start image API.
  5. Boot host: handover_processor -> give control to ‘processor host’
  6. Boot host: PM apis to control clock and release processor from reset. ‘processor host’ gets active. It is probably better to release the processor from reset after handover, in case the ‘processor host’ tries to do additional operations. however this depends on usecase - use a sane judgement as to how to sequence the APIs.
  7. Processor host: (continues to boot and do other TISCI APIs permitted)
  8. Processor host: set_processor_suspend_ready -> ready to suspend
  9. Processor WFI Wakeup:
  10. Processor host: get_processor_wake_reason -> get reason for wakeup. …. until all operations are complete…
  11. Processor host: set_processor_suspend_ready -> state it is going down
  12. Processor host: release_processor -> Mark no longer required
  13. Processor WFI (NOTE: a processor cannot switch off it’s own clocks -> so in case of a self managed processor shutdown sequence, it will need System firmware to help do the last stages of operation - typically this will involve either shutdown OR reset sequence).

Example 2: Boot a processor from one core and recover from another core:

  1. Boot host: request_processor
  2. Boot host: set_processor_config -> set bootvector
  3. Boot host: handover_processor -> give control to ‘processor host’
  4. Boot host: PM apis to control clock and release processor boot host dies
  5. Recovery Host: request_processor
  6. Recovery Host: set_processor_config -> force power off
  7. Recovery Host: PM apis to control clock and force power off of processor
  8. Recovery Host: Additional cleanup API calls …. Restoration sequence….

Processor Boot API Description

This Section goes into details on the various APIs involved for processor control

Note

Reference Chapter 5: SoC Family Specific Documentation to see Host IDs and Processor IDs for your SoC.

Book Keeping APIs

These are the top level APIs that provide access control knobs for processor operation APIs to be valid.

TISCI_MSG_PROC_REQUEST - Request Processor

Usage:

Message Type Normal
Secure Queue Only? No

TISCI Message ID

TISCI_MSG_PROC_REQUEST          (0xC000U)

Message to get a Processor

struct tisci_msg_proc_request_req

Request for physical processor control request

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.
processor_id u8 Specifies a Processor ID. See the SoC Family Specific Documentation Chapter of the TISCI User Guide for accepted values.

Provides a means for either the “recovery master” host or another host in the permitted access list to request for a physical processor control.

struct tisci_msg_proc_request_resp

Request for physical processor control response

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.

Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation. ACK response: The processor access is permitted for the host if processor is un-claimed AND host is permitted to control the processor OR if the host is the recovery master. NAK response: The processor access is not permitted.

TISCI_MSG_PROC_RELEASE - Release Processor

Usage:

Message Type Normal
Secure Queue Only? No

TISCI Message ID

TISCI_MSG_PROC_RELEASE          (0xC001U)

Message to release a Processor

struct tisci_msg_proc_release_req

Release physical processor control request

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.
processor_id u8 ID of processor to release.

Provides a means for the host with current control to relinquish a physical processor control.

struct tisci_msg_proc_release_resp

Release physical processor control response

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.

Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation. ACK Response: The host had control over the processor and is confirmed to be released to “free pool”. NAK Response: The processor access is not permitted.

TISCI_MSG_PROC_HANDOVER - Handover Processor

Usage:

Message Type Normal
Secure Queue Only? No

TISCI Message ID

TISCI_MSG_PROC_HANDOVER          (0xC005U)

Message to handover a Processor

struct tisci_msg_proc_handover_req

Request to handover control of a processor to another host if permitted.

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.
processor_id u8 Specifies a Processor ID.
host_id u8 Specifies the new host to hand over control to.

Provides a means for the host with current control to relinquish a physical processor control to another host in the permitted list.

struct tisci_msg_proc_handover_resp

Response to handover of control of a processor to another host if permitted.

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.

Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation. ACK Response: The host had control over the processor and is confirmed to be released to “free pool”. NAK Response: The processor access is not permitted.

Processor Control APIs

These are granular control APIs for control of the processor state themselves. These APIs need to be used in conjunction with standard Power Management APIs.

Note

Not all APIs are supported for all processors. See Processor Specific Flags for core specific flags (implies the applicable APIs are valid for that type of core).

TISCI_MSG_PROC_SET_CONFIG - Set Processor Configuration

Purpose: Provides a means for the host with current control to do the base configuration of the processor.

Usage:

Message Type Normal
Secure Queue Only? No

TISCI Message ID

TISCI_MSG_PROC_SET_CONFIG          (0xC100U)

Message to Set the processor configuration

struct tisci_msg_proc_set_config_req

Processor Boot Configuration

Parameter Type Description
hdr struct tisci_header Message header
processor_id u8 ID of processor
bootvector_lo u32 Lower 32bit (Little Endian) of boot vector
bootvector_hi u32 Higher 32bit (Little Endian) of boot vector
config_flags_1_set u32 Optional Processor specific Config Flags to set. Setting a bit here implies required bit has to be set to 1.
config_flags_1_clear u32 Optional Processor specific Config Flags to clear. Setting a bit here implies required bit has to be cleared to 0.

Note

Boot vector address and config are processor specific configurations. This may be done in separate invocations as required in processor specific startup sequence.

Note

Note bits 6:0 of the R5F Vector Table address are always 0. The TISCI message will return failure if the bits 6:0 of the bootvector_lo are non-zero. Refer the section on CTRLMMR_*_BOOTVECT_LO for the R5F in the TRM.

struct tisci_msg_proc_set_config_resp

Response to Processor Boot Configuration message.

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.

Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation. ACK Response: The host had control over the processor and requested operation is successful NAK Response: The processor access is not permitted or the operation failed.

Attention

Reason for failure is NOT provided to prevent security attacks by scan. If permitted, System firmware logs shall provide relevant failure information.

TISCI_MSG_PROC_SET_CONTROL - Set Processor Control Flags

Purpose: Provides a means for the host with current control to setup limited control flags in specific cases.

Usage:

Message Type Normal
Secure Queue Only? No

TISCI Message ID

TISCI_MSG_PROC_SET_CONTROL          (0xC101U)

Message to Set the processor control

struct tisci_msg_proc_set_control_req

Optional processor specific message for sequence control

Parameter Type Description
hdr struct tisci_header Message header
processor_id u8 ID of processor
control_flags_1_set u32 Optional Processor specific Control Flags to set. Setting a bit here implies required bit has to be set to 1.
control_flags_1_clear u32 Optional Processor specific Control Flags to clear. Setting a bit here implies required bit has to be cleared to 0.

struct tisci_msg_proc_set_control_resp

Response to optional processor specific message for sequence control

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.

Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation. ACK Response: The host had control over the processor and requested operation is successful NAK Response: The processor access is not permitted or the operation failed.

Attention

Reason for failure is NOT provided to prevent security attacks by scan. If permitted, System firmware logs shall provide relevant failure information.

TISCI_MSG_PROC_AUTH_BOOT - Authenticate Image and Configure Processor

Purpose: Provides a means for the host with current control to do the following:

  • Authenticate and load a binary using the certificate provided information
  • Use certificate information also to setup critical processor specific flags which is similar to Set Processor Configuration.

Usage:

Message Type Normal
Secure Queue Only? No

TISCI Message ID

TISCI_MSG_PROC_AUTH_BOOT          (0xC120U)

Message to do authenticated boot configuration of a processor

struct tisci_msg_proc_auth_boot_req

Authenticate and start image

Parameter Type Description
hdr struct tisci_header Message header
certificate_address_lo u32 Lower 32bit (Little Endian) of certificate
certificate_address_hi u32 Higher 32bit (Little Endian) of certificate

Attention

  • The certificate itself shall contain relevant information about the processor flags and configuration information.
  • ONLY secure hosts are permitted to invoke this API in addition to being part of the access control list.
  • See Hosts description for the corresponding SoC to identify which hosts are secure and which are not.

Attention

Please see Security X509 Certificate Documentation for certificate format.

struct tisci_msg_proc_auth_boot_resp

Response to authenticate and start image request

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.
image_address_lo u32 Lower 32bit (Little Endian) of image
image_address_hi u32 Higher 32bit (Little Endian) of image
image_size u32 Size of the binary

ACK Response: The host had control over the processor and requested operation is successful NAK Response: The processor access is not permitted or the operation failed. IMPORTANT: Reason for failure is NOT provided to prevent security attacks by scan. If permitted, System firmware logs shall provide relevant failure information.

Attention

Reason for failure is NOT provided to prevent security attacks by scan. If permitted, System firmware logs shall provide relevant failure information.

TISCI_MSG_PROC_GET_STATUS - Get Processor Status

Purpose: Provides a means for hosts in the permitted list to get the status of a physical processor. This is required for the hosts to sequence events in the correct order

Usage:

Message Type Normal
Secure Queue Only? No

TISCI Message ID

TISCI_MSG_PROC_GET_STATUS          (0xC400U)

Message to Get the processor status

struct tisci_msg_proc_get_status_req

Processor Status request

Parameter Type Description
hdr struct tisci_header Message header
processor_id u8 ID of processor

struct tisci_msg_proc_get_status_resp

Processor Status Response

Parameter Type Description
hdr struct tisci_header Message header
processor_id u8 ID of processor
bootvector_lo u32 Lower 32bit (Little Endian) of boot vector
bootvector_hi u32 Higher 32bit (Little Endian) of boot vector
config_flags_1 u32 Optional Processor specific Config Flags set
control_flags_1 u32 Optional Processor specific Control Flags set
status_flags_1 u32 Optional Processor specific Status Flags set

ACK Response: The host had control over the processor and requested operation is successful NAK Response: The processor access is not permitted or the operation failed. IMPORTANT: Reason for failure is NOT provided to prevent security attacks by scan. If permitted, System firmware logs shall provide relevant failure information.

Attention

Reason for failure is NOT provided to prevent security attacks by scan. If permitted, System firmware logs shall provide relevant failure information.

TISCI_MSG_PROC_WAIT_STATUS - Wait for Processor Status

Purpose: Provides a means for hosts in the permitted list to wait for the status of a physical processor.

Warning

This API that has impact on firmware performance and is typically only required for the hosts to sequence events in the correct order when executing from the processor itself. In short, avoid if possible.

The worst case delay could be upto: (register operations and code overheads) + num_wait_iterations(255) * delay_per_iteration_us(255) + delay_before_iteration_loop_start_us (255) = 65.280 milli seconds + (register operations and code overheads)

Usage:

Message Type Normal
Secure Queue Only? No

TISCI Message ID

TISCI_MSG_PROC_WAIT_STATUS          (0xC401U)

Message to Wait for processor status

struct tisci_msg_proc_status_wait_req

Processor Status Wait

Parameter Type Description
hdr struct tisci_header Message header
processor_id u8 ID of processor
num_wait_iterations u8 1-255, Total number of iterations we will check before we will timeout and give up
num_match_iterations u8 1-255, How many iterations should we have continued status to account for status bits glitching. This is to make sure that match occurs for consecutive checks. This implies that the worst case should consider that the stable time should at the worst be num_wait_iterations num_match_iterations to prevent timeout.
delay_per_iteration_us u8 0-255, Specifies how long to wait (in micro seconds) between each status checks. This is the minimum duration, and overhead of register reads and checks are on top of this and can vary based on varied conditions.
delay_before_iteration_loop_start_us u8 0-255, Specifies how long to wait (in micro seconds) before the very first check in the first iteration of status check loop. This is the minimum duration, and overhead of register reads and checks are
status_flags_1_set_all_wait u32 If non-zero, Specifies that all bits of the status matching this field requested MUST be ‘1’.
status_flags_1_set_any_wait u32 If non-zero, Specifies that at least one of the bits matching this field requested MUST be ‘1’.
status_flags_1_clr_all_wait u32 If non-zero, Specifies that all bits of the status matching this field requested MUST be ‘0’.
status_flags_1_clr_any_wait u32 If non-zero, Specifies that at least one of the bits matching this field requested MUST be ‘0’.

struct tisci_msg_proc_status_wait_resp

Processor Status Wait Response

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.

Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation. ACK Response: The status requested was achieved within the constraints provided in request. NAK Response: The processor access is not permitted or operation failed or timedout.

Warning

At least one of status_flags_1_set_all_wait, status_flags_1_set_any_wait, status_flags_1_clr_all_wait or status_flags_1_clr_any_wait must be requested.

Flags and sequences desired are very specific to processor and SoC involved. Please refer to appropriate documentation for accurate sequencing and status information.

Note

A trivial example for a hypothetical processor status wait could have the parameters as follows:

# No optional bits to be set
status_flags_1_set_all_wait = 0

# Either WFI OR WFE to be set as 1
status_flags_1_set_any_wait = WFI | WFE

# CLK_STOP must be to be cleared
status_flags_1_clr_all_wait = CLK_STOP

# No optional status bits to be cleared
status_flags_1_clr_any_wait = 0

# Check status every ~2 us
delay_per_iteration_us = 2

# Do not wait to start checks
delay_before_iteration_loop_start_us = 0

# Check for 10 times before timing out
num_wait_iterations = 10

# Must match at least for 2 consecutive iterations
num_match_iterations = 2

Attention

Reason for failure is NOT provided to prevent security attacks by scan. If permitted, System firmware logs shall provide relevant failure information.

Generic Processor Flags

  • config_flags_1 Field Reserved for Generic usage
Flag Name Bit Offset Description
GEN_IGN_BOOTVECTOR 28 Valid only for config_flags_1_clear Flag indicating that SYSFW should not use the bootvector_lo and bootvector_hi fields in the tisci_msg_proc_set_config_req structure.

Processor Specific Flags

This section lists the flags that are specific to each processor types. These flags apply to the processor control APIs.

Note

The System Firmware does not modify the silicon defaults unless the specific message to update the processor config/control flags is received.

ARMV8

  • config_flags_1 Fields
Flag Name Bit Offset Description
DBG_EN 0 invasive Debug
DBG_NIDEN 1 Non-invasive Debug
DBG_SPIDEN 2 Secure invasive Debug
DBG_SPNIDEN 3 Secure Non-invasive Debug
ARCH32 8 32bit mode (if disabled, implies 64 bit mode)
  • control_flags_1 Fields:
Flag Name Bit Offset Description
ACINACTM 0 Snoop coherency interface state
AINACTS 1 ACP interface state
L2FLUSHREQ 8 SoC level L2 Flush Request - See L2FLUSH_DONE status for completion

Note

Please refer to SoC Technical Reference Manual and ARM Technical Reference for information on sequencing required for startup and shutdown of CPUs in a cluster. Applying these flags to any CPU in a cluster affects the corresponding cluster.

  • status_flags_1 Fields
Flag Name Bit Offset Description
WFE 0 Set if the core is in WFE state
WFI 1 Set if the core is in WFI state
L2FLUSH_DONE 4 Set if the cluster’s L2 flush done is complete
STANDBYWFIL2 5 Set if the cluster’s L2 WFI is achieved

ARM R5

  • config_flags_1 Fields
Flag Name Bit Offset Description
DBG_EN 0 invasive Debug
DBG_NIDEN 1 Non-invasive Debug
LOCKSTEP 8 On Write - Enable Lockstep (if permitted) - (1: Lockstep enabled, 0 - Lockstep disabled). On Read - Core Status - (1: Core in lockstep mode, 0 - Core in split mode)
TE_INIT 9 Exception handling state at reset (0 - ARM, 1 - Thumb)
NMFI_EN 10 Enable Core Non-Maskable Fast Interrupts
TCM_RSTBASE 11 Core A/BTCM Reset Base address Indicator (0 - BTCM located at address 0x0, 1 - ATCM located at address 0x0)
BTCM_EN 12 Enable Core BTCM RAM at reset
ATCM_EN 13 Enable Core ATCM RAM at reset
MEM_INIT_DIS 14 Disables SRAM initialization (TCM, etc) at reset. (Not available on all devices. Please read TRM before trying to set this field.) (TRM Section to be referred to is: Chapter 5 (“Device Configuration”) -> Section 5.1 (“5.1 Control Module (CTRL_MMR)”) -> CTRLMMR_SEC_CLSTRx_CFG Register)
SINGLE_CORE 15 Single / Dual CPU Mode CLSTR_CFG Value 0 = Both CPUs are enabled, 1 = CPU1 Core is disabled (Not available on all devices. Please read TRM before trying to set this field.) (TRM Section to be referred to is: Chapter 5 (“Device Configuration”) -> Section 5.1 (“5.1 Control Module (CTRL_MMR)”) -> CTRLMMR_SEC_CLSTRx_CFG Register)
  • control_flags_1 Fields
Flag Name Bit Offset Description
CORE_HALT 0 Halt Core
R5_LPSC 1 Command for R5F LPSC Control (1 - LPSC ON, 0 - LPSC OFF) Reads will always return 0. You are expected to read the PM status via the PM message TISCI_MSG_GET_DEVICE This particular control is applicable only for J721E and J7200 devices (MCU_R5 only). This is done because the MCU R5F is running PM and RM and the MCU R5F cannot control its owner power down and power up.
R5 RESET 2 R5F Reset control command (1- Assert Reset, 0 - Deassert Reset) This particular control is applicable only for J721E and J7200 devices (MCU_R5 only). This is done because the MCU R5F is running PM and RM and the MCU R5F cannot control its owner power down and power up.

The usage of R5_LPSC and R5_RESET is only for the MCU R5F. On the J721E and J7200 family of devices the RM and PM functions run on the MCU R5F. The MCU R5F cannot turn off and on its own self during a re-boot sequence which requires the following fundamental sequence of steps:

  1. Wait for the R5F to hit WFI. (MCU at this point is running WFI and cannot run steps 2 and 3)
  2. Power off the R5F by writing to PSC registers.
  3. Power on the R5F by writing to PSC registers.

In order to handle this the TIFS provides a special function for handling the LPSC control only for MCU R5F core 0 and core 1 which can enable performing the sequence of powering down and powering up the MCU R5Fs once the MCU R5F hits WFI.

Similar to the LPSC control for power off and power on, the TIFS also controls the reset control for R5F LPSC reset controls as the MCU R5F cannot handle its own resets.

For all other devices in the SoC the MCU R5F handles the LPSC configuration. For the devices like AM6 the TIFS, Power Management and Resource management run on the DMSC. Hence these controls are not applicable to these devices.

  • status_flags_1 Fields
Flag Name Bit Offset Description
WFE 0 Set if the core is in WFE state
WFI 1 Set if the core is in WFI state
CLK_GATED 2 Core Clock Stopped due to WFI or WFE state
LOCKSTEP_PERMITTED 8 Is Lockstep configuration permitted - 1: yes, 0 - no
SINGLECORE_ONLY 9 Is Single Core only configuration enabled - 1: yes, 0 - no

C7x DSP

  • config_flags_1 Fields
Flag Name Bit Offset Description
L2_PIPELINE_LATENCY_VALUE 0-3 Set C7x Corepac L2 Pipeline latency. valid values: 1 to 5
L2_ACCESS_LATENCY_VALUE 4-7 Set C7x Corepac L2 Access latency. valid values: 2 to 5
  • control_flags_1 Fields

Not supported.

  • status_flags_1 Fields
Flag Name Bit Offset Description
WFE 0 Set if the core is in WFE state
WFI 1 Set if the core is in WFI state

C6x DSP

  • config_flags_1 Fields
Flag Name Bit Offset Description
SSCLK_MODE_DIV_CLK_MODE_VALUE 0-2 Controls the C66 clock rate for cluster logic and bus interfaces. (See warning note below) 0x1 - Div2 clock mode. 0x2 - Div3 clock mode. 0x3 - Div4 clock mode.

Warning

NOTE: Values of SSCLK_MODE_DIV_CLK_MODE_VALUE are TRM value + 1 for avoiding ‘0’ as a valid value which cannot be distinguished from values we are not attempting to set

  • control_flags_1 Fields

Not supported.

  • status_flags_1 Fields

Not supported.

ARM M4F

Warning

NOTE: M4F always starts from 0x0 from internal TCM RAM. There is no specific bootvector configuration possible. We need to request the device with reset enabled and load the TCM RAM prior to releasing the reset to allow the processor to execute.

  • config_flags_1 Fields
Flag Name Bit Offset Description
DBG_EN 0 invasive Debug
DBG_NIDEN 1 Non-invasive Debug
  • control_flags_1 Fields

Not supported.

  • status_flags_1 Fields
Flag Name Bit Offset Description
WFI 1 Set if the core is in WFI state