kopia lustrzana https://github.com/stlink-org/stlink
Updated README.md
rodzic
d312ca267f
commit
ee20ab091e
209
README.md
209
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+.
|
||||
|
|
Ładowanie…
Reference in New Issue