platforms: Cleaned up and fixed many markdown lint errors, improving the formatting of many of the platform README's

This commit is contained in:
dragonmux 2022-06-15 21:52:45 -04:00 committed by Piotr Esden-Tempski
parent 0dae6a4019
commit 12fefa73c9
8 changed files with 142 additions and 133 deletions

View File

@ -1,5 +1,6 @@
Connections
===========
# 96b Carbon
## Connections
The pinout for the programmer is concentrated within a single part of
the Low Speed connector. The target control pins at the even pins 2
@ -9,8 +10,7 @@ The pinout for the programmer allows a Carbon to program another Carbon
(either the STM32 or the nRF51) with adjacent pins from LS-06 to LS-12.
The order matches that of the SWD pins for easy hook up.
JTAG/SWD
--------
### JTAG/SWD
* LS-02 (PB12): TDO/TRACESWO
* LS-04 (PB15): TDI
@ -21,28 +21,24 @@ JTAG/SWD
* LS-14 (PC3) : TRST (optional Test Reset)
* LS-16 (PC5) : nRST (nRST / System Reset)
LEDs
----
### LEDs
* USR1 (green): Debug activity indicator
* USR2 (green): UART activity indicator
* BT (blue) : Error indicator
* USR1 (green): Debug activity indicator
* USR2 (green): UART activity indicator
* BT (blue) : Error indicator
UART
----
### UART
* LS-03 (PA2): UART TX
* LS-05 (PA3): UART RX
* LS-03 (PA2): UART TX
* LS-05 (PA3): UART RX
How to Build
============
## How to Build
cd blackmagic
make clean
make PROBE_HOST=96b_carbon
Flashing using dfu-util
=======================
## Flashing using dfu-util
Connect to the USB OTG socket on the Carbon and force the device into
system bootloader mode by holding down the BOOT0 switch whilst pressing
@ -50,8 +46,7 @@ and releasing the RST switch. To program the device try:
sudo dfu-util -d [0483:df11] -a 0 -D src/blackmagic.bin -s 0x08000000
Self-programming
================
## Self-programming
A Carbon is capable of self-programming its own nRF51 by connecting two
jumper wires from LS-06 to BLE_SWD-4 (DIO) and LS-08 to BLE_SWD-3 (CLK).

View File

