Start of Kobj support: Semaphores and Threads

zephyr-build/src/lib.rs

@@ -54,24 +54,22 @@ pub fn build_kconfig_mod() {
     let gen_path = Path::new(&outdir).join("kconfig.rs");
 
     let mut f = File::create(&gen_path).unwrap();
-    writeln!(&mut f, "pub mod kconfig {{").unwrap();
 
     let file = File::open(&dotconfig).expect("Unable to open dotconfig");
     for line in BufReader::new(file).lines() {
         let line = line.expect("reading line from dotconfig");
         if let Some(caps) = config_hex.captures(&line) {
-            writeln!(&mut f, "    #[allow(dead_code)]").unwrap();
-            writeln!(&mut f, "    pub const {}: usize = {};",
+            writeln!(&mut f, "#[allow(dead_code)]").unwrap();
+            writeln!(&mut f, "pub const {}: usize = {};",
                 &caps[1], &caps[2]).unwrap();
         } else if let Some(caps) = config_int.captures(&line) {
-            writeln!(&mut f, "    #[allow(dead_code)]").unwrap();
-            writeln!(&mut f, "    pub const {}: isize = {};",
+            writeln!(&mut f, "#[allow(dead_code)]").unwrap();
+            writeln!(&mut f, "pub const {}: isize = {};",
                 &caps[1], &caps[2]).unwrap();
         } else if let Some(caps) = config_str.captures(&line) {
-            writeln!(&mut f, "    #[allow(dead_code)]").unwrap();
-            writeln!(&mut f, "    pub const {}: &'static str = {};",
+            writeln!(&mut f, "#[allow(dead_code)]").unwrap();
+            writeln!(&mut f, "pub const {}: &'static str = {};",
                 &caps[1], &caps[2]).unwrap();
         }
     }
-    writeln!(&mut f, "}}").unwrap();
 }

zephyr-sys/build.rs

@@ -71,6 +71,7 @@ fn main() -> Result<()> {
         .allowlist_function("k_.*")
         .allowlist_function("gpio_.*")
         .allowlist_function("sys_.*")
+        .allowlist_item("E.*")
         // Deprecated
         .blocklist_function("sys_clock_timeout_end_calc")
         .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))

zephyr/src/error.rs

@@ -0,0 +1,56 @@
+// Copyright (c) 2024 Linaro LTD
+// SPDX-License-Identifier: Apache-2.0
+
+//! # Zephyr errors
+//!
+//! This module contains an `Error` and `Result` type for use in wrapped Zephyr calls.  Many
+//! operations in Zephyr return an int result where negative values correspond with errnos.
+//! Convert those to a `Result` type where the `Error` condition maps to errnos.
+//!
+//! Initially, this will just simply wrap the numeric error code, but it might make sense to make
+//! this an enum itself, however, it would probably be better to auto-generate this enum instead of
+//! trying to maintain the list manually.
+
+use core::ffi::c_int;
+use core::fmt;
+
+// This is a little messy because the constants end up as u32 from bindgen, although the values are
+// negative.
+
+/// A Zephyr error.
+///
+/// Represents an error result returned within Zephyr.
+pub struct Error(pub u32);
+
+impl core::error::Error for Error {}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "zephyr error errno:{}", self.0)
+    }
+}
+
+impl fmt::Debug for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "zephyr error errno:{}", self.0)
+    }
+}
+
+/// Wraps a value with a possible Zephyr error.
+pub type Result<T> = core::result::Result<T, Error>;
+
+/// Map a return result from Zephyr into an Result.
+///
+/// Negative return results being considered errors.
+pub fn to_result(code: c_int) -> Result<c_int> {
+    if code < 0 {
+        Err(Error(-code as u32))
+    } else {
+        Ok(code)
+    }
+}
+
+/// Map a return result, with a void result.
+pub fn to_result_void(code: c_int) -> Result<()> {
+    to_result(code).map(|_| ())
+}

zephyr/src/lib.rs

@@ -8,12 +8,29 @@
 
 #![no_std]
 #![allow(unexpected_cfgs)]
+#![deny(missing_docs)]
 
+pub mod error;
 pub mod sys;
 pub mod time;
 
+pub use error::{Error, Result};
+
 // Bring in the generated kconfig module
