Examples

Author: ivmarkov

.cargo/config.toml

@@ -0,0 +1,30 @@
+[build]
+target = "riscv32imc-esp-espidf"
+#target = "xtensa-esp32-espidf"
+
+[target.xtensa-esp32-espidf]
+linker = "ldproxy"
+rustflags = ["--cfg", "espidf_time64"]
+
+[target.xtensa-esp32s2-espidf]
+linker = "ldproxy"
+rustflags = ["--cfg", "espidf_time64"]
+
+[target.xtensa-esp32s3-espidf]
+linker = "ldproxy"
+rustflags = ["--cfg", "espidf_time64"]
+
+[target.riscv32imc-esp-espidf]
+linker = "ldproxy"
+rustflags = ["--cfg", "espidf_time64"]
+
+[target.riscv32imac-esp-espidf]
+linker = "ldproxy"
+rustflags = ["--cfg", "espidf_time64"]
+
+[env]
+ESP_IDF_SDKCONFIG_DEFAULTS = ".github/configs/sdkconfig.defaults"
+ESP_IDF_VERSION = "v5.1.2"
+
+[unstable]
+build-std = ["std", "panic_abort"]

.github/configs/sdkconfig.defaults

@@ -0,0 +1,3 @@
+# The examples require a larger than the default stack size for the main thread and the posix threads.
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=20000
+CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT=8192

.github/workflows/ci.yml

@@ -68,3 +68,17 @@ jobs:
           RUSTFLAGS: "${{ '--cfg espidf_time64' }}"
           ESP_IDF_VERSION: release/v5.1
         run: cargo clean; cargo build --target ${{ matrix.target }} -Zbuild-std=std,panic_abort -Zbuild-std-features=panic_immediate_abort
+
+      - name: Setup | ldproxy
+        if: matrix.target == 'riscv32imc-esp-espidf'
+        run: |
+          curl -L https://github.com/esp-rs/embuild/releases/latest/download/ldproxy-x86_64-unknown-linux-gnu.zip -o $HOME/.cargo/bin/ldproxy.zip
+          unzip "$HOME/.cargo/bin/ldproxy.zip" -d "$HOME/.cargo/bin/"
+          chmod a+x $HOME/.cargo/bin/ldproxy
+
+      - name: Build | Examples
+        env:
+          RUSTFLAGS: "${{ '--cfg espidf_time64' }}"
+          ESP_IDF_SDKCONFIG_DEFAULTS: "${{ github.workspace }}/.github/configs/sdkconfig.defaults"
+          ESP_IDF_VERSION: release/v5.1
+        run: cargo build --examples --target ${{ matrix.target }} -Zbuild-std=std,panic_abort -Zbuild-std-features=panic_immediate_abort

README.md

@@ -31,6 +31,25 @@ Follow the [Prerequisites](https://github.com/esp-rs/esp-idf-template#prerequisi
 
 Read the [documentation here](BUILD-OPTIONS.md).
 
+## Examples
+
+The examples could be built and flashed conveniently with [`cargo-espflash`](https://github.com/esp-rs/espflash/). To run e.g. `std_basics` on an e.g. ESP32-C3:
+(Swap the Rust target and example name with the target corresponding for your ESP32 MCU and with the example you would like to build)
+
+with `cargo-espflash` V2+:
+```sh
+$ cargo espflash flash --target riscv32imc-esp-espidf --example std_basics --monitor
+```
+
+with older `cargo-espflash`:
+```sh
+$ cargo espflash --target riscv32imc-esp-espidf --example std_basics --monitor /dev/ttyUSB0
+```
+
+## Setting up a "Hello, world!" binary crate with ESP IDF
+
+Use the [esp-idf-template](https://github.com/esp-rs/esp-idf-template) project. Everything would be arranged and built for you automatically - no need to manually clone the ESP IDF repository.
+
 ## More information
 
 For more information, check out:

build/build.rs

@@ -202,14 +202,17 @@ fn main() -> anyhow::Result<()> {
         cargo::set_metadata(embuild::build::ENV_PATH_VAR, env_path);
     }
 
-    // In case other crates need to the ESP-IDF SDK
+    // In case other crates need access to the ESP-IDF SDK
     cargo::set_metadata(
         embuild::build::ESP_IDF_PATH_VAR,
         build_output.esp_idf.try_to_str()?,
     );
 
     if let Some(link_args) = build_output.link_args {
         link_args.propagate();
+
+        // Only necessary for building the examples
+        link_args.output();
     }
 
     Ok(())

examples/std_basics.rs

@@ -0,0 +1,130 @@
+use core::cell::RefCell;
+use core::ptr;
+use core::sync::atomic::{AtomicUsize, Ordering};
+use core::time::Duration;
+
+use std::env;
+use std::io;
+use std::thread;
+
+thread_local! {
+    static TLS: RefCell<u32> = RefCell::new(13);
+}
+
+fn main() -> Result<(), io::Error> {
+    esp_idf_sys::link_patches();
+
+    // Get backtraces from anyhow; only works for Xtensa arch currently
+    #[cfg(target_arch = "xtensa")]
+    env::set_var("RUST_BACKTRACE", "1");
+
+    test_print();
+
+    test_atomics();
+
+    test_threads()?;
+
+    #[cfg(not(esp_idf_version = "4.3"))]
+    test_fs()?;
+
+    loop {
+        println!("Sleeping for 2 seconds...");
+        thread::sleep(Duration::from_secs(2));
+    }
+}
+
+#[allow(clippy::vec_init_then_push)]
+fn test_print() {
+    // Start simple
+    println!("Hello from Rust!");
+
+    // Check collections
+    let mut children = vec![];
+
+    children.push("foo");
+    children.push("bar");
+    println!("More complex print {children:?}");
+}
+
+#[allow(deprecated)]
+fn test_atomics() {
+    let a = AtomicUsize::new(0);
+    let v1 = a.compare_and_swap(0, 1, Ordering::SeqCst);
+    let v2 = a.swap(2, Ordering::SeqCst);
+
+    let (r1, r2) = unsafe {
+        // don't optimize our atomics out
+        let r1 = ptr::read_volatile(&v1);
+        let r2 = ptr::read_volatile(&v2);
+
+        (r1, r2)
+    };
+
+    println!("Result: {r1}, {r2}");
+}
+
+fn test_threads() -> Result<(), io::Error> {
+    let mut children = vec![];
+
+    println!("Rust main thread: {:?}", thread::current());
+
+    TLS.with(|tls| {
+        println!("Main TLS before change: {}", *tls.borrow());
+    });
+
+    TLS.with(|tls| *tls.borrow_mut() = 42);
+
+    TLS.with(|tls| {
+        println!("Main TLS after change: {}", *tls.borrow());
+    });
+
+    for i in 0..5 {
+        // Spin up another thread
+        children.push(thread::spawn(move || {
+            println!("This is thread number {}, {:?}", i, thread::current());
+
+            TLS.with(|tls| *tls.borrow_mut() = i);
+
+            TLS.with(|tls| {
+                println!("Inner TLS: {}", *tls.borrow());
+            });
+        }));
+    }
+
+    println!("About to join the threads.");
+
+    for child in children {
+        // Wait for the thread to finish. Returns a result.
+        let _ = child.join();
+    }
+
+    TLS.with(|tls| {
+        println!("Main TLS after threads: {}", *tls.borrow());
+    });
+
+    thread::sleep(Duration::from_secs(2));
+
+    println!("Joins were successful.");
+
+    Ok(())
+}
+
+#[cfg(not(esp_idf_version = "4.3"))]
+fn test_fs() -> Result<(), io::Error> {
+    use std::{fs, path::PathBuf};
+
+    assert_eq!(fs::canonicalize(PathBuf::from("."))?, PathBuf::from("/"));
+    assert_eq!(
+        fs::canonicalize(
+            PathBuf::from("/")
+                .join("foo")
+                .join("bar")
+                .join(".")
+                .join("..")
+                .join("baz")
+        )?,
+        PathBuf::from("/foo/baz")
+    );
+
+    Ok(())
+}