Documentation for removing flash protection (dirtyjtag#85)

* Fix typo * Add STM32F1 flash protection documentation page * Add reference to flash protection page * Make flash protection documentation more uniform across different hardware pages * Uniformize OpenOCD unlock procedure in the docs, include example of flash protection failure * Add link to "Fixing STM32F1xx flash protection issues"
Woolfy025 · Jan 28, 2021 · 001480b · 001480b
1 parent 72a2bce
commit 001480b
Show file tree

Hide file tree

Showing 5 changed files with 129 additions and 13 deletions.
diff --git a/README.md b/README.md
@@ -58,6 +58,7 @@ Older versions of DirtyJTAG reported "DirtyJTAG" as the manufacturer, this bug h
 
  * [Compiling DirtyJTAG yourself](docs/building-dirtyjtag.md)
  * [Validate your DirtyJTAG cable with JTAG targets](docs/jtag-validation.md)
+ * [Fixing STM32F1xx flash protection issues](docs/stm32f1-flash-protection.md)
 
 ## Inspiration & links
 

diff --git a/docs/install-baite.md b/docs/install-baite.md
@@ -16,23 +16,36 @@ To gain access to the internal SWD connector in your Baite dongle, pry apart the
 
 The unpopulated connector can fit a generic 2.54mm male header if needed. When programming the Baite dongle, **it is advised to not plug the Baite dongle via USB** to avoid confusion while flashing DirtyJTAG (you might brick your ST-Link programmer!).
 
-## Unlocking the memory
+## Remove flash protection
 
-Like every other ST-Link clone on the market, its flash memory is protected against SWD readouts. To remove that protection we will have to use OpenOCD.
+Any ST-Link currently sold (even the clones) have their readout protection enabled. This means that when you want to flash another firmware than the factory-supplied one, you will have to disable the read protection using OpenOCD. Hopefully you will only have to do it once!
 
-To start OpenOCD with the adequate settings for an ST-Link v2 programmer use this command:
+Connect the ST-Link that will act as a programmer to the target on its SWD header. Open up a terminal and type in the following command:
 
 ```
 openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg
 ```
 
-Then while keeping OpenOCD open, open a new terminal window and connect to OpenOCD server:
+You might get an error similar to
+```
+Warn : UNEXPECTED idcode: 0x2ba01477 Error: expected 1 of 1: 0x1ba01477
+```
+which indicates that your ST-Link V2 clone has a STM32 clone MCU.
+
+In this case, create a custom config file with the reported idcode, eg "`my-stlink-v2.cfg`" with the content:
+```
+source [find interface/stlink-v2.cfg]
+set CPUTAPID 0x2ba01477
+```
+and substitute `-f interface/stlink-v2.cfg` with `-f my-stlink-v2.cfg` when invoking openocd.
+
+Now while keeping this terminal open, open another one and connect to the OpenOCD server:
 
 ```
 telnet localhost 4444
 ```
 
-You now have an OpenOCD prompt (congratulations!). You may now enter the following OpenOCD commands to reset the MCU flash protection (and its content by the way).
+Then type in the following commands to reset the readout protection and exit the telnet session:
 
 ```
 halt
@@ -41,6 +54,10 @@ reset
 exit
 ```
 
+You can `CTRL+C` on the OpenOCD terminal to terminate it.
+
+More detailed explanations are available in [a separate documentation page](stm32f1-flash-protection.md).
+
 ## Flashing DirtyJTAG
 
 Download a binary version of DirtyJTAG (make sure to get the `baite` build!) or [compile it yourself](building-dirtyjtag.md), then flash it using `st-flash`:

diff --git a/docs/install-stlinkv2-swd.md b/docs/install-stlinkv2-swd.md
@@ -1,6 +1,6 @@
 # Installing DirtyJTAG on a ST-Link clone dongle
 
-ST-Link clone dongles are the cheap dongles you can find on AliExpress. They provide the minimum amount of signals needed for JTAG operation. They currently require an SWD programmed in order to install DirtyJTAG on it.
+ST-Link clone dongles are the cheap dongles you can find on AliExpress. They provide the minimum amount of signals needed for JTAG operation. They currently require an SWD programmer in order to install DirtyJTAG on it.
 
 ## Requirements
 
@@ -18,23 +18,36 @@ To gain access to the internal SWD connector in your ST-Link dongle, press firml
 
 If you don't want to solder to your ST-Link dongle, you can either use [dupont header cables](img/stlinkv2-header-cable.jpg) or like zoobab hack a small jig with pogo pins ([[1]](img/stlinkv2-jig-1.jpg), [[2]](img/stlinkv2-jig-2.jpg)).
 
-## Unlocking the memory
+## Remove flash protection
 
-Like every other ST-Link clone on the market, its flash memory is protected against SWD readouts. To remove that protection we will have to use OpenOCD.
+Any ST-Link currently sold (even the clones) have their readout protection enabled. This means that when you want to flash another firmware than the factory-supplied one, you will have to disable the read protection using OpenOCD. Hopefully you will only have to do it once!
 
-To start OpenOCD with the adequate settings for an ST-Link v2 programmer use this command:
+Connect the ST-Link that will act as a programmer to the target on its SWD header. Open up a terminal and type in the following command:
 
 ```
 openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg
 ```
 
-Then while keeping OpenOCD open, open a new terminal window and connect to OpenOCD server:
+You might get an error similar to
+```
+Warn : UNEXPECTED idcode: 0x2ba01477 Error: expected 1 of 1: 0x1ba01477
+```
+which indicates that your ST-Link V2 clone has a STM32 clone MCU.
+
+In this case, create a custom config file with the reported idcode, eg "`my-stlink-v2.cfg`" with the content:
+```
+source [find interface/stlink-v2.cfg]
+set CPUTAPID 0x2ba01477
+```
+and substitute `-f interface/stlink-v2.cfg` with `-f my-stlink-v2.cfg` when invoking openocd.
+
+Now while keeping this terminal open, open another one and connect to the OpenOCD server:
 
 ```
 telnet localhost 4444
 ```
 
-You now have an OpenOCD prompt (congratulations!). You may now enter the following OpenOCD commands to reset the MCU flash protection (and its content by the way).
+Then type in the following commands to reset the readout protection and exit the telnet session:
 
 ```
 halt
@@ -43,6 +56,10 @@ reset
 exit
 ```
 
+You can `CTRL+C` on the OpenOCD terminal to terminate it.
+
+More detailed explanations are available in [a separate documentation page](stm32f1-flash-protection.md).
+
 ## Flashing DirtyJTAG
 
 Download a binary version of DirtyJTAG (make sure to get the `baite` build!) or [compile it yourself](building-dirtyjtag.md), then flash it using `st-flash`:

diff --git a/docs/install-stlinkv2white.md b/docs/install-stlinkv2white.md
@@ -28,7 +28,7 @@ To be safe, you should confirm the pinout with a continuity tester:
 
 A normal pin header won't fit the housing, so better use a right-angled connector, as shown in the photo. Also, you don't really need a 2x3 header, you get by with a 2x1 header for SWDIO and SWCLK and connecting 3V3 and GND to the 2x20 header.
 
-## Remove write protection
+## Remove flash protection
 
 Any ST-Link currently sold (even the clones) have their readout protection enabled. This means that when you want to flash another firmware than the factory-supplied one, you will have to disable the read protection using OpenOCD. Hopefully you will only have to do it once!
 
@@ -42,7 +42,7 @@ You might get an error similar to
 ```
 Warn : UNEXPECTED idcode: 0x2ba01477 Error: expected 1 of 1: 0x1ba01477
 ```
-which indicates that your ST-Link V2 clone has a stm32 clone MCU.
+which indicates that your ST-Link V2 clone has a STM32 clone MCU.
 
 In this case, create a custom config file with the reported idcode, eg "`my-stlink-v2.cfg`" with the content:
 ```
@@ -68,6 +68,8 @@ exit
 
 You can `CTRL+C` on the OpenOCD terminal to terminate it.
 
+More detailed explanations are available in [a separate documentation page](stm32f1-flash-protection.md).
+
 ## Flashing DirtyJTAG
 
 With your target ST-Link connected to the programmer ST-Link you can now flash DirtyJTAG:

diff --git a/docs/stm32f1-flash-protection.md b/docs/stm32f1-flash-protection.md
@@ -0,0 +1,79 @@
+# Fixing STM32F1xx flash protection issues
+
+One of the most common issues when working with pre-programmed STM32F1 MCUs is having the flash protection bit set. You might encounter messages like these when the protection is activated:
+
+```
+(..)
+2021-01-28T20:34:11 INFO flash_loader.c: Successfully loaded flash loader in sram
+2021-01-28T20:34:14 ERROR flash_loader.c: flash loader run error
+2021-01-28T20:34:14 ERROR common.c: stlink_flash_loader_run(0x8000000) failed! == -1
+stlink_fwrite_flash() == -1
+```
+
+The following documentation explains how to disable it through two different techniques. **Be aware that disabling flash protection will erase the whole flash!**
+
+## Unlocking method #1: OpenOCD
+
+This first method requires you to connect an ST-Link programmer to your target. If you're unsure how to do so, check out [our documentation](https://github.com/jeanthom/DirtyJTAG/tree/master/docs).
+
+Connect the ST-Link that will act as a programmer to the target on its SWD header. Open up a terminal and type in the following command:
+
+```
+openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg
+```
+
+You might get an error similar to
+```
+Warn : UNEXPECTED idcode: 0x2ba01477 Error: expected 1 of 1: 0x1ba01477
+```
+which indicates that your ST-Link V2 clone has a STM32 clone MCU.
+
+In this case, create a custom config file with the reported idcode, eg "`my-stlink-v2.cfg`" with the content:
+```
+source [find interface/stlink-v2.cfg]
+set CPUTAPID 0x2ba01477
+```
+and substitute `-f interface/stlink-v2.cfg` with `-f my-stlink-v2.cfg` when invoking openocd.
+
+Now while keeping this terminal open, open another one and connect to the OpenOCD server:
+
+```
+telnet localhost 4444
+```
+
+Then type in the following commands to reset the readout protection and exit the telnet session:
+
+```
+halt
+stm32f1x unlock 0
+reset
+exit
+```
+
+You can `CTRL+C` on the OpenOCD terminal to terminate it.
+
+## Unlocking method #2: stm32flash
+
+[@aalku](https://github.com/aalku) offers another method for removing the flash lock by using [stm32flash](https://github.com/stm32duino/stm32flash). stm32flash is a small utility that lets you flash STM32 devices using the built-in UART bootloader. Hardware-wise you will only need a cheap USB-UART dongle. The following two commands disable the read-protection and write-protection:
+
+```
+stm32flash -k /dev/ttyUSB0
+stm32flash -u /dev/ttyUSB0
+```
+
+## Working with STM32 clones
+
+[@brainstorm](https://github.com/brainstorm) reported that the CKS32 clones can also be unlocked using the above procedure. However OpenOCD does not support CKS32 out of the box so you need to patch the STM32 configuration file to include the JTAG id for CKS32:
+
+```diff
+--- stm32f1x.cfg	2021-01-28 22:55:43.000000000 +1100
++++ ck32.cfg	2021-01-28 22:55:55.000000000 +1100
+@@ -39,7 +39,7 @@
+       set _CPUTAPID 0x3ba00477
+    } {
+       # this is the SW-DP tap id not the jtag tap id
+-      set _CPUTAPID 0x1ba01477
++      set _CPUTAPID 0x2ba01477
+    }
+ }
+```