misc: general updates and improvements (#63)

* further improve docs

* bump toolchain to `nightly-2024-01-13`

* move linting to workspace (root `Cargo.toml`)

* update dependencies

* updated `riscv-rt` crate and handlers

* fix grammaer in PR template

* add sccache

* update APT index before installing QEMU

.github/pull_request_template.md

@@ -23,5 +23,5 @@
 - [ ] I have performed a self-review of my own code
 - [ ] I have commented my code, particularly in hard-to-understand areas
 - [ ] I have made corresponding changes to the documentation (README.md or the documentation under `documentation/`)
-- [ ] If necessary I have added tests that prove my fix is effective or that my feature works
+- [ ] If necessary, I have added tests that prove my fix is effective or that my feature works
 - [ ] New and existing unit tests pass locally with my changes

.github/workflows/code_tests_and_checks.yml

@@ -14,6 +14,7 @@ on: # yamllint disable-line rule:truthy
 
 defaults:
   run:
+    shell: bash
     working-directory: code
 
 jobs:
@@ -27,7 +28,23 @@ jobs:
       - name: Install Rust
         run: ../misc/scripts/install_rust.sh
 
+      - name: Run sccache-cache only on non-release runs
+        if: github.event_name != 'release' && github.event_name != 'workflow_dispatch'
+        uses: mozilla-actions/sccache-action@v0.0.3
+
+      - name: Set Rust caching env vars only on non-release runs
+        if: github.event_name != 'release' && github.event_name != 'workflow_dispatch'
+        run: |
+          echo 'SCCACHE_GHA_ENABLED=true' >>"${GITHUB_ENV}"
+          echo 'RUSTC_WRAPPER=sccache' >>"${GITHUB_ENV}"
+
+      - name: Run sccache stat for check
+        run: ${SCCACHE_PATH} --show-stats
+
       - name: Run all checks
+        env:
+          SCCACHE_GHA_ENABLED: 'true'
+          RUSTC_WRAPPER: sccache
         run: >-
           cargo run -- -vv check
 
@@ -40,16 +57,36 @@ jobs:
 
       - name: Install QEMU
         run: |
+          sudo apt-get update
           sudo apt-get -y install --no-install-recommends qemu-system-riscv64
           qemu-system-riscv64 --version
 
       - name: Install Rust
         run: ../misc/scripts/install_rust.sh
 
+      - name: Run sccache-cache only on non-release runs
+        if: github.event_name != 'release' && github.event_name != 'workflow_dispatch'
+        uses: mozilla-actions/sccache-action@v0.0.3
+
+      - name: Set Rust caching env vars only on non-release runs
+        if: github.event_name != 'release' && github.event_name != 'workflow_dispatch'
+        run: |
+          echo 'SCCACHE_GHA_ENABLED=true' >>"${GITHUB_ENV}"
+          echo 'RUSTC_WRAPPER=sccache' >>"${GITHUB_ENV}"
+
+      - name: Run sccache stat for check
+        run: ${SCCACHE_PATH} --show-stats
+
       - name: Run all unit-test
+        env:
+          SCCACHE_GHA_ENABLED: 'true'
+          RUSTC_WRAPPER: sccache
         run: >-
           cargo run -- -vv u-test
 
       - name: Run all integration-tests
+        env:
+          SCCACHE_GHA_ENABLED: 'true'
+          RUSTC_WRAPPER: sccache
         run: >-
           cargo run -- -vv i-test

code/Cargo.toml

@@ -37,6 +37,9 @@ autobins = true
 autoexamples = true
 autotests = true
 
+[lints]
+workspace = true
+
 # -----------------------------------------------
 # ----  Profiles  -------------------------------
 # -----------------------------------------------
@@ -61,14 +64,14 @@ lto = false
 # -----------------------------------------------
 
 [dependencies]
-anyhow = "1.0.75"
+anyhow = "1.0.79"
 chrono = "0.4.31"
-clap = { version = "4.4.6", features = ["derive"] }
-clap-verbosity-flag = "2.0.1"
-colored = "2.0.4"
+clap = { version = "4.4.16", features = ["derive"] }
+clap-verbosity-flag = "2.1.1"
+colored = "2.1.0"
 log = "0.4.20"
 regex = "1.10.2"
-toml = "0.8.4"
+toml = "0.8.8"
 wait-timeout = "0.2.0"
 which = "5.0.0"
 
@@ -78,3 +81,36 @@ which = "5.0.0"
 
 [workspace]
 members = ["uncore"]
+
+# General lints "inherent" in Rustlang.
+[workspace.lints.rust]
+# We require docs on all items
+missing_docs = "deny"
+# We require a debug implementation on all items
+missing_debug_implementations = "deny"
+
+# Lint target for code documentation. When running `rustdoc`,
+# show an error when using broken links.
+[workspace.lints.rustdoc]
+all = "deny"
+broken_intra_doc_links = "deny"
+private_intra_doc_links = "allow"
+
+# Lint target for Clippy ("A collection of lints to catch common
+# mistakes and improve your Rust code.", ref:
+# https://doc.rust-lang.org/nightly/clippy/)
+[workspace.lints.clippy]
+# Clippy lint target one. Enables all lints that are on by
+# default (correctness, suspicious, style, complexity, perf).
+all = "deny"
+# Clippy lint target two. Enables lints which are rather strict
+# or have occasional false positives.
+nursery = "deny"
+# Clippy lint target three. Enables new lints that are still
+# under development
+pedantic = "deny"
+# Clippy lint target four. Enable lints for the cargo manifest
+# file, a.k.a. Cargo.toml.
+cargo = "deny"
+# Individual lints go here now:
+missing_docs_in_private_items = "deny"

code/rust-toolchain.toml

@@ -11,6 +11,6 @@
 # General information about the keys below can be found under
 # https://rust-lang.github.io/rustup/concepts/index.html
 [toolchain]
-channel = 'nightly-2023-11-10'
+channel = 'nightly-2024-01-13'
 components = [ 'cargo', 'rustc', 'rust-std', 'clippy', 'rustfmt' ]
 targets = ['riscv64gc-unknown-none-elf']

code/src/command.rs

@@ -304,17 +304,15 @@ where
 
   // Create a list of all binaries to run
   let jq = jq.wait_with_output()?;
-  let test_binaries: Vec<&str> = std::str::from_utf8(&jq.stdout)?.trim().split('\n').collect();
+  let test_binaries: Vec<String> = std::str::from_utf8(&jq.stdout)?
+    .lines()
+    .map(std::string::ToString::to_string)
+    .collect();
   if test_binaries.is_empty() {
     anyhow::bail!("Cargo did not create a test binary?!");
   }
 
-  Ok(
-    test_binaries
-      .into_iter()
-      .map(std::string::ToString::to_string)
-      .collect(),
-  )
+  Ok(test_binaries)
 }
 
 /// When we parse Cargo's output (when `--message-format=json`) with `jq`, we get the
