PLIC - Revision history

Veloya: Updated priorities and threshold section, I suggest someone double check just in case

2023-02-08T02:53:11Z

Updated priorities and threshold section, I suggest someone double check just in case

@@ Line 80: / Line 80: @@
 === Setting Interrupt Source Priorities & Thresholds ===
-TODO
+TODO: Explain better
 === Enabling and Disabling Interrupts ===
@@ Line 145: / Line 175: @@
      // Write the interrupt
-     unsafe { threshold_and_claim[context][1] = interrupt_source };
+     threshold_and_claim[context][1] = interrupt_source;
+}
 </syntaxhighlight>
 __FORCETOC__

Icefox at 04:44, 7 February 2023

2023-02-07T04:44:56Z

← Older revision		Revision as of 04:44, 7 February 2023
Line 132:		Line 132:
	TODO: Explain it better		TODO: Explain it better

	When receiving an interrupt before you can return from it you need to acknowledge that you finished the interrupt, this is the Claim/Complete mechanism.		When receiving an interrupt before you can return from it you need to acknowledge that you finished the interrupt, this is the Claim/Complete mechanism. As the name implies, first you must "claim" an interrupt, which is tells the PLIC "I am working on handling this interrupt, do not try to tell other CPU's about it while I'm working on it". Then once it is handled you must "complete" it, which tells the PLIC "this interrupt is finished and the hardware device can signal again if it wants". It is perfectly normal for claiming an interrupt to sometimes fail if you have multiple CPU's, essentially another CPU has beaten you in the race. The race is mediated by the hardware so it all works out in the end.

	In order to claim it you must take the interrupt number, and write that to the `threshold_and_claim` register, first index it based off the context, and then index to 1, and write the interrupt number.		In order to claim it you must take the interrupt number, and write that to the `threshold_and_claim` register, first index it based off the context, and then index to 1, and write the interrupt number.
	Example rust code:<syntaxhighlight lang="rust" line="1">		Example rust code:<syntaxhighlight lang="rust" line="1">

Veloya: Did my best to explain and demonstrate Claim/Complete Mechanism, I suggest someone who is more qualified review this later

2023-02-06T13:55:42Z

Did my best to explain and demonstrate Claim/Complete Mechanism, I suggest someone who is more qualified review this later

@@ Line 130: / Line 130: @@
 === Acknowledging Interrupts — Claim/Complete Mechanism ===
-TODO
+TODO: Explain it better
 __FORCETOC__

Repnop at 02:29, 3 February 2023

2023-02-03T02:29:24Z

← Older revision		Revision as of 02:29, 3 February 2023
Line 78:		Line 78:
	\|}		\|}
	<sup>†</sup>This platform contains a [[Monitor Hart]] which does not support S-mode and does not have the same extension availability as the general-purpose harts		<sup>†</sup>This platform contains a [[Monitor Hart]] which does not support S-mode and does not have the same extension availability as the general-purpose harts

			=== Setting Interrupt Source Priorities & Thresholds ===
			TODO

	=== Enabling and Disabling Interrupts ===		=== Enabling and Disabling Interrupts ===
Line 125:		Line 128:
	}		}
	</syntaxhighlight>		</syntaxhighlight>

			=== Acknowledging Interrupts — Claim/Complete Mechanism ===
			TODO
	__FORCETOC__		__FORCETOC__

Repnop at 02:15, 3 February 2023

2023-02-03T02:15:21Z

← Older revision		Revision as of 02:15, 3 February 2023
Line 118:		Line 118:
	let previous = unsafe { bit_group_ptr.read_volatile() };		let previous = unsafe { bit_group_ptr.read_volatile() };

	// ~~Set~~ the bit for the interrupt source		// Clear the bit for the interrupt source
	let new = previous & !(1 << bit);		let new = previous & !(1 << bit);

Repnop at 02:13, 3 February 2023

2023-02-03T02:13:41Z

