machine: add tool to check consistency with documentation

This tool checks whether the machine package matches the documentation
in https://tinygo.org/docs/reference/machine/.

.github/workflows/linux.yml

@@ -236,6 +236,8 @@ jobs:
         run: |
           make ASSERT=1
           echo "$(pwd)/build" >> $GITHUB_PATH
+      - name: Test machine package
+        run: make check-machine
       - name: Test stdlib packages
         run: make tinygo-test
       - name: Install Xtensa toolchain

CHANGELOG.md

@@ -1,87 +1,3 @@
-0.26.0
----
-
-* **general**
-  - remove support for LLVM 13
-  - remove calls to deprecated ioutil package
-  - move from `os.IsFoo` to `errors.Is(err, ErrFoo)`
-  - fix for builds using an Android host
-  - make interp timeout configurable from command line
-  - ignore ports with VID/PID if there is no candidates
-  - drop support for Go 1.16 and Go 1.17
-  - update serial package to v1.3.5 for latest bugfixes
-  - remove GOARM from `tinygo info`
-  - add flag for setting the goroutine stack size
-  - add serial port monitoring functionality
-* **compiler**
-  - `cgo`: implement support for static functions
-  - `cgo`: fix panic when FuncType.Results is nil
-  - `compiler`: add aliases for `edwards25519/field.feMul` and `field.feSquare`
-  - `compiler`: fix incorrect DWARF type in some generic parameters
-  - `compiler`: use LLVM math builtins everywhere
-  - `compiler`: replace some math operation bodies with LLVM intrinsics
-  - `compiler`: replace math aliases with intrinsics
-  - `compiler`: fix `unsafe.Sizeof` for chan and map values
-  - `compileopts`: use tags parser from buildutil
-  - `compileopts`: use backticks for regexp to avoid extra escapes
-  - `compileopts`: fail fast on duplicate values in target field slices
-  - `compileopts`: fix windows/arm target triple
-  - `compileopts`: improve error handling when loading target/*.json
-  - `compileopts`: add support for stlink-dap programmer
-  - `compileopts`: do not complain about `-no-debug` on MacOS
-  - `goenv`: support `GOOS=android`
-  - `interp`: fix reading from external global
-  - `loader`: fix link error for `crypto/internal/boring/sig.StandardCrypto`
-* **standard library**
-  - rename assembly files to .S extension
-  - `machine`: add PWM peripheral comments to pins
-  - `machine`: improve UARTParity slightly
-  - `machine`: do not export DFU_MAGIC_* constants on nrf52840
-  - `machine`: rename `PinInputPullUp`/`PinInputPullDown`
-  - `machine`: add `KHz`, `MHz`, `GHz` constants, deprecate `TWI_FREQ_*` constants
-  - `machine`: remove level triggered pin interrupts
-  - `machine`: do not expose `RESET_MAGIC_VALUE`
-  - `machine`: use `NoPin` constant where appropriate (instead of `0` for example)
-  - `net`: sync net.go with Go 1.18 stdlib
-  - `os`: add `SyscallError.Timeout`
-  - `os`: add `ErrProcessDone` error
-  - `reflect`: implement `CanInterface` and fix string `Index`
-  - `runtime`: make `MemStats` available to leaking collector
-  - `runtime`: add `MemStats.TotalAlloc`
-  - `runtime`: add `MemStats.Mallocs` and `Frees`
-  - `runtime`: add support for `time.NewTimer` and `time.NewTicker`
-  - `runtime`: implement `resetTimer`
-  - `runtime`: ensure some headroom for the GC to run
-  - `runtime`: make gc and scheduler asserts settable with build tags
-  - `runtime/pprof`: add `WriteHeapProfile`
-  - `runtime/pprof`: `runtime/trace`: stub some additional functions
-  - `sync`: implement `Map.LoadAndDelete`
-  - `syscall`: group WASI consts by purpose
-  - `syscall`: add WASI `{D,R}SYNC`, `NONBLOCK` FD flags
-  - `syscall`: add ENOTCONN on darwin
-  - `testing`: add support for -benchmem
-* **targets**
-  - remove USB vid/pid pair of bootloader
-  - `esp32c3`: remove unused `UARTStopBits` constants
-  - `nrf`: implement `GetRNG` function
-  - `nrf`: `rp2040`: add `machine.ReadTemperature`
-  - `nrf52`: cleanup s140v6 and s140v7 uf2 targets
-  - `rp2040`: implement semi-random RNG based on ROSC based on pico-sdk
-  - `wasm`: add summary of wasm examples and fix callback bug
-  - `wasm`: do not allow undefined symbols (`--allow-undefined`)
-  - `wasm`: make sure buffers returned by `malloc` are kept until `free` is called
-  - `windows`: save and restore xmm registers when switching goroutines
-* **boards**
-  - add Pimoroni's Tufty2040
-  - add XIAO ESP32C3
-  - add Adafruit QT2040
-  - add Adafruit QT Py RP2040
-  - `esp32c3-12f`: `matrixportal-m4`: `p1am-100`: remove duplicate build tags
-  - `hifive1-qemu`: remove this emulated board
-  - `wioterminal`: add UART3 for RTL8720DN
-  - `xiao-ble`: fix usbpid
-
-
 0.25.0
 ---
 

Makefile

@@ -267,6 +267,18 @@ tinygo:
 test: wasi-libc
 	CGO_CPPFLAGS="$(CGO_CPPFLAGS)" CGO_CXXFLAGS="$(CGO_CXXFLAGS)" CGO_LDFLAGS="$(CGO_LDFLAGS)" $(GO) test $(GOTESTFLAGS) -timeout=20m -buildmode exe -tags "byollvm osusergo" ./builder ./cgo ./compileopts ./compiler ./interp ./transform .
 
+# Check whether the machine package matches the documentation.
+# TODO: improve `tinygo targets` so it doesn't return these invalid targets.
+CHECK_MACHINE_EXCULDE = \
+	cortex-m-qemu \
+	particle-3rd-gen \
+	riscv-qemu \
+	riscv64-qemu \
+	rp2040 \
+	$(nil)
+check-machine:
+	$(GO) run ./tools/machinecheck $(filter-out $(CHECK_MACHINE_EXCULDE),$(shell $(TINYGO) targets))
+
 # Standard library packages that pass tests on darwin, linux, wasi, and windows, but take over a minute in wasi
 TEST_PACKAGES_SLOW = \
 	compress/bzip2 \

builder/build.go

@@ -700,18 +700,21 @@ func Build(pkgName, outpath string, config *compileopts.Config, action func(Buil
 	// Add embedded files.
 	linkerDependencies = append(linkerDependencies, embedFileObjects...)
 
-	// Determine whether the compilation configuration would result in debug
-	// (DWARF) information in the object files.
-	var hasDebug = true
-	if config.GOOS() == "darwin" {
-		// Debug information isn't stored in the binary itself on MacOS but
-		// is left in the object files by default. The binary does store the
-		// path to these object files though.
-		hasDebug = false
-	}
-
 	// Strip debug information with -no-debug.
-	if hasDebug && !config.Debug() {
+	if !config.Debug() {
+		for _, tag := range config.BuildTags() {
+			if tag == "baremetal" {
+				// Don't use -no-debug on baremetal targets. It makes no sense:
+				// the debug information isn't flashed to the device anyway.
+				return fmt.Errorf("stripping debug information is unnecessary for baremetal targets")
+			}
+		}
+		if config.GOOS() == "darwin" {
+			// Debug information isn't stored in the binary itself on MacOS but
+			// is left in the object files by default. The binary does store the
+			// path to these object files though.
+			return errors.New("cannot remove debug information: MacOS doesn't store debug info in the executable by default")
+		}
 		if config.Target.Linker == "wasm-ld" {
 			// Don't just strip debug information, also compress relocations
 			// while we're at it. Relocations can only be compressed when debug

cgo/cgo.go

@@ -948,9 +948,6 @@ func (p *cgoPackage) isEquivalentAST(a, b ast.Node) bool {
 		if !ok {
 			return false
 		}
-		if node == nil || b == nil {
-			return node == b
-		}
 		if len(node.List) != len(b.List) {
 			return false
 		}

cgo/cgo_test.go

@@ -115,84 +115,6 @@ func TestCGo(t *testing.T) {
 	}
 }
 
-func Test_cgoPackage_isEquivalentAST(t *testing.T) {
-	fieldA := &ast.Field{Type: &ast.BasicLit{Kind: token.STRING, Value: "a"}}
-	fieldB := &ast.Field{Type: &ast.BasicLit{Kind: token.STRING, Value: "b"}}
-	listOfFieldA := &ast.FieldList{List: []*ast.Field{fieldA}}
-	listOfFieldB := &ast.FieldList{List: []*ast.Field{fieldB}}
-	funcDeclA := &ast.FuncDecl{Name: &ast.Ident{Name: "a"}, Type: &ast.FuncType{Params: &ast.FieldList{}, Results: listOfFieldA}}
-	funcDeclB := &ast.FuncDecl{Name: &ast.Ident{Name: "b"}, Type: &ast.FuncType{Params: &ast.FieldList{}, Results: listOfFieldB}}
-	funcDeclNoResults := &ast.FuncDecl{Name: &ast.Ident{Name: "C"}, Type: &ast.FuncType{Params: &ast.FieldList{}}}
-
-	testCases := []struct {
-		name     string
-		a, b     ast.Node
-		expected bool
-	}{
-		{
-			name:     "both nil",
-			expected: true,
-		},
-		{
-			name:     "not same type",
-			a:        fieldA,
-			b:        &ast.FuncDecl{},
-			expected: false,
-		},
-		{
-			name:     "Field same",
-			a:        fieldA,
-			b:        fieldA,
-			expected: true,
-		},
-		{
-			name:     "Field different",
-			a:        fieldA,
-			b:        fieldB,
-			expected: false,
-		},
-		{
-			name:     "FuncDecl Type Results nil",
-			a:        funcDeclNoResults,
-			b:        funcDeclNoResults,
-			expected: true,
-		},
-		{
-			name:     "FuncDecl Type Results same",
-			a:        funcDeclA,
-			b:        funcDeclA,
-			expected: true,
-		},
-		{
-			name:     "FuncDecl Type Results different",
-			a:        funcDeclA,
-			b:        funcDeclB,
-			expected: false,
-		},
-		{
-			name:     "FuncDecl Type Results a nil",
-			a:        funcDeclNoResults,
-			b:        funcDeclB,
-			expected: false,
-		},
-		{
-			name:     "FuncDecl Type Results b nil",
-			a:        funcDeclA,
-			b:        funcDeclNoResults,
-			expected: false,
-		},
-	}
-
-	for _, tc := range testCases {
-		t.Run(tc.name, func(t *testing.T) {
-			p := &cgoPackage{}
-			if got := p.isEquivalentAST(tc.a, tc.b); tc.expected != got {
-				t.Errorf("expected %v, got %v", tc.expected, got)
-			}
-		})
-	}
-}
-
 // simpleImporter implements the types.Importer interface, but only allows
 // importing the unsafe package.
 type simpleImporter struct {

compileopts/config.go

@@ -377,8 +377,8 @@ func (c *Config) VerifyIR() bool {
 }
 
 // Debug returns whether debug (DWARF) information should be retained by the
-// linker. By default, debug information is retained, but it can be removed
-// with the -no-debug flag.
+// linker. By default, debug information is retained but it can be removed with
+// the -no-debug flag.
 func (c *Config) Debug() bool {
 	return c.Options.Debug
 }

goenv/version.go

@@ -12,7 +12,7 @@ import (
 
 // Version of TinyGo.
 // Update this value before release of new version of software.
-const Version = "0.26.0"
+const Version = "0.26.0-dev"
 
 var (
 	// This variable is set at build time using -ldflags parameters.

src/machine/board_macropad-rp2040.go

@@ -52,8 +52,8 @@ const (
 	I2C0_SDA_PIN = GPIO20
 	I2C0_SCL_PIN = GPIO21
 
-	I2C1_SDA_PIN = NoPin // not pinned out
-	I2C1_SCL_PIN = NoPin // not pinned out
+	I2C1_SDA_PIN = 31 // not pinned out
+	I2C1_SCL_PIN = 31 // not pinned out
 )
 
 // SPI default pins
@@ -65,9 +65,9 @@ const (
 	// Default Serial In Bus 1 for SPI communications
 	SPI1_SDI_PIN = GPIO28 // Rx
 
-	SPI0_SCK_PIN = NoPin // not pinned out
-	SPI0_SDO_PIN = NoPin // not pinned out
-	SPI0_SDI_PIN = NoPin // not pinned out
+	SPI0_SCK_PIN = 31 // not pinned out
+	SPI0_SDO_PIN = 31 // not pinned out
+	SPI0_SDI_PIN = 31 // not pinned out
 )
 
 // UART pins

src/machine/board_mdbt50qrx.go

@@ -18,15 +18,15 @@ const (
 
 // MDBT50Q-RX dongle does not have pins broken out for the peripherals below,
 // however the machine_nrf*.go implementations of I2C/SPI/etc expect the pin
-// constants to be defined, so we are defining them all as NoPin
+// constants to be defined, so we are defining them all as 0
 const (
-	UART_TX_PIN  = NoPin
-	UART_RX_PIN  = NoPin
-	SDA_PIN      = NoPin
-	SCL_PIN      = NoPin
-	SPI0_SCK_PIN = NoPin
-	SPI0_SDO_PIN = NoPin
-	SPI0_SDI_PIN = NoPin
+	UART_TX_PIN  = 0
+	UART_RX_PIN  = 0
+	SDA_PIN      = 0
+	SCL_PIN      = 0
+	SPI0_SCK_PIN = 0
+	SPI0_SDO_PIN = 0
+	SPI0_SDI_PIN = 0
 )
 
 // USB CDC identifiers

testdata/timers.go

@@ -4,51 +4,51 @@ import "time"
 
 func main() {
 	// Test ticker.
-	ticker := time.NewTicker(time.Millisecond * 500)
+	ticker := time.NewTicker(time.Millisecond * 250)
 	println("waiting on ticker")
 	go func() {
-		time.Sleep(time.Millisecond * 150)
-		println(" - after 150ms")
-		time.Sleep(time.Millisecond * 200)
-		println(" - after 200ms")
-		time.Sleep(time.Millisecond * 300)
-		println(" - after 300ms")
+		time.Sleep(time.Millisecond * 125)
+		println(" - after 125ms")
+		time.Sleep(time.Millisecond * 250)
+		println(" - after 375ms")
+		time.Sleep(time.Millisecond * 250)
+		println(" - after 625ms")
 	}()
 	<-ticker.C
-	println("waited on ticker at 500ms")
+	println("waited on ticker at 250ms")
 	<-ticker.C
-	println("waited on ticker at 1000ms")
+	println("waited on ticker at 500ms")
 	ticker.Stop()
-	time.Sleep(time.Millisecond * 750)
+	time.Sleep(time.Millisecond * 500)
 	select {
 	case <-ticker.C:
 		println("fail: ticker should have stopped!")
 	default:
-		println("ticker was stopped (didn't send anything after 750ms)")
+		println("ticker was stopped (didn't send anything after 500ms)")
 	}
 
-	timer := time.NewTimer(time.Millisecond * 500)
+	timer := time.NewTimer(time.Millisecond * 250)
 	println("waiting on timer")
 	go func() {
-		time.Sleep(time.Millisecond * 200)
-		println(" - after 200ms")
-		time.Sleep(time.Millisecond * 400)
-		println(" - after 400ms")
+		time.Sleep(time.Millisecond * 125)
+		println(" - after 125ms")
+		time.Sleep(time.Millisecond * 250)
+		println(" - after 250ms")
 	}()
 	<-timer.C
-	println("waited on timer at 500ms")
-	time.Sleep(time.Millisecond * 500)
+	println("waited on timer at 250ms")
+	time.Sleep(time.Millisecond * 250)
 
-	reset := timer.Reset(time.Millisecond * 500)
+	reset := timer.Reset(time.Millisecond * 250)
 	println("timer reset:", reset)
 	println("waiting on timer")
 	go func() {
-		time.Sleep(time.Millisecond * 200)
-		println(" - after 200ms")
-		time.Sleep(time.Millisecond * 400)
-		println(" - after 400ms")
+		time.Sleep(time.Millisecond * 125)
+		println(" - after 125ms")
+		time.Sleep(time.Millisecond * 250)
+		println(" - after 250ms")
 	}()
 	<-timer.C
-	println("waited on timer at 500ms")
-	time.Sleep(time.Millisecond * 500)
+	println("waited on timer at 250ms")
+	time.Sleep(time.Millisecond * 250)
 }

testdata/timers.txt

@@ -1,16 +1,16 @@
 waiting on ticker
- - after 150ms
- - after 200ms
+ - after 125ms
+waited on ticker at 250ms
+ - after 375ms
 waited on ticker at 500ms
- - after 300ms
-waited on ticker at 1000ms
-ticker was stopped (didn't send anything after 750ms)
+ - after 625ms
+ticker was stopped (didn't send anything after 500ms)
 waiting on timer
- - after 200ms
-waited on timer at 500ms
- - after 400ms
+ - after 125ms
+waited on timer at 250ms
+ - after 250ms
 timer reset: false
 waiting on timer
- - after 200ms
-waited on timer at 500ms
- - after 400ms
+ - after 125ms
+waited on timer at 250ms
+ - after 250ms

tools/machinecheck/main.go

@@ -0,0 +1,225 @@
+package main
+
+// This file runs some checks on the machine package, to make sure it matches
+// the documentation and that it is internally consistent between targets.
+
+import (
+	"fmt"
+	"go/ast"
+	"go/scanner"
+	"go/token"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	"github.com/tinygo-org/tinygo/compileopts"
+	"github.com/tinygo-org/tinygo/loader"
+	"golang.org/x/tools/go/packages"
+)
+
+// Constants that are documented and always have a particular type.
+var knownConsts = map[string]string{
+	// Chip name, something like "nrf51" or "STM32F429".
+	"Device": "untyped string",
+
+	// Generic constants.
+	"KHz": "untyped int",
+	"MHz": "untyped int",
+	"GHz": "untyped int",
+
+	// Pin mode types for machine.PinConfig.
+	"PinInput":         "machine.PinMode",
+	"PinOutput":        "machine.PinMode",
+	"PinInputPullup":   "machine.PinMode",
+	"PinInputPulldown": "machine.PinMode",
+
+	// Pin change events for pin interrupts.
+	"PinRising":  "machine.PinChange",
+	"PinFalling": "machine.PinChange",
+	"PinToggle":  "machine.PinChange",
+
+	// UART parity
+	"ParityNone": "machine.UARTParity",
+	"ParityEven": "machine.UARTParity",
+	"ParityOdd":  "machine.UARTParity",
+
+	// SPI modes
+	"Mode0": "untyped int",
+	"Mode1": "untyped int",
+	"Mode2": "untyped int",
+	"Mode3": "untyped int",
+
+	// Board specific constants.
+	"HasLowFrequencyCrystal": "untyped bool", // for nrf boards
+}
+
+func main() {
+	targets := os.Args[1:]
+
+	// Start worker goroutines to run checkTarget.
+	results := make(map[string]chan []error)
+	for _, target := range targets {
+		results[target] = make(chan []error, 1)
+	}
+	targetsChan := make(chan string)
+	for i := 0; i < runtime.NumCPU(); i++ {
+		go func() {
+			for target := range targetsChan {
+				errs := checkTarget(target)
+				if len(errs) != 0 {
+					results[target] <- errs
+				}
+				close(results[target])
+			}
+		}()
+	}
+
+	// Check all targets.
+	go func() {
+		for _, target := range targets {
+			targetsChan <- target
+		}
+	}()
+
+	// Read the result of each check.
+	failedTargets := 0
+	for _, target := range targets {
+		errs := <-results[target]
+		if len(errs) != 0 {
+			failedTargets++
+			fmt.Printf("found errors for %s:\n", target)
+			for _, err := range errs {
+				fmt.Println(err)
+			}
+			fmt.Println()
+		}
+	}
+
+	if failedTargets != 0 {
+		fmt.Printf("Failed checks for %d out of %d targets.\n", failedTargets, len(targets))
+		os.Exit(1)
+	}
+}
+
+// Check whether the machine package of the given targets is valid.
+func checkTarget(target string) []error {
+	// Load target configuration.
+	options := &compileopts.Options{
+		Target: target,
+	}
+	spec, err := compileopts.LoadTarget(options)
+	if err != nil {
+		return []error{err}
+	}
+	config := &compileopts.Config{Options: options, Target: spec}
+
+	// Load the package.
+	goroot, err := loader.GetCachedGoroot(config)
+	if err != nil {
+		return []error{err}
+	}
+	cfg := &packages.Config{
+		Env: append(os.Environ(),
+			"GOOS="+config.GOOS(),
+			"GOARCH="+config.GOARCH(),
+			"GOROOT="+goroot,
+		),
+		BuildFlags: []string{
+			"-tags=" + strings.Join(spec.BuildTags, " "),
+		},
+		Mode: packages.NeedSyntax | packages.NeedTypes,
+	}
+	pkgs, err := packages.Load(cfg, "machine")
+	if err != nil {
+		return []error{err}
+	}
+	pkg := pkgs[0]
+	if len(pkg.Errors) != 0 {
+		var errors []error
+		for _, err := range pkg.Errors {
+			errors = append(errors, err)
+		}
+		return errors
+	}
+
+	// Check the package!
+	checker := Checker{
+		goroot: goroot,
+		pkg:    pkg,
+	}
+	for _, file := range pkg.Syntax {
+		if checker.getPosition(file.Package).Filename == "i2s.go" {
+			// TODO: check I2S.
+			continue
+		}
+		for _, decl := range file.Decls {
+			switch decl := decl.(type) {
+			case *ast.GenDecl:
+				if isDeprecated(decl.Doc.Text()) {
+					// Don't check deprecated declarations. They will be removed
+					// with TinyGo 1.0.
+					continue
+				}
+				switch decl.Tok {
+				case token.CONST:
+					for _, spec := range decl.Specs {
+						spec := spec.(*ast.ValueSpec)
+						for _, name := range spec.Names {
+							if !ast.IsExported(name.Name) {
+								continue
+							}
+							checker.checkConst(spec, name)
+						}
+					}
+				}
+			}
+		}
+	}
+
+	return checker.errors
+}
+
+// Return whether the comment is for a deprecated declaration.
+// The convention is explained here:
+// https://github.com/golang/go/wiki/Deprecated
+func isDeprecated(comment string) bool {
+	for _, line := range strings.Split(comment, "\n") {
+		if strings.HasPrefix(line, "Deprecated: ") {
+			return true
+		}
+	}
+	return false
+}
+
+type Checker struct {
+	goroot string
+	pkg    *packages.Package
+	errors []error
+}
+
+// Check whether a constant declaration follows the documentation.
+func (c *Checker) checkConst(spec *ast.ValueSpec, name *ast.Ident) {
+	t := c.pkg.Types.Scope().Lookup(name.Name).Type()
+	if knownConsts[name.Name] == t.String() {
+		return
+	}
+	switch {
+	case t.String() == "machine.Pin":
+		// Pins have all kinds of names. They might need some checking, but
+		// right now all pin names are fine.
+	default:
+		c.errors = append(c.errors, scanner.Error{
+			Pos: c.getPosition(name.NamePos),
+			Msg: fmt.Sprintf("unknown name: %-20s (type %s)", name.Name, t.String()),
+		})
+	}
+}
+
+func (c *Checker) getPosition(pos token.Pos) token.Position {
+	position := c.pkg.Fset.Position(pos)
+	if newpath, err := filepath.Rel(filepath.Join(c.goroot, "src/machine"), position.Filename); err == nil {
+		position.Filename = newpath
+	}
+	return position
+}