diff --git a/src/platforms/common/blackpill-f4/README.md b/src/platforms/common/blackpill-f4/README.md index d5f2cd4c97d..eb10f7051d0 100644 --- a/src/platforms/common/blackpill-f4/README.md +++ b/src/platforms/common/blackpill-f4/README.md @@ -7,6 +7,11 @@ This directory contains the common code for the following platforms: - [blackpill-f401ce](./../../blackpill-f401ce/README.md) - [blackpill-f411ce](./../../blackpill-f411ce/README.md) +In the example command lines for building and flashing the firmware to the Blackpill, 'xxxxxx' is used and should be replaced with one of the following: + f401cc + f401ce + f411ce + ## Pinout | Function | Pinout | Alternative pinout 1 | Cluster | @@ -26,39 +31,45 @@ This directory contains the common code for the following platforms: | LED UART | PA4 | PA1 | LED | | User button KEY | PA0 | PA0 | | -## Instructions for Makefile buildsystem and ST MaskROM -### How to Build +## Instructions for build system -In the following commands replace `blackpill-f4x1cx` with the platform you are using, e.g. `blackpill-f401cc`. +### Variant with meson and BMD bootloader enabled (default) -To build the code using the default pinout, run: +0. Clone the repo and libopencm3 submodule, install toolchains, meson, etc. ```sh +git clone https://github.com/blackmagic-debug/blackmagic.git cd blackmagic -make clean -make PROBE_HOST=blackpill-f4x1cx +git submodule update --init ``` -or, to use alternative pinout 1, run: +1. Create a build configuration for specific platform (WeActStudio F401CC, F401CE, or F411CE) with specific options (enable BMD bootloader flags and offsets -- this is the default) ```sh -cd blackmagic -make clean -make PROBE_HOST=blackpill-f4x1cx ALTERNATIVE_PINOUT=1 +meson setup build_blackpill_xxxxxx --cross-file=cross-file/blackpill-xxxxxx.ini -Dbmd_bootloader=true ``` -or, if you are using a PCB (printed circuit board) as a shield for your Black Pill F4, run: +2. Compile the firmware and bootloader ```sh -cd blackmagic -make clean -make PROBE_HOST=blackpill-f4x1cx SHIELD=1 +ninja -C build_blackpill_xxxxxx blackmagic_blackpill_xxxxxx_firmware.bin +ninja -C build_blackpill_xxxxxx boot-bin ``` ### Firmware upgrade with dfu-util - Install [dfu-util](https://dfu-util.sourceforge.net). - Connect the Black Pill to the computer via USB. Make sure it is a data cable, not a charging cable. +- Force the F4 into system bootloader mode: + - Push NRST and BOOT0 + - Wait a moment + - Release NRST + - Wait a moment + - Release BOOT0 +- Upload the bootloader +```sh +dfu-util -d 0483:df11 --alt 0 -s 0x08000000:leave -D build_blackpill_xxxxxx/blackmagic_blackpill_xxxxxx_bootloader.bin +``` - Force the F4 into system bootloader mode: - Push NRST and BOOT0 - Wait a moment @@ -67,8 +78,9 @@ make PROBE_HOST=blackpill-f4x1cx SHIELD=1 - Release BOOT0 - Upload the firmware: ``` -./dfu-util -a 0 --dfuse-address 0x08000000:leave -R -D blackmagic.bin +./dfu-util -d 0483:df11 --alt 0 -s 0x08000000:leave -D build_blackpill_xxxxxx/blackmagic_blackpill_xxxxxx_firmware.bin ``` + - Exit dfu mode: press and release nRST. The newly flashed Black Magic Probe should boot and enumerate. For other firmware upgrade instructions see the [Firmware Upgrade](https://black-magic.org/upgrade.html) section. @@ -96,69 +108,8 @@ TraceSWO Async capture runs via USART1 DMA on APB2 (Pclk = 96 MHz) at 1465..6000 SPI ports are set to Pclk/8 each (use with `bmpflash`). As SPI1 pins may conflict with certain functions, and platform code does not bother restoring them, please soft-reset the probe when done with SPI operations. -## Instructions for Meson buildsystem - -### Variant with meson and BMD bootloader enabled (default) - -0. Clone the repo and libopencm3 submodule, install toolchains, meson, etc. - -```sh -git clone https://github.com/blackmagic-debug/blackmagic.git -cd blackmagic -git submodule update --init -``` - -1. Create a build configuration for specific platform (WeActStudio MiniSTM32F401CC) with specific options (enable BMD bootloader flags and offsets -- this is the default) - -```sh -meson setup build --cross-file=cross-file/blackpill-f401cc.ini -Dbmd_bootloader=true -``` - -2. Compile the firmware and bootloader - -```sh -ninja -C build blackmagic_blackpill_f401cc_firmware.bin -ninja -C build boot-bin -``` - -3. Flash the "BMD bootloader" to blank board in ST MaskROM (BOOT0) mode (then it switches to this bootloader): - -```sh -dfu-util -d 0483:df11 -S 375F334C3032 --alt 0 -s 0x08000000:leave -D build/blackmagic_blackpill_f401cc_bootloader.bin -``` - -4. Flash the [Black Magic Debug Probe compatible platform] firmware at offset to board which is running BMD bootloader (then it reboots and jumps to firmware): - -```sh -dfu-util -d 1d50:6018 -S 375F334C3032 --alt 0 -s 0x08004000:leave -D build/blackmagic_blackpill_f401cc_firmware.bin -``` - -5. Verify the board enumerates, jumps between bootloader and firmware (hold PA0 onboard pushbutton active-low on reset to stay in bootloader) by `dfu-util --detach` and `dfu-util -s :leave`, verify the firmware works with GDB and BMDA HL-remote and bmpflash SPI. - -### Variant with meson and ST MaskROM for bootloader -1. Create a build configuration for specific platform (WeActStudio MiniSTM32F401CC) with specific options (disable BMD bootloader flags and offsets, use ST MaskROM) - -```sh -meson setup build --cross-file=cross-file/blackpill-f401cc.ini -Dbmd_bootloader=false -``` - -2. Compile the firmware - -```sh -ninja -C build blackmagic_blackpill_f401cc_firmware.bin -``` - -3. Flash the [Black Magic Debug Probe compatible platform] firmware to blank board in ST MaskROM (BOOT0) mode (then it reboots and jumps to firmware), this will take a while: - -```sh -dfu-util -d 0483:df11 -S 375F334C3032 --alt 0 -s 0x08000000:leave -D build/blackmagic_blackpill_f401cc_firmware.bin -``` - -4. Verify the board enumerates, jumps between MaskROM and firmware (hold PA0 onboard pushbutton active-low on reset to make it jump to MaskROM, or hold BOOT0 to enter MaskROM directly) by `dfu-util --detach` and `dfu-util -s :leave`, verify the firmware works with GDB and BMDA HL-remote and bmpflash SPI. - ## More details -* The Makefiles are the historical build system, and it also supports both variants: pass `BMD_BOOTLOADER=1` makeflag to switch into two-binaries configuration (was `BMP_BOOTLOADER=1` for a year between PR1508 and PR1843). * ST MaskROM is the read-only System Memory bootloader which starts up per BOOT0-triggered SYSCFG mem-remap. It talks USART AN2606 so you can use stm32flash etc. When USBOTG_FS is plugged, it spins up HSE 25 MHz and measures its frequency relative to HSI (RC 8 MHz with worse tolerance) and sometimes can misdetect it as 24 or 26 MHz then configure a wrong input PLL divider, resulting in broken USB DFU. New 8 MHz HSE boards should not be affected by this, but also they are not yet supported (needs a different pll config). * BMD bootloader is the port of BMP bootloader with dfu_f1.c internal flash driver swapped to dfu_f4.c (and different serialno algorithm etc.) which a) has a fixed per-board PLL config, no autodetection;