Ensure checked-in RAL is consistent with generated RAL

.github/workflows/rust.yml

@@ -3,6 +3,20 @@ name: All Checks
 on: [push, pull_request]
 
 jobs:
+  gen-ral:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install virtualenv
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.7
+      - name: Install Python dependencies
+        run: cd imxrt-ral && pip install -U -r requirements.txt
+      - name: Generate RAL
+        run: make -C imxrt-ral ci
+      - name: Ensure RAL is consistent with checked-in code
+        run: git update-index --refresh && git diff-index --quiet HEAD
 
   build-ral:
     runs-on: ubuntu-latest
@@ -11,25 +25,6 @@ jobs:
         feature: ["imxrt1011", "imxrt1015", "imxrt1021", "imxrt1051", "imxrt1052", "imxrt1061", "imxrt1062", "imxrt1064"]
     steps:
     - uses: actions/checkout@v2
-    - name: Cache generated code
-      uses: actions/cache@v1
-      id: ral-cache
-      with:
-        path: imxrt-ral
-        key: ${{ runner.OS }}-ral-cache-${{ hashFiles('imxrt-ral/imxrtral.py') }}
-    # These steps only run if we have a RAL cache miss.
-    - name: install virtualenv
-      if: steps.ral-cache.outputs.cache-hit != 'true'
-      uses: actions/setup-python@v1
-      with:
-        python-version: 3.7
-    - name: Install python dependencies
-      if: steps.ral-cache.outputs.cache-hit != 'true'
-      run: cd imxrt-ral && pip install -U -r requirements.txt
-    - name: Generate code
-      if: steps.ral-cache.outputs.cache-hit != 'true'
-      run: cd imxrt-ral && make
-    # Build and test the RAL
     - name: Build imxrt-ral for (${{ matrix.feature }}) RAL
       run: cd imxrt-ral && cargo build --verbose --features ${{ matrix.feature }}
     - name: Run tests (${{ matrix.feature }}) for RAL
@@ -42,25 +37,6 @@ jobs:
         feature: ["imxrt1062"]
     steps:
     - uses: actions/checkout@v2
-    - name: Cache generated code
-      uses: actions/cache@v1
-      id: ral-cache
-      with:
-        path: imxrt-ral
-        key: ${{ runner.OS }}-ral-cache-${{ hashFiles('imxrt-ral/imxrtral.py') }}
-    # These steps only run if we have a RAL cache miss
-    - name: install virtualenv
-      if: steps.ral-cache.outputs.cache-hit != 'true'
-      uses: actions/setup-python@v1
-      with:
-        python-version: 3.7
-    - name: Install python dependencies
-      if: steps.ral-cache.outputs.cache-hit != 'true'
-      run: cd imxrt-ral && pip install -U -r requirements.txt
-    - name: Generate code
-      if: steps.ral-cache.outputs.cache-hit != 'true'
-      run: cd imxrt-ral && make
-    # Build and test the HAL
     - name: Build imxrt-hal for (${{ matrix.feature }}) HAL
       run: cd imxrt-hal && cargo build --verbose --features ${{ matrix.feature }}
     - name: Run tests (${{ matrix.feature }}) for HAL

CONTRIBUTING.md

@@ -23,17 +23,17 @@ rustup target add thumbv7em-none-eabihf
 
 ### RAL
 
-The `imxrt-ral` crate is auto-generated from the checked-in SVD files, available in `imxrt-ral/svd`. Note that the auto-generated RAL source files are not checked into git. They're ignored so that developers are not encouraged to directly modify the Rust source files. If we modified the files directly, the changes might be lost the next time we auto-generate the RAL crate.
+The `imxrt-ral` crate is auto-generated from the checked-in SVD files, available in `imxrt-ral/svd`. It's checked into git, and you should always have whatever represents the latest auto-generated RAL. Generally, you should **not** manually change RAL source files; rather, you should describe changes in `imxrtral.py`, the Python script that auto-generates the RAL.
 
 To generate the RAL,
 
 - Install Python 3. You'll need at least Python 3.6.
 - Install the Python dependencies needed to generate the RAL: `pip3 install --user svdtools`. Alternatively, use the rules in the RAL's `Makefile` to create a virtual environment with the necessary dependencies: `make venv update-venv && source venv/bin/activate`.
-- Run `make` in the `imxrt-ral` directory: `cd imxrt-ral; make; cd ..;`. The auto-generation script might generate warnings; that's OK.
+- Run `make` in the `imxrt-ral` directory: `make -C imxrt-ral`. The auto-generation script might generate warnings; that's OK.
 
-If everything went well, you should find that the `imxrt-ral/src` directory is populated with Rust files. The RAL can build by itself: `cd imxrt-ral && cargo check --features imxrt1062 --target thumbv7em-none-eabihf`.
+If everything went well, you should find that the `imxrt-ral/src` directory is populated with Rust files. If you made changes in `imxrtral.py`, you should see those changes reflected in the Rust files. The RAL can build by itself: `cd imxrt-ral && cargo check --features imxrt1062 --target thumbv7em-none-eabihf`.
 
-The RAL doesn't change too frequently. But, if you add an SVD patch, you'll need to re-generate the RAL to realize the change. Keep an eye on pull requests that mention a RAL change.
+If you add a SVD patch, or if you change something in `imxrtral.py`, you'll need to re-generate the RAL to realize the change.
 
 ### HAL
 

imxrt-ral/Makefile

@@ -6,7 +6,10 @@
 SHELL := /usr/bin/env bash
 DEVICES ?= imxrt1011 imxrt1015 imxrt1021 imxrt1051 imxrt1052 imxrt1061 imxrt1062 imxrt1064 
 
-all: patch crate rustfmt check 
+all: patch crate rustfmt check
+
+# Things to do in CI
+ci: patch crate rustfmt
 
 # All yaml files in devices/ will be used to patch an SVD
 DEVICE_YAMLS := $(foreach device, $(DEVICES), \
@@ -68,7 +71,7 @@ clean-patch:
 clean-html:
 	rm -rf html
 
-clean: clean-patch clean-html
+clean: clean-patch clean-html clean-check
 	rm -rf .deps
 
 # As alternative to `pip install --user svdtools`: