From 70a9437f270644469f0f54a5c758a5b23eecd1fb Mon Sep 17 00:00:00 2001 From: bjoernQ Date: Fri, 22 Jul 2022 11:41:58 +0200 Subject: [PATCH] Add more documentation to the examples --- esp32-hal/examples/blinky.rs | 4 ++++ esp32-hal/examples/gpio_interrupt.rs | 5 +++++ esp32-hal/examples/hello_world.rs | 3 +++ esp32-hal/examples/multicore.rs | 4 ++++ esp32-hal/examples/ram.rs | 7 +++++++ esp32-hal/examples/read_efuse.rs | 3 +++ esp32-hal/examples/timer_interrupt.rs | 4 ++++ esp32c3-hal/examples/blinky.rs | 4 ++++ esp32c3-hal/examples/gpio_interrupt.rs | 5 +++++ esp32c3-hal/examples/hello_world.rs | 3 +++ esp32c3-hal/examples/ram.rs | 7 +++++++ esp32c3-hal/examples/read_efuse.rs | 3 +++ esp32c3-hal/examples/systimer.rs | 3 +++ esp32c3-hal/examples/timer_interrupt.rs | 4 ++++ esp32c3-hal/examples/usb_serial_jtag.rs | 5 +++++ esp32s2-hal/examples/blinky.rs | 4 ++++ esp32s2-hal/examples/gpio_interrupt.rs | 5 +++++ esp32s2-hal/examples/hello_world.rs | 3 +++ esp32s2-hal/examples/ram.rs | 7 +++++++ esp32s2-hal/examples/read_efuse.rs | 3 +++ esp32s2-hal/examples/systimer.rs | 3 +++ esp32s2-hal/examples/timer_interrupt.rs | 4 ++++ esp32s2-hal/examples/watchdog.rs | 2 +- esp32s3-hal/examples/blinky.rs | 4 ++++ esp32s3-hal/examples/gpio_interrupt.rs | 5 +++++ esp32s3-hal/examples/hello_world.rs | 3 +++ esp32s3-hal/examples/multicore.rs | 4 ++++ esp32s3-hal/examples/ram.rs | 7 +++++++ esp32s3-hal/examples/read_efuse.rs | 3 +++ esp32s3-hal/examples/systimer.rs | 3 +++ esp32s3-hal/examples/timer_interrupt.rs | 4 ++++ esp32s3-hal/examples/usb_serial_jtag.rs | 4 ++++ esp32s3-hal/examples/watchdog.rs | 2 +- 33 files changed, 132 insertions(+), 2 deletions(-) diff --git a/esp32-hal/examples/blinky.rs b/esp32-hal/examples/blinky.rs index c4a893d73..da6039d85 100644 --- a/esp32-hal/examples/blinky.rs +++ b/esp32-hal/examples/blinky.rs @@ -1,3 +1,7 @@ +//! Blinks an LED +//! +//! This assumes that a LED is connected to the pin assigned to `led`. (GPIO15) + #![no_std] #![no_main] diff --git a/esp32-hal/examples/gpio_interrupt.rs b/esp32-hal/examples/gpio_interrupt.rs index 3ad53d2ec..c0dfd194d 100644 --- a/esp32-hal/examples/gpio_interrupt.rs +++ b/esp32-hal/examples/gpio_interrupt.rs @@ -1,3 +1,8 @@ +//! GPIO interrupt +//! +//! This prints "Interrupt" when the boot button is pressed. +//! It also blinks an LED like the blinky example. + #![no_std] #![no_main] diff --git a/esp32-hal/examples/hello_world.rs b/esp32-hal/examples/hello_world.rs index 9bbe65f3a..48541fda2 100644 --- a/esp32-hal/examples/hello_world.rs +++ b/esp32-hal/examples/hello_world.rs @@ -1,3 +1,6 @@ +//! This shows how to write text to serial0. +//! You can see the output with `espflash` if you provide the `--monitor` option + #![no_std] #![no_main] diff --git a/esp32-hal/examples/multicore.rs b/esp32-hal/examples/multicore.rs index aae6a0096..8438ff750 100644 --- a/esp32-hal/examples/multicore.rs +++ b/esp32-hal/examples/multicore.rs @@ -1,3 +1,7 @@ +//! This shows how to spawn a task on the second core. +//! The first core will print the value of a counter which is incremented by the +//! second core. + #![no_std] #![no_main] diff --git a/esp32-hal/examples/ram.rs b/esp32-hal/examples/ram.rs index db3992911..e96bbd8e1 100644 --- a/esp32-hal/examples/ram.rs +++ b/esp32-hal/examples/ram.rs @@ -1,3 +1,10 @@ +//! This shows how to use RTC memory. +//! RTC memory is retained during resets and during most sleep modes. +//! Initialized memory is always re-initialized on startup. +//! Uninitialzed memory isn't initialized on startup and can be used to keep +//! data during resets. Zeroed memory is initialized to zero on startup. +//! We can also run code from RTC memory. + #![no_std] #![no_main] diff --git a/esp32-hal/examples/read_efuse.rs b/esp32-hal/examples/read_efuse.rs index 642d4e3b7..0b38542f4 100644 --- a/esp32-hal/examples/read_efuse.rs +++ b/esp32-hal/examples/read_efuse.rs @@ -1,3 +1,6 @@ +//! This shows how to read selected information from eFuses. +//! e.g. the MAC address + #![no_std] #![no_main] diff --git a/esp32-hal/examples/timer_interrupt.rs b/esp32-hal/examples/timer_interrupt.rs index 5ffad1e0a..bb37b9e4c 100644 --- a/esp32-hal/examples/timer_interrupt.rs +++ b/esp32-hal/examples/timer_interrupt.rs @@ -1,3 +1,7 @@ +//! This shows how to use the TIMG peripheral interrupts. +//! There is TIMG0 and TIMG1 each of them containing two general purpose timers +//! and a watchdog timer. + #![no_std] #![no_main] diff --git a/esp32c3-hal/examples/blinky.rs b/esp32c3-hal/examples/blinky.rs index f737f6310..ba263d9f5 100644 --- a/esp32c3-hal/examples/blinky.rs +++ b/esp32c3-hal/examples/blinky.rs @@ -1,3 +1,7 @@ +//! Blinks an LED +//! +//! This assumes that a LED is connected to the pin assigned to `led`. (GPIO5) + #![no_std] #![no_main] diff --git a/esp32c3-hal/examples/gpio_interrupt.rs b/esp32c3-hal/examples/gpio_interrupt.rs index 4fca90159..ae7f0a6d6 100644 --- a/esp32c3-hal/examples/gpio_interrupt.rs +++ b/esp32c3-hal/examples/gpio_interrupt.rs @@ -1,3 +1,8 @@ +//! GPIO interrupt +//! +//! This prints "Interrupt" when the boot button is pressed. +//! It also blinks an LED like the blinky example. + #![no_std] #![no_main] diff --git a/esp32c3-hal/examples/hello_world.rs b/esp32c3-hal/examples/hello_world.rs index 031739cff..712f36e8c 100644 --- a/esp32c3-hal/examples/hello_world.rs +++ b/esp32c3-hal/examples/hello_world.rs @@ -1,3 +1,6 @@ +//! This shows how to write text to serial0. +//! You can see the output with `espflash` if you provide the `--monitor` option + #![no_std] #![no_main] diff --git a/esp32c3-hal/examples/ram.rs b/esp32c3-hal/examples/ram.rs index 4870bffc9..2bdf2b51a 100644 --- a/esp32c3-hal/examples/ram.rs +++ b/esp32c3-hal/examples/ram.rs @@ -1,3 +1,10 @@ +//! This shows how to use RTC memory. +//! RTC memory is retained during resets and during most sleep modes. +//! Initialized memory is always re-initialized on startup. +//! Uninitialzed memory isn't initialized on startup and can be used to keep +//! data during resets. Zeroed memory is initialized to zero on startup. +//! We can also run code from RTC memory. + #![no_std] #![no_main] diff --git a/esp32c3-hal/examples/read_efuse.rs b/esp32c3-hal/examples/read_efuse.rs index bcfec333d..ebe2eb105 100644 --- a/esp32c3-hal/examples/read_efuse.rs +++ b/esp32c3-hal/examples/read_efuse.rs @@ -1,3 +1,6 @@ +//! This shows how to read selected information from eFuses. +//! e.g. the MAC address + #![no_std] #![no_main] diff --git a/esp32c3-hal/examples/systimer.rs b/esp32c3-hal/examples/systimer.rs index d53315a9a..dfd60cca1 100644 --- a/esp32c3-hal/examples/systimer.rs +++ b/esp32c3-hal/examples/systimer.rs @@ -1,3 +1,6 @@ +//! This shows how to use the SYSTIMER peripheral including interrupts. +//! It's an additional timer besides the TIMG peripherals. + #![no_std] #![no_main] diff --git a/esp32c3-hal/examples/timer_interrupt.rs b/esp32c3-hal/examples/timer_interrupt.rs index 89b6a4ca2..81f398b54 100644 --- a/esp32c3-hal/examples/timer_interrupt.rs +++ b/esp32c3-hal/examples/timer_interrupt.rs @@ -1,3 +1,7 @@ +//! This shows how to use the TIMG peripheral interrupts. +//! There is TIMG0 and TIMG1 each of them containing a general purpose timer and +//! a watchdog timer. + #![no_std] #![no_main] diff --git a/esp32c3-hal/examples/usb_serial_jtag.rs b/esp32c3-hal/examples/usb_serial_jtag.rs index 926712cce..94df2728d 100644 --- a/esp32c3-hal/examples/usb_serial_jtag.rs +++ b/esp32c3-hal/examples/usb_serial_jtag.rs @@ -1,3 +1,8 @@ +//! This shows how to output text via USB Serial/JTAG. +//! You need to connect via the Serial/JTAG interface to see any output. +//! Most dev-kits use a USB-UART-bridge - in that case you won't see any output. +//! This will work with the ESP32-C3-DevKit-RUST-1 + #![no_std] #![no_main] diff --git a/esp32s2-hal/examples/blinky.rs b/esp32s2-hal/examples/blinky.rs index a0fcca810..7b05662d8 100644 --- a/esp32s2-hal/examples/blinky.rs +++ b/esp32s2-hal/examples/blinky.rs @@ -1,3 +1,7 @@ +//! Blinks an LED +//! +//! This assumes that a LED is connected to the pin assigned to `led`. (GPIO4) + #![no_std] #![no_main] diff --git a/esp32s2-hal/examples/gpio_interrupt.rs b/esp32s2-hal/examples/gpio_interrupt.rs index 06c4c6b88..cc251dfd4 100644 --- a/esp32s2-hal/examples/gpio_interrupt.rs +++ b/esp32s2-hal/examples/gpio_interrupt.rs @@ -1,3 +1,8 @@ +//! GPIO interrupt +//! +//! This prints "Interrupt" when the boot button is pressed. +//! It also blinks an LED like the blinky example. + #![no_std] #![no_main] diff --git a/esp32s2-hal/examples/hello_world.rs b/esp32s2-hal/examples/hello_world.rs index 4721e0fc3..8bed05afe 100644 --- a/esp32s2-hal/examples/hello_world.rs +++ b/esp32s2-hal/examples/hello_world.rs @@ -1,3 +1,6 @@ +//! This shows how to write text to serial0. +//! You can see the output with `espflash` if you provide the `--monitor` option + #![no_std] #![no_main] diff --git a/esp32s2-hal/examples/ram.rs b/esp32s2-hal/examples/ram.rs index f21bf638d..9f864e72a 100644 --- a/esp32s2-hal/examples/ram.rs +++ b/esp32s2-hal/examples/ram.rs @@ -1,3 +1,10 @@ +//! This shows how to use RTC memory. +//! RTC memory is retained during resets and during most sleep modes. +//! Initialized memory is always re-initialized on startup. +//! Uninitialzed memory isn't initialized on startup and can be used to keep +//! data during resets. Zeroed memory is initialized to zero on startup. +//! We can also run code from RTC memory. + #![no_std] #![no_main] diff --git a/esp32s2-hal/examples/read_efuse.rs b/esp32s2-hal/examples/read_efuse.rs index 7c5a9bb3f..f61c0d5b5 100644 --- a/esp32s2-hal/examples/read_efuse.rs +++ b/esp32s2-hal/examples/read_efuse.rs @@ -1,3 +1,6 @@ +//! This shows how to read selected information from eFuses. +//! e.g. the MAC address + #![no_std] #![no_main] diff --git a/esp32s2-hal/examples/systimer.rs b/esp32s2-hal/examples/systimer.rs index 1abd7416d..da9ce26c1 100644 --- a/esp32s2-hal/examples/systimer.rs +++ b/esp32s2-hal/examples/systimer.rs @@ -1,3 +1,6 @@ +//! This shows how to use the SYSTIMER peripheral including interrupts. +//! It's an additional timer besides the TIMG peripherals. + #![no_std] #![no_main] diff --git a/esp32s2-hal/examples/timer_interrupt.rs b/esp32s2-hal/examples/timer_interrupt.rs index 4d2f87633..99e5f19c9 100644 --- a/esp32s2-hal/examples/timer_interrupt.rs +++ b/esp32s2-hal/examples/timer_interrupt.rs @@ -1,3 +1,7 @@ +//! This shows how to use the TIMG peripheral interrupts. +//! There is TIMG0 and TIMG1 each of them containing two general purpose timers +//! and a watchdog timer. + #![no_std] #![no_main] diff --git a/esp32s2-hal/examples/watchdog.rs b/esp32s2-hal/examples/watchdog.rs index d6d8719e2..b5c296086 100644 --- a/esp32s2-hal/examples/watchdog.rs +++ b/esp32s2-hal/examples/watchdog.rs @@ -1,6 +1,6 @@ //! This demos the watchdog timer. //! Basically the same as `hello_world` but if you remove the call to -//! `wdt.feed()` the watchdog will reset the system.#![no_std] +//! `wdt.feed()` the watchdog will reset the system. #![no_std] #![no_main] diff --git a/esp32s3-hal/examples/blinky.rs b/esp32s3-hal/examples/blinky.rs index 316b96e68..d72f88bd4 100644 --- a/esp32s3-hal/examples/blinky.rs +++ b/esp32s3-hal/examples/blinky.rs @@ -1,3 +1,7 @@ +//! Blinks an LED +//! +//! This assumes that a LED is connected to the pin assigned to `led`. (GPIO4) + #![no_std] #![no_main] diff --git a/esp32s3-hal/examples/gpio_interrupt.rs b/esp32s3-hal/examples/gpio_interrupt.rs index 33f885420..223d8eb5b 100644 --- a/esp32s3-hal/examples/gpio_interrupt.rs +++ b/esp32s3-hal/examples/gpio_interrupt.rs @@ -1,3 +1,8 @@ +//! GPIO interrupt +//! +//! This prints "Interrupt" when the boot button is pressed. +//! It also blinks an LED like the blinky example. + #![no_std] #![no_main] diff --git a/esp32s3-hal/examples/hello_world.rs b/esp32s3-hal/examples/hello_world.rs index 42c1a66ed..c41c26c8e 100644 --- a/esp32s3-hal/examples/hello_world.rs +++ b/esp32s3-hal/examples/hello_world.rs @@ -1,3 +1,6 @@ +//! This shows how to write text to serial0. +//! You can see the output with `espflash` if you provide the `--monitor` option + #![no_std] #![no_main] diff --git a/esp32s3-hal/examples/multicore.rs b/esp32s3-hal/examples/multicore.rs index 32a58a1ec..f3ca1c022 100644 --- a/esp32s3-hal/examples/multicore.rs +++ b/esp32s3-hal/examples/multicore.rs @@ -1,3 +1,7 @@ +//! This shows how to spawn a task on the second core. +//! The first core will print the value of a counter which is incremented by the +//! second core. + #![no_std] #![no_main] diff --git a/esp32s3-hal/examples/ram.rs b/esp32s3-hal/examples/ram.rs index 1c719b375..1d1f77f17 100644 --- a/esp32s3-hal/examples/ram.rs +++ b/esp32s3-hal/examples/ram.rs @@ -1,3 +1,10 @@ +//! This shows how to use RTC memory. +//! RTC memory is retained during resets and during most sleep modes. +//! Initialized memory is always re-initialized on startup. +//! Uninitialzed memory isn't initialized on startup and can be used to keep +//! data during resets. Zeroed memory is initialized to zero on startup. +//! We can also run code from RTC memory. + #![no_std] #![no_main] diff --git a/esp32s3-hal/examples/read_efuse.rs b/esp32s3-hal/examples/read_efuse.rs index 5a0b45498..1fc908526 100644 --- a/esp32s3-hal/examples/read_efuse.rs +++ b/esp32s3-hal/examples/read_efuse.rs @@ -1,3 +1,6 @@ +//! This shows how to read selected information from eFuses. +//! e.g. the MAC address + #![no_std] #![no_main] diff --git a/esp32s3-hal/examples/systimer.rs b/esp32s3-hal/examples/systimer.rs index 1aea536f9..12d33f174 100644 --- a/esp32s3-hal/examples/systimer.rs +++ b/esp32s3-hal/examples/systimer.rs @@ -1,3 +1,6 @@ +//! This shows how to use the SYSTIMER peripheral including interrupts. +//! It's an additional timer besides the TIMG peripherals. + #![no_std] #![no_main] diff --git a/esp32s3-hal/examples/timer_interrupt.rs b/esp32s3-hal/examples/timer_interrupt.rs index ac40be7e9..f540df0f5 100644 --- a/esp32s3-hal/examples/timer_interrupt.rs +++ b/esp32s3-hal/examples/timer_interrupt.rs @@ -1,3 +1,7 @@ +//! This shows how to use the TIMG peripheral interrupts. +//! There is TIMG0 and TIMG1 each of them containing two general purpose timers +//! and a watchdog timer. + #![no_std] #![no_main] diff --git a/esp32s3-hal/examples/usb_serial_jtag.rs b/esp32s3-hal/examples/usb_serial_jtag.rs index d0e0a0c07..fcc41a1b1 100644 --- a/esp32s3-hal/examples/usb_serial_jtag.rs +++ b/esp32s3-hal/examples/usb_serial_jtag.rs @@ -1,3 +1,7 @@ +//! This shows how to output text via USB Serial/JTAG. +//! You need to connect via the Serial/JTAG interface to see any output. +//! Most dev-kits use a USB-UART-bridge - in that case you won't see any output. + #![no_std] #![no_main] diff --git a/esp32s3-hal/examples/watchdog.rs b/esp32s3-hal/examples/watchdog.rs index 222585526..b4e5aea2f 100644 --- a/esp32s3-hal/examples/watchdog.rs +++ b/esp32s3-hal/examples/watchdog.rs @@ -1,6 +1,6 @@ //! This demos the watchdog timer. //! Basically the same as `hello_world` but if you remove the call to -//! `wdt.feed()` the watchdog will reset the system.#![no_std] +//! `wdt.feed()` the watchdog will reset the system. #![no_std] #![no_main]