FriendOS Wiki - User contributions [en]

Limine-zig

2023-09-01T00:48:16Z

Veloya: Added basic info on code for getting x86 limine with zig working

Limine is a modern boot protocol developed with the Limine bootloader, this page covers how to take advantage of that protocol in a zig-based kernel. This does not cover making an ISO, just the code required, in the future this will change, but this is it for now.

== Code ==
This code should work as long as you have zig 0.11.0 installed. As of writing this it is untested, but if you do test it out, and it works, remove this sentence, if it doesn't work please message me (veloya) on the discord server with the error message.

=== src/main.zig ===
<syntaxhighlight lang="zig" line="1">
const limine = @import("./limine.zig");

pub export var FRAMEBUF: limine.FramebufferRequest = .{};

export fn _start() void {
// Get an array of framebuffer pointers
const framebuffers = FRAMEBUF.response.?.framebuffers();

// Get the first framebuffer provided
const framebuffer = framebuffers[0];

// Height is in pixels, convert it to bytes
const byte_height = framebuffer.height * 4;

// Get total byte size by multiplying the height by the stride (or pitch)
const size = byte_height * framebuffer.pitch;

// Fill the framebuffer with white
for (0..size) |index| {
framebuffer.address[index] = 0xff;
}

while (true) {}
}

</syntaxhighlight>

