srvgrp-system-msi.adoc

Service Group - SYSTEM_MSI (SERVICEGROUP_ID: 0x0002)

The SYSTEM_MSI service group defines services to allow application processors to receive MSIs upon system events such as P2A doorbell, graceful shutdown/reboot request, CPU hotplug event, memory hotplug event, etc.

The number of system MSIs supported by this service group is fixed and referred to as SYS_NUM_MSI. Each system MSI is associated with a unique index which is also referred to as SYS_MSI_INDEX where 0 ⇐ SYS_MSI_INDEX < SYS_NUM_MSI.

The association between system events and system MSI index (aka SYS_MSI_INDEX) is platform specific and must be discovered using hardware description mechanisms such as device tree or ACPI. The SYS_NUM_MSI value and SYS_MSI_INDEX of the P2A doorbell system MSI can be discovered using the SYSMSI_GET_ATTRIBUTES service.

The system MSI state is 32-bit word also referred to as SYS_MSI_STATE which includes whether the system MSI is enabled/disabled and whether system MSI is currently pending at the platform microcontroller. The System MSI State below shows the encoding of SYS_MSI_STATE.

Note	A system MSI can be pending for several reasons. For example, if the MSI target address and data are not configured, or if the configured MSI target address is not valid.

Table 1. System MSI State

Bits	Permission	Description
[31:2]	NA	Reserved and must be 0.
[1]	Read-Only	MSI pending state. 0b1: MSI is pending. 0b0: MSI is not pending.
[0]	Read-Write	MSI enable state. 0b1: MSI enabled. 0b0: MSI disabled.

The platform microcontroller can only send a pending system MSI if it is enabled and the configured with a valid MSI target address. The system MSI can be enabled/disabled using the SYSMSI_SET_MSI_STATE service whereas the system MSI target configuration can be done using the SYSMSI_SET_MSI_TARGET service.

Note	If the system MSI target address is IMSIC, then the application processors will directly receive the system MSI whereas if the system MSI target address is setipnum register of a APLIC domain then the application processors receive it as wired interrupt.

The SYSTEM_MSI Services below lists the services in the SYSTEM_MSI service group:

Table 2. SYSTEM_MSI Services

Service ID	Service Name	Request Type
0x01	SYSMSI_ENABLE_NOTIFICATION	NORMAL_REQUEST
0x02	SYSMSI_GET_ATTRIBUTES	NORMAL_REQUEST
0x03	SYSMSI_GET_MSI_ATTRIBUTES	NORMAL_REQUEST
0x04	SYSMSI_SET_MSI_STATE	NORMAL_REQUEST
0x05	SYSMSI_GET_MSI_STATE	NORMAL_REQUEST
0x06	SYSMSI_SET_MSI_TARGET	NORMAL_REQUEST
0x07	SYSMSI_GET_MSI_TARGET	NORMAL_REQUEST

Notifications

This service group does not support any events for notification.

Service: SYSMSI_ENABLE_NOTIFICATION (SERVICE_ID: 0x01)

This service allows the application processor to subscribe to SYSTEM_MSI service group notifications. The platform may optionally support notifications for events that may occur. The platform microcontroller can send these notification messages to the application processor if they are implemented and the application processor has subscribed to them. The supported events are described in Notifications.

Table 3. Request Data

Word	Name	Type	Description
0	EVENT_ID	uint32	The event to be subscribed for notification.
1	REQ_STATE	uint32	Requested event notification state. Change or query the current state of EVENT_ID notification. 0: Disable. 1: Enable. 2: Return current state. Any other values of REQ_STATE field other than the defined ones are reserved for future use.

Table 4. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code. Error Code Description RPMI_SUCCESS Event is subscribed successfully. RPMI_ERR_INVALID_PARAM EVENT_ID or REQ_STATE is invalid. RPMI_ERR_NOT_SUPPORTED Notification is not supported. Other errors [table_error_codes].
1	CURRENT_STATE	uint32	Current EVENT_ID notification state. 0: Notification is disabled. 1: Notification is enabled. In case of REQ_STATE = 0 or 1, the CURRENT_STATE will return the requested state. In case of an error, the value of CURRENT_STATE is unspecified.

Service: SYSMSI_GET_ATTRIBUTES (SERVICE_ID: 0x02)

This service is used to discover attributes of the system MSI service group.

Table 5. Request Data

NA

