Skip to content

zephyr: Expound upon the rustdoc docs in the source. #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 27, 2025
Merged

zephyr: Expound upon the rustdoc docs in the source. #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
abe8860
zephyr: Expand top-level crate docs
d3zd3z Feb 19, 2025
bcb1515
docs: Update top-level index
d3zd3z Feb 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions docs/top-index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,25 @@
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Documentation Index</title>
<title>Rust for Zephyr Documentation Index</title>
</head>
<body>
<h1>Documentation Index</h1>
<p>
The documentation for the Rust documentation for Rust on Zephyr is divided into two parts.
<ul>
<li><a href="nostd/zephyr/index.html">zephyr crate Documentation</a></li>
<li><a href="std/zephyr_build/index.html">zephyr_build support Documentation</a></li>
<li><a href="nostd/zephyr/index.html">zephyr crate Documentation</a>
The main documentation for interfacing with Zephyr from Rust code.
</li>
<li><a href="std/zephyr_build/index.html">zephyr_build support Documentation</a>
Documentation for build-time utilities, available from <code>build.rs</code>, primarily
for allowing compile-time determination of the Zephyr configuration (e.g. conditional
compilation based on Kconfig or DeviceTree values).
</li>
</ul>
<h2>Git reference</h2>
<p>
This documentation has been generated from the zephyr-lang-rust repo as of the following commit:
<pre>
{{COMMIT}}
</pre>
Expand Down
68 changes: 67 additions & 1 deletion zephyr/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,73 @@
//! Zephyr application support for Rust
//!
//! This crates provides the core functionality for applications written in Rust that run on top of
//! Zephyr.
//! 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.
//! - [`kio`]: An implementation of an async executor built around triggerable work queues in
//! Zephyr. Although there is a bit more overhead to this executor, it is compatible with many of
//! the Zephyr synchronization types, and many of these [`sys::sync::Semaphore`], and
//! [`sync::channel`] will provide `_async` variants of most of the blocking operations. These
//! will return a `Future`, and can be used from async code started by the [`spawn`] function.
//! In addition, because Zephyr's work queues do not work well with Zephyr's Mutex type, this is
//! also a [`kio::sync::Mutex`] type that works with async.
//! - [`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
//! [`spawn`]: kio::spawn
//!
//! 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)]
Expand Down