Detail HW support, flashing and bugs

Board-STM32F429.md

@@ -2,16 +2,89 @@ Cortex M4 STM32F429ZI
 * on STM site - http://www.st.com/web/catalog/tools/FM116/SC959/SS1532/LN1199/PF259090
 * [datasheet](http://www.st.com/st-web-ui/static/active/en/resource/technical/document/data_brief/DM00094498.pdf)
 
-###Features###
-* STM32F429ZI 168MHz (144pin)
-* 2MB flashROM, 256KB RAM
-* 64Mbits SDRAM
-* 3axis gyro L3GD20
+### Features ###
+* STM32F429ZI 168MHz (LQFP-144)
+* 2MiB flash, 256KiB RAM
+* 8MiB (64Mbit) SDRAM
+* 3-axis gyro (L3GD20)
 * 2.4 inch TFT display
-* 6 LEDs
+* 2 LEDs
 * USB OTG
 
-###Status###
-No work has yet been done on porting to this chip
+### Status ###
 
-Unlike the STM32F4 Discovery board, this board is not recognized under Linux via the microUSB port. To power the board one has to use the miniUSB connector in addition or bridge 5V with PB13. However, the schematics looks very much like the STM32F4 Discovery board and porting should be easily done after the above problem is solved.
+Not officially supported (no downloads provided, no customised documentation), but the stmhal variant supports the basic board well.
+
+Unlike the STM32F4 Discovery board, this board is designed to be powered and flashed via the mini-USB connector; to run on the micro-USB connector alone you have to bridge 5V with PB13.
+
+MicroPython does not use the 8MiB SDRAM on the board (it won't appear in `micropython.mem_info()`).  Reports welcomed of whether it's enabled at all and of what tweaks are required to make MicroPython use it.
+
+Similarly, bare MicroPython does not initialise any of the other peripherals and they're connected in ways that make them easy to isolate or ignore, so almost all the pins they use should be available as GPIOs.  There may well be drivers for them in other STM32 eval board variants.
+
+The chip's 256KiB RAM is made up of 192KiB contiguous general-purpose SRAM and a separate 64KiB core-coupled memory. MicroPython reserves the 64KiB for caching flash writes.  MicroPython uses 80KiB for the stack, 112KiB for the statics/heap.  That stack/heap split results in quite a generous stack which you're unlikely to use unless you use deeply nested calls or heavy recursion, but is easily tuned by modifying `_heap_end` in the [linker script](https://github.com/micropython/micropython/blob/761e4c7f/stmhal/boards/stm32f429.ld).
+
+The chip's 2MiB flash is made up of various pages of different sizes, split across two non-contiguous 1MiB blocks, and only the first 64KiB of any page can be used.  By default that leaves 112KiB available before filesystem overheads, ~95KiB after overheads.  It's pretty simple to [increase this](https://forum.micropython.org/viewtopic.php?t=777#p4491) to 304KiB (before overheads) by enabling the non-contiguous flash features in `storage.c`, rebuilding, reflashing, then carrying out a [factory reset](http://docs.micropython.org/en/v1.9/pyboard/pyboard/tutorial/reset.html) to enlarge the filesystem.  It should be possible to increase this by another 64KiB by using the first half of sector 5; haven't managed to get this working like it should just yet though.
+
+On the mini-USB, the STLinkV2 offers a virtual mass storage device plus a virtual serial port that's connected to the target's USART1.  On the micro-USB, MicroPython adds a its own mass storage device and a .second virtual serial port which is emulated and connected to the REPL.
+
+### Building ###
+
+    cd stmhal
+    make BOARD=STM32F429DISC
+
+Do not confuse `STM32F4DISC` with the similarly named `STM32F429DISC`.  Images for the F4DISC will not boot on the F429.
+
+### Flashing ###
+
+Several mechanisms are available for getting MicroPython onto the board initially.
+
+#### stlink ####
+
+The easiest mechanism is via the onboard STLinkV2.  On Linux, install [texane's stlink](https://github.com/texane/stlink/) and use:
+
+    make BOARD=STM32F429DISC deploy-stlink
+
+#### Drag & drop ####
+
+The STLinkV2 supports writing flat binaries via a virtual mass storage device, but the Makefile produces DFUs, ELFs and split binaries by default.  On Linux, once you've built an image, generate a flat binary using:
+
+    arm-none-eabi-objcopy -O binary build-STM32F429DISC/firmware.elf build-STM32F429DISC/firmware.bin
+
+then copy `firmware.bin` into the virtual drive.
+
+This should probably be added as a deploy target to the port's Makefile.
+
+#### Serial ####
+
+Flashing over serial using the ROM serial bootloader is also possible using `stm32loader`.  On Linux, probably any variant will do, but [jsnyder's variant](https://github.com/jsnyder/stm32loader) is known to work, at least on the USART1 PA9/PA10 pins:
+
+    # These values come from the stmhal Makefile.
+    # Vector table (tiny, probably unvarying)
+    FLASH_ADDR=0x08000000
+    # Main body of uPy (bigger, and could embed frozen bytecode/source)
+    TEXT_ADDR=0x08020000
+ 
+    # Full erase.  Typically ~20s.
+    stm32loader.py -b 460800 -p /dev/ttyACM0 -e
+
+    # Vector table flash.  Typically ~5s.  Quite noisy!
+    # I think I found I had to reset between invocations of stm32loader.
+    # You can do that with the button, or via "st-flash reset" if you have texane's st-util
+    stm32loader.py -b 460800 -p /dev/ttyACM0 -a $FLASH_ADDR -wv ./build-STM32F429DISC/firmware0.bin
+ 
+    # Main body flash.  Typically ~70s.  Again, may need a reset first.
+    stm32loader.py -b 460800 -p /dev/ttyACM0 -a $TEXT_ADDR  -wv ./build-STM32F429DISC/firmware1.bin
+
+This should probably be added as a deploy target to the port's Makefile.
+
+#### DFU ####
+
+DFU is not easily available on this board because it's only available on one USB peripheral of the STM32 (the `OTG_FS` block), and that peripheral is not brought out to a connector, only to pins.  The `OTG_HS` block is the one brought out to the micro-USB connector, but confusingly it's marked as "OTG_FS" in some Discovery schematics/labels because it's used in full-speed mode.
+
+People have reported [successful DFU flashing](https://forum.micropython.org/viewtopic.php?t=777) using [butchered USB cables](https://forum.micropython.org/download/file.php?id=95&sid=8d5e16b1ed22b6ba278e3ae038969aa9) with PA11 = D-, PA12 = D+.
+
+### Bugs ###
+
+If the REPL is duplicated on a UART, Ctrl-C may not work on that UART, per [issue 1568](https://github.com/micropython/micropython/issues/1568).
+
+Relative imports like `from . import submodule` seem to cause crashes.  Not yet fully investigated/reported as an issue.