Memory Protection

The Ibex core lacks a Memory Management Unit (MMU), so the memory access policy is controlled using the RISC-V enhanced physical memory protection (ePMP). In addition, the option for a single- or dual-stage ROM in different top-level designs presents unique challenges for correctly managing memory access. This document describes the management of the ePMP at each stage of the boot.

Background: ePMP on Ibex

ePMP controls what regions of the Ibex RISC-V core’s memory map may be used for what purpose at what time. Ibex contains 16 slots for ePMP configurations that apply access controls to different regions of the address space.

The addresses referenced by each ePMP region are controlled by the PMPADDR0–PMPADDR15 registers. Access controls for each region are controlled by individual bytes within four 4-byte registers, PMPCFG0–PMPCFG3. For example, the least-significant byte (LSB) of PMPCFG0 controls the configuration for the region assigned to PMPADDR0. The second-LSB of PMPCFG0 is associated with PMPADDR1, and so on.

Below is a table summarizing the registers controlling each region:

ePMP Addressing Modes

ePMP supports multiple options for encoding an address range that make different tradeoffs between the number of ePMP slots consumed and required alignment of the region.

The simplest addressing mode is Top of Range (TOR). A TOR region specifies explicitly the start and end address of the region, consuming two consecutive ePMP slots. Per the RISC-V spec, the TOR address mode is only set to the PMPCFG* byte associated with the slot containing the upper-bound of the range. The slot containing the lower-bound must have its configuration byte set to OFF, even though its PMPADDR* register is set.

The other important addressing mode is Naturally Aligned Power of Two (NAPOT). NAPOT regions consume only one ePMP slot instead of two, but the memory region is required to be a power-of-two size and have its start address aligned to a multiple of its size. For example, a 64-kibibyte NAPOT region must be aligned to a 64K boundary. The PMPADDR register for a NAPOT region is encoded as start >> 2 | (end - start - 1) >> 3). The Naturally Aligned 4-byte (NA4) region type is a variation of NAPOT that locks the alignment to 4-bytes.

Access Control

RISC-V provides three mechanisms for enforcing security constraints on different levels of the software stack with respect to ePMP: privilege levels and locking.

RISC-V has three privilege levels (from most to least restrictive): User (U), Supervisor (S), and Machine (M). The Machine Mode Whitelist Policy (MMWP) bit of the MSECCFG register controls whether writes by M-Mode code to unmapped regions should trigger a fault. In addition, each ePMP slot has a Locked bit. The relationship between this bit and the privilege modes changes dramatically depending on the value of the Machine Mode Lockdown (MML) bit of the MSECCFG register. After a reset, MML=0, and it can be irreversibly set to 1 at any point during boot.

When MML=0

In this mode, the Locked bit on an ePMP slot means that the restrictions of the slot apply to M-Mode in addition to U/S-Mode, and the slot cannot be modified by M-Mode code unless the Read Lock Bypass (RLB) bit is set. RLB is set to 1 at boot and can be irreversibly cleared at any point during boot.

For security, locked regions must reside in the lowest-numbered slots when jumping to untrusted code using this mode. This is because RISC-V accepts the lowest-numbered matching slot in the event of a region overlap. If a lower-numbered slot than a locked region uses were unlocked, malicious firmware could overwrite the unlocked slot to grant arbitrary permissions to the same address range as the locked slot.

When MML=1

In this mode, the Locked bit has an entirely different meaning. Setting Locked on a slot when MML=1 marks the slot as accessible only in M-Mode. When Locked is clear, the slot is accessible only in U/S-Mode. An exception is slots marked both writable and executable, which mark the slot as shared between M-Mode and U/S-Mode, rather than actually granting write and execute permissions at the same time.

An additional consequence of having MML set is that the restrictions imposed by setting Locked when MML=0 always apply, regardless of whether Locked is set or not. This means that MML=1 and RLB=0 implies no ePMP updates can be performed until the next reset, even by M-Mode code.

Boot ePMP Management Sequence

The remainder of this document describes the management of ePMP at each stage of the boot flow, from chip reset through user application execution.

Ibex ePMP State on Reset

Ibex is hard-coded to boot with the following ePMP configuration. Notably, MMWP is set to 1 from the outset and can never be cleared at any time. As a result, the configuration below enables the ROM to execute and read/write to CSRs, but it cannot access any other memory until it performs explicit ePMP configuration.

• MMWP=1
• MML=0
• RLB=1

ROM Initial Setup

Shortly after reset, the ROM updates the ePMP from the initial boot configuration to:

