feat(awkernel_userland): userland is both library and binary, so users can extend base userland (#767)

Author: romancardenas

.cargo/config.toml

@@ -1,35 +1,35 @@
 [alias]
-x86 = "build --package userland --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-aarch64 = "build --package userland --no-default-features --features aarch64 --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-rv32 = "build --package userland --no-default-features --features rv32 --target riscv32imac-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-rv64 = "build --package userland --no-default-features --features rv64 --target riscv64gc-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-std = "build --package userland --no-default-features --features std"
+x86 = "build --package awkernel_userland --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+aarch64 = "build --package awkernel_userland --no-default-features --features aarch64 --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+rv32 = "build --package awkernel_userland --no-default-features --features rv32 --target riscv32imac-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+rv64 = "build --package awkernel_userland --no-default-features --features rv64 --target riscv64gc-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+std = "build --package awkernel_userland --no-default-features --features std"
 
 test_awkernel_lib = "test --package awkernel_lib --no-default-features --features std"
 test_awkernel_async_lib = "test --package awkernel_async_lib --no-default-features --features std"
 test_awkernel_drivers = "test --package awkernel_drivers --no-default-features --features std"
 test_smoltcp = "test --package smoltcp --no-default-features --features std --features awkernel"
 test_rd_gen_to_dags = "test --package rd_gen_to_dags --no-default-features --features std --features milliseconds"
 
-clippy_x86 = "clippy --package userland --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-clippy_raspi = "clippy --package userland --no-default-features --features raspi --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-clippy_raspi5 = "clippy --package userland --no-default-features --features raspi5 --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-clippy_aarch64_virt = "clippy --package userland --no-default-features --features aarch64_virt --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-clippy_std = "clippy --package userland --no-default-features --features std"
-clippy_rv32 = "clippy --package userland --no-default-features --features rv32 --target riscv32imac-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-clippy_rv64 = "clippy --package userland --no-default-features --features rv64 --target riscv64gc-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+clippy_x86 = "clippy --package awkernel_userland --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+clippy_raspi = "clippy --package awkernel_userland --no-default-features --features raspi --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+clippy_raspi5 = "clippy --package awkernel_userland --no-default-features --features raspi5 --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+clippy_aarch64_virt = "clippy --package awkernel_userland --no-default-features --features aarch64_virt --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+clippy_std = "clippy --package awkernel_userland --no-default-features --features std"
+clippy_rv32 = "clippy --package awkernel_userland --no-default-features --features rv32 --target riscv32imac-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+clippy_rv64 = "clippy --package awkernel_userland --no-default-features --features rv64 --target riscv64gc-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
 clippy_rd_gen_to_dags = "clippy --package rd_gen_to_dags --no-default-features  --features std --features milliseconds"
 
-check_aarch64 = "check --package userland --no-default-features --features aarch64 --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-check_x86 = "check --package userland --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-check_rv32 = "check --package userland --no-default-features --features rv32 --target riscv32imac-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-check_rv64 = "check --package userland --no-default-features --features rv64 --target riscv64gc-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-check_no_std = "check --package userland -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem --quiet --message-format=json -Zjson-target-spec"
-check_std = "check --package userland --no-default-features --features std"
+check_aarch64 = "check --package awkernel_userland --no-default-features --features aarch64 --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+check_x86 = "check --package awkernel_userland --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+check_rv32 = "check --package awkernel_userland --no-default-features --features rv32 --target riscv32imac-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+check_rv64 = "check --package awkernel_userland --no-default-features --features rv64 --target riscv64gc-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+check_no_std = "check --package awkernel_userland -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem --quiet --message-format=json -Zjson-target-spec"
+check_std = "check --package awkernel_userland --no-default-features --features std"
 
-doc_raspi = "doc --package userland --no-default-features --features raspi --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-doc_aarch64_virt = "doc --package userland --no-default-features --features aarch64_virt --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-doc_x86 = "doc --package userland --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+doc_raspi = "doc --package awkernel_userland --no-default-features --features raspi --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+doc_aarch64_virt = "doc --package awkernel_userland --no-default-features --features aarch64_virt --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+doc_x86 = "doc --package awkernel_userland --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
 
 udeps_x86 = "udeps --package awkernel --no-default-features --features x86 --target x86_64-unknown-linux-gnu"
 udeps_raspi = "udeps --package awkernel --no-default-features --features x86 --target x86_64-unknown-linux-gnu"

userland/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "userland"
+name = "awkernel_userland"
 version = "0.1.0"
 edition = "2021"
 

userland/src/lib.rs

@@ -0,0 +1,66 @@
+#![cfg_attr(not(feature = "std"), no_std)]
+
+extern crate alloc;
+extern crate awkernel;
+
+use alloc::borrow::Cow;
+
+pub async fn run() -> Result<(), Cow<'static, str>> {
+    awkernel_services::run().await;
+
+    #[cfg(feature = "autoware")]
+    autoware::run().await; // run the autoware application
+
+    #[cfg(feature = "rd_gen_to_dags")]
+    rd_gen_to_dags::run().await; // run the rd_gen_to_dags application
+
+    #[cfg(feature = "test_network")]
+    test_network::run().await; // test for network
+
+    #[cfg(feature = "test_pubsub")]
+    test_pubsub::run().await; // test for pubsub
+
+    #[cfg(feature = "test_rpi_hal")]
+    test_rpi_hal::run().await; // test for RPi HAL
+
+    #[cfg(feature = "test_graphics")]
+    test_graphics::run().await; // test for graphics
+
+    #[cfg(feature = "test_prioritized_fifo")]
+    test_prioritized_fifo::run().await; // test for prioritized_fifo
+
+    #[cfg(feature = "test_multi_prioritized_scheduler")]
+    test_multi_prioritized_scheduler::run().await; // test for multi prioritized scheduler
+
+    #[cfg(feature = "test_prioritized_rr")]
+    test_prioritized_rr::run().await; // test for prioritized_rr
+
+    #[cfg(feature = "test_async_mutex")]
+    test_async_mutex::run().await; // test for async_mutex
+
+    #[cfg(feature = "test_gedf")]
+    test_gedf::run().await; // test for Global Earliest Deadline First scheduler
+
+    #[cfg(feature = "test_measure_channel")]
+    test_measure_channel::run().await; // measure channel
+
+    #[cfg(feature = "test_measure_channel_heavy")]
+    test_measure_channel_heavy::run().await; // measure channel heavy
+
+    #[cfg(feature = "test_dag")]
+    test_dag::run().await; // test for DAG
+
+    #[cfg(feature = "test_dvfs")]
+    test_dvfs::run().await; // test for DVFS
+
+    #[cfg(feature = "test_raspi_dvfs")]
+    test_raspi_dvfs::run().await; // test for Raspberry Pi firmware mailbox DVFS
+
+    #[cfg(feature = "test_voluntary_preemption")]
+    test_voluntary_preemption::run().await; // test for voluntary preemption
+
+    #[cfg(feature = "test_clustered_edf")]
+    test_clustered_edf::run().await; // test for Clustered EDF scheduler
+
+    Ok(())
+}