=== src/limine.zig ===
The limine.zig file can be found [https://github.com/limine-bootloader/limine-zig/tree/trunk here]

=== config/linker.ld ===
TODO: Write a better linker script<syntaxhighlight>
ENTRY(_start)

SECTIONS
{
. = 0xffffffff80000000;

.text : ALIGN(4096) { *(.text .text.*) }
.rodata : ALIGN(4096) { *(.rodata .rodata.*) }
.data : ALIGN(4096) { *(.data .data.*) }
.dynamic : ALIGN(4096) { *(.dynamic) }
.bss : ALIGN(4096) {
*(.bss .bss.*)
*(COMMON)
}
}
</syntaxhighlight>

=== config/limine.cfg ===
<syntaxhighlight lang="cfg">
boot "test-kern" {
protocol = "limine";
kernel-path = "boot:///boot/test-kern";
}
</syntaxhighlight>

=== build.zig ===
A build.zig file is required to properly customize the target.<syntaxhighlight lang="zig">
const std = @import("std");
const Target = @import("std").Target;
const CrossTarget = @import("std").zig.CrossTarget;
const Feature = @import("std").Target.Cpu.Feature;

pub fn build(b: *std.Build) !void {
var stdout = std.io.getStdOut();

const target = CrossTarget{
.cpu_arch = Target.Cpu.Arch.x86_64,
.os_tag = Target.Os.Tag.freestanding,
.abi = Target.Abi.none,
};
const optimize = b.standardOptimizeOption(.{});

const kernel = b.addExecutable(.{
.name = "test-kern",
.root_source_file = .{ .path = "src/main.zig" },
.target = target,
.optimize = optimize,
});

kernel.setLinkerScriptPath(.{ .path = "config/linker.ld" });
kernel.code_model = .medium;
kernel.rdynamic = true;
kernel.pie = true;

_ = try stdout.write("Building kernel\n");
b.installArtifact(kernel);
}

</syntaxhighlight>

Category:X86

2023-08-31T23:45:39Z

Veloya: Created the page, time to work on it

TODO

RISC-V/Paging

2023-08-31T23:34:34Z

Veloya: Added information on Sv32, also added a section for RSW bits.

Paging in RISC-V can be enabled by first setting up a page table, then pointing the CPU to that page table via the [[RISC-V/CSR#satp | <code>satp</code> CSR]]. This article will describe these steps.

Paging type can be determined at runtime using the device tree, its typically located in the CPU specific nodes, such as `cpu@x` where x denotes which number of CPU it is, it will be located under the `mmu-type` property in the form of a string such as `riscv,svY` is either "32", "39", "48", or "57" depending on paging type.

== Terminology ==

There are many acronyms and other terms that are used in the RISC-V specification which, for the purpose of brevity and consistency, will be used in this article as well. I will assume a baseline knowledge of the purpose and basics of paging and virtual addressing.

=== PPNs and VPNs ===

A physical page number (or PPN) is a unique, page-aligned identifier for a page in physical memory. The number of PPN segments for an address will depend on the paging mode.

To construct a PPN from a physical address, you can simply (logically, not arithmetically) shift the value right by 12 bits (as 2**12 = 4096). Note that this operation will truncate the offset into the page, if the address was not page-aligned.

A virtual page number (or VPN) is very similar to a PPN, but in the virtual address space. Again, the number of VPN segments for a virtual address will depend on the paging mode.

=== RSW ===
Bits marked as RSW indicate that they can be written, read, and handled in any way the OS wants without causing issues. These can be used as OS-specific flags.

== RISC-V Page Table Layout ==

There are various paging modes available in the RISC-V ISA, differing by the number of virtual address bits:
{| class="wikitable"
|-
! Name !! Memory Size !! SXLEN
|-
| Sv32 || 4GiB || 32-bit only
|-
| Sv39 || 512GiB || 64-bit only
|-
| Sv48 || 256TiB || 64-bit only
|-
| Sv57 || 128PiB || 64-bit only
|}

Feel free to choose between these modes as you see fit; this page will describe all of them. Note that in 64-bit systems, Sv39 is more than enough for most hobby operating systems (though it is not much more difficult to go further).

=== Sv32 ===

Sv32 is the only available paging mode for a 32 bit system, it provides 32 bit virtual addresses, and 34 bit physical addresses.

'''Address and PTE Layouts'''
{| class="wikitable"
|+Sv32 virtual address
!Bit Range (inclusive)
!Length (bits)
!Description
|-
|0-11
|12
|Page offset
|-
|12-21
|10
|Page VPN (VPN[0])
|-
|22-31
|10
|Megapage VPN (VPN[0])
|}
{| class="wikitable"
|+Sv32 physical address
!Bit Range (inclusive)
!Length (bits)
!Description
|-
|0-11
|12
|Page offset
|-
|12-21
|10
|PPN[0]
|-
|22-33
|12
|PPN[1]
|}
{| class="wikitable"
|+Sv32 page table entry layout
!Bit Range (inclusive)
!Length (bits)
!Description
|-
|0
|1
|Valid flag (V)
|-
|1
|1
|Readable flag (R)
|-
|2
|1
|Writable flag (W)
|-
|3
|1
|Executable flag (X)
|-
|4
|1
|U-mode accessible flag (U)
|-
|5
|1
|Global flag (G)
|-
|6
|1
|Accessed flag (A)
|-
|7
|1
|Dirty flag (D)
|-
|8-9
|2
|RSW
|-
|10-19
|10
|<nowiki>PPN[0]</nowiki>
|-
|20-31
|12
|<nowiki>PPN[1]</nowiki>
|}

=== Sv39 ===

Sv39 is the simplest paging mode for 64-bit systems (though larger modes are not too much more difficult to implement). It supports the standard 4KiB pages, as well as 2MiB megapages and 1GiB gigapages.

TODO: actually describe what a page table looks like, and also PTE's RWX encoding

==== Address and PTE Layouts ====

{| class="wikitable mw-collapsible"
|+ Sv39 virtual address
|-
! Bit Range (inclusive) !! Length (bits) !! Description
|-
| 0-11 || 12 || Page offset
|-
| 12-20 || 9 || Page VPN (<nowiki>VPN[0]</nowiki>)
|-
| 21-29 || 9 || Megapage VPN (<nowiki>VPN[1]</nowiki>)
|-
| 30-38 || 9 || Gigapage VPN (<nowiki>VPN[2]</nowiki>)
|}

{| class="wikitable mw-collapsible"
|+ Sv39 physical address
|-
! Bit Range (inclusive) !! Length (bits) !! Description
|-
| 0-11 || 12 || Page offset
|-
| 12-20 || 9 || <nowiki>PPN[0]</nowiki>
|-
| 21-29 || 9 || <nowiki>PPN[1]</nowiki>
|-
| 30-55 || 26 || <nowiki>PPN[2]</nowiki>
|}

{| class="wikitable mw-collapsible"
|+ Sv39 page table entry layout
|-
! Bit Range (inclusive) !! Length (bits) !! Description
|-
| 0 || 1 || Valid flag (V)
|-
| 1 || 1 || Readable flag (R)
|-
| 2 || 1 || Writable flag (W)
|-
| 3 || 1 || Executable flag (X)
|-
| 4 || 1 || U-mode accessible flag (U)
|-
| 5 || 1 || Global flag (G)
|-
| 6 || 1 || Accessed flag (A)
|-
| 7 || 1 || Dirty flag (D)
|-
| 8-9 || 2 || RSW
|-
| 10-18 || 9 || <nowiki>PPN[0]</nowiki>
|-
| 19-27 || 9 || <nowiki>PPN[1]</nowiki>
|-
| 28-53 || 26 || <nowiki>PPN[2]</nowiki>
|-
| 54-60 || 7 || Reserved
|-
| 61-62 || 2 || PBMT (TODO)
|-
| 63 || 1 || N bit (TODO)
|}

=== Sv48 ===

TODO: Explain

==== Address and PTE Layouts ====

{| class="wikitable mw-collapsible"
|+ Sv48 virtual address
|-
! Bit Range (inclusive) !! Length (bits) !! Description
|-
| 0-11 || 12 || Page offset
|-
| 12-20 || 9 || Page VPN (<nowiki>VPN[0]</nowiki>)
|-
| 21-29 || 9 || Megapage VPN (<nowiki>VPN[1]</nowiki>)
|-
| 30-38 || 9 || Gigapage VPN (<nowiki>VPN[2]</nowiki>)
|-
| 39-47 || 9 || (<nowiki>VPN[3]</nowiki>)
|}

{| class="wikitable mw-collapsible"
|+ Sv48 physical address
|-
! Bit Range (inclusive) !! Length (bits) !! Description
|-
| 0-11 || 12 || Page offset
|-
| 12-20 || 9 || (<nowiki>PPN[0]</nowiki>)
|-
| 21-29 || 9 || (<nowiki>PPN[1]</nowiki>)
|-
| 30-38 || 9 || (<nowiki>PPN[2]</nowiki>)
|-
| 39-47 || 9 || (<nowiki>PPN[3]</nowiki>)
|}

{| class="wikitable mw-collapsible"
|+ Sv48 page table entry layout
|-
! Bit Range (inclusive) !! Length (bits) !! Description
|-
| 0 || 1 || Valid flag (V)
|-
| 1 || 1 || Readable flag (R)
|-
| 2 || 1 || Writable flag (W)
|-
| 3 || 1 || Executable flag (X)
|-
| 4 || 1 || U-mode accessible flag (U)
|-
| 5 || 1 || Global flag (G)
|-
| 6 || 1 || Accessed flag (A)
|-
| 7 || 1 || Dirty flag (D)
|-
| 8-9 || 2 || RSW
|-
| 10-18 || 9 || <nowiki>PPN[0]</nowiki>
|-
| 19-27 || 9 || <nowiki>PPN[1]</nowiki>
|-
| 28-36 || 9 || <nowiki>PPN[2]</nowiki>
|-
| 37-53 || 17 || <nowiki>PPN[3]</nowiki>
|-
| 54-60 || 7 || Reserved
|-
| 61-62 || 2 || PBMT (TODO)
|-
| 63 || 1 || N bit (TODO)
|}

=== Sv57 ===

TODO

== Enabling Paging ==

TODO: Explain better

Paging on RISC-V is split into 4 different modes, 32 bit, 39 bit, 48 bit, and 57 bit. 32 bit is only available on 32 bit systems, and not available on 64 bit systems.
Paging is handled by the `SATP` CSR which contains 3 separate sections, the PPN(Physical Page Number) which is similar to the physical address, the ASID(Address Space Identifier), and finally, the Mode. To enable paging you need to write a paging mode into the Mode section of the `SATP` register. On 64 bits you can write 0 for no paging, 8 for Sv39, 9 for Sv48, 10 for Sv57, and in the future 11 will be available for 64 bits. On 32 bits you can write 0 for no paging, or 1 for Sv32.

Rust example code:

32 bits
<syntaxhighlight lang="rust" line>
pub unsafe fn enable_paging(root_page_table: usize) {
let ppn = root_page_table >> 12;
let mode = 1 << 31;

let write = mode | ppn;

core::arch::asm(
"csrw satp, {}",
in(reg) write
);
}
</syntaxhighlight>

64 bits
<syntaxhighlight lang="rust" line>
pub unsafe fn enable_paging(root_page_table: usize, mode: u8) {
let ppn = root_page_table >> 12;
let new_mode = (mode & 0xf) << 60;

let write = mode | ppn;

core::arch::asm(
"csrw satp, {}",
in(reg) write
);
}
</syntaxhighlight>

CLINT

2023-02-16T03:15:06Z

Veloya: VERY basic description of it, as well as a memory map as specified by the following link, update HIGHLY recommended https://sifive.cdn.prismic.io/sifive/ad5577a0-9a00-45c9-a5d0-424a3d586060_u74_core_complex_manual_21G3.pdf

The CLINT(Core-Local Interruptor) is a device made for handling interrupts occurring within a core, such as software interrupts. The CLINT operates on individual cores, meaning there is 1 for each core.

== SiFive U74 CLINT ==
Memory layout:

base + 0x0000: MSIP, used for generating machine level interrupts

base + 0x0004: Reserved

...

base + 0x3FFF: Reserved

base + 0x4000: MTIMECMP, not sure

base + 0x4008: Reserved

...

base + 0xBFF7: Reserved

base + 0xBFF8: mtime, Timer register

base + 0xC000: Reserved

RISC-V/Paging

2023-02-10T23:18:03Z

Veloya: Added paging enabling code, and a short explanation on it

Paging in RISC-V can be enabled by first setting up a page table, then pointing the CPU to that page table via the [[RISC-V/CSR#satp | <code>satp</code> CSR]]. This article will describe these steps.

Paging type can be determined at runtime using the device tree, its typically located in the CPU specific nodes, such as `cpu@x` where x denotes which number of CPU it is, it will be located under the `mmu-type` property in the form of a string such as `riscv,svY` is either "32", "39", "48", or "57" depending on paging type.

== Terminology ==

There are many acronyms and other terms that are used in the RISC-V specification which, for the purpose of brevity and consistency, will be used in this article as well. I will assume a baseline knowledge of the purpose and basics of paging and virtual addressing.

=== PPNs and VPNs ===

A physical page number (or PPN) is a unique, page-aligned identifier for a page in physical memory. The number of PPN segments for an address will depend on the paging mode.

To construct a PPN from a physical address, you can simply (logically, not arithmetically) shift the value right by 12 bits (as 2**12 = 4096). Note that this operation will truncate the offset into the page, if the address was not page-aligned.

A virtual page number (or VPN) is very similar to a PPN, but in the virtual address space. Again, the number of VPN segments for a virtual address will depend on the paging mode.

== RISC-V Page Table Layout ==

There are various paging modes available in the RISC-V ISA, differing by the number of virtual address bits:
{| class="wikitable"
|-
! Name !! Memory Size !! SXLEN
|-
| Sv32 || 4GiB || 32-bit only
|-
| Sv39 || 512GiB || 64-bit only
|-
| Sv48 || 256TiB || 64-bit only
|-
| Sv57 || 128PiB || 64-bit only
|}

Feel free to choose between these modes as you see fit; this page will describe all of them. Note that in 64-bit systems, Sv39 is more than enough for most hobby operating systems (though it is not much more difficult to go further).

=== Sv32 ===

TODO

=== Sv39 ===

Sv39 is the simplest paging mode for 64-bit systems (though larger modes are not too much more difficult to implement). It supports the standard 4KiB pages, as well as 2MiB megapages and 1GiB gigapages.

TODO: actually describe what a page table looks like, and also PTE's RWX encoding

==== Address and PTE Layouts ====

{| class="wikitable mw-collapsible"
|+ Sv39 virtual address
|-
! Bit Range (inclusive) !! Length (bits) !! Description
|-
| 0-11 || 12 || Page offset
|-
| 12-20 || 9 || Page VPN (<nowiki>VPN[0]</nowiki>)
|-
| 21-29 || 9 || Megapage VPN (<nowiki>VPN[1]</nowiki>)
|-
| 30-38 || 9 || Gigapage VPN (<nowiki>VPN[2]</nowiki>)
|}

{| class="wikitable mw-collapsible"
|+ Sv39 physical address
|-
! Bit Range (inclusive) !! Length (bits) !! Description
|-
| 0-11 || 12 || Page offset
|-
| 12-20 || 9 || <nowiki>PPN[0]</nowiki>
|-
| 21-29 || 9 || <nowiki>PPN[1]</nowiki>
|-
| 30-55 || 26 || <nowiki>PPN[2]</nowiki>
|}

{| class="wikitable mw-collapsible"
|+ Sv39 page table entry layout
|-
! Bit Range (inclusive) !! Length (bits) !! Description
|-
| 0 || 1 || Valid flag (V)
|-
| 1 || 1 || Readable flag (R)
|-
| 2 || 1 || Writable flag (W)
|-
| 3 || 1 || Executable flag (X)
|-
| 4 || 1 || U-mode accessible flag (U)
|-
| 5 || 1 || Global flag (G)
|-
| 6 || 1 || Accessed flag (A)
|-
| 7 || 1 || Dirty flag (D)
|-
| 8-9 || 2 || RSW (TODO)
|-
| 10-18 || 9 || <nowiki>PPN[0]</nowiki>
|-
| 19-27 || 9 || <nowiki>PPN[1]</nowiki>
|-
| 28-53 || 26 || <nowiki>PPN[2]</nowiki>
|-
| 54-60 || 7 || Reserved
|-
| 61-62 || 2 || PBMT (TODO)
|-
| 63 || 1 || N bit (TODO)
|}

=== Sv48 ===

TODO: Explain

==== Address and PTE Layouts ====

{| class="wikitable mw-collapsible"
|+ Sv48 virtual address
|-
! Bit Range (inclusive) !! Length (bits) !! Description
|-
| 0-11 || 12 || Page offset
|-
| 12-20 || 9 || Page VPN (<nowiki>VPN[0]</nowiki>)
|-
| 21-29 || 9 || Megapage VPN (<nowiki>VPN[1]</nowiki>)
|-
| 30-38 || 9 || Gigapage VPN (<nowiki>VPN[2]</nowiki>)
|-
| 39-47 || 9 || (<nowiki>VPN[3]</nowiki>)
|}

{| class="wikitable mw-collapsible"
|+ Sv48 physical address
|-
! Bit Range (inclusive) !! Length (bits) !! Description
|-
| 0-11 || 12 || Page offset
|-
| 12-20 || 9 || (<nowiki>PPN[0]</nowiki>)
|-
| 21-29 || 9 || (<nowiki>PPN[1]</nowiki>)
|-
| 30-38 || 9 || (<nowiki>PPN[2]</nowiki>)
|-
| 39-47 || 9 || (<nowiki>PPN[3]</nowiki>)
|}

{| class="wikitable mw-collapsible"
|+ Sv48 page table entry layout
|-
! Bit Range (inclusive) !! Length (bits) !! Description
|-
| 0 || 1 || Valid flag (V)
|-
| 1 || 1 || Readable flag (R)
|-
| 2 || 1 || Writable flag (W)
|-
| 3 || 1 || Executable flag (X)
|-
| 4 || 1 || U-mode accessible flag (U)
|-
| 5 || 1 || Global flag (G)
|-
| 6 || 1 || Accessed flag (A)
|-
| 7 || 1 || Dirty flag (D)
|-
| 8-9 || 2 || RSW (TODO)
|-
| 10-18 || 9 || <nowiki>PPN[0]</nowiki>
|-
| 19-27 || 9 || <nowiki>PPN[1]</nowiki>
|-
| 28-36 || 9 || <nowiki>PPN[2]</nowiki>
|-
| 37-53 || 17 || <nowiki>PPN[3]</nowiki>
|-
| 54-60 || 7 || Reserved
|-
| 61-62 || 2 || PBMT (TODO)
|-
| 63 || 1 || N bit (TODO)
|}

=== Sv57 ===

TODO

== Enabling Paging ==

TODO: Explain better

Paging on RISC-V is split into 4 different modes, 32 bit, 39 bit, 48 bit, and 57 bit. 32 bit is only available on 32 bit systems, and not available on 64 bit systems.
Paging is handled by the `SATP` CSR which contains 3 separate sections, the PPN(Physical Page Number) which is similar to the physical address, the ASID(Address Space Identifier), and finally, the Mode. To enable paging you need to write a paging mode into the Mode section of the `SATP` register. On 64 bits you can write 0 for no paging, 8 for Sv39, 9 for Sv48, 10 for Sv57, and in the future 11 will be available for 64 bits. On 32 bits you can write 0 for no paging, or 1 for Sv32.

Rust example code:

32 bits
<syntaxhighlight lang="rust" line>
pub unsafe fn enable_paging(root_page_table: usize) {
let ppn = root_page_table >> 12;
let mode = 1 << 31;

let write = mode | ppn;

core::arch::asm(
"csrw satp, {}",
in(reg) write
);
}
</syntaxhighlight>

64 bits
<syntaxhighlight lang="rust" line>
pub unsafe fn enable_paging(root_page_table: usize, mode: u8) {
let ppn = root_page_table >> 12;
let new_mode = (mode & 0xf) << 60;

let write = mode | ppn;

core::arch::asm(
"csrw satp, {}",
in(reg) write
);
}
</syntaxhighlight>

RISC-V/Paging

2023-02-10T18:11:13Z

Veloya: Messed up on the bit sizes for PPN3 in Sv48

RISC-V/Paging

2023-02-10T16:38:14Z

Veloya: Added some info about Sv48 paging

RISC-V/Paging

2023-02-10T16:21:24Z

Veloya: Added a short explanation for getting the MMU type with the DT

Interrupts

2023-02-08T14:23:22Z

Veloya: Not a very good explanation, but I thought it'd be good enough, for now.

Interrupts are used in operating system design in order to allow things such as input, or timing, and often used with system calls to allow for an easy interface with the operating system. Interrupts can typically be split into several categories. External interrupts, Exceptions, and Software interrupts are some.

== External Interrupts ==
External interrupts are used by external devices, such as keyboards, to tell the CPU that there has been an update in their state. The way of handling these external interrupts differs from platform to platform, but on RISC-V its handled with the [[PLIC]].

== Exceptions ==
Exceptions are errors that occur on a hardware level, sometimes from issues with the software, such as illegally storing to memory. Exceptions typically have specific error codes, and specific ways of getting details on why they occurred, often stored in specific registers.

== Software Interrupts ==
Software interrupts are generated, as the name implies, by software, these are used to time things, interact with the operating system, through syscalls, or to handle something important within the operating system.

PLIC

2023-02-08T02:53:11Z

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

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:

<syntaxhighlight lang="rust" line>
#[repr(C)]
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; 1024]; 15872],
}
</syntaxhighlight>

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†
|Monitor hart: <code>0</code>

Other harts: <code>hart_id * 2 + 1</code>
|<code>hart_id * 2</code>
|}
†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: Explain better

Every interrupt source has a priority, these priorities effect which interrupts get dealt with first, and which don't get dealt with at all. An interrupt won't be dealt with at all if it is below the threshold of the context handling it.
To set the interrupt source priority, index into the `source_priorities` field of the PLIC, and then write the desired priority(typically from 0-7).
To set the threshold of a context, index into the `threshold_and_claim` field of the PLIC based off the context, and then index to 0 in that, then write the desired threshold(typically 0-7 like priority).

Example in rust:

<syntaxhighlight lang="rust" line>
unsafe fn set_priority(plic: *mut Plic, interrupt_source: usize, priority: u32) {
// Sanity check
if interrupt_source >= 1024 {
return;
}

let src_priority = unsafe {&mut (*plic).source_priorities[interrupt_source]};

*src_priority = priority;
}

unsafe fn set_threshold(plic: *mut Plic, context: usize, thresh: u32) {
// Sanity check
if context >= 15872 {
return;
}

let threshold = unsafe {&mut (*plic).threshold_and_claim[context][0]};

*threshold = thresh;
}
</syntaxhighlight>

=== 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() };

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

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