← Older revision		Revision as of 02:13, 3 February 2023
Line 58:		Line 58:

	Each <code>u32</code> inside of the <code>source_priorities</code> is a priority level from <code>0..=7</code> (on most platforms, see your platform specification for more complete information) of increasing priority level where priority <code>0</code> is considered "never interrupt" and will cause the interrupt to effectively be disabled, with the exception of interrupt #0, which does not exist and is reserved. <code>interrupt_pending</code> is a read-only bitmap of the pending status for priorities <code>1..=1024</code> (with the interrupt #0 bit hardwired to zero). Both <code>interrupt_enable</code> and <code>threshold_and_claim</code> work on the aforementioned contexts, and need to be indexed at a platform-specific index for a given hart and privilege mode combination. The <code>interrupt_enable</code> consists of another bitmap of interrupt sources (again with interrupt #0 for each context being hardwired to zero) which allow enabling and disabling specific interrupt sources at the context level, but also means that if you wish for a given interrupt to trigger across any hart, it will need to be enabled for each context for the privilege mode you are executing in. <code>threshold_and_claim</code> is made up of a threshold <code>u32</code> value and a claim <code>u32</code> value, with the rest of the <code>u32</code>s being reserved and should not be written to.		Each <code>u32</code> inside of the <code>source_priorities</code> is a priority level from <code>0..=7</code> (on most platforms, see your platform specification for more complete information) of increasing priority level where priority <code>0</code> is considered "never interrupt" and will cause the interrupt to effectively be disabled, with the exception of interrupt #0, which does not exist and is reserved. <code>interrupt_pending</code> is a read-only bitmap of the pending status for priorities <code>1..=1024</code> (with the interrupt #0 bit hardwired to zero). Both <code>interrupt_enable</code> and <code>threshold_and_claim</code> work on the aforementioned contexts, and need to be indexed at a platform-specific index for a given hart and privilege mode combination. The <code>interrupt_enable</code> consists of another bitmap of interrupt sources (again with interrupt #0 for each context being hardwired to zero) which allow enabling and disabling specific interrupt sources at the context level, but also means that if you wish for a given interrupt to trigger across any hart, it will need to be enabled for each context for the privilege mode you are executing in. <code>threshold_and_claim</code> is made up of a threshold <code>u32</code> value and a claim <code>u32</code> value, with the rest of the <code>u32</code>s being reserved and should not be written to.

			=== Hart & Privilege Context Mappings ===
			{\| class="wikitable"
			\|+
			!Platform
			!M-mode Context
			!S-mode Context
			\|-
			\|QEMU virt
			\|<code>hart_id * 2</code>
			\|
			hart_id * 2 + 1
			\|-
			\|QEMU sifive_u<sup>†</sup>
			\|Monitor hart: <code>0</code>

			Other harts: <code>hart_id * 2 + 1</code>
			\|<code>hart_id * 2</code>
			\|}
			<sup>†</sup>This platform contains a [[Monitor Hart]] which does not support S-mode and does not have the same extension availability as the general-purpose harts

			=== Enabling and Disabling Interrupts ===
			To enable or disable any given interrupt source, simply toggle the specific bit that corresponds to the interrupt source in the <code>interrupt_enable</code> for the context for which you wish to enable or disable the interrupt. Example Rust code:<syntaxhighlight lang="rust" line="1">
			unsafe fn enable_interrupt(plic: *mut Plic, context: usize, interrupt_source: usize) {
			// Sanity checks, neither values would be valid
			if context >= 15872 \|\| interrupt_source >= 1024 {
			return;
			}

			// Calculate the bit-group index and the bit index for that bit-group
			let (u32_index, bit) = (interrupt_source / 32, interrupt_source % 32);

			// Calculate the address of the bit-group
			let bit_group_ptr = unsafe { core::ptr::addr_of_mut!((*plic).interrupt_enable[context][u32_index]) };

			// Read the current value
			let previous = unsafe { bit_group_ptr.read_volatile() };

			// Set the bit for the interrupt source
			let new = previous \| (1 << bit);

			// Write the new value
			unsafe { bit_group_ptr.write_volatile(new) };
			}

			unsafe fn disable_interrupt(plic: *mut Plic, context: usize, interrupt_source: usize) {
			// Sanity checks, neither values would be valid
			if context >= 15872 \|\| interrupt_source >= 1024 {
			return;
			}

			// Calculate the bit-group index and the bit index for that bit-group
			let (u32_index, bit) = (interrupt_source / 32, interrupt_source % 32);

			// Calculate the address of the bit-group
			let bit_group_ptr = unsafe { core::ptr::addr_of_mut!((*plic).interrupt_enable[context][u32_index]) };

			// Read the current value
			let previous = unsafe { bit_group_ptr.read_volatile() };

			// Set the bit for the interrupt source
			let new = previous & !(1 << bit);

			// Write the new value
			unsafe { bit_group_ptr.write_volatile(new) };
			}
			</syntaxhighlight>
			__FORCETOC__

