From 63d1c87a6683b90ad08c890fea5d794bcf04b2a3 Mon Sep 17 00:00:00 2001 From: Ian Rees Date: Fri, 17 Nov 2023 12:44:03 +1300 Subject: [PATCH] README refresh, moves some content to wiki --- README.md | 370 +++++------------------- boards/feather_m0/examples/adalogger.rs | 1 - hal/CHANGELOG.md | 1 + 3 files changed, 67 insertions(+), 305 deletions(-) diff --git a/README.md b/README.md index 9b45e8f0f510..31b1a0897f4f 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,49 @@ # atsamd & atsame support for Rust -This repository holds various crates that support/enable working with Atmel `samd11`, `samd21`, `samd51` and `same5x` based devices using Rust. +This repository holds various crates that support/enable working with Microchip (nee Atmel) `samd11`, `samd21`, `samd51` and `same5x` based devices using Rust. ![CI Build](https://github.com/atsamd-rs/atsamd/workflows/Build%20BSPs/badge.svg) -The **P**eripheral **A**ccess **C**rates (**PAC**s) are automatically generated, and provide low-level access to the peripherals specified by a device's SVD file. +![CI Build](https://github.com/atsamd-rs/atsamd/workflows/Build%20HAL/badge.svg) -The **H**ardware **A**bstraction **L**ayer (**HAL**) is the result of reading the datasheet for the device and encoding a type-safe layer over the raw PACs. This crate implements traits specified by the [embedded-hal](https://github.com/rust-embedded/embedded-hal) project, making it compatible with various drivers in the embedded rust ecosystem. +## HAL - Hardware Abstraction Layer -In addition to the PACs and HAL, there numerous **B**oard **S**upport **P**ackages (**BSP**s) for popular development boards. They aim to rename pins to match silk screens or Arduino pin assignments, add helpers for initialization, and re-export the `atsamd-hal` crate. These BSPs are listed beside their respective PACs below. +The Hardware Abstraction Layer (HAL - [![Crates.io](https://img.shields.io/crates/v/atsamd_hal.svg)](https://crates.io/crates/atsamd_hal)) crate encodes a type-safe layer over the raw PACs. This crate implements traits specified by the [embedded-hal](https://github.com/rust-embedded/embedded-hal) project, making it compatible with various drivers in the embedded Rust ecosystem. Cargo features are used to enable support for specific hardware variations and features. Online documentation for commonly-used feature sets is provided: -| Crate | Version | Board Support Packages | -|:------|:--------|:-----------------------| -| [atsamd11c](https://docs.rs/atsamd11c/) | [![Crates.io](https://img.shields.io/crates/v/atsamd11c.svg)](https://crates.io/crates/atsamd11c) | [Bare atsamd11][samd11_bare] | +| Chip family | Documented features | +|:------------|:----------------------| +| [samd11c] | samd11c unproven | +| [samd11d] | samd11d unproven | +| [samd21g] | samd21g unproven usb | +| [samd21j] | samd21j unproven usb | +| [samd51g] | samd51g unproven usb | +| [samd51j] | samd51j unproven usb | +| [samd51n] | samd51n unproven usb | +| [samd51p] | samd51p unproven usb | + +[samd11c]: https://atsamd-rs.github.io/docs/samd11c/thumbv6m-none-eabi/doc/atsamd_hal/index.html +[samd11d]: https://atsamd-rs.github.io/docs/samd11d/thumbv6m-none-eabi/doc/atsamd_hal/index.html +[samd21g]: https://atsamd-rs.github.io/docs/samd21g/thumbv6m-none-eabi/doc/atsamd_hal/index.html +[samd21j]: https://atsamd-rs.github.io/docs/samd21j/thumbv6m-none-eabi/doc/atsamd_hal/index.html +[samd51g]: https://atsamd-rs.github.io/docs/samd51g/thumbv7em-none-eabihf/doc/atsamd_hal/index.html +[samd51j]: https://atsamd-rs.github.io/docs/samd51j/thumbv7em-none-eabihf/doc/atsamd_hal/index.html +[samd51n]: https://atsamd-rs.github.io/docs/samd51n/thumbv7em-none-eabihf/doc/atsamd_hal/index.html +[samd51p]: https://atsamd-rs.github.io/docs/samd51p/thumbv7em-none-eabihf/doc/atsamd_hal/index.html + +## PAC and BSP - Peripheral Access Crate and Board Support Package + +The Peripheral Access Crates (PACs) are automatically generated from Microchip SVD files, and provide low-level access to the peripherals specified by a device's SVD file. + +**B**oard **S**upport **P**ackages (**BSP**s) are provided for popular development boards, which rename pins to match silk screens or Arduino pin assignments, add helpers for initialization, and re-export the `atsamd-hal` crate. The BSPs included in `atsamd-rs` are separated in to two tiers: Tier 1 BSPs use the latest version of `atsamd-hal`, Tier 2 BSPs use a specific version of `atsamd-hal` that is not necessarily the latest. + +| PAC docs | crates.io | Provided BSPs | +|:---------|:----------|:---------------| +| [atsamd11c](https://docs.rs/atsamd11c/) | [![Crates.io](https://img.shields.io/crates/v/atsamd11c.svg)](https://crates.io/crates/atsamd11c) | [Bare atsamd11][samd11_bare]\* | | [atsamd21e](https://docs.rs/atsamd21e/) | [![Crates.io](https://img.shields.io/crates/v/atsamd21e.svg)](https://crates.io/crates/atsamd21e) | [Gemma M0][gemma_m0], [Serpente][serpente], [Trinket M0][trinket_m0], [Neo Trinkey][neo_trinkey], [NeoKey Trinkey][neokey_trinkey], [QT Py][qt_py_m0] | -| [atsamd21g](https://docs.rs/atsamd21g/) | [![Crates.io](https://img.shields.io/crates/v/atsamd21g.svg)](https://crates.io/crates/atsamd21g) | [Arduino Nano 33 IOT][arduino_nano33_iot], [Circuit Playground Express][circuit_playground_express], [Feather M0][feather_m0], [ItsyBitsy M0][itsybitsy_m0], [Metro M0][metro_m0], [MKR1000][arduino_mkr1000], [MKR Vidor 4000][arduino_mkr_vidor_4000], [MKR ZERO][arduino_mkrzero], [P1AM-100][p1am_100], [SAMD21 Mini][samd21_mini], [SODAQ ONE][sodaq_one], [Wio Lite MG126][wio_lite_mg126], [Wio Lite W600][wio_lite_w600], [Xiao M0][xiao_m0] | +| [atsamd21g](https://docs.rs/atsamd21g/) | [![Crates.io](https://img.shields.io/crates/v/atsamd21g.svg)](https://crates.io/crates/atsamd21g) | [Arduino Nano 33 IOT][arduino_nano33_iot], [Circuit Playground Express][circuit_playground_express], [Feather M0][feather_m0]\*, [ItsyBitsy M0][itsybitsy_m0], [Metro M0][metro_m0]\*, [MKR1000][arduino_mkr1000], [MKR Vidor 4000][arduino_mkr_vidor_4000], [MKR ZERO][arduino_mkrzero], [P1AM-100][p1am_100], [SAMD21 Mini][samd21_mini], [SODAQ ONE][sodaq_one], [Wio Lite MG126][wio_lite_mg126], [Wio Lite W600][wio_lite_w600], [Xiao M0][xiao_m0] | | [atsamd21j](https://docs.rs/atsamd21j/) | [![Crates.io](https://img.shields.io/crates/v/atsamd21j.svg)](https://crates.io/crates/atsamd21j) | [SODAQ SARA AFF][sodaq_sara_aff] | | [atsamd51g](https://docs.rs/atsamd51g/) | [![Crates.io](https://img.shields.io/crates/v/atsamd51g.svg)](https://crates.io/crates/atsamd51g) | [ItsyBitsy M4][itsybitsy_m4], [Trellis M4][trellis_m4] | -| [atsamd51j](https://docs.rs/atsamd51j/) | [![Crates.io](https://img.shields.io/crates/v/atsamd51j.svg)](https://crates.io/crates/atsamd51j) | [EdgeBadge][edgebadge], [Feather M4][feather_m4], [Metro M4][metro_m4], [PyPortal][pyportal] | +| [atsamd51j](https://docs.rs/atsamd51j/) | [![Crates.io](https://img.shields.io/crates/v/atsamd51j.svg)](https://crates.io/crates/atsamd51j) | [EdgeBadge][edgebadge], [Feather M4][feather_m4]\*, [Metro M4][metro_m4]\*, [PyPortal][pyportal] | | [atsame51n](https://docs.rs/atsame51n/) | [![Crates.io](https://img.shields.io/crates/v/atsame51n.svg)](https://crates.io/crates/atsame51n) | | | [atsamd51p](https://docs.rs/atsamd51p/) | [![Crates.io](https://img.shields.io/crates/v/atsamd51p.svg)](https://crates.io/crates/atsamd51p) | [Grand Central M4 Express][grand_central_m4], [Wio Terminal][wio_terminal] | | [atsame51g](https://docs.rs/atsame51g/) | [![Crates.io](https://img.shields.io/crates/v/atsame51g.svg)](https://crates.io/crates/atsame51g) | | @@ -26,8 +52,9 @@ In addition to the PACs and HAL, there numerous **B**oard **S**upport **P**ackag | [atsame53j](https://docs.rs/atsame53j/) | [![Crates.io](https://img.shields.io/crates/v/atsame53j.svg)](https://crates.io/crates/atsame53j) | [pygamer][PyGamer] | | [atsame53n](https://docs.rs/atsame53n/) | [![Crates.io](https://img.shields.io/crates/v/atsame53n.svg)](https://crates.io/crates/atsame53n) | | | [atsame54n](https://docs.rs/atsame54n/) | [![Crates.io](https://img.shields.io/crates/v/atsame54n.svg)](https://crates.io/crates/atsame54n) | | -| [atsame54p](https://docs.rs/atsame54p/) | [![Crates.io](https://img.shields.io/crates/v/atsame54p.svg)](https://crates.io/crates/atsame54p) | [PathfinderZA Proto1][pfza_proto1], [SAM E54 Xplained Pro Evaluation Kit][atsame54_xpro] | -| [atsamd-hal](https://docs.rs/atsamd_hal/) | [![Crates.io](https://img.shields.io/crates/v/atsamd_hal.svg)](https://crates.io/crates/atsamd_hal) | | +| [atsame54p](https://docs.rs/atsame54p/) | [![Crates.io](https://img.shields.io/crates/v/atsame54p.svg)](https://crates.io/crates/atsame54p) | [PathfinderZA Proto1][pfza_proto1], [SAM E54 Xplained Pro Evaluation Kit][atsame54_xpro]\* | + +\* Tier 1 BSP [arduino_mkr1000]: https://github.com/atsamd-rs/atsamd/tree/master/boards/arduino_mkr1000 [arduino_mkr_vidor_4000]: https://github.com/atsamd-rs/atsamd/tree/master/boards/arduino_mkrvidor4000 @@ -63,320 +90,55 @@ In addition to the PACs and HAL, there numerous **B**oard **S**upport **P**ackag [wio_terminal]: https://github.com/atsamd-rs/atsamd/tree/master/boards/wio_terminal [xiao_m0]: https://github.com/atsamd-rs/atsamd/tree/master/boards/xiao_m0 -## Building - -Make sure that you have a new enough version of the gcc toolchain; the one installable even on recent versions of Ubuntu can fail to correctly link the vector table: +### Examples -**Note**: you may be able to avoid this step if using `cargo-binutils`. See board specific instructions in `boards/` for more details. +The BSPs include examples to quickly get up and running with the board. Building the examples +requires changing directory into one of the board support package directories, and some examples +will require additional features: ```bash -$ sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa -y -$ sudo apt update -$ sudo apt install gcc-arm-embedded +$ cd boards/metro_m0 +$ cargo build --examples --features="usb" ``` -You'll need to add the proper compilation target prior to building as well: - -```bash -$ # for samd11, samd21: -$ rustup target add thumbv6m-none-eabi -$ # for samd51, same51, same53, same54: -$ rustup target add thumbv7em-none-eabihf -``` - -Since a number of different MCUs are used, building the examples requires changing directory into one of the board support package directories prior to building. For example: - -```bash -$ cd metro_m0 -$ cargo build --examples -$ cd ../gemma_m0 -$ cargo build --examples -``` - -## How to use a BSP (i.e. getting started writing your own code) - -A BSP (**B**oard **S**upport **P**ackage) is a crate that contains definitions specific to a particular board. These generally contain pin definitions, sometimes helper functions to setup certain peripherals, as well as examples to quickly get up and running with your board. BSPs are separated into 2 tiers: - -* Tier 1 boards are guaranteed to be up to date with the latest version of `atsamd-hal` - -* Tier 2 boards are tied to a specific version of `atsamd-hal`. They are not guaranteed to be updated when a new version of `atsamd-hal` gets released. - -### Tier 1 BSPs - -* `feather_m0` - -* `feather_m4` - -* `metro_m0` - -* `metro_m4` - -* `pygamer` - -* `samd11_bare` - -* `atsame54_xpro` - -To bootstrap your own project you should be able to copy/paste the Rust code from the examples folder within the folder of the BSP you've chosen. But you shouldn't copy the `Cargo.toml` file from there, since that's not only used for the examples, but also for the whole BSP itself. You want to make your own `Cargo.toml` file. If you're new to this and have no clue what you're doing then this is probably the line you want in there: - -```rust +A new firmware can be made from one of the examples: + 1. Create a new Cargo package for the firmware `cargo new my_firmware`, `cd my_firmware` + 2. Copy the BSP example source file `cp feather_m0/examples/blinky_basic.rs src/main.rs` + 3. Copy Cargo config and memory layout `cp -R feather_m0/.cargo feather_m0/memory.x .` + 4. Add the BSP and any other required dependencies to `Cargo.toml`: +``` TOML [dependencies] -feather_m0 = { git = "https://github.com/atsamd-rs/atsamd" } +feather_m0 = "0.13" +panic-halt = "0.2" ``` + 5. `cargo build` should create an ELF in `target/thumbv6m-none-eabi/debug/my_firmware` -Replace "feather_m0" with the name of the BSP you want to use. Note a few things: -* By specifying the dependency as a remote git repo without specifying a branch, rather than pinning a specific version, we ask Cargo to always grab the latest master branch from Github. This is probably what you want in the beginning, at least now when the project is young, but expect that you'll later want to pin down a specific version. -* There's a whole bunch of crates inside that git repo, and Cargo automatically figures out which one you want to use by checking what you're naming the dependency. In this case we named it "feather_m0" so Cargo will try to find a BSP called that, somewhere inside the repo. - -Now the imports in your Rust code should work, if they look something like this: -```rust -use feather_m0 as bsp; -use bsp::hal; -use bsp::pac; -``` - -You should now have objects called `bsp` and `hal` and `pac`, which contain all the good stuff. - -## Getting code onto the device: Adafruit M0/M4 board (such as Gemma M0 & Feather M0) - -If you want to flash the device using the tools that come with the Adafruit arduino support package: - -```bash -$ cd gemma_m0 -$ cargo build --example blinky_basic -$ arm-none-eabi-objcopy -O binary \ - target/thumbv6m-none-eabi/debug/examples/blinky_basic \ - target/thumbv6m-none-eabi/debug/examples/blinky_basic.bin -# if using cargo-binutils, you can `rust-objcopy` with the same flags, or combine the previous 2 steps with `cargo objcopy` -$ stty -F /dev/ttyACM1 ospeed 1200 -$ ~/.arduino15/packages/arduino/tools/bossac/1.7.0/bossac -i -d \ - --port=ttyACM1 -U -e -w -v \ - target/thumbv6m-none-eabi/debug/examples/blinky_basic.bin -R -``` - -This same technique should work for all of the Adafruit M0/M4 boards, as they all ship with a bossac compatible bootloader. Note that M0 devices may need `-o 0x2000` and M4 devices may need `-o 0x4000` added to the `bossac` parameter lists. - -## Getting code onto the device: JLink - -If you have a board with a SWD debug header, such as the [Metro M0][metro_m0], or if you attached the header yourself, you can use your JLink programmer to either flash the device or debug it (together with gdb). - -You can use JFlashLiteExe to just flash the .bin file (note that for some boards, such as [Feather M0][feather_m0], you need to specify the program memory starting address offset or you'll just get a nondescript flashing error). - -To debug your board you can run JLinkGDBServer instead of JFlashLiteExe. @wez prefers using the JLinkGDBServer, but you can also use OpenOCD. Note that if you have a `load` command within your .gdbinit then starting a debug session triggers a flashing, so you don't need a separate flashing step before this. - -In one window, run `JLinkGDBServer -if SWD -device ATSAMD21G18`, then in another, run these commands from the root of this repo so that you pick up its `.gdbinit` file: - -```bash -$ cargo build --manifest-path metro_m0/Cargo.toml --example blinky_basic -$ arm-none-eabi-gdb metro_m0/target/thumbv6m-none-eabi/debug/examples/blinky_basic -``` - -If you prefer or otherwise need to use OpenOCD, then you'd run it in place of the JLinkGDBServer and then modify the `.gdbinit` file to comment out the JLink section and uncomment the OpenOCD section. - -## Getting code onto the devices with bootloaders: hf2-rs - -This is the preferred pure rust ecosystem method for interacting with bootloaders. - -[hf2-rs](https://github.com/jacobrosenthal/hf2-rs) implements [Microsofts HID Flashing Format (HF2)](https://github.com/microsoft/uf2/blob/86e101e3a282553756161fe12206c7a609975e70/hf2.md) to upload firmware to UF2 bootloaders. UF2 is factory programmed extensively by [Microsoft MakeCode](https://www.microsoft.com/en-us/makecode) and [Adafruit](https://www.adafruit.com/) hardware. - -The `cargo-hf2` crate replaces the `cargo build` command to include flashing over USB to connected UF2 devices, using hf2 flashing over HID protocol. - -```Shell -$ cargo install cargo-hf2 -``` - -and from a bsp directory - -```Shell -$ cargo hf2 --example blinky_basic --features unproven --release -``` - -If you are on Linux and hf2 fails to flash your board even if it is connected and in bootloader -mode, you might need to add some `udev` rules if you have not done that yet. - -You might want to have all the hf2 related rules in a single file, i.e. `/etc/udev/rules.d/99-hf2-boards.rules`, -or have a different rules file for each vendor. - -The rules for Seeeduino and Adafruit boards look like this: - -```Shell -#adafruit rules -ATTRS{idVendor}=="239a", ENV{ID_MM_DEVICE_IGNORE}="1" -SUBSYSTEM=="usb", ATTRS{idVendor}=="239a", MODE="0666" -SUBSYSTEM=="tty", ATTRS{idVendor}=="239a", MODE="0666" - -#seeeduino rules -ATTRS{idVendor}=="2886", ENV{ID_MM_DEVICE_IGNORE}="1" -SUBSYSTEM=="usb", ATTRS{idVendor}=="2886", MODE="0666" -SUBSYSTEM=="tty", ATTRS{idVendor}=="2886", MODE="0666" -``` - -If you want to add boards from another vendor, you can get the vendor id with the `lsusb` command, -for example: - -```Shell -$ lsusb -Bus 001 Device 005: ID 2886:002f Seeed Technology Co., Ltd. Seeeduino XIAO -... -``` - -Here `2886` is the vendor id and `002f` the product id. - -After adding the rules remember to reboot or run: - -```Shell -sudo udevadm control --reload-rules -sudo udevadm trigger -``` - -For more information, refer to the `README` files for each crate: - -* [hf2 library (`hf2`)](https://github.com/jacobrosenthal/hf2-rs/tree/master/hf2) -* [hf2 binary (`hf2-cli`)](https://github.com/jacobrosenthal/hf2-rs/tree/master/hf2-cli) -* [hf2 cargo subcommand (`hf2-cargo`)](https://github.com/jacobrosenthal/hf2-rs/tree/master/cargo-hf2) - -## Getting code onto the devices with bootloaders: uf2conv-rs - -[uf2conv](https://github.com/sajattack/uf2conv-rs) adds a uf2 header [Microsofts HID Flashing Format (UF2)](https://github.com/microsoft/uf2/blob/86e101e3a282553756161fe12206c7a609975e70/README.md) for copying over to UF2 bootloader mass storage devices. UF2 is factory programmed extensively by [Microsoft MakeCode](https://www.microsoft.com/en-us/makecode) and [Adafruit](https://www.adafruit.com/) hardware. -[cargo-binutils](https://github.com/rust-embedded/cargo-binutils) replaces the `cargo build` command to find and convert elf files into binary. - -Install the dependencies -```bash -$ rustup component add llvm-tools-preview -$ cargo install uf2conv cargo-binutils -``` - -Then for say, metro_m0 examples -```bash -$ cargo objcopy --example blinky_basic --features unproven --release -- -O binary blinky_basic.bin -$ uf2conv blinky_basic.bin --base 0x2000 --output blinky_basic.uf2 -$ cp blinky_basic.uf2 /Volumes/PYGAMERBOOT/ -``` - -For more information, refer to the `README` files for each crate: -* [uf2conv (`uf2conv-rs`)](https://github.com/sajattack/uf2conv-rs) -* [cargo-binutils (`cargo-binutils`)](https://github.com/rust-embedded/cargo-binutils) - -## Getting code onto the device with bootloaders: bossac - -If you want to flash the device using the tools that come with the Adafruit arduino support package: - -```bash -$ cd gemma_m0 -$ cargo build --example blinky_basic -$ arm-none-eabi-objcopy -O binary \ - target/thumbv6m-none-eabi/debug/examples/blinky_basic \ - target/thumbv6m-none-eabi/debug/examples/blinky_basic.bin -# if using cargo-binutils, you can `rust-objcopy` with the same flags, or combine the previous 2 steps with `cargo objcopy` -$ stty -F /dev/ttyACM1 ospeed 1200 -$ ~/.arduino15/packages/arduino/tools/bossac/1.7.0/bossac -i -d \ - --port=ttyACM1 -U -e -w -v \ - target/thumbv6m-none-eabi/debug/examples/blinky_basic.bin -R -``` - -This same technique should work for all of the Adafruit M0/M4 boards, as they all ship with a bossac compatible bootloader. Note that M0 devices may need `-o 0x2000` and M4 devices may need `-o 0x4000` added to the `bossac` parameter lists. - -## Getting code onto the device with debugger: cargo-flash - -This is the preferred pure rust ecosystem method for flashing with debugger. - -[cargo flash](https://github.com/probe-rs/cargo-flash) replaces the `cargo build` command to include flashing over debugger using probe-rs and libusb. - -```bash -$ cargo install cargo-flash -``` -We need to know the specific id of your device's chip. Luckily adafruit lists ATSAMD21G18 for metro_m0 -```bash -$ cargo flash --list-chips | grep ATSAMD21G18 - ATSAMD21G18A - ATSAMD21G18AU -``` - -You can stash this chip in the cargo toml so you never have to pass it as an argument, which we recommend. -``` -# for cargo flash -[package.metadata] -chip = "ATSAMD21G18A" -``` +## Building -And cargo flash simply replaces your cargo build command! -```bash -$ cargo flash --example blinky_basic --features unproven --release -``` +You'll need to add the proper compilation target prior to building: -Or you can provide it via the chip command line argument ```bash -$ cargo flash --example blinky_basic --features unproven --release --chip ATSAMD21G18A +$ # for samd11, samd21: +$ rustup target add thumbv6m-none-eabi +$ # for samd51, same51, same53, same54: +$ rustup target add thumbv7em-none-eabihf ``` -## Debugging: probe-run - -This is the preferred pure rust ecosystem method for debugging. It requires no external gdb server, nor C or Python tooling like openocd. +### CI -[probe-run](https://github.com/probe-rs/cargo-flash) attemps to bring the hosted cargo run print line debugging experience to embedded. It also has advanced logging features to vastly reduce format size under the [defmt](https://github.com/knurling-rs/defmt) project which is not covered here. - -`probe-run` needs to be set as your `runner` in the `.cargo/config` along with the id of your chip. Also debug symbols need to be enabled for any profile you're building for. In your application you'll want to use a `probe-run` compatible panic crate like `panic-probe` and an rtt debug logging crate like `rtt-target`. Also don't forget to init your rtt machinery. - -`probe-run` will then be called after a successful build to flash the code directly to the target via debugger and will then wait to receive any rtt prints from your target. Finally if a panic occurs or you ever call `cortex_m::asm::bkpt()` `probe-run` will detect, print a stack trace, and exit. You can exit `probe-run` on the host side with ctrl-c. - -```bash -$ cargo install probe-run -``` +If you'd like to build all the same things that the CI would build but on your local system, you can run: -Then simply use your ide's run or play button, or run: ```bash -$ cargo run --release --example adc --features=unproven - Finished release [optimized + debuginfo] target(s) in 1.10s - Running `probe-run --chip ATSAMD11C14A target/thumbv6m-none-eabi/release/examples/adc` - (HOST) INFO flashing program (35.17 KiB) - (HOST) INFO success! -──────────────────────────────────────────────────────────────────────────────── -4129 -4074 -4177 -^Cstack backtrace: - 0: >::delay_us - at /home/atsamd/hal/src/common/delay.rs:72 - 1: >::delay_ms - at /home/atsamd/hal/src/common/delay.rs:35 - 2: >::delay_ms - at /home/atsamd/hal/src/common/delay.rs:41 - 3: neopixel_adc_battery::__cortex_m_rt_main - at examples/neopixel_adc_battery.rs:50 - 4: main - at examples/neopixel_adc_battery.rs:23 - 5: ResetTrampoline - at /home/.cargo/registry/src/github.com-1ecc6299db9ec823/cortex-m-rt-0.6.13/src/lib.rs:547 - 6: Reset - at /home/.cargo/registry/src/github.com-1ecc6299db9ec823/cortex-m-rt-0.6.13/src/lib.rs:550 +$ ./build-all.py ``` -## Debugging: JLink - -If you have a board with a SWD debug header, such as the [Metro M0][metro_m0], or if you attached the header yourself, you can use your JLink together with gdb. @wez prefers using the JLinkGDBServer, but you can also use OpenOCD. - -In one window, run `JLinkGDBServer -if SWD -device ATSAMD21G18`, then in another, run these commands from the root of this repo so that you pick up its `.gdbinit` file: - -```bash -$ cargo build --manifest-path metro_m0/Cargo.toml --example blinky_basic -$ arm-none-eabi-gdb metro_m0/target/thumbv6m-none-eabi/debug/examples/blinky_basic -``` +## Running and debugging firmware on target hardware -If you prefer or otherwise need to use OpenOCD, then you'd run it in place of the JLinkGDBServer and then modify the `.gdbinit` file to comment out the JLink section and uncomment the OpenOCD section. +See our wiki page about [loading code onto the device](https://github.com/atsamd-rs/atsamd/wiki/Loading-code-onto-the-device). ## Adding a new board -See our wiki page for a [complete guide](https://github.com/atsamd-rs/atsamd/wiki/Adding-a-new-board) on adding a new board. - -### Building everything locally - -If you'd like to build all the same things that the CI would build but on your local system, you can run: - -```bash -$ ./build-all.py -``` - -Please note that this script requires Python 3. +See our wiki page about [adding a new board](https://github.com/atsamd-rs/atsamd/wiki/Adding-a-new-board). ## License @@ -392,7 +154,7 @@ The remainder of the code is licensed under either of: at your option. -### Contribution +## Contribution Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any diff --git a/boards/feather_m0/examples/adalogger.rs b/boards/feather_m0/examples/adalogger.rs index b693dccc8400..1b2d498c74e8 100644 --- a/boards/feather_m0/examples/adalogger.rs +++ b/boards/feather_m0/examples/adalogger.rs @@ -25,7 +25,6 @@ use hal::delay::Delay; use hal::pac::{interrupt, CorePeripherals, Peripherals}; use hal::prelude::*; use hal::rtc; -use hal::time::U32Ext; use hal::usb::UsbBus; use heapless::String; diff --git a/hal/CHANGELOG.md b/hal/CHANGELOG.md index b6e328cffaa0..e0a86df2b8f3 100644 --- a/hal/CHANGELOG.md +++ b/hal/CHANGELOG.md @@ -4,6 +4,7 @@ - Add `dma` feature to docs metadata - Update the PACs to svd2rust 0.30.2. - Fix warnings for thumbv7 targets +- Update README.md - moves some content to wiki # v0.16.0