Resource Management IRQ TISCI Message Description

Introduction

This chapter provides information on usage of the RM Interrupt Request (IRQ) management TISCI message API parameters.

TISCI Message ID Message Name
0x1000 TISCI_MSG_RM_IRQ_SET
N/A TISCI_MSG_RM_IRQ_SET Response
0x1001 TISCI_MSG_RM_IRQ_RELEASE
N/A TISCI_MSG_RM_IRQ_RELEASE Response

TISCI_MSG_RM_IRQ_SET - IRQ Route Set

The IRQ route set TISCI message API is used to configure peripherals within SoC interrupt architecture. This includes, SoC dependent, peripheral output event steering (OES) registers, interrupt aggregators, and interrupt routers. To configure a desired interrupt route between a peripheral and host processor the IRQ route set API must be called to configure each hop in the route between source and destination. What is configured in each call depends on the valid_params bit configuration and the SoC device ID and indexes provided.

The IRQ route set API does not configure destination processor interrupt controllers. This job is left to the HLOS.

When configuring interrupt aggregator virtual interrupt global event to status bit mappings, each time an event is mapped to a VINT status bit the mapping is enabled after it is configured. The OS can manipulate the status bit’s enable/disable setting on-the-fly via the VINT’s real-time registers. The host is granted access to the virtual interrupt real-time registers via the SoC channelized firewalls based on the RM board configuration. The OS can access the virtual interrupt real-time registers directly after interrupt aggregator configuration is complete.

NOTE (Subject to Change):

Some System Firmware peripheral drivers have not implemented OES register management yet. The HLOS must program the global event value into peripheral’s OES register. For System Firmware drivers that have implemented internal handling of OES registers, the allocated global event is programmed into the peripheral element’s OES register internally. Peripherals implementing OES management thus far:

  • Ring Accelerator
  • UDMAP
  • Proxy

Usage

Message Type Normal
Secure Queue Only? No

TISCI Message ID

TISCI_MSG_RM_IRQ_SET          (0x1000U)

RM TISCI message to set an IRQ between a peripheral and host processor

IRQ Route Set Message Parameters

struct tisci_msg_rm_irq_set_req

Configures peripherals within the interrupt subsystem according to the valid configuration provided. The following @ref tisci_msg_rm_irq_set_req::valid_params valid bit combinations are allowed: Interrupt Router Mux Configuration - Configures an IR input to output mux connection where the IR input is the src_index and the IR output is the dst_host_irq. Both the src_id and the dst_id must be the device ID of the IR being configured. @ref tisci_msg_rm_irq_set_req::dst_id valid bit == STRUE @ref tisci_msg_rm_irq_set_req::dst_host_irq valid bit == STRUE @ref tisci_msg_rm_irq_set_req::ia_id valid bit == SFALSE @ref tisci_msg_rm_irq_set_req::vint valid bit == SFALSE @ref tisci_msg_rm_irq_set_req::global_event valid bit == SFALSE @ref tisci_msg_rm_irq_set_req::vint_status_bit_index valid bit == SFALSE Event to VINT Mapping Only - Configure peripheral OES register and add an event mapping to an IA VINT @ref tisci_msg_rm_irq_set_req::dst_id valid bit == SFALSE @ref tisci_msg_rm_irq_set_req::dst_host_irq valid bit == SFALSE @ref tisci_msg_rm_irq_set_req::ia_id valid bit == STRUE @ref tisci_msg_rm_irq_set_req::vint valid bit == STRUE @ref tisci_msg_rm_irq_set_req::global_event valid bit == STRUE @ref tisci_msg_rm_irq_set_req::vint_status_bit_index valid bit == STRUE OES Register Programming Only - Only programs the OES register of the source. Useful for setting UDMAP trigger events and any other events that are not translated to the interrupt domain: @ref tisci_msg_rm_irq_set_req::dst_id valid bit == SFALSE @ref tisci_msg_rm_irq_set_req::dst_host_irq valid bit == SFALSE @ref tisci_msg_rm_irq_set_req::ia_id valid bit == SFALSE @ref tisci_msg_rm_irq_set_req::vint valid bit == SFALSE @ref tisci_msg_rm_irq_set_req::global_event valid bit == STRUE @ref tisci_msg_rm_irq_set_req::vint_status_bit_index valid bit == SFALSE

