Board Configuration¶
Board Configuration in System Firmware¶
There is board configuration data that serves two roles:
- Actual board design choices.
- Application defined boot-time configuration. These are detailed below.
Functional goals¶
Board configuration module enables one time (per boot) configuration of the details of the integration of the SoC onto the board as well as one-time application specific configuration.
Design¶
Board configuration consists of structured configurations that are placed into regular memory by the host software, made coherent (writeback and fences as required by host architecture) then passed to System Firmware via TISCI_MSG_BOARD_CONFIG. On HS devices, the board config blob is signed and encrypted using customer root public key and customer encryption key for HS-SE devices. For HS-FS and GP devices there are no customer keys, therefore board config must be unsigned and plain text. Please refer to Signing Board Configuration on HS devices on how to sign and encrypt board configuration on HS devices.
It is presumed that this memory is owned by trusted software that will not intentionally corrupt the memory while System Firmware is processing. However, System Firmware will take reasonable precautions for misconfiguration by validating data before it is used.
Warning
It is highly recommended that the TISCI_MSG_BOARD_CONFIG_PM message be sent immediately after TISCI_MSG_BOARD_CONFIG before sending other boardcfg messages to ensure RM and SECURITY have all resources configured as needed.
Power management data used to statically define power management configuration is discussed in detail in Power Management Board Configuration.
Resource management board configuration data is detailed in Resource Management Board Configuration. The RM data defines the following for Hosts:
- Resource range assignments
- Order IDs
- Quality of Service (QoS) values
- Priority values
- Host hierarchy
Security data used to statically define security configuration is discussed in detail in Security Management Board Configuration.
Compile Time Configuration¶
| Define | Type | Description |
|---|---|---|
| BOARDCFG_MAX_MAIN_HOST_COUNT | (u16) | Maximum number of different processing entities for main, scales all main boardcfg tables. This is the number of simutaneous host id permitted after compacting the holes. Thus, as an example, in soc_doc_am6_public_host_desc_host_list, it is ((u16)18u). |
| BOARDCFG_MAX_MCU_HOST_COUNT | (u16) | Maximum number of different processing entities for MCU, scales all MCU boardcfg tables. This is the number of simutaneous host id permitted after compacting the holes. In the example soc_doc_am6_public_host_desc_host_list, it could be up to ((u16)18u) to allow all processing entities to use dedicated resources in MCU. |
TISCI API for Board Config¶
The following are the parameters required in the TI-SCI message to pass board configuration data to System Firmware after System Firmware sends boot notification complete.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | Yes |
TISCI Message ID¶
TISCI_MSG_BOARD_CONFIG (0x000BU)
Message Data Structures¶
struct tisci_msg_board_config_req
TISCI_MSG_BOARD_CONFIG request to provide the location and size of the boardcfg structure.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| boardcfgp_low | u32 | Low 32-bits of physical pointer to boardcfg struct. |
| boardcfgp_high | u32 | High 32-bits of physical pointer to boardcfg struct. |
| boardcfg_size | u16 | Size of configuration data. |
| boardcfg_devgrp | devgrp_t | Device group for the base board configuration. |
struct tisci_msg_board_config_resp
Empty response for TISCI_MSG_BOARD_CONFIG.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header. |
Although this message is essentially empty and contains only a header a full data structure is created for consistency in implementation.
Warning
The boardcfg data structures described below must be placed in MCU OCMC SRAM. The address used in the TISCI message will be in MCU OCMC SRAM.
Warning
Please ensure that MSMC is not being accessed when TISCI_MSG_BOARD_CONFIG
is sent. System Firmware reconfigures the MSMC firewall on receiving this message.
MSMC needs to be inactive for the firewall reconfiguration to succeed.
ABI revision structure¶
This design requires that both boardcfg_abi_maj and boardcfg_abi_min exactly match what is expected by System Firmware.
| Element | Type | Description |
|---|---|---|
| boardcfg_abi_maj | u8 | Major ABI version (for boardcfg_cfg version, not overall System Firmware version) |
| boardcfg_abi_min | u8 | Minor ABI version (for boardcfg_cfg version, not overall System Firmware version) |
Configuration substructure enumeration¶
This is a fixed size c-structure which defines the format of the configuration.
| Element | Type | Description |
|---|---|---|
| boardcfg_abi_rev | struct boardcfg_abi_rev | Board Config ABI version (separate from System Firmware ABI version) |
| control | struct boardcfg_control | System Firmware feature control selections |
| secproxy | struct boardcfg_secproxy | Secure proxy configuration |
| msmc | struct boardcfg_msmc | MSMC configuration |
| debug_cfg | struct boardcfg_dbg_cfg | Debug/trace configuration |
boardcfg substructure header¶
This contains a unique magic number for each substructure and the size of the associated superstructure for data validation/API compatibility checks.
| Element | Type | Description |
|---|---|---|
| magic | u16 | unique magic number for data integrity check matching boardcfg substructure header magic numbers |
| size | u16 | sizeof(superstructure containing this header) for data integrity check |
boardcfg substructure header magic numbers¶
A unique magic number must be provided for each of the boardcfg
structures listed below. The exact value must be used in the
magic field of boardcfg substructure header or the boardcfg
data will be rejected.
| Boardcfg Structure | Macro Name | Value |
|---|---|---|
| boardcfg_control structure | BOARDCFG_CONTROL_MAGIC_NUM | 0xC1D3U |
| boardcfg_secproxy structure | BOARDCFG_SECPROXY_MAGIC_NUM | 0x1207U |
| Design for boardcfg_msmc | BOARDCFG_MSMC_MAGIC_NUM | 0xA5C3U |
| Processor Access List | BOARDCFG_PROC_ACL_MAGIC_NUM | 0xF1EAU |
| Host Hierarchy | BOARDCFG_HOST_HIERARCHY_MAGIC_NUM | 0x8D27U |
| boardcfg_dbg_cfg | BOARDCFG_DBG_CFG_MAGIC_NUM | 0x020CU |
| Extended OTP array configuration | BOARDCFG_OTP_CFG_MAGIC_NUM | 0x4081U |
| boardcfg_rm_host_cfg structure | BOARDCFG_RM_HOST_CFG_MAGIC_NUM | 0x4C41U |
| boardcfg_rm_resasg structure | BOARDCFG_RM_RESASG_MAGIC_NUM | 0x7B25U |
| Derived KEK Management | BOARDCFG_DKEK_CFG_MAGIC_NUM | 0x5170U |
boardcfg_control structure¶
The boardcfg_control structure is used to enable/disable features in System Firmware based on usecase.
| Element | Type | Description |
|---|---|---|
| subhdr | struct boardcfg_subhdr | Magic and size for integrity check |
| main_isolation_enable | ftbool | Enable/disable support for System Firmware main isolation. If disabled, main isolation SCI message will be rejected with NAK. |
| main_isolation_hostid | u16 | Host-ID allowed to send SCI-message for main isolation. If mismatch, SCI message will be rejected with NAK. |
boardcfg_secproxy structure¶
| Element | Type | Description |
|---|---|---|
| subhdr | struct boardcfg_subhdr | Magic and size for integrity check |
| scaling_factor | u8 | Memory allocation for messages scaling factor. In current design, only value of “1” is supported. For future design, a value of “2” would double all memory allocations and credits, “3” would triple, and so on. |
| scaling_profile | u8 | Memory allocation for messages profile number. In current design, only a value of “1” is supported. “0” is always invalid due to fault tolerance. |
| disable_main_nav_secure_proxy | u8 | Do not configure main nav secure proxy. This removes all MSMC memory demands from System Firmware but limits MPU channels to one set of secure and one set of insecure. In current design, supports only “0”. |
Note
disable_main_nav_secure_proxy paramter is not used in the current System Firmware.
Design for boardcfg_msmc¶
Cache must be configured by System Firmware in order for MSMC to be used for main secure proxy backing memory and ring memory.
boardcfg_msmc structure¶
| Element | Type | Description |
|---|---|---|
| subhdr | struct boardcfg_subhdr | Magic and size for integrity check |
| msmc_cache_size | u8 | fraction of msmc to be cache in /32 units. Rounds up. Since current msmc support /8 allocation this means that 1/32 rounds up to 1/8. |
Design details for System Firmware Debug Console¶
One value is provided to specific the debug console from the following options specified as bits (so all, some, or none can be enabled)
boardcfg_dbg_dst_ports¶
| Bit | Value | Definition |
|---|---|---|
| TRACE_DST_UART0 | 0x0001 | Traces to UART enabled |
| TRACE_DST_ITM | 0x0004 | Traces to ITM (JTAG) enabled |
| TRACE_DST_MEM | 0x0008 | Traces to memory buffer enabled |
For information on UART instance used for a specific SoC refer to Trace UART Allocation
boardcfg_dbg_src¶
| Bit | Value | Definition |
|---|---|---|
| TRACE_SRC_PM | 0x0001 | Traces from power management are allowed |
| TRACE_SRC_RM | 0x0002 | Traces from resource management are allowed |
| TRACE_SRC_SEC | 0x0004 | Traces from security management are allowed |
| TRACE_SRC_BASE | 0x0008 | Traces from baseport are allowed |
| TRACE_SRC_USER | 0x0010 | Traces from user tasks are allowed |
| TRACE_SRC_SUPR | 0x0020 | Traces from supervisor tasks are allowed |
boardcfg_dbg_cfg¶
| Field | Type | Description |
|---|---|---|
| subhdr | struct boardcfg_subhdr | Magic and size for integrity check |
| trace_dst_enables | u16 | Each bit from TRACE_DST in struct boardcfg_dbg_dst_ports. Using u16 to allow 2 bits per value for fault tolerance |
| trace_src_enables | u16 | Each bit from TRACE_SRC in struct boardcfg_dbg_src. Using u16 to allow 2 bits per value for fault tolerance |