[Fixes #72] Deal with dependencies to fix things, mostly doctests (#73)

Since Rust 1.60 it's possible to enable dependencies' features only for included dependencies.

That's going to work for `rt` and `critical-section` and some other features in future.

It would be nice to have a tool that extracts all basic checks from workflow to be run before commit.

Not working on machine I normally burn for this stuff has downsides, as I rush things...

.github/workflows/build.yml

@@ -18,7 +18,7 @@ jobs:
       - id: boards
         run: echo "::set-output name=board_matrix::$(ls ./boards --indicator-style=none | jq -ncR '[inputs]')"
       - id: features
-        run: echo "::set-output name=feature_matrix::[\"reconfigurable-system-pins\",\"usart-spi-host-without-select\"]"
+        run: echo "::set-output name=feature_matrix::[\"reconfigurable-system-pins\",\"usart-spi-host-without-select\",\"rt\",\"critical-section\"]"
     outputs:
       pac_matrix: ${{ steps.pacs.outputs.pac_matrix }}
       board_matrix: ${{ steps.boards.outputs.board_matrix }}
@@ -39,7 +39,7 @@ jobs:
       - name: Install Rust (thumbv7em)
         run: rustup target add thumbv7em-none-eabihf
       - name: Build HAL for ${{ matrix.pac }}
-        run: cargo check --package atsamx7x-hal --features ${{ matrix.pac }},unproven
+        run: cargo check --package atsamx7x-hal --features ${{ matrix.pac }},unproven,rt,critical-section
 
   build-latest:
     if: github.event.pull_request.head.repo.full_name != github.repository
@@ -59,7 +59,7 @@ jobs:
       - name: Install Rust (thumbv7em)
         run: rustup target add thumbv7em-none-eabihf
       - name: Build HAL for ${{ matrix.pac }}
-        run: cargo check --package atsamx7x-hal --features ${{ matrix.pac }},unproven
+        run: cargo check --package atsamx7x-hal --features ${{ matrix.pac }},unproven,rt,critical-section
 
   build-features:
     if: github.event.pull_request.head.repo.full_name != github.repository
@@ -111,7 +111,7 @@ jobs:
       - name: Install Clippy
         run: rustup component add clippy
       - name: Lint HAL
-        run: cargo clippy --package atsamx7x-hal --no-deps --features samv71q21b,unproven,reconfigurable-system-pins -- --deny warnings
+        run: cargo clippy --package atsamx7x-hal --no-deps --features samv71q21b,unproven,reconfigurable-system-pins,rt -- --deny warnings
 
   clippy-examples:
     if: github.event.pull_request.head.repo.full_name != github.repository
@@ -146,8 +146,6 @@ jobs:
       - name: Install Rust (thumbv7em)
         run: rustup target add thumbv7em-none-eabihf
       - name: Build HAL documentation
-        run: cargo doc --package atsamx7x-hal --no-deps --features samv71q21b,unproven,reconfigurable-system-pins
+        run: cargo doc --package atsamx7x-hal --no-deps --features samv71q21b,unproven,reconfigurable-system-pins,rt,critical-section
       - name: Build HAL doc tests
-        run: cargo test --package atsamx7x-hal --doc --features samv71q21b,unproven --target x86_64-unknown-linux-gnu
-
-
+        run: cargo test --package atsamx7x-hal --doc --features samv71q21b,unproven,rt,critical-section --target x86_64-unknown-linux-gnu

CHANGELOG.md

@@ -6,21 +6,24 @@
 
 - [Integration](https://crates.io/crates/mcan-core) with the [`mcan`](https://crates.io/crates/mcan) crate.
 - Implementation of blocking::i2c::Transactional trait from [embedded-hal](https://crates.io/crates/embedded-hal) for TWI device.
+- Support for `critical-section` feature, falling down to PAC optional dependency.
 
 ### Changed
-- Remove `rust-toolchain.toml` and control MSRV from .github/workflow/ files instead.
+- Remove `rust-toolchain.toml` and control MSRV from `.github/workflow/` files instead.
 - Update `cortex-m-rt` version in examples to `0.7.3`.
 - Switched from AFE0_AD6 to  AFE0_AD8 for the atsamv71_xult board ADC example code.
+- The `rt` separated to not act as part of chip selection feature any more.
 
 ### Removed
 - Huge generated source code for PACs removed, new location for them [`atsamx7x-pac`](/atsams-rs/atsamx7x-pac) (user side generated)
 
 ### Fixed
-- Examples now build and link again
-- Examples now build again again
+- Examples now build and link again.
+- Examples now build again again.
 - [#62] Remove ambiguous reexports from `src/serial/mod.rs`.
 - TWIHS: Fix issue with clock frequency calculation.
-- Fix CI: source of PACs matrix + clippy satisfaction
+- Fix CI: source of PACs matrix + clippy satisfaction.
+- Fixes doctest use of `take()` which now require `critical-section`.
 
 ## [v0.4.2] 2022-11-06
 
@@ -79,7 +82,7 @@
 - `pwm` module: allows frequencies and duty-rates to be independently set for each `pwm::Channel`, with help from `ehal::PwmPin`.
 - `hal/rust-toolchain.toml` that pins `rustc` (and relevant components/targets) to MSRV 1.63.0.
 - Crate feature: `reconfigurable-system-pins`; see below.
-- CI job that enforces `CHANGELOG.md` additions, unless the MR is labeled `skip-changelog`.
+- CI job that enforces `CHANGELOG.md` additions, unless the MR is labelled `skip-changelog`.
 
 ### Removed
 - `serial::Uart::UartError::BaudRateNotInRange` error.

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 [email protected]/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.
+

Cargo.toml

@@ -8,4 +8,3 @@ exclude = [
     "boards/",
     "pac/templates"
 ]
-

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
 ---