Parameter Type Description
hdr struct tisci_header Standard TISCI header
valid_params u32 Bitfield defining validity of interrupt route set parameters. The interrupt route set fields are not valid, and will not be used for route set, if their corresponding valid bit is zero. Valid bit usage: 0 - Valid bit for @ref tisci_msg_rm_irq_set_req::dst_id 1 - Valid bit for @ref tisci_msg_rm_irq_set_req::dst_host_irq 2 - Valid bit for @ref tisci_msg_rm_irq_set_req::ia_id 3 - Valid bit for @ref tisci_msg_rm_irq_set_req::vint 4 - Valid bit for @ref tisci_msg_rm_irq_set_req::global_event 5 - Valid bit for @ref tisci_msg_rm_irq_set_req::vint_status_bit_index 31 - Valid bit for @ref tisci_msg_rm_irq_set_req::secondary_host
src_id u16 ID of interrupt source peripheral
src_index u16 Interrupt source index within source peripheral
dst_id u16 SoC IR device ID when the valid_params bits are set to configure an IR mux connection. This field is only valid if @ref TISCI_MSG_VALUE_RM_DST_ID_VALID is set in @ref tisci_msg_rm_irq_set_req::valid_params.
dst_host_irq u16 SoC IR output index when the valid_params are set to configure an IR mux connection. This field is only valid if @ref TISCI_MSG_VALUE_RM_DST_HOST_IRQ_VALID is set in @ref tisci_msg_rm_irq_set_req::valid_params.
ia_id u16 Device ID of interrupt aggregator in which the virtual interrupt resides. This field is only valid if @ref TISCI_MSG_VALUE_RM_IA_ID_VALID is set in @ref tisci_msg_rm_irq_set_req::valid_params.
vint u16 Virtual interrupt number when configuring an interrupt aggregator. This field is only valid if @ref TISCI_MSG_VALUE_RM_VINT_VALID is set in @ref tisci_msg_rm_irq_set_req::valid_params.
global_event u16 Global event mapped to interrupt aggregator virtual interrupt status bit. The event is programmed into the OES register of the interrupt source. This field is only applicable for interrupt source’s capable of generating global events. This field is only valid if @ref TISCI_MSG_VALUE_RM_GLOBAL_EVENT_VALID is set in @ref tisci_msg_rm_irq_set_req::valid_params.
vint_status_bit_index u8 Virtual interrupt status bit to set if the interrupt route utilizes an interrupt aggregator virtual interrupt. The host processor uses the status bit value within the interrupt aggregator vint status register to find the source event which triggered the interrupt. This field is only valid if @ref TISCI_MSG_VALUE_RM_VINT_STATUS_BIT_INDEX_VALID is set in @ref tisci_msg_rm_irq_set_req::valid_params.
secondary_host u8 The interrupt route destination is the specified secondary host if the secondary_host’s corresponding valid bit is set in @ref tisci_msg_rm_irq_set_req::valid_params. Otherwise, the host within the TISCI message header is the route destination.

IRQ Route Set Valid Parameters

The following table describes the valid bit mappings for the IRQ route set message optional parameters:

valid_params Bit Corresponding tisci_msg_rm_irq_set_req Optional Parameter
0 dst_id
1 dst_host_irq
2 ia_id
3 vint
4 global_event
5 vint_status_bit_index
31 secondary_host

The following table describes the valid bit combinations used to configure the peripherals within the interrupt management architecture

Configuration dst_id dst_host_irq ia_id vint global_event vint_status_bit_index Description
Interrupt Router Mux Configuration X X         Configures an IR input to output mux connection where the IR input is the src_index and the IR output is the dst_host_irq. Both src_id and dst_id must be be the device ID of the IR being configured.
Event to VINT Mapping Only     X X X X Configure peripheral OES register and add an event mapping to an IA VINT.
OES Register Programming Only         X   Only programs the OES register of the source. Useful for setting UDMAP trigger events and any other events that are not translated to the interrupt domain.

TISCI_MSG_RM_IRQ_SET - IRQ Route Set Response

The irq_set_response message returns the result status of the processed irq_set message.

IRQ Route Set Response Message Parameters

