From e6282ce9a501c0f5899fe1d971d3a6d769d80a1a Mon Sep 17 00:00:00 2001
From: R <rqou@berkeley.edu>
Date: Tue, 23 Apr 2024 16:37:23 +0100
Subject: [PATCH] more docs for examples

---
 README.md                       | 12 ++++++++++++
 example-payload-flash/startup.S |  1 +
 example-payload-ram/Makefile    |  3 +++
 example-payload-ram/startup.S   |  1 +
 4 files changed, 17 insertions(+)

diff --git a/README.md b/README.md
index fa39b37..f6ecdbb 100644
--- a/README.md
+++ b/README.md
@@ -19,3 +19,15 @@
     - The entire size of the SRAM can be used, as USBD contains its own buffer memory independent of the main SRAM
 - Auto-reboot on complete download, _but_ **only** works if the download is sufficiently small. Larger downloads will of course still flash, but they will not trigger auto-reboot and a manual reboot will be required.
 - Lots of nasty code golfing tricks -- see comments in [bootloader.c](https://github.com/ArcaneNibble/wch-uf2/blob/main/bootloader.c)
+
+## Examples
+
+There are two included examples which build "blinky" applications (that blink pin PA0). The "RAM" example blinks at a different speed than the "flash" example so that you can tell that you've successfully loaded it.
+
+The examples do *not* use a verbatim copy of the vendor startup bits -- some elements which we (IANAL) consider to be purely functional have been borrowed, but other things have been changed substantially:
+- Vector table isn't hardcoded in the startup assembly file (as it doesn't need to be located at the beginning of flash, this isn't necessary)
+- Preinit, init, and fini functions (`.init_array`, e.g. `__attribute__((constructor))` and (untested) C++ static constructors) are properly called
+    - Legacy `.init` is *not* called
+- Various initialization for CSRs, interrupt handling, etc. are not hardcoded in the startup assembly code. The intention is that this can be done with `__attribute__((constructor))`.
+
+The example Makefiles contain a horrible hardcoded path to `uf2conv.py`. This needs to be fixed before they will work on your computer.
diff --git a/example-payload-flash/startup.S b/example-payload-flash/startup.S
index ebc1776..a563fb6 100644
--- a/example-payload-flash/startup.S
+++ b/example-payload-flash/startup.S
@@ -34,6 +34,7 @@ _start:
     bltu a0, a1, 1b
 2:
 
+    // NOTE: Vendor startup code does *NOT* call these functions
     // Call preinit array functions
     la s0, __preinit_array_start
     la s1, __preinit_array_end
diff --git a/example-payload-ram/Makefile b/example-payload-ram/Makefile
index 3637010..c2de2f2 100644
--- a/example-payload-ram/Makefile
+++ b/example-payload-ram/Makefile
@@ -14,7 +14,10 @@ main.elf: startup.o main.o
 
 %.uf2: %.bin
 	~/code/uf2/utils/uf2conv.py -c -f 0x699b62ec -b 0x20000000 -o $@.temp $<
+# This is a *terrible* hack
+# (there isn't a flag for setting the "not main flash" bit)
 	xxd $@.temp | sed 's/5546 320a 5751 5d9e 0020 0000/5546 320a 5751 5d9e 0120 0000/g' | xxd -r >$@
+	rm $@.temp
 
 %.bin: %.elf
 	$(OBJCOPY) -O binary $< $@
diff --git a/example-payload-ram/startup.S b/example-payload-ram/startup.S
index 8f75cc1..814eba4 100644
--- a/example-payload-ram/startup.S
+++ b/example-payload-ram/startup.S
@@ -22,6 +22,7 @@ _start:
     bltu a0, a1, 1b
 2:
 
+    // NOTE: Vendor startup code does *NOT* call these functions
     // Call preinit array functions
     la s0, __preinit_array_start
     la s1, __preinit_array_end