targets: refactor flash/gdb target configuration

Instead of specifying explicit commands, most of these commands have
been replaced by more specific properties.

This is work that will be necessary for an eventual -programmer flag to
the compiler, with which it is possible to select which programmer to
use to flash or debug a chip. That's not very useful for boards that
already include a programmer or bootloader for that purpose, but is very
useful for novel boards or single-purpose boards that are not already
included in TinyGo.

Author: aykevl

main.go

@@ -403,24 +403,34 @@ func Flash(pkgName, target, port string, config *BuildConfig) error {
 	// determine the type of file to compile
 	var fileExt string
 
-	switch {
-	case strings.Contains(spec.Flasher, "{hex}"):
+	switch spec.FlashMethod {
+	case "command", "":
+		switch {
+		case strings.Contains(spec.FlashCommand, "{hex}"):
+			fileExt = ".hex"
+		case strings.Contains(spec.FlashCommand, "{elf}"):
+			fileExt = ".elf"
+		case strings.Contains(spec.FlashCommand, "{bin}"):
+			fileExt = ".bin"
+		case strings.Contains(spec.FlashCommand, "{uf2}"):
+			fileExt = ".uf2"
+		default:
+			return errors.New("invalid target file - did you forget the {hex} token in the 'flash-command' section?")
+		}
+	case "msd":
+		if spec.FlashFilename == "" {
+			return errors.New("invalid target file: flash-method was set to \"msd\" but no msd-firmware-name was set")
+		}
+		fileExt = filepath.Ext(spec.FlashFilename)
+	case "openocd":
 		fileExt = ".hex"
-	case strings.Contains(spec.Flasher, "{elf}"):
-		fileExt = ".elf"
-	case strings.Contains(spec.Flasher, "{bin}"):
-		fileExt = ".bin"
-	case strings.Contains(spec.Flasher, "{uf2}"):
-		fileExt = ".uf2"
+	case "native":
+		return errors.New("unknown flash method \"native\" - did you miss a -target flag?")
 	default:
-		return errors.New("invalid target file - did you forget the {hex} token in the 'flash' section?")
+		return errors.New("unknown flash method: " + spec.FlashMethod)
 	}
 
 	return Compile(pkgName, fileExt, spec, config, func(tmppath string) error {
-		if spec.Flasher == "" {
-			return errors.New("no flash command specified - did you miss a -target flag?")
-		}
-
 		// do we need port reset to put MCU into bootloader mode?
 		if spec.PortReset == "true" {
 			err := touchSerialPortAt1200bps(port)
@@ -432,7 +442,25 @@ func Flash(pkgName, target, port string, config *BuildConfig) error {
 		}
 
 		// this flashing method copies the binary data to a Mass Storage Device (msd)
-		if spec.FlashMethod == "msd" {
+		switch spec.FlashMethod {
+		case "", "command":
+			// Create the command.
+			flashCmd := spec.FlashCommand
+			fileToken := "{" + fileExt[1:] + "}"
+			flashCmd = strings.Replace(flashCmd, fileToken, tmppath, -1)
+			flashCmd = strings.Replace(flashCmd, "{port}", port, -1)
+
+			// Execute the command.
+			cmd := exec.Command("/bin/sh", "-c", flashCmd)
+			cmd.Stdout = os.Stdout
+			cmd.Stderr = os.Stderr
+			cmd.Dir = sourceDir()
+			err := cmd.Run()
+			if err != nil {
+				return &commandError{"failed to flash", tmppath, err}
+			}
+			return nil
+		case "msd":
 			switch fileExt {
 			case ".uf2":
 				err := flashUF2UsingMSD(spec.FlashVolume, tmppath)
@@ -449,24 +477,23 @@ func Flash(pkgName, target, port string, config *BuildConfig) error {
 			default:
 				return errors.New("mass storage device flashing currently only supports uf2 and hex")
 			}
+		case "openocd":
+			args, err := spec.OpenOCDConfiguration()
+			if err != nil {
+				return err
+			}
+			args = append(args, "-c", "program "+tmppath+" reset exit")
+			cmd := exec.Command("openocd", args...)
+			cmd.Stdout = os.Stdout
+			cmd.Stderr = os.Stderr
+			err = cmd.Run()
+			if err != nil {
+				return &commandError{"failed to flash", tmppath, err}
+			}
+			return nil
+		default:
+			return fmt.Errorf("unknown flash method: %s", spec.FlashMethod)
 		}
-
-		// Create the command.
-		flashCmd := spec.Flasher
-		fileToken := "{" + fileExt[1:] + "}"
-		flashCmd = strings.Replace(flashCmd, fileToken, tmppath, -1)
-		flashCmd = strings.Replace(flashCmd, "{port}", port, -1)
-
-		// Execute the command.
-		cmd := exec.Command("/bin/sh", "-c", flashCmd)
-		cmd.Stdout = os.Stdout
-		cmd.Stderr = os.Stderr
-		cmd.Dir = sourceDir()
-		err := cmd.Run()
-		if err != nil {
-			return &commandError{"failed to flash", tmppath, err}
-		}
-		return nil
 	})
 }
 
@@ -485,9 +512,33 @@ func FlashGDB(pkgName, target, port string, ocdOutput bool, config *BuildConfig)
 	}
 
 	return Compile(pkgName, "", spec, config, func(tmppath string) error {
-		if len(spec.OCDDaemon) != 0 {
+		// Find a good way to run GDB.
+		gdbInterface := spec.FlashMethod
+		switch gdbInterface {
+		case "msd", "command", "":
+			if gdbInterface == "" {
+				gdbInterface = "command"
+			}
+			if spec.OpenOCDInterface != "" && spec.OpenOCDTarget != "" {
+				gdbInterface = "openocd"
+			}
+		}
+
+		// Run the GDB server, if necessary.
+		var gdbCommands []string
+		switch gdbInterface {
+		case "native":
+			// Run GDB directly.
+			gdbCommands = append(gdbCommands, "run")
+		case "openocd":
+			gdbCommands = append(gdbCommands, "target remote :3333", "monitor halt", "load", "monitor reset", "c")
+
 			// We need a separate debugging daemon for on-chip debugging.
-			daemon := exec.Command(spec.OCDDaemon[0], spec.OCDDaemon[1:]...)
+			args, err := spec.OpenOCDConfiguration()
+			if err != nil {
+				return err
+			}
+			daemon := exec.Command("openocd", args...)
 			if ocdOutput {
 				// Make it clear which output is from the daemon.
 				w := &ColorWriter{
@@ -512,6 +563,10 @@ func FlashGDB(pkgName, target, port string, ocdOutput bool, config *BuildConfig)
 				// Maybe we should send a .Kill() after x seconds?
 				daemon.Wait()
 			}()
+		case "msd":
+			return errors.New("gdb is not supported for drag-and-drop programmable devices")
+		default:
+			return fmt.Errorf("gdb is not supported with interface %#v", gdbInterface)
 		}
 
 		// Ignore Ctrl-C, it must be passed on to GDB.
@@ -526,7 +581,7 @@ func FlashGDB(pkgName, target, port string, ocdOutput bool, config *BuildConfig)
 		// By default: gdb -ex run <binary>
 		// Exit GDB with Ctrl-D.
 		params := []string{tmppath}
-		for _, cmd := range spec.GDBCmds {
+		for _, cmd := range gdbCommands {
 			params = append(params, "-ex", cmd)
 		}
 		cmd := exec.Command(spec.GDB, params...)
@@ -606,7 +661,7 @@ func flashUF2UsingMSD(volume, tmppath string) error {
 		return err
 	}
 	if d == nil {
-		return errors.New("unable to locate UF2 device:" + volume)
+		return errors.New("unable to locate UF2 device: " + volume)
 	}
 
 	return moveFile(tmppath, filepath.Dir(d[0])+"/flash.uf2")
@@ -624,7 +679,7 @@ func flashHexUsingMSD(volume, tmppath string) error {
 		return err
 	}
 	if d == nil {
-		return errors.New("unable to locate device:" + volume)
+		return errors.New("unable to locate device: " + volume)
 	}
 
 	return moveFile(tmppath, d[0]+"/flash.hex")

target.go

@@ -26,29 +26,32 @@ var TINYGOROOT string
 // https://doc.rust-lang.org/nightly/nightly-rustc/rustc_target/spec/struct.TargetOptions.html
 // https://github.com/shepmaster/rust-arduino-blink-led-no-core-with-cargo/blob/master/blink/arduino.json
 type TargetSpec struct {
-	Inherits    []string `json:"inherits"`
-	Triple      string   `json:"llvm-target"`
-	CPU         string   `json:"cpu"`
-	Features    []string `json:"features"`
-	GOOS        string   `json:"goos"`
-	GOARCH      string   `json:"goarch"`
-	BuildTags   []string `json:"build-tags"`
-	GC          string   `json:"gc"`
-	Scheduler   string   `json:"scheduler"`
-	Compiler    string   `json:"compiler"`
-	Linker      string   `json:"linker"`
-	RTLib       string   `json:"rtlib"` // compiler runtime library (libgcc, compiler-rt)
-	CFlags      []string `json:"cflags"`
-	LDFlags     []string `json:"ldflags"`
-	ExtraFiles  []string `json:"extra-files"`
-	Emulator    []string `json:"emulator"`
-	Flasher     string   `json:"flash"`
-	OCDDaemon   []string `json:"ocd-daemon"`
-	GDB         string   `json:"gdb"`
-	GDBCmds     []string `json:"gdb-initial-cmds"`
-	PortReset   string   `json:"flash-1200-bps-reset"`
-	FlashMethod string   `json:"flash-method"`
-	FlashVolume string   `json:"flash-msd-volume-name"`
+	Inherits         []string `json:"inherits"`
+	Triple           string   `json:"llvm-target"`
+	CPU              string   `json:"cpu"`
+	Features         []string `json:"features"`
+	GOOS             string   `json:"goos"`
+	GOARCH           string   `json:"goarch"`
+	BuildTags        []string `json:"build-tags"`
+	GC               string   `json:"gc"`
+	Scheduler        string   `json:"scheduler"`
+	Compiler         string   `json:"compiler"`
+	Linker           string   `json:"linker"`
+	RTLib            string   `json:"rtlib"` // compiler runtime library (libgcc, compiler-rt)
+	CFlags           []string `json:"cflags"`
+	LDFlags          []string `json:"ldflags"`
+	ExtraFiles       []string `json:"extra-files"`
+	Emulator         []string `json:"emulator"`
+	FlashCommand     string   `json:"flash-command"`
+	OCDDaemon        []string `json:"ocd-daemon"`
+	GDB              string   `json:"gdb"`
+	PortReset        string   `json:"flash-1200-bps-reset"`
+	FlashMethod      string   `json:"flash-method"`
+	FlashVolume      string   `json:"msd-volume-name"`
+	FlashFilename    string   `json:"msd-firmware-name"`
+	OpenOCDInterface string   `json:"openocd-interface"`
+	OpenOCDTarget    string   `json:"openocd-target"`
+	OpenOCDTransport string   `json:"openocd-transport"`
 }
 
 // copyProperties copies all properties that are set in spec2 into itself.
@@ -91,18 +94,15 @@ func (spec *TargetSpec) copyProperties(spec2 *TargetSpec) {
 	if len(spec2.Emulator) != 0 {
 		spec.Emulator = spec2.Emulator
 	}
-	if spec2.Flasher != "" {
-		spec.Flasher = spec2.Flasher
+	if spec2.FlashCommand != "" {
+		spec.FlashCommand = spec2.FlashCommand
 	}
 	if len(spec2.OCDDaemon) != 0 {
 		spec.OCDDaemon = spec2.OCDDaemon
 	}
 	if spec2.GDB != "" {
 		spec.GDB = spec2.GDB
 	}
-	if len(spec2.GDBCmds) != 0 {
-		spec.GDBCmds = spec2.GDBCmds
-	}
 	if spec2.PortReset != "" {
 		spec.PortReset = spec2.PortReset
 	}
@@ -112,6 +112,18 @@ func (spec *TargetSpec) copyProperties(spec2 *TargetSpec) {
 	if spec2.FlashVolume != "" {
 		spec.FlashVolume = spec2.FlashVolume
 	}
+	if spec2.FlashFilename != "" {
+		spec.FlashFilename = spec2.FlashFilename
+	}
+	if spec2.OpenOCDInterface != "" {
+		spec.OpenOCDInterface = spec2.OpenOCDInterface
+	}
+	if spec2.OpenOCDTarget != "" {
+		spec.OpenOCDTarget = spec2.OpenOCDTarget
+	}
+	if spec2.OpenOCDTransport != "" {
+		spec.OpenOCDTransport = spec2.OpenOCDTransport
+	}
 }
 
 // load reads a target specification from the JSON in the given io.Reader. It
@@ -248,9 +260,8 @@ func defaultTarget(goos, goarch, triple string) (*TargetSpec, error) {
 		Compiler:    "clang",
 		Linker:      "cc",
 		GDB:         "gdb",
-		GDBCmds:     []string{"run"},
 		PortReset:   "false",
-		FlashMethod: "command",
+		FlashMethod: "native",
 	}
 	if goos == "darwin" {
 		spec.LDFlags = append(spec.LDFlags, "-Wl,-dead_strip")
@@ -277,6 +288,33 @@ func defaultTarget(goos, goarch, triple string) (*TargetSpec, error) {
 	return &spec, nil
 }
 
+// OpenOCDConfiguration returns a list of command line arguments to OpenOCD.
+// This list of command-line arguments is based on the various OpenOCD-related
+// flags in the target specification.
+func (spec *TargetSpec) OpenOCDConfiguration() (args []string, err error) {
+	if spec.OpenOCDInterface == "" {
+		return nil, errors.New("OpenOCD programmer not set")
+	}
+	if !regexp.MustCompile("^[\\p{L}0-9_-]+$").MatchString(spec.OpenOCDInterface) {
+		return nil, fmt.Errorf("OpenOCD programmer has an invalid name: %#v", spec.OpenOCDInterface)
+	}
+	if spec.OpenOCDTarget == "" {
+		return nil, errors.New("OpenOCD chip not set")
+	}
+	if !regexp.MustCompile("^[\\p{L}0-9_-]+$").MatchString(spec.OpenOCDTarget) {
+		return nil, fmt.Errorf("OpenOCD target has an invalid name: %#v", spec.OpenOCDTarget)
+	}
+	if spec.OpenOCDTransport != "" && spec.OpenOCDTransport != "swd" {
+		return nil, fmt.Errorf("unknown OpenOCD transport: %#v", spec.OpenOCDTransport)
+	}
+	args = []string{"-f", "interface/" + spec.OpenOCDInterface + ".cfg"}
+	if spec.OpenOCDTransport != "" {
+		args = append(args, "-c", "transport select "+spec.OpenOCDTransport)
+	}
+	args = append(args, "-f", "target/"+spec.OpenOCDTarget+".cfg")
+	return args, nil
+}
+
 // Return the TINYGOROOT, or exit with an error.
 func sourceDir() string {
 	// Use $TINYGOROOT as root, if available.

targets/arduino-nano33.json

@@ -1,6 +1,6 @@
 {
     "inherits": ["atsamd21g18a"],
     "build-tags": ["sam", "atsamd21g18a", "arduino_nano33"],
-    "flash": "bossac -d -i -e -w -v -R --port={port} --offset=0x2000 {bin}",
+    "flash-command": "bossac -d -i -e -w -v -R --port={port} --offset=0x2000 {bin}",
     "flash-1200-bps-reset": "true"
 }

targets/arduino.json

@@ -15,5 +15,5 @@
 		"targets/avr.S",
 		"src/device/avr/atmega328p.s"
 	],
-	"flash": "avrdude -c arduino -p atmega328p -P {port} -U flash:w:{hex}"
+	"flash-command": "avrdude -c arduino -p atmega328p -P {port} -U flash:w:{hex}"
 }

targets/bluepill.json

@@ -12,7 +12,7 @@
 	"extra-files": [
 		"src/device/stm32/stm32f103xx.s"
 	],
-	"flash": "openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg -c 'program {hex} reset exit'",
-	"ocd-daemon": ["openocd", "-f", "interface/stlink-v2.cfg", "-f", "target/stm32f1x.cfg"],
-	"gdb-initial-cmds": ["target remote :3333", "monitor halt", "load", "monitor reset", "c"]
+	"flash-method": "openocd",
+	"openocd-interface": "stlink-v2",
+	"openocd-target": "stm32f1x"
 }

targets/circuitplay-express.json

@@ -1,8 +1,8 @@
 {
     "inherits": ["atsamd21g18a"],
     "build-tags": ["sam", "atsamd21g18a", "circuitplay_express"],
-    "flash": "{uf2}",
     "flash-1200-bps-reset": "true",
     "flash-method": "msd",
-    "flash-msd-volume-name": "CPLAYBOOT"
+    "msd-volume-name": "CPLAYBOOT",
+    "msd-firmware-name": "firmware.uf2"
 }

targets/digispark.json

@@ -15,5 +15,5 @@
 		"targets/avr.S",
 		"src/device/avr/attiny85.s"
 	],
-	"flash": "micronucleus --run {hex}"
+	"flash-command": "micronucleus --run {hex}"
 }

targets/feather-m0.json

@@ -1,8 +1,8 @@
 {
     "inherits": ["atsamd21g18a"],
     "build-tags": ["sam", "atsamd21g18a", "feather_m0"],
-    "flash": "{uf2}",
     "flash-1200-bps-reset": "true",
     "flash-method": "msd",
-    "flash-msd-volume-name": "FEATHERBOOT"
+    "msd-volume-name": "FEATHERBOOT",
+    "msd-firmware-name": "firmware.uf2"
 }

targets/hifive1b.json

@@ -4,7 +4,7 @@
 	"ldflags": [
 		"-T", "targets/hifive1b.ld"
 	],
-	"flash": "{hex}",
 	"flash-method": "msd",
-    "flash-msd-volume-name": "HiFive"
+	"msd-volume-name": "HiFive",
+	"msd-firmware-name": "firmware.hex"
 }