Merge pull request #56 from datdenkikniet/docs

Docs & Examples updates

Author: datdenkikniet

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,6 @@
+# Description
+<!-- Give a description of what this PR adds -->
+
+# TODO
+1. [ ] Step 1
+2. [ ] Update CHANGELOG.md

.github/workflows/build.yml

@@ -11,7 +11,6 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  # Run cargo fmt --check, includes macros/
   style:
     name: style
     runs-on: ubuntu-20.04
@@ -60,7 +59,9 @@ jobs:
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --target=${{ matrix.target }} --features ${{ matrix.features }}
+          # We use `--no-default-features` because compiling `defmt` for non-embedded targets
+          # doesn't work.
+          args: --target=${{ matrix.target }} --no-default-features --features ${{ matrix.features }}
 
 
   # Compilation
@@ -78,7 +79,6 @@ jobs:
           - stm32f407
           - stm32f417
           - stm32f427
-          - stm32f429
           - stm32f437
           - stm32f439
           - stm32f469
@@ -117,70 +117,30 @@ jobs:
     runs-on: ubuntu-20.04
     strategy:
       matrix:
-        target:
-          - thumbv7m-none-eabi
+        example:
+          - name: arp
+            example: arp
+            features: defmt
+          - name: ip
+            example: ip
+            features: defmt,smoltcp-phy,smoltcp/defmt,smoltcp/socket-tcp
+          - name: pktgen
+            example: pktgen
+            features: defmt
+          - name: rtic-echo
+            example: rtic-echo
+            features: rtic-echo-example
+          - name: rtic-echo with nucleo pins
+            example: rtic-echo
+            features: rtic-echo-example,example-nucleo-pins
+        mcu:
+          - stm32f107
+          - stm32f429
+          - stm32f745
         toolchain:
           - stable
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Install Rust ${{ matrix.toolchain }} with target (${{ matrix.target }})
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: ${{ matrix.toolchain }}
-          target: ${{ matrix.target }}
-          override: true
-
-      - name: cargo build f4 example pktgen
-        uses: actions-rs/cargo@v1
-        with:
-          use-cross: false
-          command: build
-          args: --release --target=${{ matrix.target }} --example pktgen --features stm32f429
-
-      - name: cargo build f4 example ip
-        uses: actions-rs/cargo@v1
-        with:
-          use-cross: false
-          command: build
-          args: --release --target=${{ matrix.target }} --example ip --features stm32f429,smoltcp-phy,log,smoltcp/socket-tcp,smoltcp/socket-icmp,smoltcp/log,smoltcp/verbose
-
-      - name: cargo build f4 example arp
-        uses: actions-rs/cargo@v1
-        with:
-          use-cross: false
-          command: build
-          args: --release --target=${{ matrix.target }} --example arp --features stm32f407
-
-      - name: cargo build f4 example arp-smoltcp
-        uses: actions-rs/cargo@v1
-        with:
-          use-cross: false
-          command: build
-          args: --release --target=${{ matrix.target }} --example arp-smoltcp --features stm32f407,smoltcp-phy,smoltcp/socket-icmp
-
-      - name: cargo build f1 example ip
-        uses: actions-rs/cargo@v1
-        with:
-          use-cross: false
-          command: build
-          args: --release --target=${{ matrix.target }} --example ip-f107 --features stm32f107,smoltcp-phy,log,smoltcp/socket-tcp,smoltcp/socket-icmp,smoltcp/log,smoltcp/verbose
-  
-  rtic-echo-example:
-    name: rtic-echo example
-    runs-on: ubuntu-20.04
-    strategy:
-      matrix:
         target:
           - thumbv7m-none-eabi
-        toolchain:
-          - stable
-        features:
-          - stm32f107
-          - stm32f407
-          - stm32f765
-          - rtic-echo-example-altpin,stm32f765
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -192,12 +152,12 @@ jobs:
           target: ${{ matrix.target }}
           override: true
 
-      - name: build rtic-echo-example with features ${{ matrix.features }}
+      - name: Build example ${{ matrix.example.name }} for ${{ matrix.mcu }}
         uses: actions-rs/cargo@v1
         with:
           use-cross: false
           command: build
-          args: --release --target=${{ matrix.target }} --example rtic-echo --features rtic-echo-example,${{ matrix.features }}
+          args: --release --target=${{ matrix.target }} --example ${{ matrix.example.example}} --features ${{ matrix.mcu }},${{ matrix.example.features }}
 
   # Refs: https://github.com/rust-lang/crater/blob/9ab6f9697c901c4a44025cf0a39b73ad5b37d198/.github/workflows/bors.yml#L125-L149
   #
