Refactor Cargo features (atsamd-rs#656)

Refactor the Cargo features to provide a better, more fine-grained
structure. Separate the features for selecting pins from the features
for selecting peripherals. Reorganize and better document the Cargo.toml
file.

The previous update scripts assumed a particular structure of the TOML
files. This approach is extremely brittle in the face of formatting or
comments. Instead, use the Python package `tomlkit` to parse, modify and
dump TOML files while still preserving all formatting and commenting.

.github/actions/sync-bsp-versions/action.yml

@@ -3,7 +3,7 @@ description: 'Updates BSP files to point to latest HAL'
 runs:
   using: "composite"
   steps:
-    - run: sudo apt install python3-toml
+    - run: sudo apt install python3-pip && pip install tomlkit
       shell: bash
     - run: python3 ${{ github.action_path }}/update-from-hal.py
       shell: bash

.github/actions/sync-bsp-versions/update-from-hal.py

@@ -1,38 +1,24 @@
-#!/bin/python3
+#!/usr/bin/env python3
 
+from tomlkit import parse, dumps
+from pathlib import Path
 import json
-import os
-import re
 import sys
-import toml
 
+hal_path = Path("hal") / "Cargo.toml"
+hal = parse(hal_path.read_text())
+hal_version = hal["package"]["version"]
 
-def upgrade_bsp(path, vers):
-    '''Update the HAL version in the Cargo.toml file at the given path.'''
-    start = -1
-    with open(path, 'r') as f:
-        lines = f.read().splitlines()
-        for i, l in enumerate(lines):
-            l = l.strip()
-            if l == '[dependencies.atsamd-hal]':
-                start = i
-    assert lines[start+2].startswith('version = "')
-    lines[start+2] = "version = \"%s\"" % vers
-    with open(path, 'w') as f:
-        f.write('\n'.join(lines) + '\n')
+crates = Path("crates.json")
+boards = json.loads(crates.read_text())["boards"]
+board_names = [name for name, info in boards.items() if info["tier"] == 1]
 
+for name in board_names:
+    bsp_path = Path("boards") / name / "Cargo.toml"
+    bsp = parse(bsp_path.read_text())
+    bsp_version = bsp["dependencies"]["atsamd-hal"]["version"]
+    if bsp_version != hal_version:
+        print(f"Upgrading {name} from {bsp_version} to {hal_version}.", file=sys.stderr)
+        bsp["dependencies"]["atsamd-hal"]["version"] = hal_version
+        bsp_path.write_text(dumps(bsp))
 
-h = toml.load("hal/Cargo.toml")
-hal_version = '.'.join(h['package']['version'].split('.')[:-1]) # Trim the patch.
-
-
-with open('crates.json', 'r') as f:
-    j = json.load(f)
-    bsps = [b for b in j['boards'].keys() if j['boards'][b]['tier'] == 1]
-
-for bsp in bsps:
-    cargo = toml.load("boards/" + bsp + "/Cargo.toml")
-    current = cargo['dependencies']['atsamd-hal']['version']
-    if current != hal_version:
-        print("Upgrading %s from %s to %s." % (bsp, current, hal_version))
-        upgrade_bsp("boards/" + bsp + "/Cargo.toml", hal_version)

.github/actions/sync-pac-versions/action.yml

@@ -3,7 +3,7 @@ description: 'Updates HAL file with latest PAC versions'
 runs:
   using: "composite"
   steps:
-    - run: sudo apt install python3-toml
+    - run: sudo apt install python3-pip && pip install --user tomlkit
       shell: bash
     - run: python3 ${{ github.action_path }}/update-from-pac.py
       shell: bash

.github/actions/sync-pac-versions/update-from-pac.py

@@ -1,63 +1,25 @@
-#!/bin/python3
+#!/usr/bin/env python3
 
-import os
-import re
+from tomlkit import parse, dumps
+from pathlib import Path
 import sys
-import toml
 
-class PacDep(object):
-    def __init__(self, name, hal_info, pac_info):
-        self._name = name
-        h = toml.load("hal/Cargo.toml")
-        # Trim the patch from the versions.
-        self._hal_version = '.'.join(hal_info['version'].split('.')[:-1])
-        self._pac_version = '.'.join(pac_info['package']['version'].split('.')[:-1])
-        self._line = None
+hal_path = Path("hal") / "Cargo.toml"
+hal = parse(hal_path.read_text())
 
-    @property
-    def hal_version(self):
-        return self._hal_version
+pacs = {}
+for path in Path("pac").glob("atsam*/Cargo.toml"):
+    name = path.parent.name
+    pacs[name] = parse(path.read_text())
 
-    @property
-    def pac_version(self):
-        return self._pac_version
-
-    @property
-    def line(self):
-        return self._line
-
-    @line.setter
-    def line(self, value):
-        self._line = value
-
-# Populate a dictionary containing the different PACs and their version.
-pacs = dict()
-h = toml.load("hal/Cargo.toml")
-for dep, info in h['dependencies'].items():
-    is_pac = os.path.isdir("pac/" + dep)
-    if is_pac:
-        pacs[dep] = PacDep(dep, info, toml.load("pac/" + dep + "/Cargo.toml"))
-
-# Collect version and line information for each PAC.
-with open('hal/Cargo.toml', 'r') as f:
-    lines = f.read().splitlines()
-    for i, l in enumerate(lines):
-        l = l.strip()
-        if l.startswith('[dependencies.') and l.endswith(']'):
-            crate = re.search(r'(\[dependencies)\.(.+)]', l).group(2)
-            if crate in pacs:
-                pacs[crate].line = i
-
-# Update our line array
-for crate, p in pacs.items():
-    if p.hal_version != p.pac_version:
-        assert lines[p.line+2].startswith('version = "')
-        lines[p.line+2] = "version = \"%s\"" % p.pac_version
-        print("HAL dependency on %s upgraded from %s to %s." %
-                (crate, p.hal_version, p.pac_version),
-                file=sys.stderr)
+for name, pac in pacs.items():
+    hal_version = hal["dependencies"][name]["version"]
+    pac_version = pac["package"]["version"]
+    if hal_version == pac_version:
+        print(f"HAL dependency on {name} is up-to-date.", file=sys.stderr)
     else:
-        print("HAL dependency on %s is up-to-date." % crate, file=sys.stderr)
+        hal["dependencies"][name]["version"] = pac_version
+        msg = f"HAL dependency on {name} upgraded from {hal_version} to {pac_version}."
+        print(msg, file=sys.stderr)
 
-with open('hal/Cargo.toml', 'w') as f:
-    f.write('\n'.join(lines) + '\n')
+hal_path.write_text(dumps(hal))

crates.json

@@ -256,15 +256,15 @@
       "target": "thumbv6m-none-eabi"
     },
     "samd21el":  {
-      "features": [ "samd21el", "unproven", "usb", "dma", "rtic" ],
+      "features": [ "samd21el", "unproven", "dma", "rtic" ],
       "target": "thumbv6m-none-eabi"
     },
     "samd21g":  {
       "features": [ "samd21g", "unproven", "usb", "dma", "rtic" ],
       "target": "thumbv6m-none-eabi"
     },
     "samd21gl":  {
-      "features": [ "samd21gl", "unproven", "usb", "dma", "rtic" ],
+      "features": [ "samd21gl", "unproven", "dma", "rtic" ],
       "target": "thumbv6m-none-eabi"
     },
     "samd21j":  {