added a README and moved build.mk to build.mk.example

.gitignore

@@ -1,3 +1,6 @@
+# The customized build.mk file
+build.mk
+
 # Prerequisites
 *.d
 *.tmp

Makefile

@@ -8,6 +8,9 @@ GEX_PLAT          = UNSET
 DISABLE_DEBUG     = 0
 DISABLE_MSC       = 0
 CDC_LOOPBACK_TEST = 0
+
+# Enable the embedding of debug symbols in the binary
+# - might slightly increase build speed, no impact on binary size
 DEBUG             = 1
 
 PLAT_C_DIRS =

README.md

@@ -0,0 +1,29 @@
+# GEX Firmware for STM32F072
+
+Copy `build.mk.example` to `build.mk`, configure as desired,
+and build the firmware image with `make build`.
+
+Individual GEX units can be enabled or disabled in this config file, and the target platform is selected here as well.
+
+## Requirements
+
+Listed versions were used during development. Other (particularly newer) versions may work too, but without guarantee. 
+Please submit patches needed to fix incompatibilities, or at least let me know.
+
+- **arm-none-eabi-gcc** (v8.1)
+- **arm-none-eabi-binutils** (v2.30)
+- **arm-none-eabi-newlib** (v3.0)
+- **make** (GNU, v4.2)
+- **tr** (GNU coreutils 8.29 - but any version should work)
+- **dfu-util** (v0.9) for DFU flashing
+- **stlink** (texane, v1.5) for ST-Link flashing
+
+## Make Targets
+
+- **make** - basic build (recommended to use with `-j4` for faster builds)
+- **make flash** - flash using `st-flash`
+- **make dfu** - flash using `dfu-convert` and `dfu-util`
+- **make clean** - clean files generated during build
+
+All make targets depend on all Makefiles, meaning any modification triggers a full (`-B`) 
+rebuild the next time you try to build or flash the firmware.

build.mk

@@ -1,25 +0,0 @@
-
-GEX_PLAT=F072_ZERO
-#GEX_PLAT=F072_HUB
-#GEX_PLAT=F072_DISCOVERY
-
-DISABLE_DEBUG     = 0
-DISABLE_MSC       = 0
-CDC_LOOPBACK_TEST = 0
-
-# Units included in the built image
-GEX_UNITS += 1wire
-GEX_UNITS += adc
-GEX_UNITS += dac
-GEX_UNITS += din
-GEX_UNITS += dout
-GEX_UNITS += fcap
-GEX_UNITS += i2c
-GEX_UNITS += neopixel
-GEX_UNITS += pwmdim
-GEX_UNITS += sipo
-GEX_UNITS += spi
-#GEX_UNITS += template
-#GEX_UNITS += test
-GEX_UNITS += touch
-GEX_UNITS += usart

build.mk.example

@@ -0,0 +1,39 @@
+# GEX platform
+# - alternate configurations defining board layout anb capabilities
+
+GEX_PLAT=F072_ZERO
+#GEX_PLAT=F072_HUB
+#GEX_PLAT=F072_DISCOVERY
+
+# Disable debug UART (saves some Flash and RAM)
+DISABLE_DEBUG     = 0
+
+# Disable USB Mass Storage support 
+# - significant FLASH and RAM savings, but the virtual filesystem will be
+#   accessible only through the communication interface
+DISABLE_MSC       = 0
+
+# Disconnect GEX from the USB library, and connect CDC/ACM Rx directly to Tx
+# - this is used during porting / USB debugging to verify the USB subsystem 
+#   is configured correcctly
+CDC_LOOPBACK_TEST = 0
+
+# Enabled GEX units
+# - comment out units you don't want to include in the firmware image
+# - additional units have minimal impact on performance, but take up space
+#   in the Flash memory; enabling all units at once might not even be possible
+#   due to this limitation
+# - this also lets you switch between alternate implementations
+GEX_UNITS += 1wire
+GEX_UNITS += adc
+GEX_UNITS += dac
+GEX_UNITS += din
+GEX_UNITS += dout
+GEX_UNITS += fcap
+GEX_UNITS += i2c
+GEX_UNITS += neopixel
+GEX_UNITS += pwmdim
+GEX_UNITS += sipo
+GEX_UNITS += spi
+GEX_UNITS += touch
+GEX_UNITS += usart