userland/src/main.rs

@@ -2,68 +2,10 @@
 #![no_main]
 
 extern crate alloc;
-// Links the kernel's entry points and panic handler.
-extern crate awkernel;
 
 use alloc::borrow::Cow;
 
 #[awkernel::main]
 async fn main() -> Result<(), Cow<'static, str>> {
-    awkernel_services::run().await;
-
-    #[cfg(feature = "autoware")]
-    autoware::run().await; // run the autoware application
-
-    #[cfg(feature = "rd_gen_to_dags")]
-    rd_gen_to_dags::run().await; // run the rd_gen_to_dags application
-
-    #[cfg(feature = "test_network")]
-    test_network::run().await; // test for network
-
-    #[cfg(feature = "test_pubsub")]
-    test_pubsub::run().await; // test for pubsub
-
-    #[cfg(feature = "test_rpi_hal")]
-    test_rpi_hal::run().await; // test for RPi HAL
-
-    #[cfg(feature = "test_graphics")]
-    test_graphics::run().await; // test for graphics
-
-    #[cfg(feature = "test_prioritized_fifo")]
-    test_prioritized_fifo::run().await; // test for prioritized_fifo
-
-    #[cfg(feature = "test_multi_prioritized_scheduler")]
-    test_multi_prioritized_scheduler::run().await; // test for multi prioritized scheduler
-
-    #[cfg(feature = "test_prioritized_rr")]
-    test_prioritized_rr::run().await; // test for prioritized_rr
-
-    #[cfg(feature = "test_async_mutex")]
-    test_async_mutex::run().await; // test for async_mutex
-
-    #[cfg(feature = "test_gedf")]
-    test_gedf::run().await; // test for Global Earliest Deadline First scheduler
-
-    #[cfg(feature = "test_measure_channel")]
-    test_measure_channel::run().await; // measure channel
-
-    #[cfg(feature = "test_measure_channel_heavy")]
-    test_measure_channel_heavy::run().await; // measure channel heavy
-
-    #[cfg(feature = "test_dag")]
-    test_dag::run().await; // test for DAG
-
-    #[cfg(feature = "test_dvfs")]
-    test_dvfs::run().await; // test for DVFS
-
-    #[cfg(feature = "test_raspi_dvfs")]
-    test_raspi_dvfs::run().await; // test for Raspberry Pi firmware mailbox DVFS
-
-    #[cfg(feature = "test_voluntary_preemption")]
-    test_voluntary_preemption::run().await; // test for voluntary preemption
-
-    #[cfg(feature = "test_clustered_edf")]
-    test_clustered_edf::run().await; // test for Clustered EDF scheduler
-
-    Ok(())
+    awkernel_userland::run().await
 }

userland_extern_template/Cargo.toml

@@ -7,10 +7,12 @@ edition = "2021"
 [workspace]
 
 [[bin]]
+# To make sure the binary's name is always awkernel
 name = "awkernel"
 path = "src/main.rs"
 
 [features]
+perf = ["awkernel/perf"]
 debug = ["awkernel/debug"]
 # Select exactly one architecture (the Makefile does it).
 x86 = ["awkernel/x86"]
@@ -19,6 +21,7 @@ raspi = ["awkernel/raspi"]
 raspi5 = ["awkernel/raspi5"]
 rv32 = ["awkernel/rv32"]
 rv64 = ["awkernel/rv64"]
+std = ["awkernel/std"]
 
 [dependencies]
 log = "0.4"
@@ -27,6 +30,13 @@ log = "0.4"
 path = "../kernel"
 default-features = false
 
+[dependencies.awkernel_userland]
+# As an example, you can extend the base userland crate with your own code in this crate!
+# Here, I will only use the basic awkernel services and the test_dvfs application
+path = "../userland"
+default-features = false
+features = ["test_dvfs"]
+
 [dependencies.awkernel_async_lib]
 path = "../awkernel_async_lib"
 default-features = false

userland_extern_template/src/main.rs

@@ -11,6 +11,7 @@ use core::time::Duration;
 
 #[awkernel::main]
 async fn main() -> Result<(), Cow<'static, str>> {
+    awkernel_userland::run().await?;
     loop {
         log::info!("Hello from an out-of-tree userland!");
         sleep(Duration::from_secs(1)).await;