Resource Management Ring Accelerator TISCI Message Description¶
Introduction¶
This chapter provides information on usage of the RM Ring Accelerator management TISCI message API parameters.
| TISCI Message ID | Message Name |
|---|---|
| 0x1100 | RESERVED, DO NOT (RE)USE |
| 0x1101 | RESERVED, DO NOT (RE)USE |
| 0x1102 | RESERVED, DO NOT (RE)USE |
| 0x1103 | RESERVED, DO NOT (RE)USE |
| 0x1110 | TISCI_MSG_RM_RING_CFG |
| N/A | TISCI_MSG_RM_RING_CFG Response |
| 0x1111 | RESERVED, DO NOT (RE)USE |
| 0x1120 | TISCI_MSG_RM_RING_MON_CFG |
| N/A | TISCI_MSG_RM_RING_MON_CFG Response |
Ring Valid Parameters Field Usage¶
Some ring TISCI message APIs make use of a valid_params bit field. Bits within the valid_params field define whether or not individual TISCI message parameters are valid. When a bit corresponding to a parameter is set (to 1) the parameter is considered valid and will be programmed into its corresponding register field, assuming validation of the parameter passes. When a valid_params bit is not set, i.e. a value of 0, the corresponding register field is read and used within the validation process of the request. The register field for a parameter is not programmed if the corresponding valid_params bit is not set.
TISCI_MSG_RM_RING_CFG - Ring Accelerator Ring Configure¶
Ring Accelerator Ring Configure Request¶
The ring cfg TISCI message API is used to configure SoC Navigator Subsystem Ring Accelerator rings. The API only allows configuration of a ring by passing the ring index and the Navigator SoC device ID in which the ring is located. Only the non-real-time ring registers are programmed as part of the ring configuration. The host is granted access to the ring real-time registers via the SoC channelized firewalls based on the RM board configuration. The OS can access the ring real-time registers directly after ring configuration is complete.
Ring ISC Virt IDs are programmable through the ring cfg TISCI message. Host access permissions to program the ring Virt IDs are granted through the RM board configuration. A host attempting to program the Virt ID must be assigned a Virt ID range and own, or be a supervisor of the owner of, the ring as defined in the board configuration. Virt IDs are typically programmed by hypervisor. Subordinates of the hypervisor are assigned and configure rings. The hypervisor programs the ring’s Virt IDs separately (or at the same time if the hypervisor is tasked with configuring a ring’s non-real-time registers as well).
Ring parameter validation steps are performed against passed valid configuration parameters in combination with existing register settings for configuration parameters specified as not valid.
The ring global error event and per-ring event registers are not programmed as part of the ring cfg API. These registers are decoupled from ring configuration for security reasons. They’re programmed internally via the RM IRQ Set message.
The ring cfg TISCI message API resets the ring if any of the RING_BA_HI, RING_BA_LO, or RING_SIZE registers are written as part of the ring configuration. Resetting a ring resets the ring’s occupancies and pointers. The host, or a supervisor of the host, who owns the ring must be the requesting host.
The ring cfg API can be used to configure rings within any Navigator Subsystem Ring Accelerator on the device.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
TISCI Message ID¶
TISCI_MSG_RM_RING_CFG (0x1110U)
RM TISCI message to configure a Navigator Subsystem ring
Ring Configure Message Parameters¶
struct tisci_msg_rm_ring_cfg_req
Configures a Navigator Subsystem ring
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | Standard TISCI header |
| valid_params | u32 | Bitfield defining validity of ring configuration parameters. The ring configuration fields are not valid, and will not be used for ring configuration, if their corresponding valid bit is zero. Valid bit usage: 0 - Valid bit for @ref tisci_msg_rm_ring_cfg_req::addr_lo 1 - Valid bit for @ref tisci_msg_rm_ring_cfg_req::addr_hi 2 - Valid bit for @ref tisci_msg_rm_ring_cfg_req::count 3 - Valid bit for @ref tisci_msg_rm_ring_cfg_req::mode 4 - Valid bit for @ref tisci_msg_rm_ring_cfg_req::size 5 - Valid bit for @ref tisci_msg_rm_ring_cfg_req::order_id 6 - Valid bit for @ref tisci_msg_rm_ring_cfg_req::virtid |
| nav_id | u16 | SoC device ID of Navigator Subsystem where ring is located |
| index | u16 | Ring index. |
| addr_lo | u32 | 32 LSBs of ring base address to be programmed into the ring’s RING_BA_LO register. |
| addr_hi | u32 | 16 MSBs of ring base address to be programmed into the ring’s RING_BA_HI register. Only the 16 LSBs of @ref addr_hi are used when programming RING_BA_HI, the upper 16 bits are discarded. |
| count | u32 | Number of ring elements to be programmed into the size field of the ring’s RING_SIZE register. |
| mode | u8 | Ring mode to be programmed into the qmode field of the ring’s RING_SIZE register. Can be set to: @ref TISCI_MSG_VALUE_RM_RING_MODE_RING @ref TISCI_MSG_VALUE_RM_RING_MODE_MESSAGE @ref TISCI_MSG_VALUE_RM_RING_MODE_CREDENTIALS @ref TISCI_MSG_VALUE_RM_RING_MODE_QM |
| size | u8 | Encoded ring element size to be programmed into the elsize field of the ring’s RING_SIZE register. To calculate the encoded size use the formula (log2(size_bytes) - 2), where “size_bytes” cannot be greater than 256 bytes. Can be set to: @ref TISCI_MSG_VALUE_RM_RING_SIZE_4B @ref TISCI_MSG_VALUE_RM_RING_SIZE_8B @ref TISCI_MSG_VALUE_RM_RING_SIZE_16B @ref TISCI_MSG_VALUE_RM_RING_SIZE_32B @ref TISCI_MSG_VALUE_RM_RING_SIZE_64B @ref TISCI_MSG_VALUE_RM_RING_SIZE_128B @ref TISCI_MSG_VALUE_RM_RING_SIZE_256B |
| order_id | u8 | Ring bus order ID value to be programmed into the orderid field of the ring’s RING_ORDERID register. When valid, the replace field of the ring’s RING_ORDERID register will be set to 1 so that the programmed order ID will be used. |
| virtid | u16 | Ring virt ID value to be programmed into the virtid field of the ring’s RING_CONTROL2 ISC region register. This field is only valid if @ref TISCI_MSG_VALUE_RM_RING_VIRTID_VALID is set in @ref tisci_msg_rm_ring_cfg_req::valid_params. |
| asel | u8 | Ring ASEL (address select) value to be set into the ASEL field of the ring’s RING_BA_HI register. This field is only valid if @ref TISCI_MSG_VALUE_RM_RING_ASEL_VALID is set in @ref tisci_msg_rm_ring_cfg_req::valid_params. This field is not supported on some SoCs. On SoCs that do not support this field the input is quietly ignored even if the valid bit is set. |
Configures the non-real-time registers of a Navigator Subsystem ring. The ring index must be assigned to the host defined in the TISCI header via the RM board configuration resource assignment range list. This field is only valid if @ref TISCI_MSG_VALUE_RM_RING_ADDR_LO_VALID is set in @ref tisci_msg_rm_ring_cfg_req::valid_params. This field is only valid if @ref TISCI_MSG_VALUE_RM_RING_ADDR_HI_VALID is set in @ref tisci_msg_rm_ring_cfg_req::valid_params. This field is only valid if @ref TISCI_MSG_VALUE_RM_RING_COUNT_VALID is set in @ref tisci_msg_rm_ring_cfg_req::valid_params. This field is only valid if @ref TISCI_MSG_VALUE_RM_RING_MODE_VALID is set in @ref tisci_msg_rm_ring_cfg_req::valid_params. This field is only valid if @ref TISCI_MSG_VALUE_RM_RING_SIZE_VALID is set in @ref tisci_msg_rm_ring_cfg_req::valid_params. This field is only valid if @ref TISCI_MSG_VALUE_RM_RING_ORDER_ID_VALID is set in @ref tisci_msg_rm_ring_cfg_req::valid_params.
Ring Configuration Valid Parameters¶
The following table describes the valid bit mappings for the ring configure message optional parameters:
| valid_params Bit | Corresponding tisci_msg_rm_ring_cfg_req Optional Parameter |
|---|---|
| 0 | addr_lo |
| 1 | addr_hi |
| 2 | count |
| 3 | mode |
| 4 | size |
| 5 | order_id |
| 6 | virtid |
Ring Accelerator Ring Configure Response¶
The ring cfg response message returns the result status of the processed ring cfg message.
Ring Configure Response Message Parameters¶
struct tisci_msg_rm_ring_cfg_resp
Response to configuring a ring.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | Standard TISCI header |
TISCI_MSG_RM_RING_MON_CFG - Ring Monitor Configuration¶
Ring Monitor Configuration Request¶
The ring_mon_cfg TISCI message API is used to configures the real-time registers of a Navigator Subsystem ring monitor. The ring monitor index must be assigned to the host defined in the TISCI header via the RM board configuration resource assignment range list. The channelized firewalls covering the ring monitor registers are configured to allow the host read-only access.
Usage¶
| Message Type | Normal |
| Secure Queue Only? | No |
TISCI Message ID¶
TISCI_MSG_RM_RING_MON_CFG (0x1120U)
RM TISCI message to configure a Navigator Subsystem ring monitor
Ring Monitor Configuration Message Parameters¶
struct tisci_msg_rm_ring_mon_cfg_req
Configures a Navigator Subsystem ring monitor. Configures the real-time registers of a Navigator Subsystem ring monitor. The ring monitor index must be assigned to the host defined in the TISCI header via the RM board configuration resource assignment range list. The channelized firewalls covering the ring monitor registers are configured to allow the host read-only access.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | Standard TISCI header |
| valid_params | u32 | Bitfield defining validity of ring monitor configuration parameters. The ring monitor configuration fields are not valid, and will not be used for ring monitor configuration, if their corresponding valid bit is zero. Valid bit usage: 0 - Valid bit for @ref tisci_msg_rm_ring_mon_cfg_req::source 1 - Valid bit for @ref tisci_msg_rm_ring_mon_cfg_req::mode 2 - Valid bit for @ref tisci_msg_rm_ring_mon_cfg_req::queue 3 - Valid bit for @ref tisci_msg_rm_ring_mon_cfg_req::data0_val 4 - Valid bit for @ref tisci_msg_rm_ring_mon_cfg_req::data1_val |
| nav_id | u16 | SoC device ID of Navigator Subsystem where ring monitor is located |
| index | u16 | Ring monitor index. |
| source | u8 | Monitor source selection programmed into RINGACC_CONTROL register. Can be set to: @ref TISCI_MSG_VALUE_RM_MON_SRC_ELEM_CNT @ref TISCI_MSG_VALUE_RM_MON_SRC_HEAD_PKT_SIZE @ref TISCI_MSG_VALUE_RM_MON_SRC_ACCUM_Q_SIZE This field is only valid if @ref TISCI_MSG_VALUE_RM_MON_SOURCE_VALID is set in @ref tisci_msg_rm_ring_mon_cfg_req::valid_params. |
| mode | u8 | Monitor mode programmed into RINGACC_CONTROL register. Can be set to: @ref TISCI_MSG_VALUE_RM_MON_MODE_DISABLED @ref TISCI_MSG_VALUE_RM_MON_MODE_PUSH_POP @ref TISCI_MSG_VALUE_RM_MON_MODE_THRESHOLD @ref TISCI_MSG_VALUE_RM_MON_MODE_WATERMARK @ref TISCI_MSG_VALUE_RM_MON_MODE_STARVATION This field is only valid if @ref TISCI_MSG_VALUE_RM_MON_MODE_VALID is set in @ref tisci_msg_rm_ring_mon_cfg_req::valid_params. |
| queue | u16 | Queue, or ring, to monitor programmed into RINGACC_QUEUE register. The specified queue must be assigned to the host, or a subordinate of the host, requesting the ring monitor configuration. This field is only valid if @ref TISCI_MSG_VALUE_RM_MON_QUEUE_VALID is set in @ref tisci_msg_rm_ring_mon_cfg_req::valid_params. |
| data0_val | u32 | Low threshold value programmed into RINGACC_DATA0 register when the ring monitor mode is configured to low/high threshold checking. Values specified in this field are ignored for other monitor modes. This field is only valid if @ref TISCI_MSG_VALUE_RM_MON_DATA0_VAL_VALID is set in @ref tisci_msg_rm_ring_mon_cfg_req::valid_params. |
| data1_val | u32 | High threshold value programmed into RINGACC_DATA1 register when the ring monitor mode is configured to low/high threshold checking. Values specified in this field are ignored for other monitor modes. This field is only valid if @ref TISCI_MSG_VALUE_RM_MON_DATA1_VAL_VALID is set in @ref tisci_msg_rm_ring_mon_cfg_req::valid_params. |
Ring Monitor Configuration Valid Parameters¶
The following table describes the valid bit mappings for the ring monitor configuration parameters:
| valid_params Bit | Corresponding tisci_msg_rm_ring_mon_cfg_req Parameter |
|---|---|
| 0 | source |
| 1 | mode |
| 2 | queue |
| 3 | data0_val |
| 4 | data1_val |
Ring Monitor Configuration Response¶
The ring_mon_cfg_response message returns the result status of the processed ring_mon_cfg message.
Ring Monitor Configuration Response Message Parameters¶
struct tisci_msg_rm_ring_mon_cfg_resp
Response to configuring a ring monitor.
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | Standard TISCI header |
Ring Reset Procedure¶
This section describes the steps the OS needs to take in order to reset a ring.
Generic reset procedure for most devices:
- OS sends the ring cfg TISCI message modifying either RING_BA_HI, RING_BA_LO, or RING_SIZE non-real-time registers to reset a ring.
Some devices require a different ring reset procedure as defined by ErrataID # i2023. The reset procedure synchronizes the occupancy count between the UDMAP ring state and the RA ring state after the ring is reset. The procedure is:
- Read the ring occupancy (RINGACC_OCC_j [CNT]) as
“adjusted ring occupancy count” from the ring’s real-time registers
- If the ring is configured in credentials mode or queue manager (QM) mode, adjust “adjusted ring occupancy count” by dividing the ring occupancy by 2. This is required because when in credentials mode or QM mode, each ring write increases the ring occupancy by 2 elements (one entry for the credentials, one entry for the data). However, the UDMAP’s local occupancy counter only records the number of writes, and the ring occupancy, therefore, needs to be divided by 2 to convert back to the number of doorbell rings needed.
- If the ring occupancy is not 0, then steps 2-5 need to be executed to implement the workaround.
- Application directly reads the RINGACC CFG registers to retrieve the ring qmode if not already in ring/doorbell mode. Save the qmode if the original mode was not ring/doorbell mode.
- Reset the ring by writing any value to the ring’s RINGACC CFG registers (i.e. enable the valid parameter bit for mode, size, or count in the ring cfg TISCI message)
- Send the ring cfg message to DMSC specifying qmode as ring/doorbell if not already in that mode.
- Ring the (doorbell 2**22 – (adjusted ring occupancy count)) through the ring’s real-time registers. This will wrap the internal UDMAP ring state occupancy counter (which is 21-bits wide) to 0. (If possible, ring the doorbell with the maximum count each iteration to minimize the total number of writes.)
- Send the ring cfg message to DMSC to program qmode back to the origin qmode (if not ring/doorbell mode).