riscv-peripheral crate

.github/workflows/changelog.yaml

@@ -23,6 +23,8 @@ jobs:
               - 'riscv-rt/**'
             riscv-pac:
               - 'riscv-pac/**'
+            riscv-peripheral:
+              - 'riscv-peripheral/**'
 
       - name: Check for CHANGELOG.md (riscv)
         if: steps.changes.outputs.riscv == 'true'
@@ -47,3 +49,11 @@ jobs:
           changeLogPath: ./riscv-pac/CHANGELOG.md
           skipLabels: 'skip changelog'
           missingUpdateErrorMessage: 'Please add a changelog entry in the riscv-pac/CHANGELOG.md file.'
+
+      - name: Check for CHANGELOG.md (riscv-peripheral)
+        if: steps.changes.outputs.riscv-peripheral == 'true'
+        uses: dangoslen/changelog-enforcer@v3
+        with:
+          changeLogPath: ./riscv-peripheral/CHANGELOG.md
+          skipLabels: 'skip changelog'
+          missingUpdateErrorMessage: 'Please add a changelog entry in the riscv-peripheral/CHANGELOG.md file.'

.github/workflows/riscv-peripheral.yaml

@@ -0,0 +1,61 @@
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+  merge_group:
+
+name: Build check (riscv-peripheral)
+
+jobs:
+  # We check that the crate builds and links for all the toolchains and targets.
+  build-riscv:
+    strategy:
+      matrix:
+        # All generated code should be running on stable now, MRSV is 1.61.0
+        toolchain: [ stable, nightly, 1.61.0 ]
+        target:
+          - riscv32i-unknown-none-elf
+          - riscv32imc-unknown-none-elf
+          - riscv32imac-unknown-none-elf
+          - riscv64imac-unknown-none-elf
+          - riscv64gc-unknown-none-elf
+        include:
+          # Nightly is only for reference and allowed to fail
+          - toolchain: nightly
+            experimental: true
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.experimental || false }}
+    steps:
+    - uses: actions/checkout@v4
+    - uses: dtolnay/rust-toolchain@master
+      with:
+        toolchain: ${{ matrix.toolchain }}
+        targets: ${{ matrix.target }}
+    - name: Build (no features)
+      run: cargo build --package riscv-peripheral --target ${{ matrix.target }}
+    - name: Build (all features)
+      run: cargo build --package riscv-peripheral --target ${{ matrix.target }} --all-features
+
+  # On MacOS, Ubuntu, and Windows, we run the tests.
+  build-others:
+    strategy:
+      matrix:
+        os: [ macos-latest, ubuntu-latest, windows-latest ]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Build (no features)
+        run: cargo test --package riscv-peripheral
+      - name: Build (all features)
+        run: cargo test --package riscv-peripheral --all-features
+
+  # Job to check that all the builds succeeded
+  build-check:
+    needs:
+    - build-riscv
+    - build-others
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - run: jq --exit-status 'all(.result == "success")' <<< '${{ toJson(needs) }}'

Cargo.toml

@@ -3,5 +3,6 @@ resolver = "2"
 members = [
     "riscv",
     "riscv-pac",
+    "riscv-peripheral",
     "riscv-rt",
 ]

README.md

@@ -4,6 +4,7 @@ This repository contains various crates useful for writing Rust programs on RISC
 
 * [`riscv`]: CPU registers access and intrinsics
 * [`riscv-pac`]: Common traits to be implemented by RISC-V PACs
+* [`riscv-peripheral`]: Interfaces for standard RISC-V peripherals
 * [`riscv-rt`]: Startup code and interrupt handling
 
 
@@ -22,6 +23,8 @@ Conduct][CoC], the maintainer of this crate, the [RISC-V team][team], promises
 to intervene to uphold that code of conduct.
 
 [`riscv`]: https://crates.io/crates/riscv
+[`riscv-pac`]: https://crates.io/crates/riscv-pac
+[`riscv-peripheral`]: https://crates.io/crates/riscv-peripheral
 [`riscv-rt`]: https://crates.io/crates/riscv-rt
 [team]: https://github.com/rust-embedded/wg#the-risc-v-team
 [CoC]: CODE_OF_CONDUCT.md

riscv-pac/CHANGELOG.md

@@ -10,3 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 
 - Add `InterruptNumber`, `PriorityNumber`, and `HartIdNumber` traits.
+
+### Changed
+
+- Update `README.md`

riscv-pac/README.md

