Why does the PLIC not support interrupt masking? Interrupts can only be enabled/disabled or claimed and completed. It would be nice to have an explanation why explicit masking is not needed and/or implementing this discouraged. It is a trade-off to reduce gate count because it should happen in software?

What's the expected behaviour of reserved addresses?
WARZ, return SLVERR, something else, or implementation defined?

'fi', 'ff', 'fl' and maybe other ligatures may appear as blank glyphs in the PDF.

Figure 2 draws a distinction between the PLIC core and PLIC gateways. Are the latter intended to be defined in the PLIC spec? If so, what is the intended functionality of the gateway and does software have an interface to those gateways?

Note that the claim register implies that the gateway masks the "Interrupt N Signals" and thus deasserts the "Interrupt Request" signal and clears the "Source's IP" signal (assuming IP = interrupt pending). Does a corresponding access to the complete register reverse this process, i.e. unmask the "Interrupt N Signals," which possibly asserts the "Interrupt Request" and "Source's IP" signal, if the "Interrupt N Signals" are still asserted?

Finally, what are the signalling requirements for "Interrupt N Signals" to the gateways? Is the assignment of polarity and level vs. edge to each input signal external to the PLIC spec?

After chatting with some vendors in the RISC-V community and learning a bit of the story behind this, I wanted to suggest a revision to the PLIC spec to remove some ambiguity.

The spec states that interrupt gateways can be level or edge triggered. Some implementations use a fully static configuration that is non-configurable and only supports e.g. level triggers. This might be fine for certain controllers. For more general-purpose designs, many customers require both level and edge triggering, as well as runtime configuration (high / low, rising / falling / both) of individual interrupts.

Many vendors have populated those registers at offset 0x1080, based on (IIRC) SIFive's work. In some cases, those registers are read-only (registers are for informational purposes only), while in other designs, the registers are writeable. In some cases, the registers are there but they are undocumented (even in the vendor data sheet).

This results in some fragmentation (especially noticeable with new, vendor-specific Devicetree bindings). From a firmware / kernel perspective, we don't want 1000 flavours of PLIC drivers. We want a single driver with 1 main Devicetree compatible. It's still OK for vendors to differentiate their interrupt gateways via functionality encoded in other mapped registers. But for the basics (which includes interrupt trigger configuration), it would be great to have a main compatible. We don't want RISC-V's Devicetree bindings to be deprecated, it should be more or less authoritative.

In any case, It would be very much in the interest of the community to remove this ambiguity from the RISC-V PLIC spec. So I would recommend at least the following

1. naming the address range in the memory map
2. outlining the desired functionality of those registers if they are implemented
3. bumping the revision of the PLIC spec
4. ensuring that vendors are aware that they must document how their interrupt gateway behaves.

There are other ways of doing this as well, but the above is the least invasive way that I can think of. It also allows existing vendors to continue with business as usual.

Other ways to solve this are runtime oriented

