Skip to content

Commit

Permalink
fix/blackpill/readme: Update to reflect current firmware
Browse files Browse the repository at this point in the history
  • Loading branch information
@sidprice
sidprice committed Nov 4, 2024
1 parent 92c13ee commit 5b33720
Showing 1 changed file with 27 additions and 76 deletions.
103 changes: 27 additions & 76 deletions src/platforms/common/blackpill-f4/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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;
Expand Down

0 comments on commit 5b33720

Please sign in to comment.