@ -4,7 +4,7 @@ Allows the use of BlackPillV2 as a Black Magic Probe
https://github.com/WeActTC/MiniSTM32F4x1
## Connections:
## Connections
* JTAG/SWD
* PA1: TDI
@ -15,39 +15,37 @@ https://github.com/WeActTC/MiniSTM32F4x1
* PB4: nRST
* USB USART
* PB6: USART1 TX (usbuart_xxx)
* PB7: USART1 RX (usbuart_xxx)
* PB6: USART1 TX (usbuart_xxx)
* PB7: USART1 RX (usbuart_xxx)
* +3V3.
* PB8 - turn on IRLML5103 transistor
* PB8 - turn on IRLML5103 transistor
How to Build
========================================
```
## How to Build
```sh
cd blackmagic
make clean
make PROBE_HOST=blackpill
```
How to Flash with dfu
========================================
## How to Flash with dfu
* After build:
* 1) `apt install dfu-util`
* 2) Force the F4 into system bootloader mode by jumpering "BOOT0" to "3V3" and "PB2/BOOT1" to "GND" and reset (RESET button). System bootloader should appear.
* 3) `dfu-util -a 0 --dfuse-address 0x08000000 -D blackmagic.bin`
* 1) `apt install dfu-util`
* 2) Force the F4 into system bootloader mode by jumpering "BOOT0" to "3V3" and "PB2/BOOT1" to "GND" and reset (RESET button). System bootloader should appear.
* 3) `dfu-util -a 0 --dfuse-address 0x08000000 -D blackmagic.bin`
To exit from dfu mode press a "key" and "reset", release reset. BMP firmware should appear
10 pin male from pins
========================================
## 10 pin male from pins
| PB3/TDO | PB7/RX | PB6/TX | X | PA1/TDI |
| -------- | ----------- | ---------- | ---------- | ------- |
| PB4/SRST | +3V3/PB8 SW | PA13/SWDIO | PA14/SWCLK | GND |
| PB4/nRST | +3V3/PB8 SW | PA13/SWDIO | PA14/SWCLK | GND |
## SWD/JTAG frequency setting
SWJ frequency setting
====================================
https://github.com/blackmagic-debug/blackmagic/pull/783#issue-529197718
`mon freq 900k` helps at most

View File

@ -1,10 +1,11 @@
System vs BMP Bootloader
========================
# STM32F072
## System vs BMP Bootloader
For the BMP bootloader, flashing was not reliable. So we use the system
bootloder unconditional.
Connections:
====================
## Connections
* PA0: User button to force system bootloader entry with reset
* PA2/PA3 eventual connected to the STLINK/ STM32F103C8

View File

@ -2,7 +2,7 @@
Allows the use of the STM32F407 Discovery board main cpu as a Black Magic Probe. Historically it was used to program the on board built in debugger before ST-Link bootloader use was possible.
## Connections:
## Connections
* PC2: TDI
* PC4: TMS/SWDIO
@ -11,20 +11,25 @@ Allows the use of the STM32F407 Discovery board main cpu as a Black Magic Probe.
* PC1: TRST
* PC8: nRST
How to Flash with dfu
## How to Flash with DFU
To exit from dfu mode press a "key" and "reset", release reset. BMP firmware should appear
After build:
1) `apt install dfu-util`
2) Force the F4 into system bootloader mode by jumpering "BOOT0" to "3V3" and "PB2/BOOT1" to
"GND" and reset (RESET button). System bootloader should appear.
3) `dfu-util -a 0 --dfuse-address 0x08000000 -D blackmagic.bin`
10 pin male from pins
========================================
To exit from DFU mode press a "key" and "reset", release reset. BMP firmware should appear
## 10 pin male from pins
| PB3/TDO | PB7/RX | PB6/TX | X | PA1/TDI |
| -------- | ----------- | ---------- | ---------- | ------- |
| PB4/SRST | +3V3/PB8 SW | PA13/SWDIO | PA14/SWCLK | GND |
| PB4/nRST | +3V3/PB8 SW | PA13/SWDIO | PA14/SWCLK | GND |
## SWD/JTAG frequency setting
SWJ frequency setting
====================================
https://github.com/blackmagic-debug/blackmagic/pull/783#issue-529197718
`mon freq 900k` helps at most

View File

@ -1,5 +1,9 @@
Hydrabus
========
Connections
====================
-----------
* PA0: User button to force system bootloader entry with reset (enter USB DFU)
* JTAG/SWD
@ -13,21 +17,22 @@ Connections
* Green Led(ULED/PA4): Indicator that system bootloader is entered via BMP
* USB USART
* PA9: USART1 TX (usbuart_xxx)
* PA10: USART1 RX (usbuart_xxx)
* PA9: USART1 TX (usbuart_xxx)
* PA10: USART1 RX (usbuart_xxx)
How to Build
============
```
------------
```sh
cd blackmagic
make clean
make PROBE_HOST=hydrabus
```
How to Flash the firmware with Windows
========================================
* After build:
* 1) Download files from https://github.com/hydrabus/hydrafw/tree/master/utils/windows_dfu_util
* 2) Force the F4 into system bootloader mode by jumpering "BOOT0" to "3V3" and "PB2/BOOT1" to "GND" and reset (RESET button). System bootloader should appear.
* 3) Run the command `DfuSeCommand.exe -c --de 0 -d --fn .\src\blackmagic.dfu`
--------------------------------------
* After build:
* 1) Download files from https://github.com/hydrabus/hydrafw/tree/master/utils/windows_dfu_util
* 2) Force the F4 into system bootloader mode by jumpering "BOOT0" to "3V3" and "PB2/BOOT1" to "GND" and reset (RESET button). System bootloader should appear.
* 3) Run the command `DfuSeCommand.exe -c --de 0 -d --fn .\src\blackmagic.dfu`

View File

