Resource Management Board Configuration¶
Static Resource Management Configuration in System Firmware¶
The host configuration attributes portion of the RM board configuration statically defines the allowed values for:
- Order IDs
- QoS levels
- Bus priorities
- Scheduling priorities
- Atype
Allowed values are defined for each host ID supported.
Applications are able to query DMSC for the allowed values assigned to hosts for runtime discovery of a host’s attributes.
The resource assignment portion of the RM board configuration statically defines usage of resource ranges for use by all SoC hosts. The resource management subsystem references the resource assignment board configuration for all resource configuration requests.
Applications are able to query DMSC for the resource ranges assigned to hosts allowing runtime discovery of assigned resources.
Please see Board Configuration for information on the overall Board Configuration design.
Warning
This message MUST be sent in order to initialize the Resource Management capabilities of system firmware. Until it is received no Resource Management services are available.
Warning
The Resource Management board configuration message is rejected if resource assignment data is not sent and does not conform to the resource assignment validation guidelines. Please see Resource Assignment Validation for a description of the resource assignment data validation guidelines.
Warning
There are limitations when using HOST_ID_ALL as the owner of a resource range assignment. Please see Static Resource Assignment Configurations for a description on the use cases and limitations behind different resource range configurations.
Functional goals¶
Resource Management board configuration gates operation of the RM subsystem until reception by DMSC and enables one time (per boot) configuration of SoC host attributes and assignment of managed SoC resources amongst SoC hosts.
Design¶
A standalone RM board configuration message initializes the RM subsystem and contains the host configuration attributes and the resource assignment data. The RM subsystem is not considered functional until after the RM board configuration message is received by DMSC. The RM board configuration data can be sent any time after the standard boardcfg message, Configuration substructure enumeration is received. The RM board configuration message can only be sent once. RM board configuration messages received after the first are NACK’d.
The separation of boardcfg reception and subsystem startup is to reduce DMSC boot time. The resource management data is 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_RM. On HS devices, the board config blob is signed and encrypted using customer root public key and customer encryption key for HS-SE or HS-Prime. For HS-FS and GP devices there are no customer keys, therefore board config must be unsigned and plain text.
The resource management data is provided separately to reduce DMSC boot time. The resource management board cfg message is sent any time after the boot notification message is sent and has no dependence upon reception of the standard board configuration message, TISCI_MSG_BOARD_CONFIG.
The RM board configuration contains host configuration data. The host configuration data format is described by boardcfg_rm_host_cfg structure.
RM board configuration contains static assignments of resources to hosts via the resource assignment data. The resource assignment data format is described by boardcfg_rm_resasg structure which defines a variable length array at the end of the RM board cfg data structure. Users must append a fixed length array to the end boardcfg_rm structure to represent the resource assignment data array. The resource assignment array is a list of boardcfg_rm_resasg_entry (resource assignment) structure elements. The final goal is for the maximum number of elements receivable by DMSC RM to be the number of hosts times the number of unique resources in the SoC. The current size is 2 times the number of unique resources in the SoC. Resource assignment lists sized greater than this will have the RM boardcfg message NACK’d.
The RM board configuration data is sorted and indexed upon reception for faster runtime access. The sort increases the response time of DMSC to the RM board configuration TISCI message. To improve the response time to the RM board configuration TISCI message the RM board configuration resource assignment array can be pre-sorted. The pre-sorted array must be in ascending resource type order. Then within each resource type the entries must be sorted in ascending start_resource value order.
Assigned resource ranges are retrievable at runtime by sending System Firmware a request via TISCI_MSG_RM_GET_RESOURCE_RANGE. The specified resource type’s range is returned for the host who sent the request.
Static Resource Assignment Configurations¶
The RM board configuration static resource assignment functionality supports the following range assignment configurations.
Single owner assignments (Most common use case, recommended configuration whenever possible):
- Every SoC host ID can be assigned no more than one resource range per resource type. At DMSC init, firewalls are configured to allow host IDs access to all resource ranges they’ve been assigned. The RM subsystem cannot guarantee resource range query response and resource configuration for ranges defined beyond the first for a host ID.
Dual owner assignments (Niche use case when two hosts require access and configuration rights to a resource):
An overlap between two resource ranges can be defined for two host IDs. Resource firewalls allow up to two unique hosts to access a resource. Overlapping ranges between host IDs allows both host IDs to configure non-real-time registers and access the real-time registers.
The RM boardcfg TISCI message is NACK’d if an overlap of more than two range definitions per resource type is detected.
Open access assignments (Extremely niche use cases where all hosts require access and configuration rights to a resource):
- The HOST_ID_ALL host ID can be used to assign a range of resources for use by all host IDs. In this case, the firewall is configured to allow all hosts to access a resource. This feature must be used judiciously, only for resources that must be shared by more than two host IDs. Management of resources within a range assigned to HOST_ID_ALL is performed by the user application.
- A resource range assigned to HOST_ID_ALL cannot overlap with another resource range. The RM boardcfg TISCI message is NACK’d if an overlap with a range assigned to HOST_ID_ALL is detected.
- Populate the secondary_host parameter of the tisci_msg_rm_get_resource_range_req TISCI message API with HOST_ID_ALL in order to retrieve the range assigned to HOST_ID_ALL for a resource type.
Resource Assignment Validation¶
The resource assignment data received through the RM boardcfg message is validated. The resource data is validated to prevent RM resource assignment errors that can cause operational failures during post-initialization runtime of the SoC applications. Validation criteria:
- The resource assignment substructure header magic number must match the magic number defined for the RM boardcfg resource assignment substructure
- The resource assignment substructure header size must match the size of boardcfg_rm_resasg substructure definition.
- The resource assignment entry array size in bytes cannot be zero. The RM subsystem requires a resource assignment array in order to operate. Passing no resource assignments causes the RM boardcfg message to be rejected.
- The resource assignment entry array size cannot be greater than the size of the DMSC internal storage for the resource assignment array.
- The resource assignment entry array size must be a multiple of the boardcfg_rm_resasg_entry size
- Resource assignments can overlap to assign resources to multiple hosts
according to Static Resource Assignment Configurations.
The overlap validation criteria:
- No more than two resource ranges of the same resource type can overlap
- Overlapping resource ranges of the same resource type cannot be assigned to the same Host ID
- Resource ranges assigned to the HOST_ID_ALL Host ID cannot overlap with any other resource ranges of the same resource type
- Resource assignment ranges and types are checked by the RM subsystem drivers to make sure they are valid according to the SoC resources managed by each driver. The RM boardcfg message is rejected if a resource range is found to not have a valid type or resource range for the SoC managed resources.
- Resource assignment ranges and types are checked by the RM subsystem drivers to verify the ranges is not assignment usage of a DMSC reserved resource to a SoC Host ID. The RM boardcfg message is rejected if a resource range assigns a DMSC reserved resource to a Host ID. Any resource defined as “Reserved for use by DMSC” in the SoC Family Specific Documentation section of the user guide cannot be part of a resource assignment entry.
TISCI API for Resource Management Board Config¶
The following are the parameters required in the TI-SCI message to pass RM resource management board configuration data to DMSC after DMSC sends boot notification complete. The resource management board configuration message is not dependent on reception of the standard board configuration message.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | Yes |
TISCI Message ID¶
TISCI_MSG_BOARD_CONFIG_RM (0x000CU)
Message Data Structures¶
struct tisci_msg_board_config_rm_req
TISCI_MSG_BOARD_CONFIG_RM request to provide the location and size of the boardcfg Resource Management configuration structure.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | TISCI header |
| boardcfg_rmp_low | u32 | Low 32-bits of physical pointer to boardcfg RM configuration struct. |
| boardcfg_rmp_high | u32 | High 32-bits of physical pointer to boardcfg RM configuration struct. |
| boardcfg_rm_size | u16 | Size of RM configuration data. |
struct tisci_msg_board_config_rm_resp
Empty response for TISCI_MSG_BOARD_CONFIG_RM.
| 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.
TI-SCI API for Get Resource Assignment Range¶
The following are the parameters required in the TI-SCI message to retrieve the range of a specific resource assigned to a host.
TISCI Message ID¶
TISCI_MSG_RM_GET_RESOURCE_RANGE (0x1500U)
RM TISCI message to request a resource range assignment for a host
Message Data Structures¶
struct tisci_msg_rm_get_resource_range_req
Retrieves a host’s assigned range for a resource
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | Standard TISCI header |
| type | u16 | Resource assignment type used to form unique resource type. Only 10 LSB are valid. Types are found in the “Enumeration of Resource Type IDs” section of the DMSC public document. |
| subtype | u8 | Resource assignment subtype used to form unique resource type. Only 6 LSB are valid. Subtypes are found in the “Enumeration of Resource Type IDs” section of the DMSC public document. |
| secondary_host | u8 | The host processing entity attempting to allocate the ring if not set to @ref TISCI_MSG_VALUE_RM_UNUSED_SECONDARY_HOST. Otherwise, the host within the TISCI message header is the host attempting to allocate the ring. |
Returns the range for a unique resource type assigned to the specified host, or secondary host. The unique resource type is formed by combining the 10 LSB of type and the 6 LSB of subtype. Unique types which do not map to an SoC resource will not be NACK’d. Instead the tisci_msg_rm_get_resource_range_resp range_start and range_num values are zeroed. This provides a known response mechanism across varied SoCs. Populating secondary_host with @ref TISCI_MSG_VALUE_RM_UNUSED_SECONDARY_HOST specifies the value as unused.
struct tisci_msg_rm_get_resource_range_resp
Get resource range response message
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | Standard TISCI header |
| range_start | u16 | Start index of retrieved resource range. Zero if the resource is not valid. |
| range_num | u16 | Number of resources in the range. Zero if the resource is not valid. |
Response sent to host processor containing the requested resource range assigned to the host who sent the range request. The range_start and range_num values are zero if the type and subtype in the range request do not form a unique resource type for the SoC. In this case, the response will still contain an ACK.
boardcfg_rm structure¶
| Field | Type | Description |
|---|---|---|
| rev | ABI revision structure | Resource Management board config ABI version (separate from primary board config ABI version) |
| host_cfg | boardcfg_rm_host_cfg structure | Host configuration structure |
| resasg | boardcfg_rm_resasg structure | Resource assignment configuration structure |
boardcfg_rm_host_cfg structure¶
| Field | Type | Description |
|---|---|---|
| subhdr | boardcfg substructure header | Magic and size for integrity check |
| host_cfg_entries | boardcfg_rm_host_cfg_entry structure [32] | Array sized for scalable number of hosts describing each host’s configuration attributes |
boardcfg_rm_host_cfg_entry structure¶
The boardcfg_rm_host_cfg_entry structure describes a host’s configuration attributes
| Field | Type | Description |
|---|---|---|
| host_id | u8 | Processing entity host ID |
| allowed_atype | u8 | Allowed atype configuration for the host ID. The host ID gets assigned a list of atypes which are allowed. atype is a 2-bit field with 3 possible values. Thus in one 8-bit word, flags are set specifying whether or not an atype value is allowed for the host ID. For each atype, the value of 01b means not allowed, 10b means allowed, and 11b and 00b are invalid/errors. These are encoded in a bitfield because there is one set of allowed atypes for every host ID. |
| allowed_qos | u16 | Allowed QoS level configuration for host ID. The host ID gets assigned a list of QoS levels which are allowed. As QoS level is a 3-bit field, there are 8 possible order-IDs. Thus in one 16-bit word, flags are set specifying whether or not the QoS level is allowed for the host ID. For each QoS level, the value of 01b means not allowed, 10b means allowed, and 11b and 00b are invalid/errors. These are encoded in a bitfield because there is one set of allowed QoS levels for every host ID. |
| allowed_orderid | u32 | Allowed order-ID configuration for the host ID. The host ID gets assigned a list of order-IDs which are allowed. As order-ID is a 4-bit field, there are 16 possible order-IDs. Thus in one 32-bit word, flags are set specifying whether or not the order-ID is allowed for the host ID. For each order-ID, the value of 01b means not allowed, 10b means allowed, and 11b and 00b are invalid/errors. These are encoded in a bitfield because there is one set of allowed order-IDs for every host ID. |
| allowed_priority | u16 | Allowed bus priority configuration for host ID. The host ID gets assigned a list of bus priorities which are allowed. As bus priority is a 3-bit field, there are 8 possible bus priorities. Thus in one 16-bit word, flags are set specifying whether or not the bus priority is allowed for the host ID. For each bus priority, the value of 01b means not allowed, 10b means allowed, and 11b and 00b are invalid/errors. These are encoded in a bitfield because there is one set of allowed bus priorities for every host ID. |
| allowed_sched_priority | u8 | Allowed UDMAP channel scheduling priority configuration for host ID. The host ID gets assigned a list of UDMAP channel scheduling priorities which are allowed. As UDMAP channel scheduling priority is a 2-bit field, there are 4 possible UDMAP channel scheduling priorities. Thus in one 8-bit word, flags are set specifying whether or not UDMAP channel scheduling priority is allowed for the host ID. For each priority, the value of 01b means not allowed, 10b means allowed, and 11b and 00b are invalid/errors. These are encoded in a bitfield because there is one set of allowed UDMAP channel scheduling priorities for every host ID. |
boardcfg_rm_resasg structure¶
| Field | Type | Description |
|---|---|---|
| subhdr | boardcfg substructure header | Magic and size for integrity check |
| resasg_entries_size | u16 | Size of resource assignment entry array in bytes |
| reserved | u16 | Reserved to keep 4-byte alignment |
| resasg_entries | boardcfg_rm_resasg_entry (resource assignment) structure [] | Array of resource assignment entries defined as variable length array. The user must define their own structure with a fixed length array in place of resasg_entries[]. |
Example user structure for RM boardcfg:
#define RESASG_ENTRIES (100)
struct local_rm_boardcfg {
struct boardcfg_rm rm_boardcfg;
struct boardcfg_rm_resasg_entry resasg_entries[RESASG_ENTRIES];
};
boardcfg_rm_resasg_entry (resource assignment) structure¶
There is one boardcfg_rm_resasg_entry per resource per host. This structure allows one contiguous block of any resource to be assigned to one processing entity
| Field | Type | Description |
|---|---|---|
| start_resource | u16 | First resource number (inclusive) for this host_id and resource type |
| num_resource | u16 | Number of continuous resources allocated to this host_id and resource type. 0 means unused |
| type | u16 | Unique type value identifying the resource whose range is assigned to host_id |
| host_id | u8 | Host ID as defined in secure proxy configuration |
| reserved | u8 | Byte reservation to assure contiguous resasg entries are aligned on 8-byte boundaries |
Design details for interrupt management¶
Within interrupt management, interrupts are routed through interrupt aggregators (IAs) and interrupt routers (IRs).
Whenever interrupt routers broadcast the interrupt to multiple interrupt controllers then it is possible for one processing entity to take outputs that could have been used by another processing entity, precluding the second processing entity from routing a required interrupt. Thus IRs with broadcast outputs need resource reservation capability. On AM6, these are the GPIO interrupt routers (in main and mcu), as well as the MAIN2MCU interrupt router.
Each interrupt aggregator virtual interrupt allows grouping up to 64 peripheral events to one host interrupt. It’s possible for one host to take all of these virtual interrupts. It’s also possible for one host to take all peripheral events. Thus, resource reservation capability is required for peripheral events and interrupt aggregator virtual interrupts.
Interrupt routes terminate at host processor interrupt controller inputs. A single host is capable of consuming all interrupt controller intputs. Therefore, resource reservation is required for host processor interrupt controller IRQs.
The unique types used to identify interrupt management reserved resources are found in Enumeration of Resource Type IDs.