struct tisci_msg_rm_irq_set_resp

Response to setting a peripheral to processor interrupt.

Parameter Type Description
hdr struct tisci_header Standard TISCI header

TISCI_MSG_RM_IRQ_RELEASE - IRQ Route Release

The IRQ route release TISCI message API is used to release an IRQ route between a device peripheral and a host processor. IRQ routes are released by specifying the interrupt source peripheral’s interrupt output index. The IRQ destination is mapped to the processor on which the host ID, or secondary host ID (if valid), is executing. The IRQ management subsystem will trace the interrupt route between the source and destination, freeing any interrupt router and interrupt aggregator resources within the route.

For routes utilizing an IA VINT event to status bit mapping, the status bit is disabled when the route is freed. The OS is not required to disable the status bit via the VINT’s real-time registers prior to route release

The IRQ route release TISCI message API is used to clear peripherals within SoC interrupt architecture. This includes, SoC dependent, peripheral output event steering (OES) registers, interrupt aggregators, and interrupt routers. To clear a desired interrupt route between a peripheral and host processor the IRQ route release API must be called to clear each hop in the route between source and destination. What is cleared in each call depends on the valid_params bit configuration and the SoC device ID and indexes provided.

The IRQ route release API does not clear destination processor interrupt controllers. This job is left to the HLOS.

When clearing interrupt aggregator virtual interrupt global event to status bit mappings, the status bit is disabled when the mapping is cleared. The OS is not required to disable the status bit via the VINT’s real-time registers prior to interrupt aggregator mapping clear.

NOTE (Subject to Change):

Some System Firmware peripheral drivers have not implemented OES register management yet. The HLOS must also make sure to clear the peripheral OES register programmed with the global event. Peripherals implementing OES management thus far:

  • Ring Accelerator
  • UDMAP
  • Proxy

Usage

Message Type Normal
Secure Queue Only? No

TISCI Message ID

TISCI_MSG_RM_IRQ_RELEASE          (0x1001U)

RM TISCI message to release a configured IRQ

IRQ Route Release Message Parameters

struct tisci_msg_rm_irq_release_req

Releases interrupt peripheral resources according to the valid configuration provided. The following @ref tisci_msg_rm_irq_release_req::valid_params valid bit combinations are allowed: Interrupt Router Mux Release - Release an IR input to output mux connection where the IR input is the src_index and the IR output is the dst_host_irq. Both the src_id and the dst_id must be the device ID of the IR being configured. @ref tisci_msg_rm_irq_release_req::dst_id valid bit == STRUE @ref tisci_msg_rm_irq_release_req::dst_host_irq valid bit == STRUE @ref tisci_msg_rm_irq_release_req::ia_id valid bit == SFALSE @ref tisci_msg_rm_irq_release_req::vint valid bit == SFALSE @ref tisci_msg_rm_irq_release_req::global_event valid bit == SFALSE @ref tisci_msg_rm_irq_release_req::vint_status_bit_index valid bit == SFALSE Event to VINT Unmap Only - Clear only peripheral OES register and event to VINT status bit mapping @ref tisci_msg_rm_irq_release_req::dst_id valid bit == SFALSE @ref tisci_msg_rm_irq_release_req::dst_host_irq valid bit == SFALSE @ref tisci_msg_rm_irq_release_req::ia_id valid bit == STRUE @ref tisci_msg_rm_irq_release_req::vint valid bit == STRUE @ref tisci_msg_rm_irq_release_req::global_event valid bit == STRUE @ref tisci_msg_rm_irq_release_req::vint_status_bit_index valid bit == STRUE OES Register Programming Only - Only clears the OES register of the source. Useful for clearing UDMAP trigger events and any other events that are not translated to the interrupt domain: @ref tisci_msg_rm_irq_release_req::dst_id valid bit == SFALSE @ref tisci_msg_rm_irq_release_req::dst_host_irq valid bit == SFALSE @ref tisci_msg_rm_irq_release_req::ia_id valid bit == SFALSE @ref tisci_msg_rm_irq_release_req::vint valid bit == SFALSE @ref tisci_msg_rm_irq_release_req::global_event valid bit == STRUE @ref tisci_msg_rm_irq_release_req::vint_status_bit_index valid bit == SFALSE