@ -1,66 +1,68 @@
# Blackmagic for STLINK Adapters
# Blackmagic for ST-Link Adapters
STLINK-V3, ST-LINK/V2-1 and /V2 with original, recent ST firmware can can use the hosted branch, running the GDB server on PC.
ST-Link v3, ST-Link v2-1 and v2 with original, recent ST firmware can can use the hosted branch, running the GDB server on PC.
Running the BMP firmware on ST-LINK/V2 and ST-LINK/V2-1 provides:
- built-in gdb server on the dongle
- VCP on ST-LINK/V2. Access to VCP lines needs additional wires to the STM32F103C8!
- VCP on ST-LINK/V2 clones ([Baite](https://www.mikrocontroller.net/attachment/356780/st-linkV2-mini_LRG.jpg)), accessible on the bare PCB.
- no mass storage device (MSD). A MSD may collide with company policies.
Running the BMP firmware on ST-Link v2 and ST-Link v2-1 provides:
For all commands below, unplug all other BMP/ST-LINK beside the target(*1)
* built-in gdb server on the dongle
* VCP on ST-Link v2. Access to VCP lines needs additional wires to the STM32F103C8!
* VCP on ST-Link v2 clones ([Baite](https://www.mikrocontroller.net/attachment/356780/st-linkV2-mini_LRG.jpg)), accessible on the bare PCB.
* no mass storage device (MSD). A MSD may collide with company policies.
## Upload BMP Firmware:
For all commands below, unplug all other BMP/ST-Link beside the target(*1)
- Keep the original ST Bootloader.
## Upload BMP Firmware
- Compile firmware with `make PROBE_HOST=stlink ST_BOOTLOADER=1`
* Keep the original ST Bootloader.
* Compile firmware with `make PROBE_HOST=stlink ST_BOOTLOADER=1`
* Upload firmware with stlink-tool from [stlink-tool](https://github.com/UweBonnes/stlink-tool/tree/stlinkv21)(*3).
* For ST-Link v2, as on older disco boards, un- and replug USB to enter the bootloader.
* Upload BMP firmware with `stlink-tool blackmagic.bin`
* For ST-Link v2, after each stlink replug, call either `blackmacic -t` or `stlink-tool` without arguments or on Linux use some udev rule like the one shown below to enter the BMP firmware
- Upload firmware with stlink-tool from [stlink-tool](https://github.com/UweBonnes/stlink-tool/tree/stlinkv21)(*3).
```sh
> cat >/etc/udev/rules.d/98-stlink.rules <<EOF
SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", ACTION=="add", RUN+="<path-to>/stlink-tool"
EOF
```
- For ST-LINK/V2, as on older disco boards, un- and replug USB to enter the bootloader.
## Reverting to original ST Firmware with running BMP firmware
- Upload BMP firmware with `stlink-tool blackmagic.bin`
* Get ST-Link upgrade [firmware](https://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/stsw-link007.html) and unzip. Change to "stsw-link007/AllPlatforms/" in the unzipped directory.
* To enter Bootloader again use `dfu-util -e`, or with ST-Link v2 un- and replug.
* For ST-Link v2(Standalone) run `java -jar STLinkUpgrade.jar -jtag_swim -force_prog`
* For ST-Link v2(embedded) run `java -jar STLinkUpgrade.jar -jtag -force_prog`
* For ST-Link v2-1 run `java -jar STLinkUpgrade.jar -msvcp -force_prog`
* For ST-Link v3 run `java -jar STLinkUpgrade.jar -d8_d32_msc_br -force_prog` (*2)
- For ST-LINK/V2, after each stlink replug, call either `blackmacic -t` or `stlink-tool` without arguments or on Linux use some udev rule like
(*1) Command arguments are available to specify some specific of several devices. Look at the help for blackmagic, stlink-tool and dfu-util if really needed. For STLinkUpgrade.jar, no documentation is known, but `strings ./st/stlinkupgrade/app/a.class` may give a clue.
`> cat /etc/udev/rules.d/98-stlink.rules`
(*2) Loading firmware V37 and higher to ST-Link v3 with original bootloader will inhibit further debugging the F723 on the ST-Link itself. There are patched bootloaders out there that do not set RDP2.
`SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", ACTION=="add", RUN+="<path-to>/stlink-tool"`
to enter the BMP firmware
## Reverting to original ST Firmware with running BMP firmware:
- Get STLINK upgrade [firmware](https://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/stsw-link007.html) and unzip. Change to "stsw-link007/AllPlatforms/" in the unzipped directory.
- To enter Bootloader again use `dfu-util -e`, or with ST-LINK/V2 un- and replug.
- For ST-LINK/V2(Standalone) run `java -jar STLinkUpgrade.jar -jtag_swim -force_prog`
- For ST-LINK/V2(embedded) run `java -jar STLinkUpgrade.jar -jtag -force_prog`
- For ST-LINK/V21 run `java -jar STLinkUpgrade.jar -msvcp -force_prog`
- For STLINK-V3 run `java -jar STLinkUpgrade.jar -d8_d32_msc_br -force_prog` (*2)
<br> (*1) Command arguments are available to specify some specific of several devices. Look at the help for blackmagic, stlink-tool and dfu-util if really needed. For STLinkUpgrade.jar, no documentation is known, but `strings ./st/stlinkupgrade/app/a.class` may give a clue.<
<br> (*2) Loading firmware V37 and higher to STLINK-V3 with original bootloader will inhibit further debugging the F723 on the ST-LINK itself. There are patched bootloaders out there that do not set RDP2.
<br> (*3) Pull request to original author pending.
(*3) Pull request to original author pending.
## Versions
### [Standalone ST-LINK/V2](https://www.st.com/content/st_com/en/products/development-tools/hardware-development-tools/development-tool-hardware-for-mcus/debug-hardware-for-mcus/debug-hardware-for-stm32-mcus/st-link-v2.html)
### [Standalone ST-Link v2](https://www.st.com/content/st_com/en/products/development-tools/hardware-development-tools/development-tool-hardware-for-mcus/debug-hardware-for-mcus/debug-hardware-for-stm32-mcus/st-link-v2.html)
Accessible connectors for JTAG/SWD (20-pin) and SWIM.
ST-LINK/V2/ISOL).
### ST-LINK/V2 clones aka "baite"
ST-Link v2/ISOL).
### ST-Link v2 clones aka "baite"
JTAG/SWD/SWIM are on a 10-pin connector. CPU SWD pins are accessible on the
board.
### SWIM-only ST-LINK adapters on STM8 Discovery boards
### SWIM-only ST-Link adapters on STM8 Discovery boards
JTAG and target SWIM pins are accessible on connector (footprints). They are handled in the swlink platform.
### SWIM-only ST-LINK adapters on STM8 Nucleo-Stm8 boards
### SWIM-only ST-Link adapters on STM8 Nucleo-Stm8 boards
As only a SWIM connector is accessible, they are not usefull as BMP target.
### [SWD only ST-LINK adapter](https://www.st.com/content/ccc/resource/technical/document/technical_note/group0/30/c8/1d/0f/15/62/46/ef/DM00290229/files/DM00290229.pdf/jcr:content/translations/en.DM00290229.pdf) (Stm32 Nucleo Boards, recent Discovery boards)
### [SWD only ST-Link adapter](https://www.st.com/content/ccc/resource/technical/document/technical_note/group0/30/c8/1d/0f/15/62/46/ef/DM00290229/files/DM00290229.pdf/jcr:content/translations/en.DM00290229.pdf) (Stm32 Nucleo Boards, recent Discovery boards)
SWD, SWO and Reset are accessible on a 6-pin connector row.
Jumper allow to route SWD to on-board target or off-board.
Newer variants have UART TX/RX accessible on a connector
@ -68,41 +70,41 @@ As only a SWIM connector is accessible, they are not usefull as BMP target.
Newer variants have transistor for USB reenumeration
Newer variants may switch onboard target power.
Newer Variants may have level shifters for some signals to onboard target.
#### ST-LINK/V1
CDCACM USART pins are not accessible. MCO output is used for LED. Use the swlink platform!
#### ST-LINK/V2 and ST-LINK/V2-A
CDCACM USART pins are not accessible. MCO is connected to on board target.
#### ST-LINK/V2-1 and ST-LINK/V2-B
#### [STLINK-V3SET](https://www.st.com/content/st_com/en/products/development-tools/hardware-development-tools/development-tool-hardware-for-mcus/debug-hardware-for-mcus/debug-hardware-for-stm32-mcus/stlink-v3set.html)
#### ST-Link v1
CDC ACM USART pins are not accessible. MCO output is used for LED. Use the swlink platform!
#### ST-Link v2 and ST-Link v2-A
CDC ACM USART pins are not accessible. MCO is connected to on board target.
#### ST-Link v2-1 and ST-Link v2-B
#### [ST-Link v3SET](https://www.st.com/content/st_com/en/products/development-tools/hardware-development-tools/development-tool-hardware-for-mcus/debug-hardware-for-mcus/debug-hardware-for-stm32-mcus/stlink-v3set.html)
## Wiring on Discovery and Nucleo Boards
If there is a 6-pin connector, connect an external target after removing
the 2 jumper shortening the 4-pin connector like this:
1: VCC sense, used only for measurement
2: SWCLK
3: GND
4: SWDIO
5: nSRST (pulled high by on board target. Will reset with on board target
unpowered.
6: SWO
1. VCC sense, used only for measurement
2. SWCLK
3. GND
4. SWDIO
5. nRST (pulled high by on board target. Will reset with on board target unpowered.
6. SWO
## BMP version detection and handling
All ST-LINK variants
PC13/14 open -> Standalone ST-LINK/V2 or baite, some STM32 Disco w/o accessible
All ST-Link variants:
* PC13/14 open -> Standalone ST-Link v2 or baite, some STM32 Disco w/o accessible
UART RX/TX
* PC13 low -> SWIM internal connection
* PC13/PC14 both low -> ST-Link v2 on some F4_Diso boards.
PC13 low -> SWIM internal connection
## ST-Link v2.1 force Bootloader entry
PC13/PC14 both low -> ST-LINK/V2 on some F4_Diso boards.
## ST-LINK V2.1 force Bootloader entry
On ST-LINK V2/2-1 boards with the original bootloader, you can force
On ST-Link v2/2-1 boards with the original bootloader, you can force
bootloader entry with asserting [NRST](https://www.carminenoviello.com/2016/02/26/restore-st-link-interface-bad-update-2-26-15-firmware/) of the STM32F103CB of the USB powered board. Serveral attempts may be needed.

View File

@ -12,6 +12,6 @@ RESET(Target) T_JRST(PB1) NRST (PB0)
On the NucleoXXXP boards, e.g. NUCLEO-L4R5ZI (144 pin) or
NUCLEO-L452RE-P (64 pins), by default nRst is not connected. To reach the
target nRST pin with the "mon connect_srst enable" option, the right NRST
target nRST pin with the "mon connect_reset enable" option, the right NRST
jumper must be placed. On Nucleo144-P boards it is JP3, on NUCLEO64-P
boards it is JP4.

View File

@ -1,6 +1,6 @@
# Blackmagic for STM8S Discovery and STM32F103 Minimum System Development Board
## External connections:
## External connections
| Function | PIN | STM8S-DISCO | BLUEPILL |
| ----------- | ----- | ----------- | ----------- |
@ -13,14 +13,16 @@
| UART1_RX | PB7 | CN7/2 | P4/6 (43) |
| SWO/RX2 | PA3 | NA(*1) | P3/8 (13) |
*1: Wire JTDO/PB3 (U2/39) to USART2_RX/PA3 (U2/13) to expose SWO for Stlink
*1: Wire JTDO/PB3 (U2/39) to USART2_RX/PA3 (U2/13) to expose SWO for ST-Link
on STM8S-Disco on CN5/3
### Force Bootloader Entry:
### Force Bootloader Entry
STM8S Discovery: Jumper CN7/4 to CN7/3 to read PB6 low.
Bluepill: Jumper Boot1 to '1' to read PB2 high.
### References:
### References
[STM8S UM0817 User manual
](https://www.st.com/resource/en/user_manual/cd00250600.pdf)
@ -67,6 +69,7 @@ accessible, with the LED depending on actual board layout routed to some
wrong pin and force boot not working.
## Other STM32F103x[8|B] boards
If the needed JTAG connections are accessible, you can use this swlink variant.
Depending on board layout, LED and force bootloader entry may be routed to
wrong pins.