diff --git a/src/ext-sse.adoc b/src/ext-sse.adoc index c85ff14..dad994e 100644 --- a/src/ext-sse.adoc +++ b/src/ext-sse.adoc @@ -7,7 +7,7 @@ receive software events only on harts which are ready to receive them. A softwar event is delivered only after supervisor software has registered an event handler and enabled the software event. -The software events can be of two types: local or global. A local software +The software events are one of two types: local or global. A local software event is local to a hart and can be handled only on that hart whereas a global software event is a system event and can be handled by any participating hart. @@ -72,7 +72,8 @@ with standard events based on the above encoding. === Software Event States -At any point in time, a software event can be in one of the following states: +At any point in time, a software event **MUST** be in one of the following +states: . **UNUSED** - Software event is not used by supervisor software . **REGISTERED** - Supervisor software has provided an event handler for @@ -112,7 +113,7 @@ image::images/riscv-sbi-sse-sm.png[] === Software Event Priority Each software event has an associated priority (referred as `event_priority`) -which can be used by an SBI implementation to select a software event for +which is used by an SBI implementation to select a software event for injection when multiple software events are pending on the same hart. The priority of a software event is a 32-bit unsigned integer where lower @@ -132,7 +133,7 @@ previous lower priority software event will be resumed. A software event can have various XLEN bits wide attributes associated to it where each event attribute is identified by a unique 32-bit unsigned integer -called `attr_id`. A software event attribute can have a Read-Only or Read-Write +called `attr_id`. A software event attribute has Read-Only or Read-Write access permissions. The <> below provides a list event attributes. @@ -162,7 +163,7 @@ event attributes. `bit[3:3]`: Event injection using the `sbi_sse_inject` call (1 = Allowed and 0 = Not allowed) + + - `bit[XLEN-1:4]`: Reserved for future use and should be zero + + `bit[XLEN-1:4]`: Reserved for future use and must be zero + + The reset value of this attribute is zero. @@ -184,7 +185,7 @@ event attributes. + `bit[0:0]`: Disable software event upon `sbi_sse_complete` call (one-shot) + + - `bit[XLEN-1:1]`: Reserved for future use and should be zero + + `bit[XLEN-1:1]`: Reserved for future use and must be zero + + The reset value of this attribute is zero. @@ -192,8 +193,8 @@ event attributes. | 0x00000003 | RW (global) + RO (local) -| Hart id of the preferred hart that should handle the global software event. - The value of this attribute must always be valid hart id for both local and +| Hart ID of the preferred hart that should handle the global software event. + The value of this attribute must always be valid hart ID for both local and global software events. This attribute is read-only for local software events and for global software events it can be updated only when the software event is in `UNUSED` or `REGISTERED` state. + @@ -244,7 +245,7 @@ event attributes. + `bit[3:3]`: interrupted `hstatus.SPVP` CSR bit value + + - `bit[XLEN-1:4]`: Reserved for future use and should be zero + + `bit[XLEN-1:4]`: Reserved for future use and must be set to zero + | INTERRUPTED_A6 | 0x00000008 @@ -269,7 +270,7 @@ event attributes. | RESERVED | > 0x00000009 | --- -| Reserved for future use +| Reserved for future use. |=== === Software Event Injection @@ -291,7 +292,7 @@ following: .. Set `INTERRUPTED_A6` event attribute = interrupted `A6` GPR value .. Set `INTERRUPTED_A7` event attribute = interrupted `A7` GPR value . Redirect execution to supervisor event handler - .. Set `A6` GPR = Current Hart id + .. Set `A6` GPR = Current Hart ID .. Set `A7` GPR = `ENTRY_ARG` event attribute value .. Set `sepc` = Interrupted program counter value .. Set `sstatus.SPP` CSR bit = interrupted privilege mode @@ -341,15 +342,15 @@ struct sbiret sbi_sse_read_attrs(uint32_t event_id, Read a range of event attribute values from a software event. -The `event_id` parameter specifies the software event whereas `base_attr_id` -and `attr_count` parameters specifies the range of event attribute ids. +The `event_id` parameter specifies the software event ID whereas `base_attr_id` +and `attr_count` parameters specifies the range of event attribute IDs. The event attribute values are written to a output shared memory which is specified by the `output_phys_lo` and `output_phys_hi` parameters where: * The `output_phys_lo` parameter MUST be `XLEN / 8` bytes aligned * The size of output shared memory is assumed to be `(XLEN / 8) * attr_count` -* The value of event attribute with id `base_attr_id + i` should be written +* The value of event attribute with ID `base_attr_id + i` should be written at offset `(XLEN / 8) * (base_attr_id + i)` In case of an error, the possible error codes are shown in the @@ -361,12 +362,14 @@ In case of an error, the possible error codes are shown in the |=== | Error code | Description | SBI_SUCCESS | Event attribute values read successfully. -| SBI_ERR_NOT_SUPPORTED | `event` is not reserved and valid, but the platform - does not support it due to one or more missing - dependencies (Hardware or SBI implementation). +| SBI_ERR_NOT_SUPPORTED | `event_id` is not reserved and valid, but the + platform does not support it due to one or more + missing dependencies (Hardware or SBI + implementation). | SBI_ERR_INVALID_PARAM | `event_id` is invalid or `attr_count` is zero. -| SBI_ERR_BAD_RANGE | One of the event attribute in the range specified - by `base_attr_id` and `attr_count` does not exist. +| SBI_ERR_BAD_RANGE | One of the event attribute IDs in the range + specified by `base_attr_id` and `attr_count` is + reserved. | SBI_ERR_INVALID_ADDRESS | The shared memory pointed to by the `output_phys_lo` and `output_phys_hi` parameters does not satisfy the requirements described in @@ -387,15 +390,15 @@ struct sbiret sbi_sse_write_attrs(uint32_t event_id, Write a range of event attribute values to a software event. -The `event_id` parameter specifies the software event whereas `base_attr_id` -and `attr_count` parameters specifies the range of event attribute ids. +The `event_id` parameter specifies the software event ID whereas `base_attr_id` +and `attr_count` parameters specifies the range of event attribute IDs. The event attribute values are read from a input shared memory which is specified by the `input_phys_lo` and `input_phys_hi` parameters where: * The `input_phys_lo` parameter MUST be `XLEN / 8` bytes aligned * The size of input shared memory is assumed to be `(XLEN / 8) * attr_count` -* The value of event attribute with id `base_attr_id + i` should be read +* The value of event attribute with ID `base_attr_id + i` should be read from offset `(XLEN / 8) * (base_attr_id + i)` For local events, the event attributes are updated only for the calling hart. @@ -410,13 +413,14 @@ The possible error codes returned in `sbiret.error` are shown in |=== | Error code | Description | SBI_SUCCESS | Event attribute values written successfully. -| SBI_ERR_NOT_SUPPORTED | `event` is not reserved and valid, but the platform - does not support it due to one or more missing - dependencies (Hardware or SBI implementation). +| SBI_ERR_NOT_SUPPORTED | `event_id` is not reserved and valid, but the + platform does not support it due to one or more + missing dependencies (Hardware or SBI + implementation). | SBI_ERR_INVALID_PARAM | `event_id` is invalid or `attr_count` is zero. -| SBI_ERR_BAD_RANGE | One of the event attribute in the range specified - by `base_attr_id` and `attr_count` does not exist - or is read-only. +| SBI_ERR_BAD_RANGE | One of the event attribute IDs in the range + specified by `base_attr_id` and `attr_count` is + reserved or is read-only. | SBI_ERR_INVALID_ADDRESS | The shared memory pointed to by the `input_phys_lo` and `input_phys_hi` parameters does not satisfy the requirements described in @@ -448,8 +452,8 @@ For global events, the event is registered for all the harts. The event MUST be in `UNUSED` state otherwise this function will fail. NOTE: It is advisable to use different values for `handler_entry_arg` for -different events because a higher priority event can preempt a lower priority -event. +different events because higher priority events preempt lower priority +events. Upon success, the event state moves from `UNUSED` to `REGISTERED`. In case of an error, possible error codes are listed in <> @@ -461,10 +465,12 @@ below. |=== | Error code | Description | SBI_SUCCESS | Event handler is registered successfully. -| SBI_ERR_NOT_SUPPORTED | `event` is not reserved and valid, but the platform - does not support it due to one or more missing - dependencies (Hardware or SBI implementation). -| SBI_ERR_INVALID_STATE | The event is not in `UNUSED` state. +| SBI_ERR_NOT_SUPPORTED | `event_id` is not reserved and valid, but the + platform does not support it due to one or more + missing dependencies (Hardware or SBI + implementation). +| SBI_ERR_INVALID_STATE | `event_id` is valid but the event is not in + `UNUSED` state. | SBI_ERR_INVALID_PARAM | `event_id` is invalid or `handler_entry_pc` is not 2-bytes aligned. |=== @@ -493,10 +499,12 @@ below. |=== | Error code | Description | SBI_SUCCESS | Event handler is unregistered successfully. -| SBI_ERR_NOT_SUPPORTED | `event` is not reserved and valid, but the platform - does not support it due to one or more missing - dependencies (Hardware or SBI implementation). -| SBI_ERR_INVALID_STATE | Event is not in `REGISTERED` state. +| SBI_ERR_NOT_SUPPORTED | `event_id` is not reserved and valid, but the + platform does not support it due to one or more + missing dependencies (Hardware or SBI + implementation). +| SBI_ERR_INVALID_STATE | `event_id` is valid but the event is not in + `REGISTERED` state. | SBI_ERR_INVALID_PARAM | `event_id` is invalid. |=== @@ -524,11 +532,13 @@ below. |=== | Error code | Description | SBI_SUCCESS | Event is successfully enabled. -| SBI_ERR_NOT_SUPPORTED | `event` is not reserved and valid, but the platform - does not support it due to one or more missing - dependencies (Hardware or SBI implementation). +| SBI_ERR_NOT_SUPPORTED | `event_id` is not reserved and valid, but the + platform does not support it due to one or more + missing dependencies (Hardware or SBI + implementation). | SBI_ERR_INVALID_PARAM | `event_id` is not valid. -| SBI_ERR_INVALID_STATE | The event is not in `REGISTERED` state. +| SBI_ERR_INVALID_STATE | `event_id` is valid but the event is not in + `REGISTERED` state. |=== === Function: Disable a software event (FID #5) @@ -555,11 +565,13 @@ below. |=== | Error code | Description | SBI_SUCCESS | Event is successfully disabled. -| SBI_ERR_NOT_SUPPORTED | `event` is not reserved and valid, but the platform - does not support it due to one or more missing - dependencies (Hardware or SBI implementation). +| SBI_ERR_NOT_SUPPORTED | `event_id` is not reserved and valid, but the + platform does not support it due to one or more + missing dependencies (Hardware or SBI + implementation). | SBI_ERR_INVALID_PARAM | `event_id` is not valid. -| SBI_ERR_INVALID_STATE | Event is not in `ENABLED` state. +| SBI_ERR_INVALID_STATE | `event_id` is valid but the event is not in + `ENABLED` state. |=== === Function: Complete software event handling (FID #6) @@ -584,8 +596,8 @@ interrupted supervisor state as decribed in <<_software_event_completion>>. struct sbiret sbi_sse_inject(uint32_t event_id, unsigned long hart_id) ---- -The supervisor software can inject a software event with the help of this -function. The `event_id` paramater refers to the event to be injected. +The supervisor software can inject a software event with this function. +The `event_id` paramater refers to the ID of the event to be injected. For local events, the `hart_id` parameter refers to the hart on which the event is to be injected. @@ -603,9 +615,10 @@ In case of an error, possible error codes are listed in |=== | Error code | Description | SBI_SUCCESS | Event is successfully injected. -| SBI_ERR_NOT_SUPPORTED | `event` is not reserved and valid, but the platform - does not support it due to one or more missing - dependencies (Hardware or SBI implementation). +| SBI_ERR_NOT_SUPPORTED | `event_id` is not reserved and valid, but the + platform does not support it due to one or more + missing dependencies (Hardware or SBI + implementation). | SBI_ERR_INVALID_PARAM | `event_id` or `hart_id` is invalid. | SBI_ERR_FAILED | The injection failed for unspecified or unknown other reasons. @@ -647,8 +660,8 @@ struct sbiret sbi_sse_hart_mask(void) ---- Stop receiving (or mask) software events on the calling hart. In other -words, the calling hart is not ready to receive software events from -the SBI implementation. +words, the calling hart will no longer be ready to receive software events +from the SBI implementation. In case of an error, possible error codes are listed in <> below.