sw/device/lib/dif/dif_rv_plic.h - 3p/lowrisc/opentitan - Git at Google

 // Copyright lowRISC contributors.
 // Licensed under the Apache License, Version 2.0, see LICENSE for details.
 // SPDX-License-Identifier: Apache-2.0

 #ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_RV_PLIC_H_
 #define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_RV_PLIC_H_

 /**
  * @file
  * @brief <a href="/hw/ip/rv_plic/doc/">PLIC</a> Device Interface Functions
  *
  * The PLIC should be largely compatible with the (currently draft) [RISC-V PLIC
  * specification][plic], but tailored for the OpenTitan rv_plic register
  * addresses. We intend to make the addresses compatible with the PLIC
  * specification in the near future.
  *
  * [plic]: https://github.com/riscv/riscv-plic-spec/blob/master/riscv-plic.adoc
  */

 #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"

 #ifdef __cplusplus
 extern "C" {
 #endif  // __cplusplus

 /**
  * The lowest interrupt priority.
  */
 extern const uint32_t kDifRvPlicMinPriority;

 /**
  * The highest interrupt priority.
  */
 extern const uint32_t kDifRvPlicMaxPriority;

 /**
  * 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".
  */
 typedef uint32_t dif_rv_plic_irq_id_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.
  */
 typedef uint32_t dif_rv_plic_target_t;

 /**
  * 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.
  *
  * @param plic A PLIC handle.
  * @return The result of the operation.
  */
 OT_WARN_UNUSED_RESULT
 dif_result_t dif_rv_plic_reset(const dif_rv_plic_t *plic);

 /**
  * Returns whether a particular interrupt is currently pending.
  *
  * @param plic A PLIC handle.
  * @param irq An interrupt type.
  * @param[out] is_pending Out-param for whether the interrupt is pending.
  * @return The result of the operation.
  */
 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);

 /**
  * Checks whether a particular interrupt is currently enabled or disabled.
  *
  * @param plic A PLIC handle.
  * @param irq An interrupt type.
  * @param target An interrupt target.
  * @param[out] state Out-param toggle state of the interrupt.
  * @return The result of the operation.
  */
 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);

 /**
  * 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.
  *
  * @param plic A PLIC handle.
  * @param irq An interrupt type.
  * @param target An interrupt target.
  * @param state The new toggle state for the interrupt.
  * @return The result of the operation.
  */
 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 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.
  *
  * @param plic A PLIC handle.
  * @param irq An interrupt type.
  * @param priority Priority to set.
  * @return The result of the operation.
  */
 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 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.
  *
  * @param plic A PLIC handle.
  * @param target Target to set the IRQ priority threshold for.
  * @param threshold IRQ priority threshold to be set.
  * @return The result of the operation.
  */
 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);

 /**
  * 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 #dif_rv_plic_irq_complete
  *
  * @param plic A PLIC handle.
  * @param target Target that claimed the IRQ.
  * @param[out] claim_data Data that describes the origin of the IRQ.
  * @return The result of the operation.
  */
 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);

 /**
  * 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 #dif_rv_plic_irq_claim
  *
  * @param plic A PLIC handle.
  * @param target Target that claimed the IRQ.
  * @param complete_data Previously claimed IRQ data that is used to signal
  *        PLIC of the IRQ servicing completion.
  * @return The result of the operation.
  */
 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);

 /**
  * 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.
  *
  * @param plic PLIC state data.
  * @param target Target HART.
  * @return `dif_result_t`.
  */
 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);

 /**
  * 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.
  *
  * @param plic PLIC state data.
  * @param target Target HART.
  * @return `dif_result_t`.
  */
 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);

 /**
  * Returns software interrupt pending state for a particular target.
  *
  * @param plic PLIC state data.
  * @param target Target HART.
  * @param[out] is_pending Flag indicating whether the interrupt is pending.
  * @return `dif_result_t`.
  */
 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);

 #ifdef __cplusplus
 }  // extern "C"
 #endif  // __cplusplus

 #endif  // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_RV_PLIC_H_
	// Copyright lowRISC contributors.
	// Licensed under the Apache License, Version 2.0, see LICENSE for details.
	// SPDX-License-Identifier: Apache-2.0

	#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_RV_PLIC_H_
	#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_RV_PLIC_H_

	/**
	* @file
	* @brief <a href="/hw/ip/rv_plic/doc/">PLIC</a> Device Interface Functions
	*
	* The PLIC should be largely compatible with the (currently draft) [RISC-V PLIC
	* specification][plic], but tailored for the OpenTitan rv_plic register
	* addresses. We intend to make the addresses compatible with the PLIC
	* specification in the near future.
	*
	* [plic]: https://github.com/riscv/riscv-plic-spec/blob/master/riscv-plic.adoc
	*/

	#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"

	#ifdef __cplusplus
	extern "C" {
	#endif // __cplusplus

	/**
	* The lowest interrupt priority.
	*/
	extern const uint32_t kDifRvPlicMinPriority;

	/**
	* The highest interrupt priority.
	*/
	extern const uint32_t kDifRvPlicMaxPriority;

	/**
	* 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".
	*/
	typedef uint32_t dif_rv_plic_irq_id_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.
	*/
	typedef uint32_t dif_rv_plic_target_t;

	/**
	* 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.
	*
	* @param plic A PLIC handle.
	* @return The result of the operation.
	*/
	OT_WARN_UNUSED_RESULT
	dif_result_t dif_rv_plic_reset(const dif_rv_plic_t *plic);

	/**
	* Returns whether a particular interrupt is currently pending.
	*
	* @param plic A PLIC handle.
	* @param irq An interrupt type.
	* @param[out] is_pending Out-param for whether the interrupt is pending.
	* @return The result of the operation.
	*/
	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);

	/**
	* Checks whether a particular interrupt is currently enabled or disabled.
	*
	* @param plic A PLIC handle.
	* @param irq An interrupt type.
	* @param target An interrupt target.
	* @param[out] state Out-param toggle state of the interrupt.
	* @return The result of the operation.
	*/
	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);

	/**
	* 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.
	*
	* @param plic A PLIC handle.
	* @param irq An interrupt type.
	* @param target An interrupt target.
	* @param state The new toggle state for the interrupt.
	* @return The result of the operation.
	*/
	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 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.
	*
	* @param plic A PLIC handle.
	* @param irq An interrupt type.
	* @param priority Priority to set.
	* @return The result of the operation.
	*/
	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 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.
	*
	* @param plic A PLIC handle.
	* @param target Target to set the IRQ priority threshold for.
	* @param threshold IRQ priority threshold to be set.
	* @return The result of the operation.
	*/
	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);

	/**
	* 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 #dif_rv_plic_irq_complete
	*
	* @param plic A PLIC handle.
	* @param target Target that claimed the IRQ.
	* @param[out] claim_data Data that describes the origin of the IRQ.
	* @return The result of the operation.
	*/
	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);

	/**
	* 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 #dif_rv_plic_irq_claim
	*
	* @param plic A PLIC handle.
	* @param target Target that claimed the IRQ.
	* @param complete_data Previously claimed IRQ data that is used to signal
	* PLIC of the IRQ servicing completion.
	* @return The result of the operation.
	*/
	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);

	/**
	* 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.
	*
	* @param plic PLIC state data.
	* @param target Target HART.
	* @return `dif_result_t`.
	*/
	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);

	/**
	* 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.
	*
	* @param plic PLIC state data.
	* @param target Target HART.
	* @return `dif_result_t`.
	*/
	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);

	/**
	* Returns software interrupt pending state for a particular target.
	*
	* @param plic PLIC state data.
	* @param target Target HART.
	* @param[out] is_pending Flag indicating whether the interrupt is pending.
	* @return `dif_result_t`.
	*/
	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);

	#ifdef __cplusplus
	} // extern "C"
	#endif // __cplusplus

	#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_RV_PLIC_H_