Start of Kobj support: Semaphores and Threads

Kconfig

@@ -19,4 +19,16 @@ config RUST
 	help
 	  This option enables the use of applications written in Rust.
 
+if RUST
+
+config RUST_ALLOC
+	bool "Support an allocator in Rust code"
+	help
+	  If enabled, the Rust zephyr support library will include support for
+	  an allocator.  This allocator will use the currently configured
+	  Zephyr allocator (malloc/free).  This this enabled, Rust
+	  applications can use the `alloc` crate.
+
+endif # RUST
+
 endmenu

README.rst

@@ -70,7 +70,7 @@ your application directory, with options set so that it can find the Zephyr supp
 that the output will be contained within the Zephyr build directory.
 
 The :file:`Cargo.toml` will need to have a ``[lib]`` section that sets ``crate-type =
-["staticlib"]``, and will need to include ``zephyr = "0.1.0"`` as a dependency.  You can use
+["staticlib"]``, and will need to include ``zephyr = "3.7.0"`` as a dependency.  You can use
 crates.io and the Crate ecosystem to include any other dependencies you need.  Just make sure that
 you use crates that support building with no-std.
 
@@ -115,7 +115,7 @@ To your ``Cargo.toml`` file, add the following:
 .. code-block:: toml
 
    [build-dependencies]
-   zephyr-build = "0.1.0"
+   zephyr-build = "3.7.0"
 
 Then, you will need a ``build.rs`` file to call the support function.  The following will work:
 

docgen/.cargo/config.toml

@@ -0,0 +1 @@
+../../../../../zephyr/build/rust/sample-cargo-config.toml

docgen/.gitignore

@@ -0,0 +1,7 @@
+# In this case, we do want the symlink checked in.  We'll assume we have the module in the standard
+# module place.
+#
+# On Windows, this symlink will just get checked out as a regular file and will have to be replaced
+# with a copy (or real symlinks enabled).  But, this shouldn't affect CI runs of the documentation,
+# which are done on Linux.
+!.cargo/

docgen/CMakeLists.txt

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+
+project(hello_rust_world)
+rust_cargo_application()

docgen/Cargo.toml

@@ -0,0 +1,16 @@
+# Copyright (c) 2024 Linaro LTD
+# SPDX-License-Identifier: Apache-2.0
+
+[package]
+# This must be rustapp for now.
+name = "rustapp"
+version = "3.7.0"
+edition = "2021"
+description = "A small application to generate documentation"
+license = "Apache-2.0 or MIT"
+
+[lib]
+crate-type = ["staticlib"]
+
+[dependencies]
+zephyr = "3.7.0"

docgen/prj.conf

@@ -0,0 +1,5 @@
+# Copyright (c) 2024 Linaro LTD
+# SPDX-License-Identifier: Apache-2.0
+
+CONFIG_RUST=y
+CONFIG_RUST_ALLOC=y

docgen/src/lib.rs

@@ -0,0 +1,16 @@
+// Copyright (c) 2024 Linaro LTD
+// SPDX-License-Identifier: Apache-2.0
+
+#![no_std]
+
+use zephyr::printkln;
+
+// Reference the Zephyr crate so that the panic handler gets used.  This is only needed if no
+// symbols from the crate are directly used.
+extern crate zephyr;
+
+#[no_mangle]
+extern "C" fn rust_main() {
+    printkln!("Hello world from Rust on {}",
+              zephyr::kconfig::CONFIG_BOARD);
+}

samples/hello_world/Cargo.toml

@@ -4,7 +4,7 @@
 [package]
 # This must be rustapp for now.
 name = "rustapp"
-version = "0.1.0"
+version = "3.7.0"
 edition = "2021"
 description = "A sample hello world application in Rust"
 license = "Apache-2.0 or MIT"
@@ -13,4 +13,4 @@ license = "Apache-2.0 or MIT"
 crate-type = ["staticlib"]
 
 [dependencies]
-zephyr = "0.1.0"
+zephyr = "3.7.0"

samples/philosophers/CMakeLists.txt

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(philosophers)
+
+rust_cargo_application()

samples/philosophers/Cargo.toml

