zephyr: Add docs to the Zephyr crate

Place documentation into this crate, so that the generated doc is more
complete.

Signed-off-by: David Brown <[email protected]>

Author: d3zd3z

zephyr/src/lib.rs

@@ -1,10 +1,85 @@
 // Copyright (c) 2024 Linaro LTD
 // SPDX-License-Identifier: Apache-2.0
 
-//! Zephyr application support for Rust
+//! # Zephyr application support for Rust
 //!
-//! This crates provides the core functionality for applications written in Rust that run on top of
-//! Zephyr.
+//! Rust is a systems programming language focused on safety, speed, and concurrency. Designed to
+//! prevent common programming errors such as null pointer deferencing and buffer overflows, Rust
+//! emphasizes memory safety without sacrificing performance. Its powerful type system and
+//! ownership model ensure thread-safe programming, making it an ideal choice for developing
+//! reliable and efficient low-level code. Rust's expressive syntax and modern features make it a
+//! robust alternative for developers working on embedded systems, operating systems, and other
+//! performance-critial applications.
+//!
+//! # Enabling Rust Support
+//!
+//! Zephyr currently supports applications that are written in Rust and C. To enable Rust support,
+//! you must select the `CONFIG_RUST` option in the application configuration file.
+//!
+//! The Rust toolchain is separate from the rest of the Zephyr SDK.  It is recommended to use the
+//! [rustup](https://rustup.rs) tool to install the Rust toolchain. In addition to the base
+//! compiler, you will need to install core libraries for the target(s) you wish to compile. The
+//! easiest way to determine what needs to be installed is to attempt a build. Compilation
+//! diagnostics will indicate the `rustup` command needed to install the appropriate target
+//! support:
+//!
+//! ```text
+//! $ west build ...
+//! ...
+//! error[E0463]: can't find crate for `core`
+//!   |
+//! = note: the `thumbv7m-none-eabi` target may not be installed
+//! = help: consider downloading the target with `rustup target add thumbv7-none-eabi`
+//! ```
+//!
+//! in this case, the provided `rustup` command will install the necessary target support. The
+//! target required depends on both the board selected and certain configuration choices, such as
+//! whether floating point is enabled.
+//!
+//! # Writing a Rust Application
+//!
+//! See the `samples` directory in the zephyr-lang-rust repo for examples of Rust applications. The
+//! cmake build system is used to build the majority of Zephyr. The declarations in the sample
+//! `CMakeLists.txt` files will show how to have cmake invoke `cargo build` at the right time, with
+//! the right settings to build for your target.  The rest of the directory is a typical Rust
+//! crate, with a few special caveats:
+//!
+//! * The crate must currently be named `"rustapp"`. This is so that the cmake rules can find the
+//!   build.
+//! * The crate must be a staticlib crate.
+//! * The crate must depend on a "zephyr" crate.  This crate does not come from crates.io, but will
+//!   be located by cmake.  This documentation is for this "zephyr" crate.
+//!
+//! cmake and/or the `west build` command will place the build in a directory (`build` by default)
+//! and the rules will direct cargo to also place its build output there (`build/rust/target` for
+//! the majority of the output).
+//!
+//! The build process will also generate a template for a `.cargo/config.toml` that will configure
+//! cargo so that tools such as `cargo check` and `rust analyzer` will work with your project.  You
+//! can make a symlink for this file to allow these tools to work
+//!
+//! ```bash
+//! $ mkdir .cargo
+//! $ cd .cargo
+//! $ ln -s ../build/rust/sample-cargo-config.toml config.coml
+//! $ cd ..
+//! $ cargo check
+//! ```
+//!
+//! # Zephyr Functionality
+//!
+//! The bindings to Rust for Zephyr are still under development and are currently minimal. However,
+//! some Zephyr functionality is available.
+//!
+//! ## Bool Kconfig Settings
+//!
+//! Boolean Kconfig settings can be accessed from within Rust code. However, since Rust requires
+//! certain compilation decisions, accessing these with `#[cfg...]` directives requires a small
+//! addition to `build.rs`. See the docs in the [`zephyr-build` crate](../zephyr-build/index.html).
+//!
+//! # Other Kconfig Settings
+//!
+//! All boolean, numeric, and string Kconfig settings are available through the `kconfig` module.
 
 #![no_std]
 #![allow(unexpected_cfgs)]

zephyr/src/printk.rs

@@ -3,6 +3,14 @@
 
 //! Printk implementation for Rust.
 //!
+//! The Zephyr configuration `CONFIG_PRINTK` must be enabled for this functionality to be present.
+//!
+//! This module provides two macros: [`printk`] and [`printkln`]. These are analagous to
+//! [`std::print`](https://doc.rust-lang.org/std/macro.print.html) and
+//! [`std::println`](https://doc.rust-lang.org/std/macro.println.html) macros.
+//!
+//! These will print messages through Zephyr's `printk` functionality.
+//!
 //! This uses the `k_str_out` syscall, which is part of printk to output to the console.
 
 use core::fmt::{
@@ -12,6 +20,14 @@ use core::fmt::{
     write,
 };
 
+/// Print to Zephyr's console.
+///
+/// Equivalent to the [`printkln!`] macro except that a newline is not printed at the end of the
+/// message.
+///
+/// Note that printk access in Zephyr are uncoordinated unless `CONFIG_PRINTK_SYNC` is enabled.
+/// Even in this case, because of mismatches between Rust and C's message formatting, messages from
+/// Rust may not be as well synchronized, even when this is defined.
 #[macro_export]
 macro_rules! printk {
     ($($arg:tt)*) => {{