@@ -211,7 +171,6 @@ jobs:
       - build
       - test
       - examples
-      - rtic-echo-example
     runs-on: ubuntu-20.04
     steps:
       - name: Mark the job as a success

CHANGELOG.md

@@ -0,0 +1,22 @@
+## Unreleased
+* General
+    * Remove the `smi` feature and always enable miim/smi. Use `ieee802_3_miim` for SMI access
+    * Split MAC and DMA setup into their own separate modules
+* CI
+    * Test compilability of examples more extensively
+* Examples:
+    * Switch to `defmt` as logger
+    * Use `probe-run` as runner
+    * Ensure that all examples build (and hopefully run) for all supported MCUs
+    * Add more extensive example run and build docs
+    * Remove arp-smoltcp example
+    * Add `rtic-echo` example
+    * Use a more simple `memory.x` that works for all supported MCUs
+
+## [0.3.0](https://github.com/stm32-rs/stm32-eth/tree/v0.3.0)
+
+* Enable ICMP, TCP, and UDP checksum offloading for IPv4 and IPv6. ([#48](https://github.com/stm32-rs/stm32-eth/pull/48))
+* Separate MAC and DMA into separate structs for separate access. ([#39](https://github.com/stm32-rs/stm32-eth/pull/39))
+* Add support for `stm32f107` and fix an MMC interrupt bug. ([#43](https://github.com/stm32-rs/stm32-eth/pull/43), [#42](https://github.com/stm32-rs/stm32-eth/pull/42), [#41](https://github.com/stm32-rs/stm32-eth/pull/41))
+* Update the HALs and dependencies to their latest versions as of 12-07-2022.
+* Add more examples

Cargo.toml

@@ -9,6 +9,7 @@ keywords = ["ethernet", "eth", "stm32", "stm32f4", "stm32f7"]
 repository = "https://github.com/stm32-rs/stm32-eth"
 documentation = "https://docs.rs/stm32-eth/"
 edition = "2018"
+autoexamples = false
 
 [badges]
 travis-ci = { repository = "astro/stm32-eth", branch = "master" }
@@ -23,7 +24,7 @@ aligned = "0.4"
 stm32f7xx-hal = { version = "0.7.0", optional = true }
 stm32f4xx-hal = { version = "0.13", optional = true }
 stm32f1xx-hal = { version = "0.9", optional = true }
-ieee802_3_miim = { version = "0.7", optional = true }
+ieee802_3_miim = "0.7"
 cortex-m = "0.7"
 log = { version = "0.4", optional = true }
 defmt = { version = "0.3", optional = true }
@@ -35,7 +36,7 @@ features = ["medium-ethernet", "proto-ipv4"]
 optional = true
 
 [features]
-default = [ "ieee802_3_miim", "defmt" ]
+default = [ "defmt" ]
 device-selected = []
 fence = []
 
@@ -63,14 +64,12 @@ stm32f779 = ["stm32f7xx-hal/stm32f779", "device-selected", "fence"]
 smoltcp-phy = ["smoltcp"]
 
 # Example features
-rtic-echo-example = [ "ieee802_3_miim", "defmt", "smoltcp-phy", "smoltcp/defmt", "smoltcp/medium-ethernet", "smoltcp/socket-tcp" ]
-rtic-echo-example-altpin = [ ]
+example-nucleo-pins = [ ]
+rtic-echo-example = [ "defmt", "smoltcp-phy", "smoltcp/defmt", "smoltcp/medium-ethernet", "smoltcp/socket-tcp" ]
 
 [dev-dependencies]
 cortex-m = "0.7"
 cortex-m-rt = "0.7"
-panic-itm = "0.4"
-cortex-m-semihosting = "0.3"
 fugit = "0.3"
 cortex-m-rtic = "1.0"
 defmt-rtt = "0.3"
@@ -79,29 +78,17 @@ systick-monotonic = "1.0"
 
 [[example]]
 name = "pktgen"
-required-features = ["stm32f429"]
+required-features = [ "defmt" ]
 
 [[example]]
 name = "ip"
 required-features = [
-    "stm32f429", "smoltcp-phy", "log", "smoltcp/socket-tcp", "smoltcp/socket-icmp",
-    "smoltcp/log", "smoltcp/verbose"
-]
-
-[[example]]
-name = "ip-f107"
-required-features = [
-    "stm32f107", "smoltcp-phy", "log", "smoltcp/socket-tcp", "smoltcp/socket-icmp",
-    "smoltcp/log", "smoltcp/verbose"
-]
+    "defmt", "smoltcp-phy", "smoltcp/defmt", "smoltcp/socket-tcp"
+    ]
 
 [[example]]
 name = "arp"
-required-features = ["stm32f407"]
-
-[[example]]
-name = "arp-smoltcp"
-required-features = ["stm32f407", "smoltcp-phy", "smoltcp/socket-icmp"]
+required-features = [ "defmt" ]
 
 [[example]]
 name = "rtic-echo"

README.md

@@ -10,14 +10,6 @@
 
 Please send pull requests.
 
-## Building Examples
-
-```bash
-cargo build --example="pktgen" --features="stm32f429"
-cargo build --example="ip" --features="stm32f429 smoltcp-phy log smoltcp/socket-tcp smoltcp/socket-icmp smoltcp/log smoltcp/verbose"
-cargo build --example="ip-f107" --features="stm32f107 smoltcp-phy log smoltcp/socket-tcp smoltcp/socket-icmp smoltcp/log smoltcp/verbose"
-```
-
 ## Usage
 
 Add one of the following to the `[dependencies]` section in your `Cargo.toml` (with the correct MCU specified):
@@ -89,6 +81,69 @@ fn main() {
 }
 ```
 
-## [smoltcp] support
+
+## `smoltcp` support
 
 Use feature-flag `smoltcp-phy`
+
+## Examples
+
+The examples should run and compile on any MCU that has an 802.3 compatible PHY capable of generating the required 50 MHz clock signal connected to the default RMII pins.
+
+The examples use `defmt` and `defmt_rtt` for logging, and `panic_probe` over `defmt_rtt` for printing panic backtraces.
+
+To run or build them, the following steps should be taken:
+
+1. Determine the correct compilation target for the MCU that you're using. For `stm32f107`, it is `thumbv7m-none-eabi`. For all others, it is `thumbv7em-none-eabihf`.
+2. Determine the MCU feature necessary for running on your MCU, e.g. `stm32f745`.
+3. Determine the Additional required features (see section below) necessary to build the example.
+4. Follow the rest of the instructions in the ["Building examples"](#building-examples) or ["Running examples"](#running-examples) subsections.
+
+### Additional required features
+
+Besides the feature selecting the correct MCU to be used when building and/or running an example, the following additional features are required:
+
+| Example       | Additional required features                         |
+| ------------- | ---------------------------------------------------- |
+| `arp`         | `defmt`                                              |
+| `ip`          | `defmt,smoltcp-phy,smoltcp/defmt,smoltcp/socket-tcp` |
+| `pktgen`      | `defmt`                                              |
+| `rtic-echo`   | `rtic-echo-example`                                  |
+
+#### 144-pin nucleo boards
+
+For `stm32` 144-pin nucleo boards that contain an MCU supported by this crate the `example-nucleo-pins` feature should be activated. This causes the examples to use PG11 as TX_EN and PG13 as TXD0, instead of PB11 and PB12, which is the configuration used on these boards.
+
+### Building examples
+Run the following command:
+```bash
+cargo build --release --example <example> --features <MCU feature>,<additional required features> --target <MCU compilation target>
+```
+
+For example, if we wish to build the `ip` example for an `stm32f429`, we should run the following command:
+
+```bash
+cargo build --release --example ip --features stm32f429,defmt,smoltcp-phy,smoltcp/defmt,smoltcp/socket-tcp --target thumbv7em-none-eabihf
+```
+
+### Running examples
+Install `probe-run` with `cargo install probe-run --version '~0.3'`
+
+Find the correct value for `PROBE_RUN_CHIP` for your MCU from the list provided by `probe-run --list-chips`.
+
+Ensure that `probe-run` can attach to your MCU
+
+Then, run the following command:
+```bash
+DEFMT_LOG=info PROBE_RUN_CHIP=<probe-run chip> cargo run --release --example <example> --features <MCU feature>,<additional required features> --target <MCU compilation target>
+```
+
+For example, if we wish to run the `rtic-echo` example on an `STM32F107RCT6`, we should run the following command:
+
+```bash
+DEFMT_LOG=info PROBE_RUN_CHIP=STM32F107RC cargo run --release --example rtic-echo --features stm32f107,rtic-echo-example --target thumbv7m-none-eabi
+```
+
+### Other pin configurations
+
+If the usage of different pins is required, the types and `setup_pins` function in `examples/common.rs` should be edited. If the pin configuration is for a `nucleo` board or other commonly used board, a PR with the changes is most welcome.