@@ -0,0 +1,25 @@
+# Copyright (c) 2024 Linaro LTD
+# SPDX-License-Identifier: Apache-2.0
+
+[package]
+# This must be rustapp for now.
+name = "rustapp"
+version = "3.7.0"
+edition = "2021"
+description = "A sample hello world application in Rust"
+license = "Apache-2.0 or MIT"
+
+[lib]
+crate-type = ["staticlib"]
+
+[dependencies]
+zephyr = "3.7.0"
+
+# Dependencies that are used by build.rs.
+[build-dependencies]
+zephyr-build = "3.7.0"
+
+[profile.release]
+debug-assertions = true
+overflow-checks = true
+debug = true

samples/philosophers/Kconfig

@@ -0,0 +1,18 @@
+# Copyright (c) 2024 Linaro LTD
+# SPDX-License-Identifier: Apache-2.0
+
+mainmenu "Rust Dining Philosphers"
+
+source "Kconfig.zephyr"
+
+choice
+	prompt "Select Synchronization implementation"
+	default SYNC_SYS_SEMAPHORE
+
+	config SYNC_SYS_SEMAPHORE
+		bool "Use sys::Semaphore to synchronize forks"
+		help
+		  Use to have the dining philosophers sample use sys::Semaphore, with one per form,
+		  to synchronize.
+
+endchoice

samples/philosophers/boards/rpi_pico.conf

@@ -0,0 +1,7 @@
+# Copyright (c) 2024 Linaro LTD
+# SPDX-License-Identifier: Apache-2.0
+
+# This board doesn't have a serial console, so use RTT.
+CONFIG_UART_CONSOLE=n
+CONFIG_RTT_CONSOLE=y
+CONFIG_USE_SEGGER_RTT=y

samples/philosophers/build.rs

@@ -0,0 +1,9 @@
+// Copyright (c) 2023 Linaro LTD
+// SPDX-License-Identifier: Apache-2.0
+
+// This crate needs access to kconfig variables.  This is an example of how to do that.  The
+// zephyr-build must be a build dependency.
+
+fn main() {
+    zephyr_build::export_bool_kconfig();
+}

samples/philosophers/prj.conf

@@ -0,0 +1,15 @@
+# Copyright (c) 2024 Linaro LTD
+# SPDX-License-Identifier: Apache-2.0
+
+CONFIG_RUST=y
+CONFIG_RUST_ALLOC=y
+CONFIG_MAIN_STACK_SIZE=8192
+
+# CONFIG_USERSPACE=y
+
+# Some debugging
+CONFIG_THREAD_MONITOR=y
+CONFIG_THREAD_ANALYZER=y
+CONFIG_THREAD_ANALYZER_USE_PRINTK=y
+CONFIG_THREAD_ANALYZER_AUTO=n
+# CONFIG_THREAD_ANALYZER_AUTO_INTERVAL=15

samples/philosophers/sample.yaml

@@ -0,0 +1,22 @@
+sample:
+  description: Philosphers, in Rust
+  name: philosophers rust
+common:
+  harness: console
+  harness_config:
+    type: one_line
+    regex:
+      # Match the statistics, and make sure that each philosopher has at least 10 (two digits)
+      # meals.
+      # - "^\\[\\d{2,}, \\d{2,}, \\d{2,}, \\d{2,}, \\d{2,}, \\d{2,}\\]"
+      #
+      # Until the stastics have been implemented, just match on one of the children thinking
+      - "^Child 5 thinking \\(\\d+ ticks.*"
+  tags: rust
+  filter: CONFIG_RUST_SUPPORTED
+tests:
+  sample.rust.philosopher.semaphore:
+    tags: introduction
+    min_ram: 32
+    extra_configs:
+      - CONFIG_SYNC_SYS_SEMAPHORE=y

samples/philosophers/src/lib.rs