Table 6. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code. Error Code Description RPMI_SUCCESS Service completed successfully. Other errors [table_error_codes].
1	SYS_NUM_MSI	uint32	Number of system MSIs.
2	P2A_DB_INDEX	uint32	System MSI index or SYS_MSI_INDEX of the P2A doorbell. If P2A doorbell is not supported as system MSI then 0xffffffff value should be returned.
3	FLAGS0	uint32	Reserved and must be 0.
4	FLAGS1	uint32	Reserved and must be 0.

Service: SYSMSI_GET_MSI_ATTRIBUTES (SERVICE_ID: 0x03)

This service is used to discover attributes of a particular system MSI.

Table 7. Request Data

Word	Name	Type	Description
0	SYS_MSI_INDEX	uint32	Index of the system MSI.

Table 8. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code. Error Code Description RPMI_SUCCESS Service completed successfully. RPMI_ERR_INVALID_PARAM SYS_MSI_INDEX value is greater than SYS_NUM_MSI. Other errors [table_error_codes].
1	FLAGS0	uint32	Bits Description [31:1] Reserved and must be 0. [0] Preferred privilege level for MSI handling. 0b1: M-mode. 0b0: M-mode or S-mode.
2	FLAGS1	uint32	Reserved and must be 0.
3:6	SYS_MSI_NAME	uint8[16]	System MSI name, a NULL-terminated ASCII string up to 16-bytes.

Service: SYSMSI_SET_MSI_STATE (SERVICE_ID: 0x04)

This service is used to update the state of a system MSI. Specifically, it allows application processors to enable or disable a system MSI. The read-only bits of the system MSI state are not updated by this service.

Table 9. Request Data

Word	Name	Type	Description
0	SYS_MSI_INDEX	uint32	Index of the system MSI.
1	SYS_MSI_STATE	uint32	System MSI state as defined in System MSI State.

Table 10. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code. Error Code Description RPMI_SUCCESS MSI is enabled or disabled successfully. RPMI_ERR_INVALID_PARAM SYS_MSI_INDEX value is greater than SYS_NUM_MSI or SYS_MSI_STATE value is reserved or invalid. Other errors [table_error_codes].

Service: SYSMSI_GET_MSI_STATE (SERVICE_ID: 0x05)

This service is used to get the current state of a system MSI.

Table 11. Request Data

Word	Name	Type	Description
0	SYS_MSI_INDEX	uint32	Index of the system MSI.

Table 12. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code. Error Code Description RPMI_SUCCESS MSI state is returned successfully. RPMI_ERR_INVALID_PARAM SYS_MSI_INDEX value is greater than SYS_NUM_MSI. Other errors [table_error_codes].
1	SYS_MSI_STATE	uint32	System MSI state as defined in System MSI State.

Service: SYSMSI_SET_MSI_TARGET (SERVICE_ID: 0x06)

This service is used to configure the target address and data of a system MSI.

Table 13. Request Data

Word	Name	Type	Description
0	SYS_MSI_INDEX	uint32	Index of the system MSI.
1	SYS_MSI_ADDRESS_LOW	uint32	Lower 32-bit of the MSI address.
2	SYS_MSI_ADDRESS_HIGH	uint32	Upper 32-bit of the MSI address.
3	SYS_MSI_DATA	uint32	32-bit MSI data.

Table 14. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code. Error Code Description RPMI_SUCCESS MSI address and data are configured successfully. RPMI_ERR_INVALID_PARAM SYS_MSI_INDEX value is greater than SYS_NUM_MSI. RPMI_ERR_INVALID_ADDR MSI target address is invalid or it is not 4-byte aligned. Other errors [table_error_codes].

Service: SYSMSI_GET_MSI_TARGET (SERVICE_ID: 0x07)

This service is used to get the current target address and data of a system MSI.

Table 15. Request Data

Word	Name	Type	Description
0	SYS_MSI_INDEX	uint32	Index of the system MSI.

Table 16. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return error code. Error Code Description RPMI_SUCCESS MSI target details returned successfully. RPMI_ERR_INVALID_PARAM SYS_MSI_INDEX value is greater than SYS_NUM_MSI. Other errors [table_error_codes].
1	SYS_MSI_ADDRESS_LOW	uint32	Lower 32-bit of the MSI address.
2	SYS_MSI_ADDRESS_HIGH	uint32	Upper 32-bit of the MSI address.
3	SYS_MSI_DATA	uint32	32-bit MSI data.