esp32: add support for running and debuggin using qemu-esp32

builder/build.go

@@ -37,8 +37,14 @@ import (
 // BuildResult is the output of a build. This includes the binary itself and
 // some other metadata that is obtained while building the binary.
 type BuildResult struct {
+	// The executable directly from the linker, usually including debug
+	// information. Used for GDB for example.
+	Executable string
+
 	// A path to the output binary. It will be removed after Build returns, so
 	// if it should be kept it must be copied or moved away.
+	// It is often the same as Executable, but differs if the output format is
+	// .hex for example (instead of the usual ELF).
 	Binary string
 
 	// The directory of the main package. This is useful for testing as the test
@@ -835,7 +841,7 @@ func Build(pkgName, outpath string, config *compileopts.Config, action func(Buil
 		if err != nil {
 			return err
 		}
-	case "esp32", "esp32c3", "esp8266":
+	case "esp32", "esp32-img", "esp32c3", "esp8266":
 		// Special format for the ESP family of chips (parsed by the ROM
 		// bootloader).
 		tmppath = filepath.Join(dir, "main"+outext)
@@ -867,6 +873,7 @@ func Build(pkgName, outpath string, config *compileopts.Config, action func(Buil
 	}
 
 	return action(BuildResult{
+		Executable: executable,
 		Binary:     tmppath,
 		MainDir:    lprogram.MainPkg().Dir,
 		ModuleRoot: moduleroot,

builder/esp.go

@@ -15,6 +15,7 @@ import (
 	"fmt"
 	"io/ioutil"
 	"sort"
+	"strings"
 )
 
 type espImageSegment struct {
@@ -78,15 +79,31 @@ func makeESPFirmareImage(infile, outfile, format string) error {
 	// An added benefit is that we don't need to check for errors all the time.
 	outf := &bytes.Buffer{}
 
+	// Separate esp32 and esp32-img. The -img suffix indicates we should make an
+	// image, not just a binary to be flashed at 0x1000 for example.
+	chip := format
+	makeImage := false
+	if strings.HasSuffix(format, "-img") {
+		makeImage = true
+		chip = format[:len(format)-len("-img")]
+	}
+
+	if makeImage {
+		// The bootloader starts at 0x1000, or 4096.
+		// TinyGo doesn't use a separate bootloader and runs the entire
+		// application in the bootloader location.
+		outf.Write(make([]byte, 4096))
+	}
+
 	// Chip IDs. Source:
 	// https://github.com/espressif/esp-idf/blob/v4.3/components/bootloader_support/include/esp_app_format.h#L22
 	chip_id := map[string]uint16{
 		"esp32":   0x0000,
 		"esp32c3": 0x0005,
-	}[format]
+	}[chip]
 
 	// Image header.
-	switch format {
+	switch chip {
 	case "esp32", "esp32c3":
 		// Header format:
 		// https://github.com/espressif/esp-idf/blob/v4.3/components/bootloader_support/include/esp_app_format.h#L71
@@ -155,12 +172,22 @@ func makeESPFirmareImage(infile, outfile, format string) error {
 	outf.Write(make([]byte, 15-outf.Len()%16))
 	outf.WriteByte(checksum)
 
-	if format != "esp8266" {
+	if chip != "esp8266" {
 		// SHA256 hash (to protect against image corruption, not for security).
 		hash := sha256.Sum256(outf.Bytes())
 		outf.Write(hash[:])
 	}
 
+	// QEMU (or more precisely, qemu-system-xtensa from Espressif) expects the
+	// image to be a certain size.
+	if makeImage {
+		// Use a default image size of 4MB.
+		grow := 4096*1024 - outf.Len()
+		if grow > 0 {
+			outf.Write(make([]byte, grow))
+		}
+	}
+
 	// Write the image to the output file.
 	return ioutil.WriteFile(outfile, outf.Bytes(), 0666)
 }