From bd929ae00529139ceb743bd9b3d67dc6f25a83de Mon Sep 17 00:00:00 2001
From: David Phillips <david@yeah.nah.nz>
Date: Mon, 8 Feb 2021 17:11:54 +1300
Subject: Add documentation to Makefile

---
 Makefile | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)

(limited to 'Makefile')

diff --git a/Makefile b/Makefile
index bb26ce1..1f57333 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,10 @@
+include config.mk
+
 CC ?= avr-gcc
+GDB ?= avr-gdb
 OBJCOPY ?= avr-objcopy
 AVRDUDE ?= avrdude
-QEMU_AVR ?= qemu-system-avr
+QEMU ?= qemu-system-avr
 
 MCU ?= atmega32u4
 SIM_MCU ?= atmega2560
@@ -17,15 +20,24 @@ $(shell mkdir -p build/{real,sim})
 
 all: build/altimeter_sim.elf build/altimeter.hex
 
+# Run the sim build software in qemu, halted ready for `make gdb` to attach and
+# continue. Note that sim build mocks out some hardware components
 emu: build/altimeter_sim.elf
-	$(QEMU_AVR) -s -S -nographic -machine mega2560 -bios $<
+	$(QEMU) -s -S -nographic -machine mega2560 -bios $<
 
+# Attach GDB session to qemu instance started with `make emu`
+gdb:
+	$(GDB) -ex "target remote :1234"
+
+# Flash AVR software to microcontroller with AVRdude
 flash: build/altimeter.hex
 	$(AVRDUDE) -F -V -c avr109 -p $(MCU) -P $(PORT) -b 115200 -U flash:w:$<
 
 clean:
 	rm -rf build/
 
+# ELF for real hardware. No mock/sim hardware included (except barometer,
+# haven't written that code yet)
 build/altimeter.elf: \
 	build/real/barometer_sim.o \
 	build/real/display_sim.o \
@@ -33,6 +45,10 @@ build/altimeter.elf: \
 	build/real/util.o
 	$(CC) -o $@ $^ $(LDFLAGS)
 
+# ELF for simulator/emu. Note that whever I/O is required, the *_sim.{o,c}
+# versions of each component will provide a mocked interface. This allows for
+# operation in QEMU (see `emu` recipe) without requring SPI, I²C and
+# peripherals to be emulated. Useful for UI testing and development etc.
 build/altimeter_sim.elf: \
 	build/sim/barometer_sim.o \
 	build/sim/display_sim.o \
@@ -40,9 +56,6 @@ build/altimeter_sim.elf: \
 	build/sim/util.o
 	$(CC) -o $@ $^ $(SIM_LDFLAGS)
 
-include config.mk
-
-
 build/sim/%.o: %.c
 	$(CC) -c -o $@ $^ $(SIM_CFLAGS)
 
@@ -55,5 +68,4 @@ build/%.hex: build/%.elf
 build/%.elf:
 	$(CC) -o $@ $^ $(CFLAGS)
 
-
-.PHONY: all emu flash clean
+.PHONY: all emu gdb flash clean
-- 
cgit v1.1