Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ext-sse: Fixes #194

Merged
merged 6 commits into from
Jan 24, 2025
Merged

ext-sse: Fixes #194

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0b05ce1
ext-sse: Require implementations to zero reserved bits
jones-drew Jan 16, 2025
665b20f
ext-sse: Capitalize ID
jones-drew Jan 16, 2025
f3cb6ca
ext-sse: Distinguish events/attributes from their IDs
jones-drew Jan 16, 2025
a901c78
ext-sse: Make some miscellaneous text improvements
jones-drew Jan 16, 2025
2c64cb2
ext-sse: Replace 'can' when it's inappropriate
jones-drew Jan 16, 2025
233cd16
ext-sse: Clarify SBI_ERR_INVALID_STATE
jones-drew Jan 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 66 additions & 53 deletions src/ext-sse.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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 <<table_sse_event_attributes>> below provides a list
event attributes.

Expand Down Expand Up @@ -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.

Expand All @@ -184,16 +185,16 @@ 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.

| PREFERRED_HART
| 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. +
Expand Down Expand Up @@ -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
Expand All @@ -269,7 +270,7 @@ event attributes.
| RESERVED
| > 0x00000009
| ---
| Reserved for future use
| Reserved for future use.
|===

=== Software Event Injection
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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 <<table_sse_register_errors>>
Expand All @@ -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.
|===
Expand Down Expand Up @@ -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.
|===

Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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
<<table_sse_hard_mask_errors>> below.
Expand Down
Loading