Software APIs
Typedefs | Functions | Variables
dif_rv_plic.h File Reference

(f166105)

PLIC Device Interface Functions More...

#include <stdbool.h>
#include <stdint.h>
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_rv_plic_autogen.h"

Go to the source code of this file.

Typedefs

typedef uint32_t dif_rv_plic_irq_id_t
 A PLIC interrupt source identifier. More...
 
typedef uint32_t dif_rv_plic_target_t
 A PLIC interrupt target. More...
 

Functions

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_reset (const dif_rv_plic_t *plic)
 Resets the PLIC to a clean state. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_irq_is_pending (const dif_rv_plic_t *plic, dif_rv_plic_irq_id_t irq, bool *is_pending)
 Returns whether a particular interrupt is currently pending. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_irq_get_enabled (const dif_rv_plic_t *plic, dif_rv_plic_irq_id_t irq, dif_rv_plic_target_t target, dif_toggle_t *state)
 Checks whether a particular interrupt is currently enabled or disabled. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_irq_set_enabled (const dif_rv_plic_t *plic, dif_rv_plic_irq_id_t irq, dif_rv_plic_target_t target, dif_toggle_t state)
 Sets whether a particular interrupt is currently enabled or disabled. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_irq_set_priority (const dif_rv_plic_t *plic, dif_rv_plic_irq_id_t irq, uint32_t priority)
 Sets IRQ source priority (0-3). More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_target_set_threshold (const dif_rv_plic_t *plic, dif_rv_plic_target_t target, uint32_t threshold)
 Sets the target priority threshold. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_irq_claim (const dif_rv_plic_t *plic, dif_rv_plic_target_t target, dif_rv_plic_irq_id_t *claim_data)
 Claims an IRQ and gets the information about the source. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_irq_complete (const dif_rv_plic_t *plic, dif_rv_plic_target_t target, dif_rv_plic_irq_id_t complete_data)
 Completes the claimed IRQ. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_software_irq_force (const dif_rv_plic_t *plic, dif_rv_plic_target_t target)
 Forces the software interrupt for a particular target. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_software_irq_acknowledge (const dif_rv_plic_t *plic, dif_rv_plic_target_t target)
 Acknowledges the software interrupt for a particular target. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_software_irq_is_pending (const dif_rv_plic_t *plic, dif_rv_plic_target_t target, bool *is_pending)
 Returns software interrupt pending state for a particular target. More...
 

Variables

const uint32_t kDifRvPlicMinPriority
 The lowest interrupt priority.
 
const uint32_t kDifRvPlicMaxPriority
 The highest interrupt priority.
 

Detailed Description

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_rv_plic.h.

Typedef Documentation

◆ dif_rv_plic_irq_id_t

typedef uint32_t dif_rv_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 54 of file dif_rv_plic.h.

◆ dif_rv_plic_target_t

typedef uint32_t dif_rv_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 66 of file dif_rv_plic.h.

Function Documentation

◆ dif_rv_plic_irq_claim()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_irq_claim ( const dif_rv_plic_t plic,
dif_rv_plic_target_t  target,
dif_rv_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_rv_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.

See also
dif_rv_plic_irq_complete
Parameters
plicA PLIC handle.
targetTarget that claimed the IRQ.
[out]claim_dataData that describes the origin of the IRQ.
Returns
The result of the operation.

Definition at line 242 of file dif_rv_plic.c.

◆ dif_rv_plic_irq_complete()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_irq_complete ( const dif_rv_plic_t plic,
dif_rv_plic_target_t  target,
dif_rv_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_rv_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.

See also
dif_rv_plic_irq_claim
Parameters
plicA PLIC handle.
targetTarget that claimed the IRQ.
complete_dataPreviously claimed IRQ data that is used to signal PLIC of the IRQ servicing completion.
Returns
The result of the operation.

Definition at line 256 of file dif_rv_plic.c.

◆ dif_rv_plic_irq_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_irq_get_enabled ( const dif_rv_plic_t plic,
dif_rv_plic_irq_id_t  irq,
dif_rv_plic_target_t  target,
dif_toggle_t state 
)

Checks whether a particular interrupt is currently enabled or disabled.

Parameters
plicA PLIC handle.
irqAn interrupt type.
targetAn interrupt target.
[out]stateOut-param toggle state of the interrupt.
Returns
The result of the operation.

Definition at line 152 of file dif_rv_plic.c.

◆ dif_rv_plic_irq_is_pending()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_irq_is_pending ( const dif_rv_plic_t plic,
dif_rv_plic_irq_id_t  irq,
bool *  is_pending 
)

Returns whether a particular interrupt is currently pending.

Parameters
plicA PLIC handle.
irqAn interrupt type.
[out]is_pendingOut-param for whether the interrupt is pending.
Returns
The result of the operation.

Definition at line 228 of file dif_rv_plic.c.

◆ dif_rv_plic_irq_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_irq_set_enabled ( const dif_rv_plic_t plic,
dif_rv_plic_irq_id_t  irq,
dif_rv_plic_target_t  target,
dif_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.

Parameters
plicA PLIC handle.
irqAn interrupt type.
targetAn interrupt target.
stateThe new toggle state for the interrupt.
Returns
The result of the operation.

Definition at line 170 of file dif_rv_plic.c.

◆ dif_rv_plic_irq_set_priority()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_irq_set_priority ( const dif_rv_plic_t plic,
dif_rv_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.

Parameters
plicA PLIC handle.
irqAn interrupt type.
priorityPriority to set.
Returns
The result of the operation.

Definition at line 200 of file dif_rv_plic.c.

◆ dif_rv_plic_reset()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_reset ( const dif_rv_plic_t plic)

Resets the PLIC to a clean state.

This function resets all the relevant PLIC registers, apart from the CC register. There is no reliable way of knowing the ID of an IRQ that has claimed the CC register, so we assume that the previous "owner" of the resource has cleared/completed the CC access.

Parameters
plicA PLIC handle.
Returns
The result of the operation.

Definition at line 119 of file dif_rv_plic.c.

◆ dif_rv_plic_software_irq_acknowledge()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_software_irq_acknowledge ( const dif_rv_plic_t plic,
dif_rv_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.

Parameters
plicPLIC state data.
targetTarget HART.
Returns
dif_result_t.

Definition at line 283 of file dif_rv_plic.c.

◆ dif_rv_plic_software_irq_force()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_software_irq_force ( const dif_rv_plic_t plic,
dif_rv_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_rv_plic_software_irq_acknowledge when the interrupt has been handled.

Parameters
plicPLIC state data.
targetTarget HART.
Returns
dif_result_t.

Definition at line 271 of file dif_rv_plic.c.

◆ dif_rv_plic_software_irq_is_pending()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_software_irq_is_pending ( const dif_rv_plic_t plic,
dif_rv_plic_target_t  target,
bool *  is_pending 
)

Returns software interrupt pending state for a particular target.

Parameters
plicPLIC state data.
targetTarget HART.
[out]is_pendingFlag indicating whether the interrupt is pending.
Returns
dif_result_t.

Definition at line 295 of file dif_rv_plic.c.

◆ dif_rv_plic_target_set_threshold()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_plic_target_set_threshold ( const dif_rv_plic_t plic,
dif_rv_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.

Parameters
plicA PLIC handle.
targetTarget to set the IRQ priority threshold for.
thresholdIRQ priority threshold to be set.
Returns
The result of the operation.

Definition at line 214 of file dif_rv_plic.c.