Add 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

@@ -0,0 +1,22 @@
+[package]
+name = "riscv-peripheral"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+embedded-hal = "1.0.0-rc.2"
+# embedded-hal-async = { version = "1.0.0-rc.1", optional =  true }
+riscv = { path = "../riscv", version = "0.10" }
+riscv-pac = { path = "../riscv-pac", version = "0.1.0" }
+
+[features]
+# hal-async = ["embedded-hal-async"]
+
+[package.metadata.docs.rs]
+default-target = "riscv64imac-unknown-none-elf"
+targets = [
+    "riscv32i-unknown-none-elf", "riscv32imc-unknown-none-elf", "riscv32imac-unknown-none-elf",
+    "riscv64imac-unknown-none-elf", "riscv64gc-unknown-none-elf",
+]

riscv-peripheral/README.md

@@ -0,0 +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`
+
+> 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

@@ -0,0 +1,152 @@
+//! 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)]
+pub enum HartId {
+    H0 = 0,
+}
+
+unsafe impl HartIdNumber for HartId {
+    const MAX_HART_ID_NUMBER: u16 = 0;
+
+    #[inline]
+    fn number(self) -> u16 {
+        self as _
+    }
+
+    #[inline]
+    fn from_number(number: u16) -> Result<Self, u16> {
+        if number > Self::MAX_HART_ID_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 {
+    WATCHDOG = 1,
+    RTC = 2,
+    UART0 = 3,
+    UART1 = 4,
+    QSPI0 = 5,
+    QSPI1 = 6,
+    QSPI2 = 7,
+    GPIO0 = 8,
+    GPIO1 = 9,
+    GPIO2 = 10,
+    GPIO3 = 11,
+    GPIO4 = 12,
+    GPIO5 = 13,
+    GPIO6 = 14,
+    GPIO7 = 15,
+    GPIO8 = 16,
+    GPIO9 = 17,
+    GPIO10 = 18,
+    GPIO11 = 19,
+    GPIO12 = 20,
+    GPIO13 = 21,
+    GPIO14 = 22,
+    GPIO15 = 23,
+    GPIO16 = 24,
+    GPIO17 = 25,
+    GPIO18 = 26,
+    GPIO19 = 27,
+    GPIO20 = 28,
+    GPIO21 = 29,
+    GPIO22 = 30,
+    GPIO23 = 31,
+    GPIO24 = 32,
+    GPIO25 = 33,
+    GPIO26 = 34,
+    GPIO27 = 35,
+    GPIO28 = 36,
+    GPIO29 = 37,
+    GPIO30 = 38,
+    GPIO31 = 39,
+    PWM0CMP0 = 40,
+    PWM0CMP1 = 41,
+    PWM0CMP2 = 42,
+    PWM0CMP3 = 43,
+    PWM1CMP0 = 44,
+    PWM1CMP1 = 45,
+    PWM1CMP2 = 46,
+    PWM1CMP3 = 47,
+    PWM2CMP0 = 48,
+    PWM2CMP1 = 49,
+    PWM2CMP2 = 50,
+    PWM2CMP3 = 51,
+    I2C0 = 52,
+}
+
+unsafe impl InterruptNumber for Interrupt {
+    const MAX_INTERRUPT_NUMBER: u16 = 52;
+
+    #[inline]
+    fn number(self) -> u16 {
+        self as _
+    }
+
+    #[inline]
+    fn from_number(number: u16) -> Result<Self, u16> {
+        if number == 0 || number > Self::MAX_INTERRUPT_NUMBER {
+            Err(number)
+        } else {
+            // SAFETY: valid interrupt number
+            Ok(unsafe { core::mem::transmute(number) })
+        }
+    }
+}
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+#[repr(u8)]
+pub enum Priority {
+    P0 = 0,
+    P1 = 1,
+    P2 = 2,
+    P3 = 3,
+    P4 = 4,
+    P5 = 5,
+    P6 = 6,
+    P7 = 7,
+}
+
+unsafe impl PriorityNumber for Priority {
+    const MAX_PRIORITY_NUMBER: u8 = 7;
+
+    #[inline]
+    fn number(self) -> u8 {
+        self as _
+    }
+
+    #[inline]
+    fn from_number(number: u8) -> Result<Self, u8> {
+        if number > Self::MAX_PRIORITY_NUMBER {
+            Err(number)
+        } else {
+            // SAFETY: valid priority number
+            Ok(unsafe { core::mem::transmute(number) })
+        }
+    }
+}
+
+riscv_peripheral::clint_codegen!(
+    base 0x0200_0000,
+    freq 32_768,
+    mtimecmps [mtimecmp0=(HartId::H0,"`H0`")],
+    msips [msip0=(HartId::H0,"`H0`")],
+);
+
+riscv_peripheral::plic_codegen!(
+    base 0x0C00_0000,
+    ctxs [ctx0=(HartId::H0,"`H0`")],
+);
+
+fn main() {}