Merge branch 'rp-rs:main' into reexport_mod_structs

Cargo.toml

@@ -5,6 +5,7 @@ members = [
     "boards/feather_rp2040",
     "boards/qt_py_rp2040",
     "boards/itsy_bitsy_rp2040",
+    "boards/kb2040",
     "boards/pico",
     "boards/pico_explorer",
     "boards/pico_lipo_16mb",

README.md

@@ -197,6 +197,26 @@ RP2040 chip according to how it is connected up on the Feather RP2040.
 [Adafruit QT Py RP2040]: https://www.adafruit.com/product/4900
 [qt_py_rp2040]: https://github.com/rp-rs/rp-hal/tree/main/boards/qt_py_rp2040
 
+### [itsy_bitsy_rp2040] - Board Support for the [Adafruit ItsyBitsy RP2040]
+You should include this crate if you are writing code that you want to run on
+an [Adafruit ItsyBitsy RP2040] - an RP2040 board in the ItsyBitsy family.
+
+This crate includes the [rp2040-hal], but also configures each pin of the
+RP2040 chip according to how it is connected up on the ItsyBitsy RP2040.
+
+[Adafruit ItsyBitsy RP2040]: https://www.adafruit.com/product/4888
+[itsy_bitsy_rp2040]: https://github.com/rp-rs/rp-hal/tree/main/boards/itsy_bitsy_rp2040
+
+### [kb2040] - Board Support for the [Adafruit KB2040]
+You should include this crate if you are writing code that you want to run on
+an [Adafruit KB2040] - an Arduino Pro Micro-shaped board for keyboards.
+
+This crate includes the [rp2040-hal], but also configures each pin of the
+RP2040 chip according to how it is connected up on the KB2040.
+
+[Adafruit KB2040]: https://www.adafruit.com/product/5302
+[kb2040]: https://github.com/rp-rs/rp-hal/tree/main/boards/kb2040
+
 <!-- PROGRAMMING -->
 ## Programming
 

boards/kb2040/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "kb2040"
+version = "0.1.0"
+authors = ["Andrew Christiansen <andrewtaylorchristiansen@gmail.com>"]
+edition = "2018"
+homepage = "https://github.com/rp-rs/rp-hal/boards/kb2040"
+description = "Board Support Package for the Adafruit KB2040"
+license = "MIT OR Apache-2.0"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+cortex-m = "0.7.2"
+rp2040-hal = { path = "../../rp2040-hal", version = "0.3.0" }
+cortex-m-rt = { version = "0.7.0", optional = true }
+embedded-hal = { version = "0.2.4", features = ["unproven"] }
+
+[features]
+default = ["rt"]
+rt = ["cortex-m-rt", "rp2040-hal/rt"]
+
+[dev-dependencies]
+panic-halt = "0.2.0"
+rp2040-boot2 = "0.2"
+smart-leds = "0.3.0"
+embedded-time = "0.12.0"
+nb = "1.0.0"
+pio = { git = "https://github.com/rp-rs/pio-rs.git", branch = "main" }
+ws2812-pio = { git = "https://github.com/ithinuel/ws2812-pio-rs", rev = "7a11616f994025f5c99f28b283d2b25d60d46a43" }

boards/kb2040/README.md

@@ -0,0 +1,94 @@
+# [kb2040] - Board Support for the [Adafruit KB2040]
+
+You should include this crate if you are writing code that you want to run on
+a [Adafruit KB2040] - an Arduino Pro Micro-shaped board for keyboards.
+
+This crate includes the [rp2040-hal], but also configures each pin of the
+RP2040 chip according to how it is connected up on the KB2040.
+
+[Adafruit KB2040]: https://www.adafruit.com/product/5302
+[kb2040]: https://github.com/rp-rs/rp-hal/tree/main/boards/kb2040
+[rp2040-hal]: https://github.com/rp-rs/rp-hal/tree/main/rp2040-hal
+[Raspberry Silicon RP2040]: https://www.raspberrypi.org/products/rp2040/
+
+## Using
+
+To use this crate, your `Cargo.toml` file should contain:
+
+```toml
+kb2040 = { git = "https://github.com/rp-rs/rp-hal.git" }
+```
+
+In your program, you will need to call `kb2040::Pins::new` to create
+a new `Pins` structure. This will set up all the GPIOs for any on-board
+devices. See the [examples](./examples) folder for more details.
+
+## Examples
+
+### General Instructions
+
+To compile an example, clone the _rp-hal_ repository and run:
+
+```console
+rp-hal/boards/kb2040 $ cargo build --release --example <name>
+```
+
+You will get an ELF file called
+`./target/thumbv6m-none-eabi/release/examples/<name>`, where the `target`
+folder is located at the top of the _rp-hal_ repository checkout. Normally
+you would also need to specify `--target=thumbv6m-none-eabi` but when
+building examples from this git repository, that is set as the default.
+
+If you want to convert the ELF file to a UF2 and automatically copy it to the
+USB drive exported by the RP2040 bootloader, simply boot your board into
+bootloader mode and run:
+
+```console
+rp-hal/boards/kb2040$ cargo run --release --example <name>
+```
+
+If you get an error about not being able to find `elf2uf2-rs`, try:
+
+```console
+$ cargo install elf2uf2-rs, then repeating the `cargo run` command above.
+```
+
+### [Rainbow](./examples/kb2040_rainbow.rs)
+
+This example will display a colour-wheel rainbow effect on the on-board LED.
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to
+be learn, inspire, and create. Any contributions you make are **greatly
+appreciated**.
+
+The steps are:
+
+1. Fork the Project by clicking the 'Fork' button at the top of the page.
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Make some changes to the code or documentation.
+4. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+5. Push to the Feature Branch (`git push origin feature/AmazingFeature`)
+6. Create a [New Pull Request](https://github.com/rp-rs/rp-hal/pulls)
+7. An admin will review the Pull Request and discuss any changes that may be required.
+8. Once everyone is happy, the Pull Request can be merged by an admin, and your work is part of our project!
+
+## Code of Conduct
+
+Contribution to this crate is organized under the terms of the [Rust Code of
+Conduct][CoC], and the maintainer of this crate, the [rp-rs team], promises
+to intervene to uphold that code of conduct.
+
+[CoC]: CODE_OF_CONDUCT.md
+[rp-rs team]: https://github.com/orgs/rp-rs/teams/rp-rs
+
+## License
+
+The contents of this repository are dual-licensed under the _MIT OR Apache
+2.0_ License. That means you can chose either the MIT licence or the
+Apache-2.0 licence when you re-use this code. See `MIT` or `APACHE2.0` for more
+information on each specific licence.
+
+Any submissions to this project (e.g. as Pull Requests) must be made available
+under these terms.

boards/kb2040/examples/kb2040_rainbow.rs

@@ -0,0 +1,115 @@
+//! # Rainbow Example for the Adafruit KB2040
+//!
+//! Runs a rainbow-effect colour wheel on the on-board LED.
+//!
+//! Uses the `ws2812_pio` driver to control the LED, which in turns uses the
+//! RP2040's PIO block.
+
+#![no_std]
+#![no_main]
+
+use core::iter::once;
+use cortex_m_rt::entry;
+use embedded_hal::timer::CountDown;
+use embedded_time::duration::Extensions;
+use panic_halt as _;
+
+use kb2040::{
+    hal::{
+        clocks::{init_clocks_and_plls, Clock},
+        pac,
+        sio::Sio,
+        timer::Timer,
+        watchdog::Watchdog,
+    },
+    XOSC_CRYSTAL_FREQ,
+};
+use rp2040_hal::pio::PIOExt;
+use smart_leds::{brightness, SmartLedsWrite, RGB8};
+use ws2812_pio::Ws2812;
+
+//// The linker will place this boot block at the start of our program image.
+/// We need this to help the ROM bootloader get our code up and running.
+#[link_section = ".boot2"]
+#[used]
+pub static BOOT2: [u8; 256] = rp2040_boot2::BOOT_LOADER_W25Q080;
+
+/// Entry point to our bare-metal application.
+///
+/// The `#[entry]` macro ensures the Cortex-M start-up code calls this
+/// function as soon as all global variables are initialised.
+///
+/// The function configures the RP2040 peripherals, then the LED, then runs
+/// the colour wheel in an infinite loop.
+#[entry]
+fn main() -> ! {
+    // Configure the RP2040 peripherals
+
+    let mut pac = pac::Peripherals::take().unwrap();
+    let mut watchdog = Watchdog::new(pac.WATCHDOG);
+
+    let clocks = init_clocks_and_plls(
+        XOSC_CRYSTAL_FREQ,
+        pac.XOSC,
+        pac.CLOCKS,
+        pac.PLL_SYS,
+        pac.PLL_USB,
+        &mut pac.RESETS,
+        &mut watchdog,
+    )
+    .ok()
+    .unwrap();
+
+    let sio = Sio::new(pac.SIO);
+
+    let pins = kb2040::Pins::new(
+        pac.IO_BANK0,
+        pac.PADS_BANK0,
+        sio.gpio_bank0,
+        &mut pac.RESETS,
+    );
+
+    let timer = Timer::new(pac.TIMER, &mut pac.RESETS);
+    let mut delay = timer.count_down();
+
+    // Configure the addressable LED
+    let (mut pio, sm0, _, _, _) = pac.PIO0.split(&mut pac.RESETS);
+
+    let mut ws = Ws2812::new(
+        pins.neopixel.into_mode(),
+        &mut pio,
+        sm0,
+        clocks.peripheral_clock.freq(),
+        timer.count_down(),
+    );
+
+    // Infinite colour wheel loop
+
+    let mut n: u8 = 128;
+    loop {
+        ws.write(brightness(once(wheel(n)), 32)).unwrap();
+        n = n.wrapping_add(1);
+
+        delay.start(25.milliseconds());
+        let _ = nb::block!(delay.wait());
+    }
+}
+
+/// Convert a number from `0..=255` to an RGB color triplet.
+///
+/// The colours are a transition from red, to green, to blue and back to red.
+fn wheel(mut wheel_pos: u8) -> RGB8 {
+    wheel_pos = 255 - wheel_pos;
+    if wheel_pos < 85 {
+        // No green in this sector - red and blue only
+        (255 - (wheel_pos * 3), 0, wheel_pos * 3).into()
+    } else if wheel_pos < 170 {
+        // No red in this sector - green and blue only
+        wheel_pos -= 85;
+        (0, wheel_pos * 3, 255 - (wheel_pos * 3)).into()
+    } else {
+        // No blue in this sector - red and green only
+        wheel_pos -= 170;
+        (wheel_pos * 3, 255 - (wheel_pos * 3), 0).into()
+    }
+}

boards/kb2040/src/lib.rs

@@ -0,0 +1,57 @@
+#![no_std]
+
+pub use rp2040_hal as hal;
+#[cfg(feature = "rt")]
+extern crate cortex_m_rt;
+#[cfg(feature = "rt")]
+pub use cortex_m_rt::entry;
+
+pub use hal::pac;
+
+hal::bsp_pins!(
+    Gpio0 {
+        name: tx,
+        aliases: { FunctionUart: UartTx }
+    },
+    Gpio1 {
+        name: rx,
+        aliases: { FunctionUart: UartRx }
+    },
+    Gpio2 { name: d2 },
+    Gpio3 { name: d3 },
+    Gpio4 { name: d4 },
+    Gpio5 { name: d5 },
+    Gpio6 { name: d6 },
+    Gpio7 { name: d7 },
+    Gpio8 { name: d8 },
+    Gpio9 { name: d9 },
+    Gpio10 { name: d10 },
+    Gpio11 { name: d11 },
+    Gpio12 {
+        name: sda,
+        aliases: { FunctionI2C: Sda }
+    },
+    Gpio13 {
+        name: scl,
+        aliases: { FunctionI2C: Scl }
+    },
+    Gpio17 { name: neopixel },
+    Gpio18 {
+        name: sclk,
+        aliases: { FunctionSpi: Sclk }
+    },
+    Gpio19 {
+        name: mosi,
+        aliases: { FunctionSpi: Mosi }
+    },
+    Gpio20 {
+        name: miso,
+        aliases: { FunctionSpi: Miso }
+    },
+    Gpio26 { name: a0 },
+    Gpio27 { name: a1 },
+    Gpio28 { name: a2 },
+    Gpio29 { name: a3 },
+);
+
+pub const XOSC_CRYSTAL_FREQ: u32 = 12_000_000;

rp2040-hal/src/gpio/reg.rs

@@ -109,6 +109,13 @@ impl From<DynPinMode> for ModeFields {
         fields
     }
 }
+
+/// # Safety
+///
+/// Users should only implement the [`id`] function. No default function
+/// implementations should be overridden. The implementing type must also have
+/// "control" over the corresponding pin ID, i.e. it must guarantee that each
+/// pin ID is a singleton
 pub(super) unsafe trait RegisterInterface {
     /// Provide a [`DynPinId`] identifying the set of registers controlled by
     /// this type.

rp2040-hal/src/pwm/reg.rs

@@ -1,5 +1,12 @@
 use super::dyn_slice::{DynSliceId, DynSliceMode};
 use pac::pwm::CH;
+
+/// # Safety
+///
+/// Users should only implement the [`id`] function. No default function
+/// implementations should be overridden. The implementing type must also have
+/// "control" over the corresponding slice ID, i.e. it must guarantee that each
+/// slice ID is a singleton
 pub(super) unsafe trait RegisterInterface {
     /// Provide a [`DynSliceId`] identifying the set of registers controlled by
     /// this type.

rp2040-hal/src/sio.rs

@@ -109,6 +109,9 @@ impl SioFifo {
     pub fn write(&mut self, value: u32) {
         let sio = unsafe { &(*pac::SIO::ptr()) };
         sio.fifo_wr.write(|w| unsafe { w.bits(value) });
+        // Fire off an event to the other core.
+        // This is required as the other core may be `wfe` (waiting for event)
+        cortex_m::asm::sev();
     }
 
     /// Read from the inter-core FIFO.