Software APIs
Data Structures | Typedefs | Enumerations | Functions | Variables
dif_plic.h File Reference

(dcee03a)

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

Functions

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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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). More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

Variables

const uint32_t kDifPlicMinPriority
 The lowest interrupt priority.
 
const uint32_t kDifPlicMaxPriority
 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_plic.h.


Data Structure Documentation

◆ dif_plic_params

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.

◆ dif_plic

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 Documentation

◆ dif_plic_irq_id_t

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.

◆ 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.

◆ dif_plic_t

typedef struct dif_plic dif_plic_t

A handle to PLIC.

This type should be treated as opaque by users.

◆ dif_plic_target_t

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.

◆ 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.

Enumeration Type Documentation

◆ 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.

◆ dif_plic_result

The result of a PLIC operation.

Enumerator
kDifPlicOk 

Indicates that the operation succeeded.

kDifPlicError 

Indicates some unspecified failure.

kDifPlicBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

Definition at line 73 of file dif_plic.h.

◆ 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.

Function Documentation

◆ dif_plic_init()

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.

Parameters
paramsHardware instantiation parameters.
[out]plicOut param for the initialized handle.
Returns
The result of the operation.

Definition at line 169 of file dif_plic.c.

◆ dif_plic_irq_claim()

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.

See also
dif_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 300 of file dif_plic.c.

◆ dif_plic_irq_complete()

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.

See also
dif_plic_irq_claim
Parameters
plicA PLIC handle.
targetTarget that claimed the IRQ.
[out]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 313 of file dif_plic.c.

◆ dif_plic_irq_get_enabled()

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.

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 182 of file dif_plic.c.

◆ dif_plic_irq_is_pending()

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.

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 286 of file dif_plic.c.

◆ dif_plic_irq_set_enabled()

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.

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 200 of file dif_plic.c.

◆ dif_plic_irq_set_priority()

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.

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

Definition at line 258 of file dif_plic.c.

◆ dif_plic_irq_set_trigger()

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.

Parameters
plicA PLIC handle.
irqAn interrupt type.
triggerA trigger type.
Returns
The result of the operation.

Definition at line 230 of file dif_plic.c.

◆ dif_plic_software_irq_acknowledge()

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.

Parameters
plicPLIC state data.
targetTarget HART.
Returns
dif_plic_result_t.

Definition at line 342 of file dif_plic.c.

◆ dif_plic_software_irq_force()

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.

Parameters
plicPLIC state data.
targetTarget HART.
Returns
dif_plic_result_t.

Definition at line 330 of file dif_plic.c.

◆ dif_plic_software_irq_is_pending()

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.

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

Definition at line 354 of file dif_plic.c.

◆ dif_plic_target_set_threshold()

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.

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 272 of file dif_plic.c.