Parameter Type Description
hdr struct tisci_header Standard TISCI header
valid_params u32 Bitfield defining validity of interrupt route release parameters. The interrupt route release fields are not valid, and will not be used for route release, if their corresponding valid bit is zero. Valid bit usage: 0 - Valid bit for @ref tisci_msg_rm_irq_release_req::dst_id 1 - Valid bit for @ref tisci_msg_rm_irq_release_req::dst_host_irq 2 - Valid bit for @ref tisci_msg_rm_irq_release_req::ia_id 3 - Valid bit for @ref tisci_msg_rm_irq_release_req::vint 4 - Valid bit for @ref tisci_msg_rm_irq_release_req::global_event 5 - Valid bit for @ref tisci_msg_rm_irq_release_req::vint_status_bit_index 31 - Valid bit for @ref tisci_msg_rm_irq_release_req::secondary_host
src_id u16 ID of interrupt source peripheral
src_index u16 Interrupt source index within source peripheral
dst_id u16 SoC IR device ID when the valid_params bits are set to release an IR mux connection. This field is only valid if @ref TISCI_MSG_VALUE_RM_DST_ID_VALID is set in @ref tisci_msg_rm_irq_release_req::valid_params.
dst_host_irq u16 SoC IR output index when the valid_params are set to release an IR mux connection. This field is only valid if @ref TISCI_MSG_VALUE_RM_DST_HOST_IRQ_VALID is set in @ref tisci_msg_rm_irq_release_req::valid_params.
ia_id u16 Device ID of interrupt aggregator in which the virtual interrupt resides. This field is only valid if @ref TISCI_MSG_VALUE_RM_IA_ID_VALID is set in @ref tisci_msg_rm_irq_release_req::valid_params.
vint u16 Virtual interrupt number if the interrupt route is through an interrupt aggregator. This field is only valid if @ref TISCI_MSG_VALUE_RM_VINT_VALID is set in @ref tisci_msg_rm_irq_release_req::valid_params.
global_event u16 Global event mapped to interrupt aggregator virtual interrupt status bit. The event is cleared from the OES register of the interrupt source. This field is only applicable for interrupt source’s capable of generating global events. This field is only valid if @ref TISCI_MSG_VALUE_RM_GLOBAL_EVENT_VALID is set in @ref tisci_msg_rm_irq_release_req::valid_params.
vint_status_bit_index u8 Virtual interrupt status bit to release if the interrupt route utilizes an interrupt aggregator virtual interrupt. This field is only valid if @ref TISCI_MSG_VALUE_RM_VINT_STATUS_BIT_INDEX_VALID is set in @ref tisci_msg_rm_irq_release_req::valid_params.
secondary_host u8 The interrupt route destination is the specified secondary host if the secondary_host’s corresponding valid bit is set in @ref tisci_msg_rm_irq_release_req::valid_params. Otherwise, the host within the TISCI message header is the route destination.

IRQ Route Release Valid Parameters

The following table describes the valid bit mappings for the IRQ route release message optional parameters:

valid_params Bit Corresponding tisci_msg_rm_irq_release_req Optional Parameter
0 dst_id
1 dst_host_irq
2 ia_id
3 vint
4 global_event
5 vint_status_bit_index
31 secondary_host

The following table describes the valid bit combinations used to clear the peripherals within the interrupt management architecture

Configuration dst_id dst_host_irq ia_id vint global_event vint_status_bit_index Description
Interrupt Router Mux Release X X         Releases an IR input to output mux connection where the IR input is the src_index and the IR output is the dst_host_irq. Both src_id and dst_id must be the device ID of the IR being configured.
Event to VINT Unmap Only     X X X X Clear only peripheral OES register and event to VINT status bit mapping.
OES Register Programming Only         X   Only clears the OES register of the source. Useful for clearing UDMAP trigger events and any other events that are not translated to the interrupt domain.

TISCI_MSG_RM_IRQ_RELEASE - IRQ Route Release Response

The irq_releaes_response message returns the result status of the processed irq_release message.

IRQ Route Release Response Message Parameters

struct tisci_msg_rm_irq_release_resp

Response to releasing a peripheral to processor interrupt.

Parameter Type Description
hdr struct tisci_header Standard TISCI header