From 229c721189587760db5509c59b3c02e93e7035c8 Mon Sep 17 00:00:00 2001
From: nightwalker-87 <15526941+Nightwalker-87@users.noreply.github.com>
Date: Wed, 24 Mar 2021 23:26:38 +0100
Subject: [PATCH] General Project Update
- Added basic security policy
- Updated info on version support for macOS
- Updated tutorial.md
> Added reference for st-info --probe command
> Added section on unknown chip id error
(Closes #107, Closes #568, Closes #669)
> Added information on HW reset pin issue
(Closes #220, Closes #238)
---
CHANGELOG.md | 18 ++++++++----
SECURITY.md | 20 +++++++++++++
doc/tutorial.md | 67 ++++++++++++++++++++++++++++++++----------
doc/version_support.md | 8 ++---
4 files changed, 87 insertions(+), 26 deletions(-)
create mode 100644 SECURITY.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7ca94dbc8..e3f8e13b5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,12 +2,13 @@
# v1.6.2
-Release date: (TBD)
+Release date: (planned H1/2021)
Features:
+- Extended support for STM32H7 & rework of software reset ([#532](https://github.com/stlink-org/stlink/pull/532), [#1059](https://github.com/stlink-org/stlink/pull/1059), [#1063](https://github.com/stlink-org/stlink/pull/1063), [#1071](https://github.com/stlink-org/stlink/pull/1071))
- Added support for STM32H742/743/753 ([#671](https://github.com/stlink-org/stlink/pull/671), [#793](https://github.com/stlink-org/stlink/pull/793), [#823](https://github.com/stlink-org/stlink/pull/823), [#998](https://github.com/stlink-org/stlink/pull/998), [#1052](https://github.com/stlink-org/stlink/pull/1052))
-- Official support for STLINK-V3 programmers ([#820](https://github.com/stlink-org/stlink/pull/820), [#1022](https://github.com/stlink-org/stlink/pull/1022), [#1025](https://github.com/stlink-org/stlink/pull/1025))
+- Official support for STLINK-V3 programmers (commit [#5e0a502](https://github.com/stlink-org/stlink/commit/5e0a502df812495bfa96fa9116a19f1306152b17), [#820](https://github.com/stlink-org/stlink/pull/820), [#1022](https://github.com/stlink-org/stlink/pull/1022), [#1025](https://github.com/stlink-org/stlink/pull/1025))
- Added preliminary support for STM32L5x2 ([#904](https://github.com/stlink-org/stlink/pull/904), [#999](https://github.com/stlink-org/stlink/pull/999))
- Option bytes on the STM32F767 ZIT6 Nucleo-144 ([#968](https://github.com/stlink-org/stlink/pull/968), [#997](https://github.com/stlink-org/stlink/pull/997))
- Use SetConsoleCtrlHandler for Windows ([#1021](https://github.com/stlink-org/stlink/pull/1021))
@@ -15,12 +16,13 @@ Features:
- `st-util`: Add specialized memory map for STM32H7 devices ([#1060](https://github.com/stlink-org/stlink/pull/1060))
- Support for STM32F4 option bytes ([#1062](https://github.com/stlink-org/stlink/pull/1062))
- Link for WIN32 & APPLE with stlink-static ([#1069](https://github.com/stlink-org/stlink/pull/1069))
-- Extended support for STM32H7 ([#1059](https://github.com/stlink-org/stlink/pull/1059), [#1063](https://github.com/stlink-org/stlink/pull/1063), [#1071](https://github.com/stlink-org/stlink/pull/1071))
- ITM functionality for STLink/V2 and STM32Fxx chipsets ([#136](https://github.com/stlink-org/stlink/pull/136), [#179](https://github.com/stlink-org/stlink/pull/179), [#815](https://github.com/stlink-org/stlink/pull/815), [#1072](https://github.com/stlink-org/stlink/pull/1072))
- Included ITM functionality for building with MSVC ([#1080](https://github.com/stlink-org/stlink/pull/1080))
Updates & changes:
+- [doc] Added tutorial section on unknown chip id error ([#107](https://github.com/stlink-org/stlink/pull/107), [#568](https://github.com/stlink-org/stlink/pull/568),
+- [doc] Updated documentation on target resetting ([#261](https://github.com/stlink-org/stlink/pull/261), [#533](https://github.com/stlink-org/stlink/pull/533), [#1107](https://github.com/stlink-org/stlink/pull/1107))
- [doc] Added note on `(gdb) run` command (commit [#03793d4](https://github.com/stlink-org/stlink/commit/03793d42b6078344a9ef8ad55f1d5d0fc19e486e), [#267](https://github.com/stlink-org/stlink/pull/267))
- [doc] `st-flash --reset` parameter (one solution for #356) ([#642](https://github.com/stlink-org/stlink/pull/642))
- [refactoring] General maintenance ([#864](https://github.com/stlink-org/stlink/pull/864), [#976](https://github.com/stlink-org/stlink/pull/976), [#978](https://github.com/stlink-org/stlink/pull/978))
@@ -33,6 +35,7 @@ Updates & changes:
Fixes:
+- Flash loader rework ([#356](https://github.com/stlink-org/stlink/pull/356), [#556](https://github.com/stlink-org/stlink/pull/556), [#593](https://github.com/stlink-org/stlink/pull/593), [#607](https://github.com/stlink-org/stlink/pull/607), [#612](https://github.com/stlink-org/stlink/pull/612), [#638](https://github.com/stlink-org/stlink/pull/638), [#661](https://github.com/stlink-org/stlink/pull/661), [#690](https://github.com/stlink-org/stlink/pull/690), [#979](https://github.com/stlink-org/stlink/pull/979), [#1043](https://github.com/stlink-org/stlink/pull/1043), [#1054](https://github.com/stlink-org/stlink/pull/1054), [#1105](https://github.com/stlink-org/stlink/pull/1105), [#1113](https://github.com/stlink-org/stlink/pull/1113))
- Fixed old DFU serial number for STLINK programmers ([#417](https://github.com/stlink-org/stlink/pull/417), [#494](https://github.com/stlink-org/stlink/pull/494), [#1106](https://github.com/stlink-org/stlink/pull/1106))
- [regression] Changed timeout on flash write ([#787](https://github.com/stlink-org/stlink/pull/787), [#981](https://github.com/stlink-org/stlink/pull/981), [#987](https://github.com/stlink-org/stlink/pull/987))
- cmake compile failure with external `CMAKE_MODULE_PATH` set ([#962](https://github.com/stlink-org/stlink/pull/962))
@@ -45,8 +48,10 @@ Fixes:
- Fix for `mmap() size_t overflow` in `st-flash` ([#988](https://github.com/stlink-org/stlink/pull/988), [#989](https://github.com/stlink-org/stlink/pull/989))
- [regression] `stlink-gui` installation issue on Ubuntu-18.04 ([#1001](https://github.com/stlink-org/stlink/pull/1001), [#1004](https://github.com/stlink-org/stlink/pull/1004), [#1006](https://github.com/stlink-org/stlink/pull/1006))
- `st-util`: wrong register values passed to `gdb` (STLink/V2) ([#1002](https://github.com/stlink-org/stlink/pull/1002), [#1011](https://github.com/stlink-org/stlink/pull/1011), [#1026](https://github.com/stlink-org/stlink/pull/1026), [#1027](https://github.com/stlink-org/stlink/pull/1027), [#1064](https://github.com/stlink-org/stlink/pull/1064), [#1065](https://github.com/stlink-org/stlink/pull/1065))
+- GDB: Fixed problems with target description ([#1013](https://github.com/stlink-org/stlink/pull/1013), [#1088](https://github.com/stlink-org/stlink/pull/1088), [#1109](https://github.com/stlink-org/stlink/pull/1109))
- [doc] Fixed wrong path for `rules.d` folder ([#1020](https://github.com/stlink-org/stlink/pull/1020))
- Use vl flashloader for all STM32F1 series ([#1041](https://github.com/stlink-org/stlink/pull/1041), [#1044](https://github.com/stlink-org/stlink/pull/1044))
+- Fixed support for STLINK/V1 programmer ([#1045](https://github.com/stlink-org/stlink/pull/1045), [#1105](https://github.com/stlink-org/stlink/pull/1105))
- st-util v1.6.1 does not recognize option --freq (commit [#e576768](https://github.com/stlink-org/stlink/commit/e5767681f14de9851aa970a9299930ca68b2ed92), [#1055](https://github.com/stlink-org/stlink/pull/1055))
- Fixed `gettimeofday` for MSVC ([#1074](https://github.com/stlink-org/stlink/pull/1074))
- Bugfixes for compilation with clang ([#1076](https://github.com/stlink-org/stlink/pull/1076), [#1078](https://github.com/stlink-org/stlink/pull/1078))
@@ -54,7 +59,6 @@ Fixes:
- [regression] Flash_loader: increased wait rounds for slow boards ([#1085](https://github.com/stlink-org/stlink/pull/1085))
- Fixed support for writing option bytes ([#1102](https://github.com/stlink-org/stlink/pull/1102))
- [doc] Corrected spelling mistake in bug report template ([#1103](https://github.com/stlink-org/stlink/pull/1103))
-- Fixed support for STLINK/V1 programmer ([#1045](https://github.com/stlink-org/stlink/pull/1045), [#1105](https://github.com/stlink-org/stlink/pull/1105))
- Fixed STM32WB55 reading DEBUG IDCODE from the wrong address ([#1100](https://github.com/stlink-org/stlink/pull/1100), [#1101](https://github.com/stlink-org/stlink/pull/1101))
# v1.6.1
@@ -179,8 +183,8 @@ Major changes and added features:
Updates and fixes:
-- Fixed `unkown chip id`, piped output and `st-util -v` ([#107](https://github.com/stlink-org/stlink/pull/107), [#665](https://github.com/stlink-org/stlink/pull/665), [#763](https://github.com/stlink-org/stlink/pull/763))
- Fixed an issue with versioning stuck at 1.4.0 for versions cloned with git ([#563](https://github.com/stlink-org/stlink/pull/563), [#762](https://github.com/stlink-org/stlink/pull/762), [#772](https://github.com/stlink-org/stlink/pull/772))
+- Fixed `unkown chip id`, piped output and `st-util -v` ([#665](https://github.com/stlink-org/stlink/pull/665), [#763](https://github.com/stlink-org/stlink/pull/763))
- Updated STM32F3xx chip ID that covers a few different devices ([#685](https://github.com/stlink-org/stlink/pull/685), [#758](https://github.com/stlink-org/stlink/pull/758))
- Made udev rules and modprobe conf installation optional ([#741](https://github.com/stlink-org/stlink/pull/741))
- Fixed case when `__FILE__` doesn't contain either `/` nor `\\` ([#745](https://github.com/stlink-org/stlink/pull/745))
@@ -385,12 +389,14 @@ Updates and fixes:
- Fixed STM32F2xx memory map (Nicolas Schodet)
- Memory map for STM32F42xxx and STM32F43xxx devices (Craig Lilley)
- Stm32l0x flash loader (Robin Kreis)
-- Use libusb synchronous api ([#194](https://github.com/stlink-org/stlink/pull/194), [#374](https://github.com/stlink-org/stlink/pull/374))
+- Modified determination of erased byte pattern when flashing ([#193](https://github.com/stlink-org/stlink/pull/193), [#377](https://github.com/stlink-org/stlink/pull/377))
+- Use libusb synchronous api ([#194](https://github.com/stlink-org/stlink/pull/194), [#225](https://github.com/stlink-org/stlink/pull/225), [#374](https://github.com/stlink-org/stlink/pull/374))
- Fixed segfault when programmer is already busy and `NULL` pointers are in the list ([#256](https://github.com/stlink-org/stlink/pull/256), [#394](https://github.com/stlink-org/stlink/pull/394))
- Fixed issue where "unknown chip id!" was seen every other time ([#352](https://github.com/stlink-org/stlink/pull/352), [#367](https://github.com/stlink-org/stlink/pull/367), [#381](https://github.com/stlink-org/stlink/pull/381))
- Send F4 memory-map and features for STM32F429 ([#188](https://github.com/stlink-org/stlink/pull/188), [#196](https://github.com/stlink-org/stlink/pull/196), [#250](https://github.com/stlink-org/stlink/pull/250), [#251](https://github.com/stlink-org/stlink/pull/251)) (Release v1.1.0)
- Added AHB3 Peripherals definition for STM32F4 ([#218](https://github.com/stlink-org/stlink/pull/218), [#288](https://github.com/stlink-org/stlink/pull/288)) (Release v1.1.0)
- Reset: st-flash does not work when CPU is in sleep mode ([#62](https://github.com/stlink-org/stlink/pull/62)) (Release v1.0.0)
+- Ensure USB device search succeeds if the matched device is at index 0 ([#126](https://github.com/stlink-org/stlink/pull/126), [#151](https://github.com/stlink-org/stlink/pull/151)) (Release v1.0.0)
- Corrected flash size register address for STM32F2 devices ([#278](https://github.com/stlink-org/stlink/pull/278)) (Release v1.0.0)
Chip support added for:
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 000000000..caa2740db
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported Versions
+
+The following versions of the stlink toolset are currently being supported.
As this is a development toolset, please note that bugfixes will only be applied to the latest version.
+
+| Version | Supported |
+| ------- | ------------------ |
+| develop | :white_check_mark: |
+| 1.6.x | :white_check_mark: |
+| 1.5.x | :x: |
+| 1.4.0 | :x: |
+| 1.3.x | :x: |
+| 1.2.0 | :x: |
+| 1.1.0 | :x: |
+| 1.0.0 | :x: |
+
+## Reporting a Vulnerability
+
+Detected vulnerabilities in the toolset should be reported by opening a regular bugreport issue.
diff --git a/doc/tutorial.md b/doc/tutorial.md
index d4cf89ce2..8b1220747 100644
--- a/doc/tutorial.md
+++ b/doc/tutorial.md
@@ -2,15 +2,16 @@
## Available tools and options
-| Option | Tool | Description | Available
since |
-| --------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| --flash=n[k][m] | st-flash | One can specify `--flash=128k` for example, to override the default value of 64k
for the STM32F103C8T6 to assume 128k of flash being present. This option accepts
decimal (128k), octal 0200k, or hex 0x80k values. Leaving the multiplier out is
equally valid, e.g.: `--flash=0x20000`. The size may be followed by an optional "k"
or "m" to multiply the given value by 1k (1024) or 1M respectively. | v1.4.0 |
-| --freq=n[k][m] | st-flash | The frequency of the SWD/JTAG interface can be specified, to override the default
1800 kHz configuration. This option solely accepts decimal values (5K or 1.8M) with
the unit `Hz` being left out. Valid frequencies are: `5K, 15K, 25K, 50K, 100K,`
`125K, 240K, 480K, 950K, 1200K(1.2M), 1800K(1.8M), 4000K(4M)`. | v1.6.1 |
-| --opt | st-flash | Optimisation can be enabled in order to skip flashing empty (0x00 or 0xff) bytes at
the end of binary file. This may cause some garbage data left after a flash operation.
This option was enabled by default in earlier releases. | v1.6.1 |
-| --reset | st-flash | Trigger a reset both before and after flashing. The default use the hardware reset
through `NRST` pin. The software system reset is used if the hardware reset failed
(`NRST` pin not connected). | v1.0.0 |
-| --connect-under-reset | st-flash | Connect under reset. Option makes it possible to connect to the device before code
executing. This is useful when the target contains a code that go device to sleep,
disables of debug pins or other special code. | v1.6.1 |
-| --version | st-info
st-flash
st-util | Print version information. | |
-| --help | st-flash
st-util | Print list of available commands. _(To be added to this table.)_ | |
+| Option | Tool | Description | Available
since |
+| --------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
+| --flash=n[k][m] | st-flash | One can specify `--flash=128k` for example, to override the default value of 64k for the STM32F103C8T6
to assume 128k of flash being present. This option accepts decimal (128k), octal 0200k, or hex 0x80k values.
Leaving the multiplier out is equally valid, e.g.: `--flash=0x20000`. The size may be followed by an optional
"k" or "m" to multiply the given value by 1k (1024) or 1M respectively. | v1.4.0 |
+| --freq=n[k][m] | st-flash | The frequency of the SWD/JTAG interface can be specified, to override the default 1800 kHz configuration.
This option solely accepts decimal values (5K or 1.8M) with the unit `Hz` being left out. Valid frequencies are:
`5K, 15K, 25K, 50K, 100K, 125K, 240K, 480K, 950K, 1200K(1.2M), 1800K(1.8M), 4000K(4M)`. | v1.6.1 |
+| --opt | st-flash | Optimisation can be enabled in order to skip flashing empty (0x00 or 0xff) bytes at the end of binary file.
This may cause some garbage data left after a flash operation. This option was enabled by default in earlier releases. | v1.6.1 |
+| --reset | st-flash | Trigger a reset both before and after flashing. The default uses the hardware reset through `NRST` pin.
The software reset is used if the hardware reset failed (`NRST` pin not connected). | v1.0.0 |
+| --connect-under-reset | st-flash | Connect under reset. Option makes it possible to connect to the device before code execution. This is useful
when the target contains code that lets the device go to sleep, disables debug pins or other special code. | v1.6.1 |
+| --probe | st-info | Display hardware information about the connected programmer and target MCU. | v1.2.0 |
+| --version | st-info
st-flash
st-util | Print version information. | v1.3.0 |
+| --help | st-flash
st-util | Print list of available commands. | |
### st-flash: Checksum for binary files
@@ -102,17 +103,52 @@ Check your hardware and try to identify what you have in front of you before ass
Please let us know, if you come across any further websites or tutorials that help to identify STM32 fake chips so we can list them here to help others.
----
+### c) Appearance of the warning message `WARN src/common.c: unknown chip id!`
+
+The chip ID is the main identifier for STM32 MCU and their specific type and provides primary information on flash and SRAM architecture.
+This so called `DBGMCU_IDCODE` register is allocated either at memory address `0xE0042000` or `0x40015800`.
+
+A failure of chip identification results in the error `WARN src/common.c: unknown chip id!`.
+There are different variants of this message that refer to different issues:
+
+- `unknown chip id! 0` --> _currently unknown_
+- `unknown chip id! 0x1a` --> _currently unknown_
+- `unknown chip id! 0x001f` --> _currently unknown_
+- `unknown chip id! 0x3e8` --> _currently unknown_
+- `unknown chip id! 0xa05f0000` --> _currently unknown_
+- `unknown chip id! 0x3748` --> A target chip / board cannot be detected.
+ 1. No target is connected --> In this case `st-info --probe` displays `chip id 0x0748` with STLINK/V2 and `chip id 0x03e8` with STLINK-V3.
+ 2. The chip is connected but has gone into an undefined state of operation where the SWD pins are unresponsive. --> Try to use `--connect-under-reset` while pressing the reset button on the target board.
+ 3. A firmware-issue prevents the programmer from normal operation. --> Ensure that your programmer runs the latest firmware version and consider to upgrade any older version by using the official firmware upgrade tool provided by STMicroelectronics.
+- `unknown chip id! 0xe0042000` --> The memory register holding the information on the chip ID could not be read. The following problems may lead to this case:
+ 1. This problem is caused by the SWDIO and SWCLK being configured for other purpose (GPIO, etc) other than Serial Wire configuration or Jtag --> A possible solution to this is to short the `BOOT0` pin with `VDD` (1) and to reset the chip / board by the execuing `st-flash erase` in order to return the MCU back to normal operation. Afterwards `BOOT0` should be set back to `GND` (0).
+ 2. There is a hardware defect in the connection between the MCU and the used programmer (solder points, cables, connectors).
+
+### d) Understanding hardware and software reset functionality for `st-flash` and reset-related device recovery
+
+Typically a reset signal is sent via the reset pin `NRST`. Using `st-flash` for flashing results in the following behaviour:
-( Content below is currently unrevised and may be outdated as of Apr 2020. )
+- without the `--reset` option: `st-flash write` results in one reset signal on the `NRST` line
+- with the `--reset` option: `st-flash write --reset` results in two subsequent reset signals on the `NRST` line
-# Using STM32 discovery kits with open source tools
+Depending on the used programmer the hardware reset line is not always connected.
+This is especially the case for low-cost STLINK/V2 clone programmers.
+Here the SWD connector consists of only 4 pins: `VCC`, `SWCLK`, `GND` and `SWDATA`.
-This guide details the use of STMicroelectronics STM32 discovery kits in an open source environment.
+When the physical reset line `NRST` is not connected, a reset is initiated by software via `SWD_SWDIO/JTAG_TMS` (software reset).
+Just as mentioned above, flashing is possible here eiher with and without the `--reset` option.
-## Installing a GNU toolchain
+Configuring the STM32 pin `JTAG_TMS/SWD_SWDIO` as an output now also prevents the SWD interface from flashing and resetting the device.
+In consequence this constellation typically requires a _hard reset_ to allow for the ST-Link/V2 programmer to reconnect to the target at all.
-Any toolchain supporting the cortex m3 should do.
+As soon as the device is in DFU mode, the `JTAG_TMS/SWD_SWDIO` pin is left in the default state with all JTAG pins available.
+Here flashing of the device is now possible with and without the `--reset` option.
+
+The debug command `(gdb) monitor jtag_reset` sends a _hard reset_ signal via the `NRST` pin to reset the device and allows for flashing it (again).
+
+---
+
+( Content below is currently unrevised and may be outdated as of Mar 2021. )
## Using the GDB server
@@ -201,7 +237,6 @@ Of course, you can use this instead of the gdb server, if you prefer.
Just remember to use the “.bin” image, rather than the .elf file.
```
-
# write blink.bin into FLASH
$> [sudo] ./st-flash write fancy_blink.bin 0x08000000
```
diff --git a/doc/version_support.md b/doc/version_support.md
index 1edf2e19c..5d2cdd375 100644
--- a/doc/version_support.md
+++ b/doc/version_support.md
@@ -14,10 +14,10 @@ Thus no user interaction regarding libusb is necessary.
### Apple macOS
-| Package Repository | libusb
version | cmake
version | gtk-3
version | Supported macOS versions |
-| ------------------ | ------------------- | ------------------ | ------------------ | -------------------------------------- |
-| homebrew | 1.0.23 | 3.17.0 | 3.24.18
gtk+3 | 10.12 (Sierra)- 10.15 (Catalina) |
-| MacPorts | 1.0.23 | 3.17.0 | 3.24.18
gtk3 | 10.6 (Snow Leopard) - 10.15 (Catalina) |
+| Package Repository | libusb
version | cmake
version | gtk-3
version | Supported macOS versions |
+| ------------------ | ------------------- | ------------------ | ------------------ | ------------------------ |
+| homebrew | 1.0.23 | 3.17.0 | 3.24.18
gtk+3 | 10.9 - 10.15 |
+| MacPorts | 1.0.23 | 3.17.0 | 3.24.18
gtk3 | 10.4 - 10.15 |
NOTE: In order to use a STLINK/V1 programmer on macOS, versions 10.14 or 10.15 are required.