From a2cfe0572e20a3f7db4b4be7ce872b72ae50b93c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Fita?= <4925040+michalfita@users.noreply.github.com> Date: Wed, 3 Jan 2024 15:57:35 +0000 Subject: [PATCH] [Fixes #72] Cleaning-up --- CONTRIBUTING.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++ Cargo.toml | 39 --------------------------------- README.md | 18 ++++++++++----- hal/Cargo.toml | 35 ----------------------------- tools/patch-pacs | 51 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 120 insertions(+), 80 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100755 tools/patch-pacs diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..2116eb88 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,57 @@ +# Contribution Guidelines + +## Branching Scheme + +This repository employs a [trunk-based development](https://trunkbaseddevelopment.com/): development occurs on `development` branch with short-lived branches that merges into it. +When a release is met, for example a `v0.3.2` release, a `v0.3.x` branch is spun of `development` and the release tagged. If this branch already exists, relevant commits are back-ported instead. + +> [!INFO] +> We don't literally stick to it as the pace is too slow to justify branching for each release. + +Development is done towards `development`. + +### Working branches naming scheme + +While we don't care how you name branches in your forks, we encourage you to branch not PR `development` from your fork, however, if you're a contributor working on this repo directly we strongly +advice to name your branches with following format `issue/99/short-kebab-case-name`, where `99` is the number of issue you're trying to fix or address as enhancement. The work `issue` may be +replaced by `bugfix` if you're fixing a bug, or `feature` if you're working on enhancement. + +## Developing with PAC changes aside + +PACs used by HAL in this repository now reside in [atsamx7x-pac](https://github.com/atsams-rs/atsamx7x-pac/) repository. Crates are published from there to crates.io, and released versions +are normally enough to work with HAL. + +However, if you're in need to incorporate some changes related to unreleased PACs, own variants of PACs, or you fix broken HAL after `svd2rust` generated breaking changes, you have to: +1. Clone the PACs repository to the directory one level above this one: + ```sh + git clone git@github.com/atsams-rs/atsamx7x-pac.git ../atsamx7x-pac + ``` + +2. Add `[patch.crates]` section to `.cargo/config`, for example: + ```toml + [patch.crates-io] + # This is example for one PAC kind, you may want to repeat for each you're using + atsamv71q21b = { path = "../../atsamx7x-pac/pac/atsamv71q21b" } + ``` + or try to run: + ```sh + tools/patch-pacs + ``` + > [!WARN] + > Please don't commit this change! + + This feature is documented [here](https://doc.rust-lang.org/cargo/reference/config.html#patch). + +3. Make changes in there and (re)generate (in this directory; with Python 3 installed): + ```sh + pushd ../atsamx7x-pac + tools/pacs.py svd + popd + ``` + +## Pull Requests + +When you submit a **Pull Request** make sure you've described your efforts in `CHANGELOG.md`, otherwise CI will fail. + +Code has to be formatted with `cargo rustfmt`, otherwise CI will fail. + diff --git a/Cargo.toml b/Cargo.toml index d6dd6fa1..4f7c16fb 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,42 +8,3 @@ exclude = [ "boards/", "pac/templates" ] - -[patch.crates-io] -# In the end it doesn't work as I supposed based on `Cargo.toml` from other -# projects. First, it works only at workspace level; second, it's not optional -# in the sense of probing for existence. We shall consider documenting use of -# https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html#paths-overrides -# atsame70j19b = { path = "../atsamx7x-pac/pac/atsame70j19b" } -# atsame70j20b = { path = "../atsamx7x-pac/pac/atsame70j20b" } -# atsame70j21b = { path = "../atsamx7x-pac/pac/atsame70j21b" } -# atsame70n19b = { path = "../atsamx7x-pac/pac/atsame70n19b" } -# atsame70n20b = { path = "../atsamx7x-pac/pac/atsame70n20b" } -# atsame70n21b = { path = "../atsamx7x-pac/pac/atsame70n21b" } -# atsame70q19b = { path = "../atsamx7x-pac/pac/atsame70q19b" } -# atsame70q20b = { path = "../atsamx7x-pac/pac/atsame70q20b" } -# atsame70q21b = { path = "../atsamx7x-pac/pac/atsame70q21b" } -# atsams70j19b = { path = "../atsamx7x-pac/pac/atsams70j19b" } -# atsams70j20b = { path = "../atsamx7x-pac/pac/atsams70j20b" } -# atsams70j21b = { path = "../atsamx7x-pac/pac/atsams70j21b" } -# atsams70n19b = { path = "../atsamx7x-pac/pac/atsams70n19b" } -# atsams70n20b = { path = "../atsamx7x-pac/pac/atsams70n20b" } -# atsams70n21b = { path = "../atsamx7x-pac/pac/atsams70n21b" } -# atsams70q19b = { path = "../atsamx7x-pac/pac/atsams70q19b" } -# atsams70q20b = { path = "../atsamx7x-pac/pac/atsams70q20b" } -# atsams70q21b = { path = "../atsamx7x-pac/pac/atsams70q21b" } -# atsamv70j19b = { path = "../atsamx7x-pac/pac/atsamv70j19b" } -# atsamv70j20b = { path = "../atsamx7x-pac/pac/atsamv70j20b" } -# atsamv70n19b = { path = "../atsamx7x-pac/pac/atsamv70n19b" } -# atsamv70n20b = { path = "../atsamx7x-pac/pac/atsamv70n20b" } -# atsamv70q19b = { path = "../atsamx7x-pac/pac/atsamv70q19b" } -# atsamv70q20b = { path = "../atsamx7x-pac/pac/atsamv70q20b" } -# atsamv71j19b = { path = "../atsamx7x-pac/pac/atsamv71j19b" } -# atsamv71j20b = { path = "../atsamx7x-pac/pac/atsamv71j20b" } -# atsamv71j21b = { path = "../atsamx7x-pac/pac/atsamv71j21b" } -# atsamv71n19b = { path = "../atsamx7x-pac/pac/atsamv71n19b" } -# atsamv71n20b = { path = "../atsamx7x-pac/pac/atsamv71n20b" } -# atsamv71n21b = { path = "../atsamx7x-pac/pac/atsamv71n21b" } -# atsamv71q19b = { path = "../atsamx7x-pac/pac/atsamv71q19b" } -# atsamv71q20b = { path = "../atsamx7x-pac/pac/atsamv71q20b" } -# atsamv71q21b = { path = "../atsamx7x-pac/pac/atsamv71q21b" } diff --git a/README.md b/README.md index 660c0848..33b2c488 100644 --- a/README.md +++ b/README.md @@ -3,21 +3,27 @@ ATSAMx7x Rust HAL and PACs This repository holds the HAL (Hardware Abstraction Layer) and PACs (Peripheral Access Crates) that supports and enable working with Microchip SAM S70/E70/V70/V71-based devices using Rust. -The PACs are generated by SVD files provided by Microchip, publically available at at the [Microship Packs Repository](https://packs.download.microchip.com/). +The PACs are generated by SVD files provided by Microchip, publicly available at at the [Microchip Packs Repository](https://packs.download.microchip.com/). -The HAL is the result of reading the MCU family datasheet, and provide a type-safe layer ovret he raw PACs. +The HAL is the result of reading the MCU family datasheet, and provide a type-safe layer over the raw PACs. Were able, information is stored in the type-layer instead of computed at run-time. The HAL implements traits specified by [embedded-hal](https://docs.rs/embedded-hal/0.2.7/embedded_hal/), making it compatible with various Embedded Rust ecosystem crates. +> [!TIP] +> We're not compatible with incoming Embedded HAL 1.0 as it's still in pre-release state. + Evaluation kit examples are available under `boards/`, and provide examples for most implemented peripherals. At present, examples are available for the [SAM V71 Xplained Ultra](https://www.microchipdeveloper.com/boards:sam-v71-xult) (`boards/atsamv71_xult`) and [SAM E70 Xplained Pro](https://microchipdeveloper.com/boards:sam-e70-xpro) (`boards/atsame70_xpro`). ## Development -This repository employs a [trunk-based development](https://trunkbaseddevelopment.com/): development occurs on `master` with short-lived branches that merges into it. -When a release is met, for example a `v0.3.2` release, a `v0.3.x` branch is spun of `master` and the release tagged. If this branch already exists, relevant commits are back-ported instead. +> [!NOTE] +> See into [contribution guidelines](CONTRIBUTING.md) for more details. + +This repository employs a [trunk-based development](https://trunkbaseddevelopment.com/): development occurs on `development` branch with short-lived branches that merges into it. +When a release is met, for example a `v0.3.2` release, a `v0.3.x` branch is spun of `development` and the release tagged. If this branch already exists, relevant commits are back-ported instead. -Development is done towards `master`. +Development is done towards `development`. ## Building @@ -34,7 +40,7 @@ $ cargo build --examples ``` ## Flashing the device -Refer to the [SAM V71 Xplained Ulta README](boards/atsamv71_xult/README.md). +Refer to the [SAM V71 Xplained Ultra README](boards/atsamv71_xult/README.md). License --- diff --git a/hal/Cargo.toml b/hal/Cargo.toml index 67771cd2..ef4b91cc 100644 --- a/hal/Cargo.toml +++ b/hal/Cargo.toml @@ -74,41 +74,6 @@ atsamv71q19b = { version = "0.29.0-alpha3", optional = true } atsamv71q20b = { version = "0.29.0-alpha3", optional = true } atsamv71q21b = { version = "0.29.0-alpha3", optional = true } -[patch.crates-io] -atsame70j19b = { path = "../../atsamx7x-pac/pac/atsame70j19b" } -atsame70j20b = { path = "../../atsamx7x-pac/pac/atsame70j20b" } -atsame70j21b = { path = "../../atsamx7x-pac/pac/atsame70j21b" } -atsame70n19b = { path = "../../atsamx7x-pac/pac/atsame70n19b" } -atsame70n20b = { path = "../../atsamx7x-pac/pac/atsame70n20b" } -atsame70n21b = { path = "../../atsamx7x-pac/pac/atsame70n21b" } -atsame70q19b = { path = "../../atsamx7x-pac/pac/atsame70q19b" } -atsame70q20b = { path = "../../atsamx7x-pac/pac/atsame70q20b" } -atsame70q21b = { path = "../../atsamx7x-pac/pac/atsame70q21b" } -atsams70j19b = { path = "../../atsamx7x-pac/pac/atsams70j19b" } -atsams70j20b = { path = "../../atsamx7x-pac/pac/atsams70j20b" } -atsams70j21b = { path = "../../atsamx7x-pac/pac/atsams70j21b" } -atsams70n19b = { path = "../../atsamx7x-pac/pac/atsams70n19b" } -atsams70n20b = { path = "../../atsamx7x-pac/pac/atsams70n20b" } -atsams70n21b = { path = "../../atsamx7x-pac/pac/atsams70n21b" } -atsams70q19b = { path = "../../atsamx7x-pac/pac/atsams70q19b" } -atsams70q20b = { path = "../../atsamx7x-pac/pac/atsams70q20b" } -atsams70q21b = { path = "../../atsamx7x-pac/pac/atsams70q21b" } -atsamv70j19b = { path = "../../atsamx7x-pac/pac/atsamv70j19b" } -atsamv70j20b = { path = "../../atsamx7x-pac/pac/atsamv70j20b" } -atsamv70n19b = { path = "../../atsamx7x-pac/pac/atsamv70n19b" } -atsamv70n20b = { path = "../../atsamx7x-pac/pac/atsamv70n20b" } -atsamv70q19b = { path = "../../atsamx7x-pac/pac/atsamv70q19b" } -atsamv70q20b = { path = "../../atsamx7x-pac/pac/atsamv70q20b" } -atsamv71j19b = { path = "../../atsamx7x-pac/pac/atsamv71j19b" } -atsamv71j20b = { path = "../../atsamx7x-pac/pac/atsamv71j20b" } -atsamv71j21b = { path = "../../atsamx7x-pac/pac/atsamv71j21b" } -atsamv71n19b = { path = "../../atsamx7x-pac/pac/atsamv71n19b" } -atsamv71n20b = { path = "../../atsamx7x-pac/pac/atsamv71n20b" } -atsamv71n21b = { path = "../../atsamx7x-pac/pac/atsamv71n21b" } -atsamv71q19b = { path = "../../atsamx7x-pac/pac/atsamv71q19b" } -atsamv71q20b = { path = "../../atsamx7x-pac/pac/atsamv71q20b" } -atsamv71q21b = { path = "../../atsamx7x-pac/pac/atsamv71q21b" } - [features] # Internal-only feature flags; do not set directly. # Refer to ยง2 in the data sheet. diff --git a/tools/patch-pacs b/tools/patch-pacs new file mode 100755 index 00000000..6f760cef --- /dev/null +++ b/tools/patch-pacs @@ -0,0 +1,51 @@ +#!/usr/bin/env bash + +set -euo pipefail + +declare -r REPO=$(git rev-parse --show-toplevel) +declare -r CARGO_CONFIG="${REPO}/.cargo/config" + +if grep -q "\[patch.crates-io\]" "${CARGO_CONFIG}" ; then + echo "Error: The [patch] section is already in \`${CARGO_CONFIG}\`" >&2 + exit 1 +fi + +cat <> ${CARGO_CONFIG} + +[patch.crates-io] +atsame70j19b = { path = "../../atsamx7x-pac/pac/atsame70j19b" } +atsame70j20b = { path = "../../atsamx7x-pac/pac/atsame70j20b" } +atsame70j21b = { path = "../../atsamx7x-pac/pac/atsame70j21b" } +atsame70n19b = { path = "../../atsamx7x-pac/pac/atsame70n19b" } +atsame70n20b = { path = "../../atsamx7x-pac/pac/atsame70n20b" } +atsame70n21b = { path = "../../atsamx7x-pac/pac/atsame70n21b" } +atsame70q19b = { path = "../../atsamx7x-pac/pac/atsame70q19b" } +atsame70q20b = { path = "../../atsamx7x-pac/pac/atsame70q20b" } +atsame70q21b = { path = "../../atsamx7x-pac/pac/atsame70q21b" } +atsams70j19b = { path = "../../atsamx7x-pac/pac/atsams70j19b" } +atsams70j20b = { path = "../../atsamx7x-pac/pac/atsams70j20b" } +atsams70j21b = { path = "../../atsamx7x-pac/pac/atsams70j21b" } +atsams70n19b = { path = "../../atsamx7x-pac/pac/atsams70n19b" } +atsams70n20b = { path = "../../atsamx7x-pac/pac/atsams70n20b" } +atsams70n21b = { path = "../../atsamx7x-pac/pac/atsams70n21b" } +atsams70q19b = { path = "../../atsamx7x-pac/pac/atsams70q19b" } +atsams70q20b = { path = "../../atsamx7x-pac/pac/atsams70q20b" } +atsams70q21b = { path = "../../atsamx7x-pac/pac/atsams70q21b" } +atsamv70j19b = { path = "../../atsamx7x-pac/pac/atsamv70j19b" } +atsamv70j20b = { path = "../../atsamx7x-pac/pac/atsamv70j20b" } +atsamv70n19b = { path = "../../atsamx7x-pac/pac/atsamv70n19b" } +atsamv70n20b = { path = "../../atsamx7x-pac/pac/atsamv70n20b" } +atsamv70q19b = { path = "../../atsamx7x-pac/pac/atsamv70q19b" } +atsamv70q20b = { path = "../../atsamx7x-pac/pac/atsamv70q20b" } +atsamv71j19b = { path = "../../atsamx7x-pac/pac/atsamv71j19b" } +atsamv71j20b = { path = "../../atsamx7x-pac/pac/atsamv71j20b" } +atsamv71j21b = { path = "../../atsamx7x-pac/pac/atsamv71j21b" } +atsamv71n19b = { path = "../../atsamx7x-pac/pac/atsamv71n19b" } +atsamv71n20b = { path = "../../atsamx7x-pac/pac/atsamv71n20b" } +atsamv71n21b = { path = "../../atsamx7x-pac/pac/atsamv71n21b" } +atsamv71q19b = { path = "../../atsamx7x-pac/pac/atsamv71q19b" } +atsamv71q20b = { path = "../../atsamx7x-pac/pac/atsamv71q20b" } +atsamv71q21b = { path = "../../atsamx7x-pac/pac/atsamv71q21b" } +EOF + +echo "Development patching added to \`${CARGO_CONFIG}\`."