From f47d7a307b4f17d7ee0f2e4c25c805b8fe8bc82f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= <ondra@ondrovo.com>
Date: Sat, 7 Jul 2018 20:31:23 +0200
Subject: [PATCH] added a README and moved build.mk to build.mk.example

---
 .gitignore       |  3 +++
 Makefile         |  3 +++
 README.md        | 29 +++++++++++++++++++++++++++++
 build.mk         | 25 -------------------------
 build.mk.example | 39 +++++++++++++++++++++++++++++++++++++++
 5 files changed, 74 insertions(+), 25 deletions(-)
 create mode 100644 README.md
 delete mode 100644 build.mk
 create mode 100644 build.mk.example

diff --git a/.gitignore b/.gitignore
index 6138ab5..6b16a98 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
+# The customized build.mk file
+build.mk
+
 # Prerequisites
 *.d
 *.tmp
diff --git a/Makefile b/Makefile
index e963619..ce5ae1b 100644
--- a/Makefile
+++ b/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 =
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c373c57
--- /dev/null
+++ b/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.
diff --git a/build.mk b/build.mk
deleted file mode 100644
index 3aa26a2..0000000
--- a/build.mk
+++ /dev/null
@@ -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
diff --git a/build.mk.example b/build.mk.example
new file mode 100644
index 0000000..1772dfa
--- /dev/null
+++ b/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