-include!(concat!(env!("OUT_DIR"), "/kconfig.rs"));
+pub mod kconfig {
+    //! Zephyr Kconfig values.
+    //!
+    //! This module contains an auto-generated set of constants corresponding to the values of
+    //! various Kconfig values during the build.
+    //!
+    //! **Note**: Unless you are viewing docs generated for a specific build, the values below are
+    //! unlikely to directly correspond to those in a given build.
+
+    // Don't enforce doc comments on the bindgen, as it isn't enforced within Zephyr.
+    #![allow(missing_docs)]
+
+    include!(concat!(env!("OUT_DIR"), "/kconfig.rs"));
+}
 
 // Ensure that Rust is enabled.
 #[cfg(not(CONFIG_RUST))]

zephyr/src/printk.rs

@@ -12,13 +12,33 @@ use core::fmt::{
     write,
 };
 
+/// Print to Zephyr's console, without a newline.
+///
+/// This macro uses the same syntax as std's [`format!`], but writes to the Zephyr console instead.
+///
+/// if `CONFIG_PRINTK_SYNC` is enabled, this locks during printing.  However, to avoid allocation,
+/// and due to private accessors in the Zephyr printk implementation, the lock is only over groups
+/// of a small buffer size.  This buffer must be kept fairly small, as it resides on the stack.
+///
+/// [`format!`]: alloc::format
 #[macro_export]
 macro_rules! printk {
     ($($arg:tt)*) => {{
         $crate::printk::printk(format_args!($($arg)*));
     }};
 }
 
+/// Print to Zephyr's console, with a newline.
+///
+/// This macro uses the same syntax as std's
+/// [`format!`], but writes to the Zephyr console
+/// instead. See `std::fmt` for more information.
+///
+/// If `CONFIG_PRINTK_SYNC` is enabled, this locks during printing.  However, to avoid allocation,
+/// and due to private accessors in the Zephyr printk implementation, the lock is only over groups
+/// of a small buffer size.  This buffer must be kept fairly small, as it resides on the stack.
+///
+/// [`format!`]: alloc::format
 #[macro_export]
 macro_rules! printkln {
     ($($arg:tt)*) => {{
@@ -93,6 +113,7 @@ impl Write for Context {
     }
 }
 
+#[doc(hidden)]
 pub fn printk(args: Arguments<'_>) {
     let mut context = Context {
         count: 0,
@@ -102,6 +123,7 @@ pub fn printk(args: Arguments<'_>) {
     context.flush();
 }
 
+#[doc(hidden)]
 pub fn printkln(args: Arguments<'_>) {
     let mut context = Context {
         count: 0,

zephyr/src/sys.rs

@@ -14,5 +14,15 @@ use zephyr_sys::k_timeout_t;
 // These two constants are not able to be captured by bindgen.  It is unlikely that these values
 // would change in the Zephyr headers, but there will be an explicit test to make sure they are
 // correct.
+
+/// Represents a timeout with an infinite delay.
+///
+/// Low-level Zephyr constant.  Calls using this value will wait as long as necessary to perform
+/// the requested operation.
 pub const K_FOREVER: k_timeout_t = k_timeout_t { ticks: -1 };
+
+/// Represents a null timeout delay.
+///
+/// Low-level Zephyr Constant.  Calls using this value will not wait if the operation cannot be
+/// performed immediately.
 pub const K_NO_WAIT: k_timeout_t = k_timeout_t { ticks: 0 };

zephyr/src/time.rs

@@ -66,7 +66,11 @@ pub type Instant = fugit::Instant<Tick, 1, SYS_FREQUENCY>;
 // The absolute time offset is only implemented when time is a 64-bit value.  This also means that
 // "Instant" isn't available when time is defined as a 32-bit value.
 
-// Wrapper around the timeout type, so we can implement From/Info.
+/// Wrapper around the timeout type, so we can implement From/Info.
+///
+/// This wrapper allows us to implement `From` and `Info` from the Fugit types into the Zephyr
+/// types.  This allows various methods to accept either value, as well as the `Forever` and
+/// `NoWait` values defined here.
 pub struct Timeout(pub k_timeout_t);
 
 // `From` allows methods to take a time of various types and convert it into a Zephyr timeout.