@@ -377,29 +375,24 @@ fn run_unit_tests(
   is_debug: bool,
 ) -> anyhow::Result<()> {
   log::info!("Building unit test binary");
-  let test_binary_path = create_test_binaries(arch_specification, ["--lib"])?;
-  let test_binary_path = test_binary_path.first();
-  if let Some(binary_path) = test_binary_path {
-    let mut qemu_arguments = arch_specification.qemu_arguments();
-    qemu_arguments.append(&mut vec!["-kernel", binary_path]);
-
-    if is_debug {
-      log::info!("Debugging unCORE unit tests");
-      qemu_arguments.append(&mut vec!["-s", "-S"]);
-      create_gdb_init_file(&parse_binary_name(binary_path)?, binary_path)?;
-    } else {
-      log::info!("Running unCORE unit tests");
-      log::trace!("The unit test binary file is '{}'", binary_path);
-    }
+  let binary_path = create_test_binaries(arch_specification, ["--lib"])?;
+  let binary_path = binary_path
+    .first()
+    .expect("This is unreachable since create_test_binaries already checks for emptiness");
+  let mut qemu_arguments = arch_specification.qemu_arguments();
+  qemu_arguments.append(&mut vec!["-kernel", binary_path]);
 
-    run_command_and_check_with_timeout!(arch_specification.qemu_command, qemu_arguments, 1)?;
+  if is_debug {
+    log::info!("Debugging unCORE unit tests");
+    qemu_arguments.append(&mut vec!["-s", "-S"]);
+    create_gdb_init_file(&parse_binary_name(binary_path)?, binary_path)?;
   } else {
-    // This part is unreachable because [`test_helper`] does already check whether the vector
-    // contains at least one element and returns an error otherwise; which is caught by the
-    // `?` operator in the line above.
-    unreachable!();
+    log::info!("Running unCORE unit tests");
+    log::trace!("The unit test binary file is '{}'", binary_path);
   }
 
+  run_command_and_check_with_timeout!(arch_specification.qemu_command, qemu_arguments, 1)?;
+
   log::info!("Unit tests finished successfully");
   Ok(())
 }
@@ -435,7 +428,7 @@ fn run_integration_tests(
     }
     log::trace!("The integration test binary file is '{}'", binary);
     let mut current_arguments = qemu_arguments.clone();
-    current_arguments.append(&mut vec!["-kernel", binary.as_str()]);
+    current_arguments.append(&mut vec!["-kernel", &binary]);
     run_command_and_check_with_timeout!(arch_specification.qemu_command, current_arguments, 60)?;
     log::info!("Integration test '{}' finished successfully", test_name);
   }

