diff --git a/README.md b/README.md index 5d98f0e..594e0fa 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,21 @@ Open source version of the STMicroelectronics Stlink Tools ========================================================== -[![GitHub release](https://img.shields.io/github/release/texane/stlink.svg)](https://github.com/texane/stlink/releases/latest) [![BSD licensed](https://img.shields.io/badge/license-BSD-blue.svg)](https://raw.githubusercontent.com/hyperium/hyper/master/LICENSE) +[![GitHub release](https://img.shields.io/github/release/texane/stlink.svg)](https://github.com/texane/stlink/releases/latest) [![GitHub commits](https://img.shields.io/github/commits-since/texane/stlink/v1.6.0.svg)](https://github.com/texane/stlink/releases/master) [![Downloads](https://img.shields.io/github/downloads/texane/stlink/total.svg)](https://github.com/texane/stlink/releases) - [![Linux Status](https://img.shields.io/travis/texane/stlink/master.svg?label=linux)](https://travis-ci.org/texane/stlink) [![macOS Status](https://img.shields.io/travis/texane/stlink/master.svg?label=osx)](https://travis-ci.org/texane/stlink) +Recent new features and bugfixes can be found in the [Changelog](CHANGELOG.md) of this software project. -## HOWTO -This stlink toolset supports several so called stlink programmer boards (and clones thereof) which use a microcontroller chip to translate commands from USB to JTAG. These programmer boards are available in four versions: +## Introduction + +This stlink toolset supports several so called stlink programmer boards (and clones thereof) which use a microcontroller chip to translate commands from USB to JTAG. + +These programmer boards are available in four versions: * **STLINKv1:** - transport layer: SCSI passthru commands over USB @@ -24,39 +27,122 @@ This stlink toolset supports several so called stlink programmer boards (and clo * transport layer: raw USB commands * present on some STM32 nucleo boards * **STLINKv3:** - * _currently not supported by this toolset_ + * _not yet supported by this toolset (but planned)_ + + +## Supported hardware combinations + +Currently known working combinations of programmers and targets are listed in [doc/tested-boards.md](doc/tested-boards.md). ## Installation -Windows users can [download v1.3.0](https://github.com/texane/stlink/releases/tag/1.3.0) from the releases page. +**Windows**: download [v1.6.0](https://github.com/texane/stlink/releases/tag/v1.6.0) from the releases page. -Mac OS X users can install from [homebrew](http://brewformulas.org/Stlink) or [download v1.3.0](https://github.com/texane/stlink/releases/tag/1.3.0) from the releases page. +**macOS**: install [from homebrew](http://brewformulas.org/Stlink) or download [v1.6.0](https://github.com/texane/stlink/releases/tag/v1.6.0) from the releases page. -Debian Linux users can install it via the ```stlink-tools``` package [repository](https://packages.debian.org/buster/stlink-tools) +**Linux**: -Ubuntu Linux users can install it via the ```stlink-tools``` package [repository](https://packages.ubuntu.com/stlink-tools) +We recommend to install `stlink-tools` from the package repository of the used distribution: -Arch Linux users can install from the [repository](https://www.archlinux.org/packages/community/x86_64/stlink) +* Debian Linux: [(Link)](https://packages.debian.org/buster/stlink-tools) +* Ubuntu Linux: [(Link)](https://packages.ubuntu.com/stlink-tools) +* Arch Linux: [(Link)](https://www.archlinux.org/packages/community/x86_64/stlink) +* Alpine Linux: [(Link)](https://pkgs.alpinelinux.org/packages?name=stlink) +* Fedora: [(Link)](https://src.fedoraproject.org/rpms/stlink) +* Gentoo Linux: [(Link)](https://packages.gentoo.org/packages/dev-embedded/stlink) -Alpine Linux users can install from the [repository](https://pkgs.alpinelinux.org/packages?name=stlink) +**Other Operating Systems**: -Fedora users can install from [repository](https://src.fedoraproject.org/rpms/stlink) - -RedHat/CentOS 7 users can install from EPEL [repository](https://src.fedoraproject.org/rpms/stlink/branch/epel7) - -Gentoo Linux users can install from the official portage [repository](https://packages.gentoo.org/packages/dev-embedded/stlink) - -FreeBSD users can install from [freshports](https://www.freshports.org/devel/stlink) - -OpenBSD users need to install [from source](doc/compiling.md). +* RedHat/CentOS 7: Users can install [from EPEL repository](https://src.fedoraproject.org/rpms/stlink/branch/epel7) +* FreeBSD: Users can install [from freshports](https://www.freshports.org/devel/stlink) +* OpenBSD: Users need to install [from source](doc/compiling.md). ## Installation from source (advanced users) -When there is no executable available for your platform or you need the latest (possible unstable) version you need to compile yourself. This is explained in the [compiling manual](doc/compiling.md). +When there is no executable available for your platform or you need the latest (possible unstable) version you need to compile the toolset yourself. This procedure is explained in the [compiling manual](doc/compiling.md). +## Contributing and versioning + +* The semantic versioning scheme is used. Read more at [semver.org](http://semver.org) +* Before creating a pull request, please _ALWAYS_ open a new issue for the discussion of the intended new features. Bugfixes don't require a discussion via a ticket-issue. However they should always be described in a few words as soon as they appear to help others as well. +* Contributors and/or maintainers may submit comments or request changes to patch-proposals and/or pull-requests. + + +## License + +The stlink library and tools are licensed under the [BSD license](LICENSE.md). + +The flashloaders/stm32l0x.s and flashloaders/stm32lx.s source files are licensed under the GPLv2+. + + +# Current state of the project + +## Known missing features + +Some features are currently missing from the `texane/stlink` toolset. +Here we would appreciate any help and would love to welcome new contributors who want to get involved: + +* Instrumentation Trace Macro (ITM) Cell ([#136](https://github.com/texane/stlink/issues/136)) +* OTP area programming ([#202](https://github.com/texane/stlink/issues/202)) +* EEPROM area programming ([#318](https://github.com/texane/stlink/issues/218)) +* Protection bits area reading ([#346](https://github.com/texane/stlink/issues/346)) +* Writing external memory connected to an STM32 controller (e.g Quad SPI NOR flash) ([#412](https://github.com/texane/stlink/issues/412)) +* MCU hotplug ([#449](https://github.com/texane/stlink/issues/449)) +* Writing options bytes (region) ([#458](https://github.com/texane/stlink/issues/458)) +* Control programming speed ([#462](https://github.com/texane/stlink/issues/462)) +* Support for STLINKv3 programmer ([#820](https://github.com/texane/stlink/issues/820)) + + +## Known bugs +### Sometimes flashing only works after a mass erase + +There is seen a problem sometimes where a flash loader run error occurs and is resolved after mass-erase of the flash: + +``` +2015-12-09T22:01:57 INFO src/stlink-common.c: Successfully loaded flash loader in sram +2015-12-09T22:02:18 ERROR src/stlink-common.c: flash loader run error +2015-12-09T22:02:18 ERROR src/stlink-common.c: run_flash_loader(0x8000000) failed! == -1 +``` + +Issue related to this bug: [#356](https://github.com/texane/stlink/issues/356) + + +### Flash size is detected as zero bytes size + +It is possible that the STM32 flash is write protected, the st-flash tool will show something like this: + +``` +st-flash write prog.bin 0x8000000 +2017-01-24T18:44:14 INFO src/stlink-common.c: Loading device parameters.... +2017-01-24T18:44:14 INFO src/stlink-common.c: Device connected is: F1 High-density device, id 0x10036414 +2017-01-24T18:44:14 INFO src/stlink-common.c: SRAM size: 0x10000 bytes (64 KiB), Flash: 0 bytes (0 KiB) in pages of 2048 bytes +``` + +As you can see, it gives out something unexpected like +``` +Flash: 0 bytes (0 KiB) in pages of 2048 bytes +``` + +``` +st-info --probe +Found 1 stlink programmers + serial: 303030303030303030303031 +openocd: "\x30\x30\x30\x30\x30\x30\x30\x30\x30\x30\x30\x31" + flash: 0 (pagesize: 2048) + sram: 65536 + chipid: 0x0414 + descr: F1 High-density device +``` + +Try to remove the write protection (probably only possible with ST Link Utility from ST itself). + +Issue related to this bug: [#545](https://github.com/texane/stlink/issues/545) + + +# HOWTO ## Using the gdb server To run the gdb server: @@ -177,84 +263,3 @@ A: Sometimes when you will try to use GDB `next` command to skip a loop, it will Q: Load command does not work in GDB. A: Some people report XML/EXPAT is not enabled by default when compiling GDB. Memory map parsing thus fail. Use --enable-expat. - - -## Currently known working combinations of programmer and target - -See [doc/tested-boards.md](doc/tested-boards.md) - -## Changelog - -The [Changelog](CHANGELOG.md) for the StLink Tools. - - -## Known missing features - -Some features are missing from the `texane/stlink` project and we would like you to help us out if you want to get involved: - -* Control programming speed (See [#462](https://github.com/texane/stlink/issues/462)) -* OTP area programming (See [#202](https://github.com/texane/stlink/issues/202)) -* EEPROM area programming (See [#318](https://github.com/texane/stlink/issues/218)) -* Protection bits area reading (See [#346](https://github.com/texane/stlink/issues/346)) -* MCU hotplug (See [#449](https://github.com/texane/stlink/issues/449)) -* Writing options bytes (region) (See [#458](https://github.com/texane/stlink/issues/458)) -* Instrumentation Trace Macro (ITM) Cell (See [#136](https://github.com/texane/stlink/issues/136)) -* Writing external memory connected to an STM32 controller (e.g Quad SPI NOR flash) (See [#412](https://github.com/texane/stlink/issues/412)) - - -## Known bugs -### Sometimes flashing only works after a mass erase - -There is seen a problem sometimes where a flash loader run error occurs and is resolved after mass-erase of the flash: - -``` -2015-12-09T22:01:57 INFO src/stlink-common.c: Successfully loaded flash loader in sram -2015-12-09T22:02:18 ERROR src/stlink-common.c: flash loader run error -2015-12-09T22:02:18 ERROR src/stlink-common.c: run_flash_loader(0x8000000) failed! == -1 -``` - -Issue related to this bug: [#356](https://github.com/texane/stlink/issues/356) - - -### Flash size is detected as zero bytes size - -It is possible that the STM32 flash is write protected, the st-flash tool will show something like this: - -``` -st-flash write prog.bin 0x8000000 -2017-01-24T18:44:14 INFO src/stlink-common.c: Loading device parameters.... -2017-01-24T18:44:14 INFO src/stlink-common.c: Device connected is: F1 High-density device, id 0x10036414 -2017-01-24T18:44:14 INFO src/stlink-common.c: SRAM size: 0x10000 bytes (64 KiB), Flash: 0 bytes (0 KiB) in pages of 2048 bytes -``` - -As you can see, it gives out something unexpected like -``` -Flash: 0 bytes (0 KiB) in pages of 2048 bytes -``` - -``` -st-info --probe -Found 1 stlink programmers - serial: 303030303030303030303031 -openocd: "\x30\x30\x30\x30\x30\x30\x30\x30\x30\x30\x30\x31" - flash: 0 (pagesize: 2048) - sram: 65536 - chipid: 0x0414 - descr: F1 High-density device -``` - -Try to remove the write protection (probably only possible with ST Link Utility from ST itself). - -Issue related to this bug: [#545](https://github.com/texane/stlink/issues/545) - - -## Contributing and versioning - -* The semantic versioning scheme is used. Read more at [semver.org](http://semver.org) -* When creating a pull request, please open first a issue for discussion of new features. Bugfixes don't need a discussion. - -## License - -The stlink library and tools are licensed under the [BSD license](LICENSE.md). - -The flashloaders/stm32l0x.s and flashloaders/stm32lx.s source files are licensed under the GPLv2+.