Repnop at 02:45, 2 February 2023

2023-02-02T02:45:36Z

← Older revision		Revision as of 02:45, 2 February 2023
Line 57:		Line 57:
	</syntaxhighlight>		</syntaxhighlight>

	Each <~~pre~~>u32</~~pre~~> inside of the <~~pre~~>source_priorities</~~pre~~> is a priority level from <~~pre~~>0..=7</~~pre~~> (on most platforms, see your platform specification for more complete information) of increasing priority level where priority <~~pre~~>0</~~pre~~> is considered "never interrupt" and will cause the interrupt to effectively be disabled, with the exception of interrupt #0, which does not exist and is reserved. <~~pre~~>interrupt_pending</~~pre~~> is a read-only bitmap of the pending status for priorities <~~pre~~>1..=1024</~~pre~~> (with the interrupt #0 bit hardwired to zero). Both <~~pre~~>interrupt_enable</~~pre~~> and <~~pre~~>threshold_and_claim</~~pre~~> work on the aforementioned contexts, and need to be indexed at a platform-specific index for a given hart and privilege mode combination. The <~~pre~~>interrupt_enable</~~pre~~> consists of another bitmap of interrupt sources (again with interrupt #0 for each context being hardwired to zero) which allow enabling and disabling specific interrupt sources at the context level, but also means that if you wish for a given interrupt to trigger across any hart, it will need to be enabled for each context for the privilege mode you are executing in. <~~pre~~>threshold_and_claim</~~pre~~> is made up of a threshold <~~pre~~>u32</~~pre~~> value and a claim <~~pre~~>u32</~~pre~~> value, with the rest of the <~~pre~~>u32</~~pre~~>s being reserved and should not be written to.		Each <code>u32</code> inside of the <code>source_priorities</code> is a priority level from <code>0..=7</code> (on most platforms, see your platform specification for more complete information) of increasing priority level where priority <code>0</code> is considered "never interrupt" and will cause the interrupt to effectively be disabled, with the exception of interrupt #0, which does not exist and is reserved. <code>interrupt_pending</code> is a read-only bitmap of the pending status for priorities <code>1..=1024</code> (with the interrupt #0 bit hardwired to zero). Both <code>interrupt_enable</code> and <code>threshold_and_claim</code> work on the aforementioned contexts, and need to be indexed at a platform-specific index for a given hart and privilege mode combination. The <code>interrupt_enable</code> consists of another bitmap of interrupt sources (again with interrupt #0 for each context being hardwired to zero) which allow enabling and disabling specific interrupt sources at the context level, but also means that if you wish for a given interrupt to trigger across any hart, it will need to be enabled for each context for the privilege mode you are executing in. <code>threshold_and_claim</code> is made up of a threshold <code>u32</code> value and a claim <code>u32</code> value, with the rest of the <code>u32</code>s being reserved and should not be written to.

Repnop at 02:44, 2 February 2023

2023-02-02T02:44:13Z

← Older revision		Revision as of 02:44, 2 February 2023
Line 42:		Line 42:
	...		...
	base + 0x3FFFFFC: Reserved		base + 0x3FFFFFC: Reserved

	Or, more usefully:		Or, more usefully:
	#[repr(C)]
	~~pub~~ struct Plic {		<syntaxhighlight lang="rust" line>
	source_priorities: [u32; 1024],		#[repr(C)]
	interrupt_pending: [u32; 32],		struct Plic {
	_padding1: [u8; 3968],		source_priorities: [u32; 1024],
	interrupt_enable: [[u32; 32]; 15872],		interrupt_pending: [u32; 32],
	_padding2: [u8; 57344],		_padding1: [u8; 3968],
	threshold_and_claim: [[u32; ~~4090~~]; 15872],		interrupt_enable: [[u32; 32]; 15872],
	~~_padding3: [u8; 8184]~~,		_padding2: [u8; 57344],
	}		threshold_and_claim: [[u32; 1024]; 15872],
			}
			</syntaxhighlight>

			Each <pre>u32</pre> inside of the <pre>source_priorities</pre> is a priority level from <pre>0..=7</pre> (on most platforms, see your platform specification for more complete information) of increasing priority level where priority <pre>0</pre> is considered "never interrupt" and will cause the interrupt to effectively be disabled, with the exception of interrupt #0, which does not exist and is reserved. <pre>interrupt_pending</pre> is a read-only bitmap of the pending status for priorities <pre>1..=1024</pre> (with the interrupt #0 bit hardwired to zero). Both <pre>interrupt_enable</pre> and <pre>threshold_and_claim</pre> work on the aforementioned contexts, and need to be indexed at a platform-specific index for a given hart and privilege mode combination. The <pre>interrupt_enable</pre> consists of another bitmap of interrupt sources (again with interrupt #0 for each context being hardwired to zero) which allow enabling and disabling specific interrupt sources at the context level, but also means that if you wish for a given interrupt to trigger across any hart, it will need to be enabled for each context for the privilege mode you are executing in. <pre>threshold_and_claim</pre> is made up of a threshold <pre>u32</pre> value and a claim <pre>u32</pre> value, with the rest of the <pre>u32</pre>s being reserved and should not be written to.