• an ID register (mentioned already in #40) with some bits set aside to enumerate the trigger control type
• writing and reading back a bit pattern on init (mentioned in #51)

The latter runtime approach depends on read / write semantics (is a fault triggered on write to reserved memory? Are writes ignored?). This is kind of a slippery-slope approach.

The ID register is at least something that can be queried during bringup and encoded offline (we don't want to add extra cycles to interrupt processing). However, that is an invasive change, because it is not backwards-compatible and requires a new register added to the memory map.

Obviously though, if vendors are required to clearly document the type of interrupt trigger configuration / control in their implementation, that should be fine (assuming one always knows the PLIC implementation). From the Devicetree perspective, this is just an enumeration, and a new PLIC spec revision could be made that is backward compatible.

However, in the case of a generic PLIC driver for e.g. Linux, where one does not know who implemented the PLIC or its characteristics, reading a few bits from an ID register at runtime would be the easiest / safest way.

The PLIC memory map requires 64MB of memory mapped system address space (26b), largely because the threshold and claim/complete registers are sparsely populated (one 4KB region per context).

Why are these registers spread apart in the address map when the other per-context control registers are not also spread apart? For example, the per-context interrupt enable bits are packed together in the address space.

Also the threshold and claim/complete registers for context 15871 should be at the base address of 0x5DFF000 (if my math is correct), which implies an even larger address space requirement.

Hi,

Could someone please clarify the following issues, which are not clear to me from the spec as-is:

Clarification 1 - Does interrupt priority 0 ('effectively' disabling the interrupt) prevent the interrupt source from showing in the claim register?

The claim register states that:

the claim operation is not affected by the setting of the priority threshold register

The interrupt priority register states that:

A priority value of 0 is reserved to mean ''never interrupt'' and effectively disables the interrupt

Figure 2 has the source interrupt priority AND'd with interrupt pending - but it is not entirely clear if this is meant to just gate priority when pending is not set, or if pending is also gated when priority is 0. I've seen this interpreted both ways.

Clarification 2 - Interrupt pending is per-source, but figure 2 has labelled the per-context EIP as "Interrupt Pending". Is the diagram wrong here, or is interrupt pending only meant to have bits set for interrupt sources which are being presented to the context?

From the wording of the spec I expect that the diagram is wrong, since the interrupt pending register specifically states:

A pending bit in the PLIC core can be cleared by setting the associated enable bit then performing a claim.

which implies that a pending bit can be seen without being enabled for a context.

Thanks!

According to the description in text. In Figure 3, "Source's IP" should be marked in light blue, while "EIP" should not be marked.
In addition, the 'Interrupt Pending' pointing to EIP is confusing. I suggest that specs need to have a clearer distinction between 'EIP' and 'IP'.

What is the range of priority levels supported by the PLIC? Is there a max number?

Hello everyone!
I have question regarding plic interrupt priorities and interrupt selection.
According to plic documentation. it selects interrupts based on priorities if there are multiple interrupts, the interrupt with highest priority will be serviced.
But, here comes the confusion. how it is possible to have multiple interrupts at the same instant of time in single hardware thread environment.
we know that our high level language is sequential in nature. lets take an example. i have two API's for gpio and spi.

int main()
{
int a, b;
a = gpio_read();
b = spi_read();
}
in above example a will have the value of any gpio pin and b will have value read from spi.
whenever i call the gpio_read it will configure gpio modue, plic and core for interrupts and after handing it will disable them. same goes for spi, because the code is sequential in nature i wont get any interrupt from spi until gpio is serviced.
so, my question is in which condition we can have multiple interrupts at same instant of time in single thread environment??

Section 6 lists the PLIC addresses for the IE bits as follows:

0x002000: Interrupt Source #0 to #31 Enable Bits on context 0
...
0x00207F: Interrupt Source #992 to #1023 Enable Bits 

(and so on).

Since each interrupt enable register is four byte wide (as it holds 32 bits of enables), the base address for the Interrupt Source #992 to #1023 Enable Bits should be 0x00207C, not 0x00207F (the same change is required for the other contexts shown).

While the riscv-plic.adoc file references the project is licensed under the CC-BY-4.0 license and provides a link to the full license text. the lack of a LICENSE file prevent GitHub from recognizing the license.

I propose adding a plain text LICENSE file like the one used in the ISA manual.

I'm happy to add this into the project directly and will do so in the coming days. If anyone has concerns, please raise them.

Thanks,
-Jeff

Would it be possible to make a PDF and/or HTML version of the PLIC document available in a Github release, as is done for other riscv specs (e.g. riscv-v-spec and riscv-isa-manual)

The PLIC spec refers to "contexts" in many places but the term is not clearly defined.

Are these truly software contexts, i.e. software threads? Or does context refer to harts?

If the former, how does one direct different contexts onto a single hart? If the latter, why not refer to them as harts in the document?

Also, how does one map a context to different modes, e.g. S-mode or M-mode?

Hello,
reading through the plic specification for the first time, I was wondering if the wording for claim and complete (chapters 8 and 9) is incorrect.

Chapter 8 says "The PLIC can perform an interrupt claim by reading the claim/complete register". Isn't it the target (a hart context) that reads the register?
The same goes for chapter 9 "The PLIC signals it has completed executing an interrupt handler by writing ...". Yet again, I guess it is the target that executes the handler and writes the register.

I'm happy to submit a PR if this needs fixing (and is not simply a misunderstanding on my part).

Original:
base + 0x3FFE000: Priority threshold for context 15871
base + 0x3FFE004: Claim/complete for context 15871
base + 0x3FFE008: Reserved

It should be:
base + 0x3FFF000: Priority threshold for context 15871
base + 0x3FFF004: Claim/complete for context 15871
base + 0x3FFF008: Reserved

My confusion is related to this statement:

If the completion ID does not match an interrupt source that is currently enabled for the target, the completion is silently ignored.

For realtime reason, an level triggered IRQ (ASAIK, all PLIC IRQs are level triggered) handler may not be able to complete an IRQ in time in the IRQ context. The hardware driver may choose to defer handling this IRQ in the task context. And the driver code may look like:

irq_irq_handler()
{
  mask irq
  schedule task_irq_handler
}

task_irq_handler()
{
  handle irq
  ack irq (clear irq)
  unmask irq
}

An IRQ controller that is ARM GIC like has claim/completion process.

As far as I know, there are GIC vendor variations implementing GICv2 in the way that if an IRQ is not completed and the IRQ handler returns, other IRQs that have same priority cannot arrive to the same CPU unless the previous claimed IRQ is completed. In order not to block other IRQs when an IRQ is handling in the deferred way, OSen will implement GIC like driver in this way:

gic_handle_irq()
{
  claim irq
  call irq_irq_hanlder
  complete irq
}

Then we clearly can see a sequence (sequence A) that:

claim irq
mask irq
complete irq
handle irq
ack irq (clear irq)
unmask irq

However if GIC allows other IRQs in the same priority arrive when one of them is not completed but claimed, the sequence (sequence B) can be:

claim irq
mask irq
handle irq
ack irq (clear irq)
unmask irq
eoi irq (complete irq)

This makes senses, but the SPEC also has no statement about this sequence. And hardware vendor may provide GIC like implementation.

So my questions are:

1. Which style is PLIC completion preferred? And if the sequence B is preferred, should it be stated in the SPEC?
2. If sequence A is preferred, can the statement in question be detailed for the deferred handling cases? How such case is meant to be handled in the PLIC environment.

The interrupt completion section may be unclear and appears to include implementation details of the SiFive PLIC as opposed to a specification. The wording in question is:

The PLIC does not check whether the completion ID is the same as the last claim ID for that target. If the completion ID does not match an interrupt source that is currently enabled for the target, the completion is silently ignored.

See https://lists.infradead.org/pipermail/linux-riscv/2021-October/009222.html for some background

For example, following link doesn't exist.

image::https://github.com/riscv/riscv-plic-spec/blob/UNIX-PLIC-Spec/Images/PLIC.jpg[GitHub][1000,643]

Are there plans for an "ID Register" that identifies what type of PLIC/CLINT/etc is present?