1. Restrict its own execute permission to the address range that actually contains its .text region.
2. Grant itself read-write access to the main SRAM, allowing it to set up a stack for itself.
3. Set up a guard region that will trigger a fault if the stack overflows.
4. In the single-stage ROM only, grant itself read-access to the region containing the Silicon Creator firmware at rest, so it can verify its manifest.

• MMWP=1
• MML=0
• RLB=1

ROM Boot Transition

When the ROM has completed its initial setup of the hardware and prepares the next boot stage, we encounter our first divergence in the ePMP setup, depending on whether our design has a single-stage or dual-stage ROM. In a single-stage ROM, the ePMP is configured for the ROM to jump directly to the Silicon Creator firmware. In a dual-stage ROM, the first-stage ROM configures ePMP for patching and execution of the second-stage ROM.

Single Stage ROM

• MMWP=1
• MML=0
• RLB=1

Dual Stage ROM

• MMWP=1
• MML=0
• RLB=1

ROM1 Initialization (Dual-stage ROM only)

After the ROM0 jumps execution to the ROM1, the ROM1 enables access to the Mailbox RAM. We also see the first instance of what we’ll call the waterfall technique, a pattern that will repeat in all later boot stages. Slots 0-2, formerly occupied by the ROM0, are now used to store a duplicate of the regions for ROM1, copied from slots 3-5. This will allow us to overwrite the original slots for the ROM1 the Silicon Creator firmware in the next stage. This pattern always works regardless of how many boot stages exist before or after the current stage, allowing later stages like the Silicon Creator firmware to always perform the same slot transitions regardless of whether it was booted by a single-stage or dual-stage ROM.

• MMWP=1
• MML=0
• RLB=1

ROM1 Boot Transition (Dual-stage ROM only)

Here, we prepare to boot the Silicon Creator firmware, which we can load in slots 3-5, now that we copied the ROM1 regions to slots 0-2 in the previous step.

• MMWP=1
• MML=0
• RLB=1

Silicon Creator Firmware Initialization

After the ROM (or ROM1) jumps execution to the Silicon Creator firmware, we run another round of the waterfall technique. We revoke access to the ROM (or ROM1) by overwriting slots 0-2 with a copy of the Silicon Creator firmware regions from slots 3-5. The slots that contained the ROM1 patch are also cleared.

• MMWP=1
• MML=0
• RLB=1

Silicon Creator Firmware Boot Transition

When the Silicon Creator Firmware prepares to boot the Silicon Owner Firmware, it loads its memory regions in slots 3-5.

• MMWP=1
• MML=0
• RLB=1

Later boot stages (Silicon Owner, Platform Integrator, Platform Owner) repeat this two-step procedure (controlled by the functions epmp_advance_boot_stage and epmp_prepare_boot_stage, repsectively, in the code) to bootstrap the following stage.

Suggested Layout for Kernel With Applications

The final boot stage (the Platform Owner in this example, but could be an earlier stage if an integration chooses not to make use of all four logical boot stages) may desire to run an OS kernel with applications that utilize isolated ePMP regions. Below is a suggested ePMP layout for such a use-case that is consistent with the above design.

Note that this example sets MML=1, which allows the kernel to prevent userland applications from arbitrarily upgrading their access permissions. As detailed above, this changes the meaning of the Locked bit from access controls affect M-Mode to accessible only in M-Mode if set, only in U/S-Mode if unset. Once MML is set, it is important not to clear RLB, as this would forfeit the kernel’s ability to reconfigure ePMP slots until the next reset.

• MMWP=1
• MML=1
• RLB=1

Upon jumping to userland, the kernel can isolate the target application’s memory by disabling the slots corresponding to the kernel and other applications. The details of such a configuration are implementation-dependent.

Testplan

On device tests require the DV address space be writable so that the test result can be reported. To allow this, the test (running in place of the Silicon Creator firmware), can allocate an additional slot for this.

• MMWP=1
• MML=0
• RLB=1

Functional Test (simulation/FPGA)

The ROM memory protection functional test will consist of the ROM (or ROM0/ROM1) images(s) and a placeholder binary running in place of the Silicon Creator firmware. The functional test will verify that the state of the ePMP registers matches the configuration listed under ROM Initial Setup when the ROM’s C code is first reached, and the configuration listed under either ROM Boot Transition or ROM1 Boot Transition, depending on the design, when the placeholder binary is reached.

Unit tests

Unit tests can make use of the existing CSR unit test framework. The focus of these tests will be on making sure that the verification functionality in the ROM validates the PMP configuration correctly.

Error handling tests

The Memory Protection module is not responsible for testing the state of the ePMP CSRs when the boot sequence is aborted. The Shutdown module tests must ensure that the ePMP CSRs are locked down correctly when an error occurs.