Repnop: Initial writeup -- incomplete but need to restart

2023-02-02T01:54:49Z

Initial writeup -- incomplete but need to restart

New page

The Platform Interrupt Controller (PLIC) is the standardized device for receiving, routing, and completing [[Interrupts#External|external interrupts]] with configuration per-[[hart]] and per-[[Privilege Mode|privilege mode]]. Originally, the PLIC design is based on early SiFive designs which were then slightly refined and standardized and only supports basic interrupt enabling/disabling, prioritization and routing. As part of the [[RISC-V Advanced Interrupt Architecture]] (AIA), the original PLIC design is extended to support more types of interrupts, namely [[Message Signaled Interrupt]]<nowiki/>s (MSIs), which are important for technologies like [[PCI]]. The PLIC specification can be found at https://github.com/riscv/riscv-plic-spec while the APLIC specification is available at https://github.com/riscv/riscv-aia.

== Original PLIC Design ==
The original PLIC design consist of a set of: interrupt source priorities, interrupt pending bits, per-context interrupt enable bits, and then per-context priority threshold & claim/complete regions. A context is the combination of a hart ID and a privilege mode, though the specific ordering of contexts is platform-specific and cannot be generalized between them. A small table below has been added for quick reference, but likely will not contain a formula for calculating the context for every platform. The memory layout for the PLIC is as follows (taken from the PLIC spec):
base + 0x000000: Reserved (interrupt source 0 does not exist)
base + 0x000004: Interrupt source 1 priority
base + 0x000008: Interrupt source 2 priority
...
base + 0x000FFC: Interrupt source 1023 priority
base + 0x001000: Interrupt Pending bit 0-31
base + 0x00107C: Interrupt Pending bit 992-1023
...
base + 0x002000: Enable bits for sources 0-31 on context 0
base + 0x002004: Enable bits for sources 32-63 on context 0
...
base + 0x00207C: Enable bits for sources 992-1023 on context 0
base + 0x002080: Enable bits for sources 0-31 on context 1
base + 0x002084: Enable bits for sources 32-63 on context 1
...
base + 0x0020FC: Enable bits for sources 992-1023 on context 1
base + 0x002100: Enable bits for sources 0-31 on context 2
base + 0x002104: Enable bits for sources 32-63 on context 2
...
base + 0x00217C: Enable bits for sources 992-1023 on context 2
...
base + 0x1F1F80: Enable bits for sources 0-31 on context 15871
base + 0x1F1F84: Enable bits for sources 32-63 on context 15871
base + 0x1F1FFC: Enable bits for sources 992-1023 on context 15871
...
base + 0x1FFFFC: Reserved
base + 0x200000: Priority threshold for context 0
base + 0x200004: Claim/complete for context 0
base + 0x200008: Reserved
...
base + 0x200FFC: Reserved
base + 0x201000: Priority threshold for context 1
base + 0x201004: Claim/complete for context 1
...
base + 0x3FFF000: Priority threshold for context 15871
base + 0x3FFF004: Claim/complete for context 15871
base + 0x3FFF008: Reserved
...
base + 0x3FFFFFC: Reserved
Or, more usefully:
#[repr(C)]
pub struct Plic {
source_priorities: [u32; 1024],
interrupt_pending: [u32; 32],
_padding1: [u8; 3968],
interrupt_enable: [[u32; 32]; 15872],
_padding2: [u8; 57344],
threshold_and_claim: [[u32; 4090]; 15872],
_padding3: [u8; 8184],
}