=== Acknowledging Interrupts — Claim/Complete Mechanism ===
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. 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.
Example rust code:<syntaxhighlight lang="rust" line="1">
unsafe fn claim_interrupt(plic: *mut Plic, context: usize, interrupt_source: usize) {
// Sanity checks, neither values would be valid
if context >= 15872 || interrupt_source >= 1024 {
return;
}

let threshold_and_claim = unsafe {&mut (*plic).threshold_and_claim};

// Write the interrupt
threshold_and_claim[context][1] = interrupt_source;
}
</syntaxhighlight>
__FORCETOC__

PLIC

2023-02-06T13:55:42Z

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

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:

<syntaxhighlight lang="rust" line>
#[repr(C)]
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; 1024]; 15872],
}
</syntaxhighlight>

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†
|Monitor hart: <code>0</code>

Other harts: <code>hart_id * 2 + 1</code>
|<code>hart_id * 2</code>
|}
†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 ===
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() };

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

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

=== Acknowledging Interrupts — Claim/Complete Mechanism ===
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.
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">
unsafe fn claim_interrupt(plic: *mut Plic, context: usize, interrupt_source: usize) {
// Sanity checks, neither values would be valid
if context >= 15872 || interrupt_source >= 1024 {
return;
}

let threshold_and_claim = unsafe {&mut (*plic).threshold_and_claim};

// Write the interrupt
unsafe { threshold_and_claim[context][1] = interrupt_source };
}
</syntaxhighlight>
__FORCETOC__