code/src/main.rs

@@ -2,30 +2,6 @@
 
 // Preventing `unsafe` code in `main.rs` completely.
 #![forbid(unsafe_code)]
-// Clippy lint target one. Enables all lints that are on by
-// default (correctness, suspicious, style, complexity, perf).
-#![deny(clippy::all)]
-// Clippy lint target two. Enables lints which are rather strict
-// or have occasional false positives.
-#![deny(clippy::nursery)]
-// Clippy lint target three. Enables new lints that are still
-// under development
-#![deny(clippy::pedantic)]
-// Clippy lint target four. Enable lints for the cargo manifest
-// file, a.k.a. Cargo.toml.
-#![deny(clippy::cargo)]
-#![allow(clippy::multiple_crate_versions)]
-// Lint target for code documentation. This lint enforces code
-// documentation on every code item.
-#![deny(missing_docs)]
-#![deny(missing_debug_implementations)]
-#![deny(clippy::missing_docs_in_private_items)]
-// Lint target for code documentation. When running `rustdoc`,
-// show an error when using broken links.
-#![deny(rustdoc::all)]
-// All other, generic lint targets that were not
-// covered previously
-#![deny(missing_debug_implementations)]
 
 //! ## `unCORE` Helper
 //!

code/uncore/Cargo.toml

@@ -51,6 +51,9 @@ autobins = true
 autoexamples = true
 autotests = false
 
+[lints]
+workspace = true
+
 # -----------------------------------------------
 # ----  Dependencies  ---------------------------
 # -----------------------------------------------
@@ -60,8 +63,8 @@ autotests = false
 [dependencies]
 linked_list_allocator = "0.10.5"
 log = "0.4.20"
-owo-colors = "3.5.0"
-riscv-rt = { git = "https://github.com/rust-embedded/riscv-rt.git", rev = "28b916d", features = ["s-mode"] }
+riscv-rt = { version = "0.12.0", features = ["s-mode"] }
+owo-colors = "4.0.0"
 sbi = "0.2.0"
 spin = "0.9.8"
 

code/uncore/src/lib.rs

@@ -8,29 +8,7 @@
 // As this is no ordinary program, we have a special entry-point,
 // which is not the `main()` function.
 #![no_main]
-// Clippy lint target one. Enables all lints that are on by
-// default (correctness, suspicious, style, complexity, perf) .
-#![deny(clippy::all)]
-// Clippy lint target two. Enables lints which are rather strict
-// or have occasional false positives.
-#![deny(clippy::nursery)]
-// Clippy lint target three. Enables new lints that are still
-// under development
-#![deny(clippy::pedantic)]
-// Clippy lint target four. Enable lints for the cargo manifest
-// file, a.k.a. Cargo.toml.
-#![deny(clippy::cargo)]
-#![allow(clippy::multiple_crate_versions)]
-// Lint target for code documentation. This lint enforces code
-// documentation on every code item.
-#![deny(missing_docs)]
-#![deny(missing_debug_implementations)]
-#![deny(clippy::missing_docs_in_private_items)]
-// Lint target for code documentation. When running `rustdoc`,
-// show an error when using broken links.
-#![deny(rustdoc::all)]
-#![deny(rustdoc::broken_intra_doc_links)]
-#![allow(rustdoc::private_intra_doc_links)]
+// #![allow(clippy::multiple_crate_versions)]
 // With our own test framework, we have to define which function
 // runs our tests.
 #![test_runner(crate::library::test::runner)]

code/uncore/src/library/arch/risc_v/interrupts_exceptions.rs

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+//! Contains all interrupt handlers. These handlers are set up by [`riscv-rt`].
+
+/// This function is used by [`riscv-rt`] to provide an exception handler.
+#[export_name = "ExceptionHandler"]
+fn default_exception_handler(_trap_frame: &riscv_rt::TrapFrame) -> ! {
+  todo!("Exception occurred but handler has not been written");
+}
+
+/// This function is used by [`riscv-rt`] to provide an interrupt handler.
+#[export_name = "DefaultHandler"]
+fn default_interrupt_handler(_trap_frame: &riscv_rt::TrapFrame) -> ! {
+  todo!("Exception occurred but handler has not been written");
+}