@@ -1,13 +1,13 @@
-[![crates.io](https://img.shields.io/crates/d/riscv.svg)](https://crates.io/crates/riscv)
-[![crates.io](https://img.shields.io/crates/v/riscv.svg)](https://crates.io/crates/riscv)
+[![crates.io](https://img.shields.io/crates/d/riscv-pac.svg)](https://crates.io/crates/riscv-pac)
+[![crates.io](https://img.shields.io/crates/v/riscv-pac.svg)](https://crates.io/crates/riscv-pac)
 
 # `riscv-pac`
 
 > Target-specific traits to be implemented by PACs
 
 This project is developed and maintained by the [RISC-V team][team].
 
-## [Documentation](https://docs.rs/crate/riscv)
+## [Documentation](https://docs.rs/crate/riscv-pac)
 
 ## Minimum Supported Rust Version (MSRV)
 

riscv-peripheral/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+- Add `ACLINT`, `CLINT`, and `PLIC` structs

riscv-peripheral/Cargo.toml

@@ -8,7 +8,8 @@ edition = "2021"
 [dependencies]
 embedded-hal = "1.0.0-rc.2"
 # embedded-hal-async = { version = "1.0.0-rc.1", optional =  true }
-riscv = { git = "https://github.com/rust-embedded/riscv", branch = "master" }
+riscv = { path = "../riscv", version = "0.10" }
+riscv-pac = { path = "../riscv-pac", version = "0.1.0" }
 
 [features]
 # hal-async = ["embedded-hal-async"]

riscv-peripheral/README.md

@@ -1,8 +1,40 @@
+[![crates.io](https://img.shields.io/crates/d/riscv-peripheral.svg)](https://crates.io/crates/riscv-peripheral)
+[![crates.io](https://img.shields.io/crates/v/riscv-peripheral.svg)](https://crates.io/crates/riscv-peripheral)
+
 # `riscv-peripheral`
 
-> Standard RISC-V peripherals for embedded systems written in Rust
+> Interfaces for standard RISC-V peripherals
+
+This project is developed and maintained by the [RISC-V team][team].
+
+## [Documentation](https://docs.rs/crate/riscv-peripheral)
 
 ## Minimum Supported Rust Version (MSRV)
 
 This crate is guaranteed to compile on stable Rust 1.61 and up. It *might*
 compile with older versions but that may change in any new patch release.
+
+## License
+
+Copyright 2023-2024s [RISC-V team][team]
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+
+## Code of Conduct
+
+Contribution to this crate is organized under the terms of the [Rust Code of
+Conduct][CoC], the maintainer of this crate, the [RISC-V team][team], promises
+to intervene to uphold that code of conduct.
+
+[CoC]: CODE_OF_CONDUCT.md
+[team]: https://github.com/rust-embedded/wg#the-risc-v-team

riscv-peripheral/examples/e310x.rs

@@ -1,7 +1,8 @@
-use riscv_peripheral::{
-    aclint::HartIdNumber,
-    plic::{ContextNumber, InterruptNumber, PriorityNumber},
-};
+//! Peripheral definitions for the E310x chip.
+//! This is a simple example of how to use the `riscv-peripheral` crate to generate
+//! peripheral definitions for a target.
+
+use riscv_pac::{HartIdNumber, InterruptNumber, PriorityNumber};
 
 #[repr(u16)]
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -28,25 +29,6 @@ unsafe impl HartIdNumber for HartId {
     }
 }
 
-unsafe impl ContextNumber for HartId {
-    const MAX_CONTEXT_NUMBER: u16 = 0;
-
-    #[inline]
-    fn number(self) -> u16 {
-        self as _
-    }
-
-    #[inline]
-    fn from_number(number: u16) -> Result<Self, u16> {
-        if number > Self::MAX_CONTEXT_NUMBER {
-            Err(number)
-        } else {
-            // SAFETY: valid context number
-            Ok(unsafe { core::mem::transmute(number) })
-        }
-    }
-}
-
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 #[repr(u16)]
 pub enum Interrupt {
@@ -162,4 +144,9 @@ riscv_peripheral::clint_codegen!(
     msips [msip0=(HartId::H0,"`H0`")],
 );
 
+riscv_peripheral::plic_codegen!(
+    base 0x0C00_0000,
+    ctxs [ctx0=(HartId::H0,"`H0`")],
+);
+
 fn main() {}

riscv-peripheral/src/aclint.rs

@@ -7,32 +7,7 @@ pub mod mswi;
 pub mod mtimer;
 pub mod sswi;
 
-/// Trait for enums of HART IDs in (A)CLINT peripherals.
-///
-/// # Note
-///
-/// If your target only has one HART (HART ID 0), you don't need to implement this trait.
-/// Instead, you can access directly to the base registers through the `(A)CLINT` structs.
-///
-/// # Safety
-///
-/// * This trait must only be implemented on a PAC of a target with a PLIC peripheral.
-/// * This trait must only be implemented on enums of HART IDs.
-/// * Each enum variant must represent a distinct value (no duplicates are permitted).
-/// * Each enum variant must always return the same value (do not change at runtime).
-/// * All the HART ID numbers must be less than or equal to `MAX_HART_ID_NUMBER`.
-/// * `MAX_HART_ID_NUMBER` must coincide with the highest allowed HART ID number.
-pub unsafe trait HartIdNumber: Copy {
-    /// Highest number assigned to a HART ID.
-    const MAX_HART_ID_NUMBER: u16;
-
-    /// Converts a HART Id to its corresponding number.
-    fn number(self) -> u16;
-
-    /// Tries to convert a number to a valid HART ID.
-    /// If the conversion fails, it returns an error with the number back.
-    fn from_number(value: u16) -> Result<Self, u16>;
-}
+pub use riscv_pac::HartIdNumber; // re-export useful riscv-pac traits
 
 /// Trait for a CLINT peripheral.
 ///