From 96256ad659adc0536d40891456e7c6499a35bdab Mon Sep 17 00:00:00 2001 From: lenvm Date: Wed, 3 May 2023 00:17:54 +0200 Subject: [PATCH 1/2] add section on firmware installation --- firmware-installation.md | 120 +++++++++++++++++++++++++++++++++++++++ index.md | 3 +- 2 files changed, 122 insertions(+), 1 deletion(-) create mode 100644 firmware-installation.md diff --git a/firmware-installation.md b/firmware-installation.md new file mode 100644 index 0000000..a3b3c3d --- /dev/null +++ b/firmware-installation.md @@ -0,0 +1,120 @@ +# Firmware Installation + +The Black Magic Firmware can be installed on hardware that did not previously contain Black Magic Firmware. We refer to this as a clean install. + +If your board already has the Black Magic Firmware installed, please refer to [Firmware Upgrade](./upgrade.md) to upgrade your Black Magic Probe with the latest firmware. + +To perform a clean install, multiple types of hardware can be used in combination with different software utilities. This section lists the options to perform a clean install by hardware, to enable you to select the right software utility for the hardware you have at hand. The options covered are: +- USB to Serial/UART/TTL converter, i.e. FTDI interface, if the targeted hardware has the built-in ST serial UART bootloader +- ST-Link +- Black Magic Probe + +## USB to serial/UART/TTL converter, i.e. FTDI interface + +```{note} +To use this method, the target hardware must have the ST serial UART bootloader. +``` + +For instance an USB to serial UART converter with [FTDI FT232RL](https://ftdichip.com/products/ft232rl/) can be used. + +Connect the GND, TXD, RXD and 3V3 pins of the converter to the pins of the target hardware. Note that TxD of the converter shall be connected to RxD of the target hardware, and RxD of the converter shall be connected to TxD of the target hardware. + +As flashing utility, use either: +- stm32loader +- stm32flash + +### stm32loader + +Download [stm32loader](https://github.com/jsnyder/stm32loader). + +To flash using `stm32loader` run the command: + +```bash +python ./stm32loader -p /dev/tty.usbserial -e -w -v src/blackmagic.bin +``` + +This will pre-erase flash, write `blackmagic.bin` to the flash on the device using the port `/dev/tty.usbserial`, and then perform a verification after writing is finished. Please udate the port to the actual port of your USB to serial converter. + + + +```{note} +This command has not been validated by the author of this section. +``` + +### stm32flash + +Install [stm32flash](https://sourceforge.net/p/stm32flash/wiki/Home/). + +To flash using `stm32flash` run the command: + +```bash +./stm32flash -w blackmagic.bin -S 0x8000000 -v -g 0x0 /dev/tty.usbserial +``` + + + +```{note} +This command has not been validated by the author of this section. +``` + +## ST-Link + +For instance an original [ST-Link/V2](https://www.st.com/en/development-tools/st-link-v2.html) or an [ST-Link clone](https://stm32-base.org/boards/Debugger-STM32F101C8T6-STLINKV2) can be used. + +Connect the GND, SWDIO, SWCLK and 3V3 pins of the ST-Link to the same pins of the target hardware which shall be flashed with the Black Magic Firmware. + +As flashing utility, use either: +- stlink +- pystlink + +### stlink + +[stlink](https://github.com/stlink-org/stlink) is an open source version of the STMicroelectronics STLINK Tools. + +For a board with flash (rom) of 128 kB, run the command: + +```bash +st-flash erase +st-flash --flash=128k write blackmagic.bin 0x8000000 +``` + +Determine the flash size of the target hardware. The flash size is stored in the linker script (.ld) of the [platform](https://github.com/blackmagic-debug/blackmagic/tree/main/src/platforms) of the target hardware. Adapt the flash size in the command accordingly. + +### pystlink + +[pystlink](https://github.com/pavelrevak/pystlink) is a python utility to interact with an ST-Link. + +For +```bash +pystlink flash:erase:verify:0x8000000:blackmagic.bin +``` + + + +```{note} +This command has not been validated by the author of this section. +This utility does not support ST-Link v1. +``` + +## Black Magic Probe + +If you already have a Black Magic Probe, you can turn another device into a Black Magic Probe using SWD (Serial Wire Debug) or JTAG (Joint Test Action Group). + +To use SWD, connect the GND, SWDIO, SWCLK and 3V3 pins of the Black Magic Probe to the same pins of target hardware and run the following commands: + +``` +arm-none-eabi-gdb blackmagic.bin +(gdb) target extended-remote /dev/ttyACM0 +(gdb) monitor swdp_scan +(gdb) attach 1 +(gdb) load +(gdb) compare-sections +``` + +Please find further details how to use the Black Magic Probe and operating system specific information on the [Getting started](./getting-started.md) and [GDB commands](./usage/gdb-commands.md) sections. diff --git a/index.md b/index.md index 5102d5f..8e2a586 100644 --- a/index.md +++ b/index.md @@ -10,8 +10,9 @@ :caption: Intro hardware -getting-started +firmware-installation upgrade +getting-started ``` ```{toctree} From 5bb0e9d2e7ea0668b460cd916f0b305ada64dced Mon Sep 17 00:00:00 2001 From: lenvm Date: Wed, 3 May 2023 00:20:03 +0200 Subject: [PATCH 2/2] rename upgrade.md to firmware-upgrade.md - update upgrade.md to firmware-upgrade.md to reflect the name of the title of the page in the name of the file --- firmware-installation.md | 2 +- upgrade.md => firmware-upgrade.md | 0 hacking/hacking.md | 2 +- hacking/target-cortex-m.md | 2 +- index.md | 2 +- knowledge/faq.md | 2 +- 6 files changed, 5 insertions(+), 5 deletions(-) rename upgrade.md => firmware-upgrade.md (100%) diff --git a/firmware-installation.md b/firmware-installation.md index a3b3c3d..16c5857 100644 --- a/firmware-installation.md +++ b/firmware-installation.md @@ -2,7 +2,7 @@ The Black Magic Firmware can be installed on hardware that did not previously contain Black Magic Firmware. We refer to this as a clean install. -If your board already has the Black Magic Firmware installed, please refer to [Firmware Upgrade](./upgrade.md) to upgrade your Black Magic Probe with the latest firmware. +If your board already has the Black Magic Firmware installed, please refer to [Firmware Upgrade](./firmware-upgrade.md) to upgrade your Black Magic Probe with the latest firmware. To perform a clean install, multiple types of hardware can be used in combination with different software utilities. This section lists the options to perform a clean install by hardware, to enable you to select the right software utility for the hardware you have at hand. The options covered are: - USB to Serial/UART/TTL converter, i.e. FTDI interface, if the targeted hardware has the built-in ST serial UART bootloader diff --git a/upgrade.md b/firmware-upgrade.md similarity index 100% rename from upgrade.md rename to firmware-upgrade.md diff --git a/hacking/hacking.md b/hacking/hacking.md index cc4acb5..3771787 100644 --- a/hacking/hacking.md +++ b/hacking/hacking.md @@ -94,4 +94,4 @@ Exit the screen session by type crt-a + ctl-\\. ## Updating firmware -Follow instructions in [Firmware Upgrade Section](/upgrade.md). +Follow instructions in [Firmware Upgrade Section](/firmware-upgrade.md). diff --git a/hacking/target-cortex-m.md b/hacking/target-cortex-m.md index 852993c..034b2b3 100644 --- a/hacking/target-cortex-m.md +++ b/hacking/target-cortex-m.md @@ -91,7 +91,7 @@ other than pin 2. If you set one BMP to debug another, then you can load firmware using GDB into the BMP. If you are simply building the firmware and evaluating its function by reading the output from `DEBUG_*` statements then you will need to use -`bmputil` or `dfu-util` to update the firmware. (see [Updating the Firmware](../upgrade.md)). +`bmputil` or `dfu-util` to update the firmware. (see [Updating the Firmware](../firmware-upgrade.md)). ### Debugging newer generations diff --git a/index.md b/index.md index 8e2a586..b977511 100644 --- a/index.md +++ b/index.md @@ -11,7 +11,7 @@ hardware firmware-installation -upgrade +firmware-upgrade getting-started ``` diff --git a/knowledge/faq.md b/knowledge/faq.md index baccd35..d11dfc3 100644 --- a/knowledge/faq.md +++ b/knowledge/faq.md @@ -164,4 +164,4 @@ Because Texas Instruments... but we are working on it. :) If you want to help wi ## How do I upgrade to a more recent version? -Follow the [upgrade](/upgrade.md) instructions. +Follow the [upgrade](/firmware-upgrade.md) instructions.