zephyr/

lib.rs

// Copyright (c) 2024 Linaro LTD
// SPDX-License-Identifier: Apache-2.0

//! Zephyr application support for Rust
//!
//! This crates provides the core functionality for applications written in Rust that run on top of
//! Zephyr.  The goal is to bridge the two worlds.  The functionality provided here shouldn't be too
//! distant from how Zephyr does things.  But, it should be "rusty" enough that Rust developers feel
//! comfortable using it.
//!
//! Some functionality:
//!
//! - [`time`]: The time module provides a [`Instant`] and [`Duration`] type that are similar to those
//!   in `std`, but are tailored for embedded systems.  These are bridged through traits, so that most
//!   API calls that offer a timeout will accept either an `Instant` or a `Duration`.
//! - [`sync`]: This crate provides various synchronization primitives that can be used to coordinate
//!   between threads.  These include
//!   - [`sync::atomic`]: Provides the same functionality as [`std::sync::atomic`], but on targets
//!     with limited synchronization primtives, re-exports features from the 'portable-atomic'
//!     crate, which can emulate atomics using critical sections.
//!   - [`sync::channel`]: Channel based synchronization built around the `k_queue` channels
//!     provided by Zephyr.  This provides both `alloc`-based unbounded channels, and bounded
//!     channels that pre-allocate.
//!   - [`sync::Mutex`]/[`sync::Condvar`]: `std`-style Mutexes and condition variables, where the
//!     Mutex protects some piece of data using Rust's features.
//!   - [`sync::SpinMutex`]: A Mutex that protects a piece of data, but does so using a spinlock.
//!     This is useful where data needs to be used exclusively, but without other types of
//!     synchronization.
//!   - [`sync::Arc`]: Atomic reference counted pointers.  Mostly like [`std::sync::Arc`] but supports
//!     all targets that support Rust on Zephyr.
//! - [`sys`]: More direct interfaces to Zephyr's primitives.  Most of the operations in `sync` are
//!   built on these.  These interfaces are 'safe', as in they can be used without the `unsafe`
//!   keyword, but the interfaces in `sync` are much more useful from Rust programs.  Although most
//!   things here won\t typically be needed, two standout:
//!   - [`sys::thread`]: A fairly direct, but safe, interface to create Zephyr threads.  At this
//!     point, this is the primary way to create threads in Rust code (see also [`work`] which
//!     supports multiple contexts using Zephyr's work queues.
//!   - [`sys::sync::Semaphore`]: The primitive Semaphore type from Zephyr.  This is the one lower
//!     level operation that is still quite useful in regular code.
//! - [`timer`]: Rust interfaces to Zephyr timers.  These timers can be used either by registering a
//!   callback, or polled or waited for for an elapsed time.
//! - [`work`]: Zephyr work queues for Rust.  The [`work::WorkQueueBuilder`] and resulting
//!   [`work::WorkQueue`] allow creation of Zephyr work queues to be used from Rust.  The
//!   [`work::Work`] item had an action that will be invoked by the work queue, and can be manually
//!   submitted when needed.
//! - [`logging`]: A logging backend for Rust on Zephyr.  This will log to either `printk` or
//!   through Zephyr's logging framework.
//!
//! [`Instant`]: time::Instant
//! [`Duration`]: time::Duration
//! [`std::sync::atomic`]: https://doc.rust-lang.org/std/sync/atomic/
//! [`std::sync::Arc`]: https://doc.rust-lang.org/std/sync/struct.Arc.html
//!
//! In addition to the above, the [`kconfig`] and [`devicetree`] provide a reflection of the kconfig
//! settings and device tree that were used for a specific build.  As such, the documentation
//! provided online is not likely to be that useful, and for these, it is best to generate the
//! documentation for a specific build:
//! ```bash
//! $ west rustdoc
//! ```
//!
//! Note, however, that the `kconfig` module only provides Kconfig **values**, and doesn't provide a
//! mechanmism to base conditional compilation.  For that, please see the
//! [zephyr-build](../../std/zephyr_build/index.html) crate, which provides routines that can be
//! called from a `build.rs` file to make these settings available.

#![no_std]
#![allow(unexpected_cfgs)]
#![deny(missing_docs)]

// Allow this crate to refer to itself by name
extern crate self as zephyr;

pub mod align;
#[cfg(all(feature = "async-drivers", CONFIG_RUST_BLOCKING_POOL))]
pub mod blocking;
pub mod device;
pub mod embassy;
pub mod error;
pub mod logging;
pub mod object;
#[cfg(CONFIG_RUST_ALLOC)]
pub mod simpletls;
pub mod sync;
pub mod sys;
pub mod thread;
pub mod time;
#[cfg(CONFIG_RUST_ALLOC)]
pub mod timer;
#[cfg(CONFIG_RUST_ALLOC)]
pub mod work;

pub use error::{Error, Result};

pub use logging::set_logger;

/// Re-exported for local macro use.
pub use paste::paste;

/// Re-export the proc macros.
pub use zephyr_macros::thread;

// Bring in the generated kconfig module
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"));
}

pub mod devicetree {
    //! Zephyr device tree
    //!
    //! This is an auto-generated module that represents the device tree for a given build.  The
    //! hierarchy here should match the device tree, with an additional top-level module "labels"
    //! that contains submodules for all of the labels.
    //!
    //! **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 generated device tree.
    #![allow(missing_docs)]
    // Allow nodes to have non-snake-case names.  This comes from addresses in the node names, which
    // usually use uppercase.
    #![allow(non_snake_case)]

    /// An expanded property in the devicetree.
    #[derive(Debug)]
    pub enum Value {
        /// A string value.
        String(&'static str),
        /// An arbitrary byte sequence.
        Bytes(&'static [u8]),
        /// A sequence of devicetree cells (numbers, phandles, or GPIO references).
        Words(&'static [Word]),
        /// A phandle value.  For now, this is just the name, since we can't dynamically reference a module.
        Phandle(&'static str),
    }

    // A single word within a devicetree property.
    #[derive(Debug)]
    pub enum Word {
        // A 32 bit number.
        Number(u32),
        /// A phandle value.  For now, this is just the name, since we can't dynamically reference a module.
        Phandle(&'static str),
        /// A specific GPIO value.
        Gpio(&'static str, &'static [u32]),
    }

    include!(concat!(env!("OUT_DIR"), "/devicetree.rs"));
}

// Ensure that Rust is enabled.
#[cfg(not(CONFIG_RUST))]
compile_error!("CONFIG_RUST must be set to build Rust in Zephyr");

// Printk is provided if it is configured into the build.
#[cfg(CONFIG_PRINTK)]
pub mod printk;

/// Re-export of zephyr-sys as `zephyr::raw`.
pub mod raw {
    pub use zephyr_sys::*;
}

/// Provide symbols used by macros in a crate-local namespace.
#[doc(hidden)]
pub mod _export {
    pub use core::format_args;

    use crate::{object::StaticKernelObject, sys::thread::StaticThreadStack};

    /// Type alias for the thread stack kernel object.
    pub type KStaticThreadStack = StaticKernelObject<StaticThreadStack>;
}

// Mark this as `pub` so the docs can be read.
// If allocation has been requested, provide the allocator.
#[cfg(CONFIG_RUST_ALLOC)]
pub mod alloc_impl;

#[cfg(CONFIG_RUST_ALLOC)]
pub mod task {
    //! Provides the portable-atomic version of `alloc::task::Wake`, which uses the compatible
    //! versionm of Arc.

    pub use portable_atomic_util::task::Wake;
}