Documentation and Cargo manifest updates, fix CI for xtensa-lx-rt

.github/workflows/ci.yml

@@ -43,27 +43,37 @@ jobs:
       - name: check (all features)
         run: cd xtensa-lx/ && cargo build --features=spin
 
-  # xtensa-lx-rt:
-  #   runs-on: ubuntu-latest
-  #
-  #   strategy:
-  #     fail-fast: false
-  #     matrix:
-  #       chip: ["esp32", "esp32s2", "esp32s3"]
-  #
-  #   steps:
-  #     - uses: actions/checkout@v4
-  #     - uses: esp-rs/xtensa-toolchain@v1.5
-  #       with:
-  #         default: true
-  #         ldproxy: false
-  #     - uses: Swatinem/rust-cache@v2
-  #
-  #     # Build the 'xtensa-lx-rt' package:
-  #     - name: check (${{ matrix.chip }}, no features)
-  #       run: cd xtensa-lx-rt/ && cargo build --features=${{ matrix.chip }}
-  #     - name: check (${{ matrix.chip }}, all features)
-  #       run: cd xtensa-lx-rt/ && cargo build --features=${{ matrix.chip }},float-save-restore
+  xtensa-lx-rt:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        chip: ["esp32", "esp32s2", "esp32s3"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: esp-rs/xtensa-toolchain@v1.5
+        with:
+          default: true
+          ldproxy: false
+      - uses: Swatinem/rust-cache@v2
+
+      # Build the 'xtensa-lx-rt' package:
+      - name: check (${{ matrix.chip }}, no features)
+        run: |
+          cd xtensa-lx-rt
+          cargo build -Zbuild-std=core \
+            --target=xtensa-${{ matrix.chip }}-none-elf \
+            --features=${{ matrix.chip }}
+      - name: check (${{ matrix.chip }}, all features)
+        run: |
+          cd xtensa-lx-rt
+          cargo build -Zbuild-std=core \
+            --target=xtensa-${{ matrix.chip }}-none-elf \
+            --features=${{ matrix.chip }},float-save-restore
 
   # --------------------------------------------------------------------------
   # Lint

xtensa-lx-rt/Cargo.toml

@@ -1,35 +1,36 @@
 [package]
-name = "xtensa-lx-rt"
-version = "0.16.0"
-authors = [
-    "Scott Mabin <scott@mabez.dev>", 
-    "Arjan Mels <arjan@mels.email>",
-    "Robin Appelman <robin@icewind.nl>",
-]
-edition = "2021"
+name         = "xtensa-lx-rt"
+version      = "0.16.0"
+edition      = "2021"
 rust-version = "1.65"
-description = "Low level access for Xtensa LX processors"
-readme = "README.md"
-repository = "https://github.com/esp-rs/xtensa-lx-rt"
-license = "MIT OR Apache-2.0"
-keywords = ["xtensa", "lx", "register", "peripheral"]
-categories = ["embedded", "hardware-support", "no-std"]
+description  = "Minimal startup/runtime for Xtensa LX CPUs"
+repository   = "https://github.com/esp-rs/xtensa-lx-rt"
+license      = "MIT OR Apache-2.0"
+keywords     = ["xtensa", "lx", "register", "peripheral"]
+categories   = ["embedded", "hardware-support", "no-std"]
 
 [package.metadata.docs.rs]
 features = ["esp32"]
 
 [dependencies]
-bare-metal = "1.0.0"
-r0 = "1.0.0"
-xtensa-lx-rt-proc-macros = { path = "procmacros", version = "=0.2.1" }
+bare-metal        = "1.0.0"
+document-features = "0.2.8"
+macros            = { version = "0.2.1", package = "xtensa-lx-rt-proc-macros", path = "./procmacros" }
+r0                = "1.0.0"
+xtensa-lx         = { version = "0.9.0", path = "../xtensa-lx" }
 
 [build-dependencies]
-core-isa-parser = { path = "../core-isa-parser", version = "=0.2.0" }
-minijinja = "1.0.7"
+core-isa-parser = { version = "0.2.0", path = "../core-isa-parser" }
+minijinja       = "1.0.16"
 
 [features]
+## Save and restore float registers for exceptions
+float-save-restore = []
+
+#! ### Chip Support Feature Flags
+## Target the ESP32
 esp32   = []
+## Target the ESP32-S2
 esp32s2 = []
+## Target the ESP32-S3
 esp32s3 = []
-
-float-save-restore = []

xtensa-lx-rt/src/interrupt.rs

@@ -1 +1,3 @@
+//! Interrupts
+
 include!(concat!(env!("OUT_DIR"), "/interrupt_level_masks.rs"));

xtensa-lx-rt/src/lib.rs

@@ -1,13 +1,22 @@
-#![no_std]
+//! Minimal startup/runtime for Xtensa LX CPUs.
+//!
+//! ## Minimum Supported Rust Version (MSRV)
+//!
+//! This crate is guaranteed to compile on stable Rust 1.65 and up. It might
+//! compile with older versions but that may change in any new patch release.
+//!
+//! ## Feature Flags
+#![doc = document_features::document_features!()]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
+#![allow(asm_sub_register, named_asm_labels)]
 #![feature(asm_experimental_arch, naked_functions)]
-#![allow(asm_sub_register)]
-// required due to: https://github.com/rust-lang/rust/pull/87324
-#![allow(named_asm_labels)]
+#![no_std]
 
 use core::arch::asm;
 
+pub use macros::{entry, exception, interrupt, pre_init};
 pub use r0::{init_data, zero_bss};
-pub use xtensa_lx_rt_proc_macros::{entry, exception, interrupt, pre_init};
+pub use xtensa_lx;
 
 pub mod exception;
 pub mod interrupt;
@@ -139,6 +148,7 @@ pub extern "Rust" fn default_mem_hook() -> bool {
     true // default to zeroing bss & initializing data
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! cfg_asm {
     (@inner, [$($x:tt)*], [$($opts:tt)*], ) => {

xtensa-lx/Cargo.toml

@@ -1,23 +1,24 @@
 [package]
-name        = "xtensa-lx"
-version     = "0.9.0"
-edition     = "2021"
-description = "Low-level access for Xtensa LX processors and peripherals"
-repository  = "https://github.com/esp-rs/xtensa-lx"
-license     = "MIT OR Apache-2.0"
-categories  = ["embedded", "hardware-support", "no-std"]
-keywords    = ["lx", "peripheral", "register", "xtensa"]
-
-# Prevent multiple versions of this crate to be linked together
-links = "xtensa-lx"
+name         = "xtensa-lx"
+version      = "0.9.0"
+edition      = "2021"
+rust-version = "1.65"
+description  = "Low-level access to Xtensa LX processors and peripherals"
+repository   = "https://github.com/esp-rs/xtensa-lx"
+license      = "MIT OR Apache-2.0"
+categories   = ["embedded", "hardware-support", "no-std"]
+keywords     = ["lx", "peripheral", "register", "xtensa"]
+links        = "xtensa-lx"
 
 [package.metadata.docs.rs]
 features = ["spin"]
 
 [dependencies]
-bare-metal  = "1.0.0"
-mutex-trait = "0.2.0"
-spin        = { version = "0.9.8", optional = true }
+bare-metal        = "1.0.0"
+document-features = "0.2.8"
+mutex-trait       = "0.2.0"
+spin              = { version = "0.9.8", optional = true }
 
 [features]
-spin               = ["dep:spin"]
+## Use the [spin] package for synchronization
+spin = ["dep:spin"]

xtensa-lx/src/lib.rs

@@ -1,6 +1,16 @@
-#![no_std]
+//! Low-level access to Xtensa LX processors and peripherals.
+//!
+//! ## Minimum Supported Rust Version (MSRV)
+//!
+//! This crate is guaranteed to compile on stable Rust 1.65 and up. It might
+//! compile with older versions but that may change in any new patch release.
+//!
+//! ## Feature Flags
+#![doc = document_features::document_features!()]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 #![allow(asm_sub_register)]
 #![feature(asm_experimental_arch)]
+#![no_std]
 
 use core::arch::asm;
 
@@ -11,8 +21,11 @@ pub mod timer;
 #[macro_use]
 mod macros;
 
+const DCR_ENABLEOCD: u32 = 0x01;
+const XDM_OCD_DCR_SET: u32 = 0x10200C;
+
 /// Move the vector base
-#[inline]
+#[inline(always)]
 pub unsafe fn set_vecbase(base: *const u32) {
     asm!("wsr.vecbase {0}", in(reg) base, options(nostack));
 }
@@ -71,18 +84,15 @@ pub fn get_program_counter() -> *const u32 {
 }
 
 /// Get the id of the current core
-#[inline]
+#[inline(always)]
 pub fn get_processor_id() -> u32 {
     let mut x: u32;
     unsafe { asm!("rsr.prid {0}", out(reg) x, options(nostack)) };
     x
 }
 
-const XDM_OCD_DCR_SET: u32 = 0x10200C;
-const DCR_ENABLEOCD: u32 = 0x01;
-
 /// Returns true if a debugger is attached
-#[inline]
+#[inline(always)]
 pub fn is_debugger_attached() -> bool {
     let mut x: u32;
     unsafe { asm!("rer {0}, {1}", out(reg) x, in(reg) XDM_OCD_DCR_SET, options(nostack)) };