@@ -0,0 +1,134 @@
+// Copyright (c) 2023 Linaro LTD
+// SPDX-License-Identifier: Apache-2.0
+
+#![no_std]
+
+// Cargo tries to detect configs that have typos in them.  Unfortunately, the Zephyr Kconfig system
+// uses a large number of Kconfigs and there is no easy way to know which ones might conceivably be
+// valid.  This prevents a warning about each cfg that is used.
+#![allow(unexpected_cfgs)]
+
+extern crate alloc;
+
+#[allow(unused_imports)]
+use alloc::boxed::Box;
+use alloc::vec::Vec;
+use zephyr::time::{Duration, sleep, Tick};
+use zephyr::{
+    printkln,
+    kobj_define,
+    sys::uptime_get,
+    sync::Arc,
+};
+
+// These are optional, based on Kconfig, so allow them to be unused.
+#[allow(unused_imports)]
+use crate::semsync::semaphore_sync;
+
+mod semsync;
+
+/// How many philosophers.  There will be the same number of forks.
+const NUM_PHIL: usize = 6;
+
+/// How much stack should each philosopher thread get.  Worst case I've seen is riscv64, with 3336
+/// bytes, when printing messages.  Make a bit larger to work.
+const PHIL_STACK_SIZE: usize = 4096;
+
+// The dining philosophers problem is a simple example of cooperation between multiple threads.
+// This implementation use one of several different underlying mechanism to support this cooperation.
+
+// This example uses dynamic dispatch to allow multiple implementations.  The intent is to be able
+// to periodically shut down all of the philosphers and start them up with a differernt sync
+// mechanism.  This isn't implemented yet.
+
+/// The philosophers use a fork synchronization mechanism.  Essentially, this is 6 locks, and will be
+/// implemented in a few different ways to demonstrate/test different mechanmism in Rust.  All of
+/// them implement The ForkSync trait which provides this mechanism.
+trait ForkSync: core::fmt::Debug + Sync + Send {
+    /// Take the given fork.  The are indexed the same as the philosopher index number.  This will
+    /// block until the fork is released.
+    fn take(&self, index: usize);
+
+    /// Release the given fork.  Index is the same as take.
+    fn release(&self, index: usize);
+}
+
+#[no_mangle]
+extern "C" fn rust_main() {
+    printkln!("Hello world from Rust on {}",
+              zephyr::kconfig::CONFIG_BOARD);
+    printkln!("Time tick: {}", zephyr::time::SYS_FREQUENCY);
+
+    let syncers = get_syncer();
+
+    printkln!("Pre fork");
+
+    for (i, syncer) in (0..NUM_PHIL).zip(syncers.into_iter()) {
+        let thread = PHIL_THREADS[i].init_once(PHIL_STACKS[i].init_once(()).unwrap()).unwrap();
+        thread.spawn(move || {
+            phil_thread(i, syncer);
+        });
+    }
+
+    let delay = Duration::secs_at_least(10);
+    loop {
+        // Periodically, printout the stats.
+        zephyr::time::sleep(delay);
+    }
+}
+
+#[cfg(CONFIG_SYNC_SYS_SEMAPHORE)]
+fn get_syncer() -> Vec<Arc<dyn ForkSync>> {
+    semaphore_sync()
+}
+
+fn phil_thread(n: usize, syncer: Arc<dyn ForkSync>) {
+    printkln!("Child {} started: {:?}", n, syncer);
+
+    // Determine our two forks.
+    let forks = if n == NUM_PHIL - 1 {
+        // Per Dijkstra, the last phyilosopher needs to reverse forks, or we deadlock.
+        (0, n)
+    } else {
+        (n, n+1)
+    };
+
+    loop {
+        {
+            printkln!("Child {} hungry", n);
+            printkln!("Child {} take left fork", n);
+            syncer.take(forks.0);
+            printkln!("Child {} take right fork", n);
+            syncer.take(forks.1);
+
+            let delay = get_random_delay(n, 25);
+            printkln!("Child {} eating ({} ms)", n, delay);
+            sleep(delay);
+            // stats.lock().unwrap().record_eat(n, delay);
+
+            // Release the forks.
+            printkln!("Child {} giving up forks", n);
+            syncer.release(forks.1);
+            syncer.release(forks.0);
+
+            let delay = get_random_delay(n, 25);
+            printkln!("Child {} thinking ({} ms)", n, delay);
+            sleep(delay);
+            // stats.lock().unwrap().record_think(n, delay);
+        }
+    }
+}
+
+/// Get a random delay, based on the ID of this user, and the current uptime.
+fn get_random_delay(id: usize, period: usize) -> Duration {
+    let tick = (uptime_get() & (usize::MAX as i64)) as usize;
+    let delay = (tick / 100 * (id + 1)) & 0x1f;
+
+    // Use one greater to be sure to never get a delay of zero.
+    Duration::millis_at_least(((delay + 1) * period) as Tick)
+}
+
+kobj_define! {
+    static PHIL_THREADS: [StaticThread; NUM_PHIL];
+    static PHIL_STACKS: [ThreadStack<PHIL_STACK_SIZE>; NUM_PHIL];
+}