 |
Software APIs
|
|
Software APIs
|
PLIC Device Interface Functions More...
#include <stdbool.h>#include <stdint.h>#include "sw/device/lib/base/mmio.h"#include "sw/device/lib/dif/dif_warn_unused_result.h"Go to the source code of this file.
Data Structures | |
| struct | dif_plic_params |
| Hardware instantiation parameters for PLIC. More... | |
| struct | dif_plic |
| A handle to PLIC. More... | |
Typedefs | |
| typedef enum dif_plic_toggle | dif_plic_toggle_t |
| A toggle state: enabled, or disabled. More... | |
| typedef struct dif_plic_params | dif_plic_params_t |
| Hardware instantiation parameters for PLIC. More... | |
| typedef struct dif_plic | dif_plic_t |
| A handle to PLIC. More... | |
| typedef enum dif_plic_result | dif_plic_result_t |
| The result of a PLIC operation. | |
| typedef uint32_t | dif_plic_irq_id_t |
| A PLIC interrupt source identifier. More... | |
| typedef uint32_t | dif_plic_target_t |
| A PLIC interrupt target. More... | |
| typedef enum dif_plic_irq_trigger | dif_plic_irq_trigger_t |
| An interrupt trigger type. | |
Enumerations | |
| enum | dif_plic_toggle { kDifPlicToggleEnabled, kDifPlicToggleDisabled } |
| A toggle state: enabled, or disabled. More... | |
| enum | dif_plic_result { kDifPlicOk = 0, kDifPlicError = 1, kDifPlicBadArg = 2 } |
| The result of a PLIC operation. More... | |
| enum | dif_plic_irq_trigger { kDifPlicIrqTriggerEdge, kDifPlicIrqTriggerLevel } |
| An interrupt trigger type. More... | |
Variables | |
| const uint32_t | kDifPlicMinPriority |
| The lowest interrupt priority. | |
| const uint32_t | kDifPlicMaxPriority |
| The highest interrupt priority. | |
PLIC Device Interface Functions
The PLIC should be largely compatible with the (currently draft) RISC-V PLIC specification, but tailored for the OpenTitan rv_plic register addresses. We intend to make the addresses compatible with the PLIC specification in the near future.
Definition in file dif_plic.h.
| struct dif_plic_params |
Hardware instantiation parameters for PLIC.
This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.
Definition at line 54 of file dif_plic.h.
| Data Fields | ||
|---|---|---|
| mmio_region_t | base_addr | The base address for the PLIC hardware registers. |
| struct dif_plic |
A handle to PLIC.
This type should be treated as opaque by users.
Definition at line 66 of file dif_plic.h.
| Data Fields | ||
|---|---|---|
| dif_plic_params_t | params | |
| typedef uint32_t dif_plic_irq_id_t |
A PLIC interrupt source identifier.
This corresponds to a specific interrupt, and not the device it originates from.
This is an unsigned 32-bit value that is at least zero and is less than the NumSrc instantiation parameter of the rv_plic device.
The value 0 corresponds to "No Interrupt".
Definition at line 112 of file dif_plic.h.
| typedef struct dif_plic_params dif_plic_params_t |
Hardware instantiation parameters for PLIC.
This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.
| typedef struct dif_plic dif_plic_t |
A handle to PLIC.
This type should be treated as opaque by users.
| typedef uint32_t dif_plic_target_t |
A PLIC interrupt target.
This corresponds to a specific system that can service an interrupt. In OpenTitan's case, that is the Ibex core. If there were multiple cores in the system, each core would have its own specific interrupt target ID.
This is an unsigned 32-bit value that is at least 0 and is less than the NumTarget instantiation parameter of the rv_plic device.
Definition at line 124 of file dif_plic.h.
| typedef enum dif_plic_toggle dif_plic_toggle_t |
A toggle state: enabled, or disabled.
This enum may be used instead of a bool when describing an enabled/disabled state.
| enum dif_plic_irq_trigger |
An interrupt trigger type.
| Enumerator | |
|---|---|
| kDifPlicIrqTriggerEdge | Trigger on an edge (when the signal changes from low to high). |
| kDifPlicIrqTriggerLevel | Trigger on a level (when the signal remains high). |
Definition at line 129 of file dif_plic.h.
| enum dif_plic_result |
The result of a PLIC operation.
Definition at line 73 of file dif_plic.h.
| enum dif_plic_toggle |
A toggle state: enabled, or disabled.
This enum may be used instead of a bool when describing an enabled/disabled state.
| Enumerator | |
|---|---|
| kDifPlicToggleDisabled | The "disabled" state. |
Definition at line 36 of file dif_plic.h.
| DIF_WARN_UNUSED_RESULT dif_plic_result_t dif_plic_init | ( | dif_plic_params_t | params, |
| dif_plic_t * | plic | ||
| ) |
Creates a new handle for PLIC.
This function does not actuate the hardware.
| params | Hardware instantiation parameters. | |
| [out] | plic | Out param for the initialized handle. |
Definition at line 169 of file dif_plic.c.
| DIF_WARN_UNUSED_RESULT dif_plic_result_t dif_plic_irq_claim | ( | const dif_plic_t * | plic, |
| dif_plic_target_t | target, | ||
| dif_plic_irq_id_t * | claim_data | ||
| ) |
Claims an IRQ and gets the information about the source.
Claims an IRQ and returns the IRQ related data to the caller. This function reads a target specific Claim/Complete register. dif_plic_irq_complete must be called in order to allow another interrupt with the same source id to be delivered. This usually would be done once the interrupt has been serviced.
Another IRQ can be claimed before a prior IRQ is completed. In this way, this functionality is compatible with nested interrupt handling. The restriction is that you must Complete a Claimed IRQ before you will be able to claim an IRQ with the same ID. This allows a pair of Claim/Complete calls to be overlapped with another pair – and there is no requirement that the interrupts should be Completed in the reverse order of when they were Claimed.
| plic | A PLIC handle. | |
| target | Target that claimed the IRQ. | |
| [out] | claim_data | Data that describes the origin of the IRQ. |
Definition at line 300 of file dif_plic.c.
| DIF_WARN_UNUSED_RESULT dif_plic_result_t dif_plic_irq_complete | ( | const dif_plic_t * | plic, |
| dif_plic_target_t | target, | ||
| const dif_plic_irq_id_t * | complete_data | ||
| ) |
Completes the claimed IRQ.
Finishes servicing of the claimed IRQ by writing the IRQ source ID back to a target specific Claim/Complete register. This function must be called after dif_plic_irq_claim, when the caller is prepared to service another IRQ with the same source ID. If a source ID is never Completed, then when future interrupts are Claimed, they will never have the source ID of the uncompleted IRQ.
| plic | A PLIC handle. | |
| target | Target that claimed the IRQ. | |
| [out] | complete_data | Previously claimed IRQ data that is used to signal PLIC of the IRQ servicing completion. |
Definition at line 313 of file dif_plic.c.
| DIF_WARN_UNUSED_RESULT dif_plic_result_t dif_plic_irq_get_enabled | ( | const dif_plic_t * | plic, |
| dif_plic_irq_id_t | irq, | ||
| dif_plic_target_t | target, | ||
| dif_plic_toggle_t * | state | ||
| ) |
Checks whether a particular interrupt is currently enabled or disabled.
| plic | A PLIC handle. | |
| irq | An interrupt type. | |
| target | An interrupt target. | |
| [out] | state | Out-param toggle state of the interrupt. |
Definition at line 182 of file dif_plic.c.
| DIF_WARN_UNUSED_RESULT dif_plic_result_t dif_plic_irq_is_pending | ( | const dif_plic_t * | plic, |
| dif_plic_irq_id_t | irq, | ||
| bool * | is_pending | ||
| ) |
Returns whether a particular interrupt is currently pending.
| plic | A PLIC handle. | |
| irq | An interrupt type. | |
| [out] | is_pending | Out-param for whether the interrupt is pending. |
Definition at line 286 of file dif_plic.c.
| DIF_WARN_UNUSED_RESULT dif_plic_result_t dif_plic_irq_set_enabled | ( | const dif_plic_t * | plic, |
| dif_plic_irq_id_t | irq, | ||
| dif_plic_target_t | target, | ||
| dif_plic_toggle_t | state | ||
| ) |
Sets whether a particular interrupt is currently enabled or disabled.
This operation does not affect IRQ generation in target, which must be configured in the corresponding peripheral itself.
| plic | A PLIC handle. |
| irq | An interrupt type. |
| target | An interrupt target. |
| state | The new toggle state for the interrupt. |
Definition at line 200 of file dif_plic.c.
| DIF_WARN_UNUSED_RESULT dif_plic_result_t dif_plic_irq_set_priority | ( | const dif_plic_t * | plic, |
| dif_plic_irq_id_t | irq, | ||
| uint32_t | priority | ||
| ) |
Sets IRQ source priority (0-3).
In order for the PLIC to set a Claim/Complete register and assert the external interrupt line to the target (Ibex, ...), the priority of the IRQ source must be higher than the threshold for this source.
| plic | A PLIC handle. |
| irq | An interrupt type. |
| priority | Priority to set. |
Definition at line 258 of file dif_plic.c.
| DIF_WARN_UNUSED_RESULT dif_plic_result_t dif_plic_irq_set_trigger | ( | const dif_plic_t * | plic, |
| dif_plic_irq_id_t | irq, | ||
| dif_plic_irq_trigger_t | trigger | ||
| ) |
Sets the IRQ trigger type.
Sets the behaviour of the Interrupt Gateway for a particular IRQ to be edge or level triggered.
| plic | A PLIC handle. |
| irq | An interrupt type. |
| trigger | A trigger type. |
Definition at line 230 of file dif_plic.c.
| DIF_WARN_UNUSED_RESULT dif_plic_result_t dif_plic_software_irq_acknowledge | ( | const dif_plic_t * | plic, |
| dif_plic_target_t | target | ||
| ) |
Acknowledges the software interrupt for a particular target.
This function indicates to the hardware that the software interrupt has been successfully serviced. It is expected to be called from a software interrupt handler.
| plic | PLIC state data. |
| target | Target HART. |
dif_plic_result_t. Definition at line 342 of file dif_plic.c.
| DIF_WARN_UNUSED_RESULT dif_plic_result_t dif_plic_software_irq_force | ( | const dif_plic_t * | plic, |
| dif_plic_target_t | target | ||
| ) |
Forces the software interrupt for a particular target.
This function causes an interrupt to the target HART to be serviced as if hardware had asserted it.
This function allows to synchronise between the HARTs, which otherwise would not be possible due to HART being only able to access own CSRs. NOTE: this is not an issue on Ibex, as it has only one HART.
An interrupt handler is expected to call dif_plic_software_irq_acknowledge when the interrupt has been handled.
| plic | PLIC state data. |
| target | Target HART. |
dif_plic_result_t. Definition at line 330 of file dif_plic.c.
| DIF_WARN_UNUSED_RESULT dif_plic_result_t dif_plic_software_irq_is_pending | ( | const dif_plic_t * | plic, |
| dif_plic_target_t | target, | ||
| bool * | is_pending | ||
| ) |
Returns software interrupt pending state for a particular target.
| plic | PLIC state data. | |
| target | Target HART. | |
| [out] | is_pending | Flag indicating whether the interrupt is pending. |
dif_plic_result_t. Definition at line 354 of file dif_plic.c.
| DIF_WARN_UNUSED_RESULT dif_plic_result_t dif_plic_target_set_threshold | ( | const dif_plic_t * | plic, |
| dif_plic_target_t | target, | ||
| uint32_t | threshold | ||
| ) |
Sets the target priority threshold.
Sets the target priority threshold. PLIC will only interrupt a target when IRQ source priority is set higher than the priority threshold for the corresponding target.
| plic | A PLIC handle. |
| target | Target to set the IRQ priority threshold for. |
| threshold | IRQ priority threshold to be set. |
Definition at line 272 of file dif_plic.c.