Skip to content

Commit

Permalink
General Project Update
Browse files Browse the repository at this point in the history 
- Updated CHANGELOG.md
- Updated README.md
- [doc] Official STLINK-V3 support
   (Closes #820, Closes #1022, Closes #1025)
- Updated list of contributors
- Updated info on version support
- Minor formatting fixes
  • Loading branch information
@Nightwalker-87
Nightwalker-87 committed Mar 20, 2021
1 parent a3f9cc2 commit 5e0a502
Show file tree
Hide file tree
Showing 5 changed files with 109 additions and 106 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Release date: (TBD)
Features:

- 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))
- 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))
Expand All @@ -32,6 +33,7 @@ Updates & changes:

Fixes:

- 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))
- doc/man: Fixed installation directory ([#970](https://github.com/stlink-org/stlink/pull/970))
Expand All @@ -53,6 +55,7 @@ Fixes:
- 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

Expand Down
18 changes: 9 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,21 +17,24 @@ The stlink library and tools are licensed under the **[BSD-3 License](LICENSE.md

## Introduction

STLink is an open source toolset to program and debug STM32 devices and boards manufactured by STMicroelectronics.
stlink is an open source toolset to program and debug STM32 devices and boards manufactured by STMicroelectronics.
It supports several so called STLINK programmer boards (and clones thereof) which use a microcontroller chip to translate commands from USB to JTAG/SWD. There are four generations available on the market which are _all_ supported by this toolset:

- **STLINK/V1** _[obsolete as of 21-11-2019, continued support by this toolset] \*)_
- transport layer: SCSI passthru commands over USB
- stand-alone programmer and present on STM32VL Discovery boards
- stand-alone programmer
- on-board on STM32VL Discovery boards
- **STLINK/V2**
- transport layer: raw USB commands
- stand-alone programmer and present on STM32L Discovery and Nucleo boards
- stand-alone programmer
- on-board on STM32L Discovery and STM32 Nucleo boards
- **STLINK/V2-1**
- transport layer: raw USB commands
- present on some STM32 Nucleo boards
- **STLINK/V3**
- on-board on some STM32 Nucleo boards
- **STLINK-V3**
- transport layer: raw USB commands
- stand-alone programmer
- stand-alone programmer (STLINK-V3SET, STLINK-V3MINI, STLINK-V3MODS)
- on-board on some STM32 Nucleo boards

_\*)_ **Note: Support for the STLINK/V1 on macOS is limited to 10.14 - 10.15. Due to the deprecation and removal of macOS Kernel Extensions (KEXT) there will be no support for this programmer on macOS 11 or any later version.**

Expand All @@ -52,9 +55,6 @@ Currently known working combinations of programmers and targets are listed in [d

Supported operating systems are listed in [version_support.md](doc/version_support.md).

The `stlink` toolset continues to maintain backwards compatibility with the **STLINK/v1** programmer.<br />
Please note that on macOS this support is limited to versions 10.13 - 10.15.

## Tutorial & HOWTO

Our [tutorial](doc/tutorial.md) may help you along with some advanced tasks and additional info.
Expand Down
1 change: 1 addition & 0 deletions contributors.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,7 @@ Simon Wright
Stany Marcel
Stefan Misik
Sven Wegener
Tarek Bochkati [tarek-bochkati] (STMicroelectronics)
Timothy Lee [timothytylee]
Tuomo Kaikkonen
Theodore A. Roth
Expand Down
113 changes: 56 additions & 57 deletions doc/compiling.md
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,29 @@
# Compiling from sources

## Microsoft Windows (10, 8.1)

### Common Requirements

On Windows users should ensure that the following software is installed:

* `git` (_optional, but recommended_)
* `cmake` (3.17.0 or later)
* `MinGW-w64` (7.0.0 or later) with GCC toolchain 8.1.0

- `git` (_optional, but recommended_)
- `cmake` (3.17.0 or later)
- `MinGW-w64` (7.0.0 or later) with GCC toolchain 8.1.0

### Installation

1. Install `git` from <https://git-scm.com/download/win>
2. Install `cmake` from <https://cmake.org/download><br />
Ensure that you add cmake to the $PATH system variable when following the instructions by the setup assistant.
3. Install
- _EITHER_: **MinGW-w64** from <https://sourceforge.net/projects/mingw-w64> (mingw-w64-install.exe)<br />
- _OR_: **MSVC toolchain** from Visual Studio Build Tools 2019

- _EITHER_: **MinGW-w64** from <https://sourceforge.net/projects/mingw-w64> (mingw-w64-install.exe)<br />
- _OR_: **MSVC toolchain** from Visual Studio Build Tools 2019

4. Create a new destination folder at a place of your choice
5. Open the command-line (cmd.exe) and execute `cd C:\$Path-to-your-destination-folder$\`
6. Fetch the project sourcefiles by running `git clone https://github.com/stlink-org/stlink.git`from the command-line (cmd.exe)<br />
or download the stlink zip-sourcefolder from the Release page on GitHub
or download the stlink zip-sourcefolder from the Release page on GitHub

#### MSVC toolchain - minimal installation

Expand All @@ -31,15 +33,19 @@ Visual Studio IDE is not necessary, only Windows SDK & build tools are required
2. Navigate through menus as follows (might change overtime)

`All downloads > Tools for Visual Studio 2019 > Build Tools for Visual Studio 2019 > Download`

3. Start downloaded executable. After Visual Studio Installer bootstraps and main window pops up, open `Individual Components` tab, and pick
- latest build tools (eg. `MSVC v142 - VS 2019 C++ x64/x86 build tools (v14.25)`)
- latest Windows SDK (eg. `Windows 10 SDK (10.0.18362.0)`)

- latest build tools (eg. `MSVC v142 - VS 2019 C++ x64/x86 build tools (v14.25)`)
- latest Windows SDK (eg. `Windows 10 SDK (10.0.18362.0)`)

4. After installation finishes, you can press `Launch` button in Visual Studio Installer's main menu.
- Thus you can open `Developer Command Prompt for VS 2019`. It is `cmd.exe` instance with adjusted PATHs including eg. `msbuild`.
- Alternatively, you can use `Developer Powershell for VS 2019` which is the same thing for `powershell.exe`. Both are available from Start menu.
- Another option is to add `msbuild` to PATH manually. Its location should be `C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\MSBuild\Current\Bin`. Then, it should be available from any `powershell.exe` or `cmd.exe` session.

### Building

#### MinGW-w64

1. Use the command-line to move to the `scripts` directory within the source-folder: `cd stlink\scripts\`
Expand All @@ -50,7 +56,6 @@ Per default the build script (currently) uses `C:\Program Files\mingw-w64\x86_64
When installing different toolchains make sure to update the path in the `mingw64-build.bat`.<br />
This can be achieved by opening the .bat file with a common text editor.


#### MSVC toolchain

1. In a command prompt, change the directory to the folder where the stlink files were cloned (or unzipped) to.
Expand All @@ -59,12 +64,15 @@ This can be achieved by opening the .bat file with a common text editor.

This will create a solution file `stlink.sln` in the build folder.
Now, you can build whole `stlink` suite using following command:

```
msbuild /m /p:Configuration=Release stlink.sln
```

Options:

- `/m` - compilation runs in parallel utilizing multiple cores
- `/p:Configuration=Release` - generates *Release*, optimized build.
- `/p:Configuration=Release` - generates _Release_, optimized build.

Directory `<project_root>\build\Release` contains final executables.
(`st-util.exe` is located in `<project_root>\build\src\gdbserver\Release`).
Expand All @@ -79,33 +87,32 @@ It can be copied from: `<project_root>\build\3rdparty\libusb-{version}\MS{arch}\
[ST-LINK drivers](https://www.st.com/en/development-tools/stsw-link009.html) are required for `stlink` to work.

## Linux

### Common requirements

Install the following packages from your package repository:

* `git`
* `gcc` or `clang` or `mingw32-gcc` or `mingw64-gcc` (C-compiler; very likely gcc is already present)
* `build-essential` (on Debian based distros (Debian, Ubuntu))
* `cmake` (3.4.2 or later, use the latest version available from the repository)
* `rpm` (on Debian based distros (Debian, Ubuntu), needed for package build with `make package`)
* `libusb-1.0`
* `libusb-1.0-0-dev` (development headers for building)
* `libgtk-3-dev` (_optional_, needed for `stlink-gui`)
* `pandoc` (_optional_, needed for generating manpages from markdown)
- `git`
- `gcc` or `clang` or `mingw32-gcc` or `mingw64-gcc` (C-compiler; very likely gcc is already present)
- `build-essential` (on Debian based distros (Debian, Ubuntu))
- `cmake` (3.4.2 or later, use the latest version available from the repository)
- `rpm` (on Debian based distros (Debian, Ubuntu), needed for package build with `make package`)
- `libusb-1.0`
- `libusb-1.0-0-dev` (development headers for building)
- `libgtk-3-dev` (_optional_, needed for `stlink-gui`)
- `pandoc` (_optional_, needed for generating manpages from markdown)

or execute (Debian-based systems only): `apt-get install gcc build-essential cmake libusb-1.0 libusb-1.0-0-dev libgtk-3-dev pandoc`

(Replace gcc with the intended C-compiler if necessary or leave out any optional package not needed.)


### Installation

1. Open a new terminal console
2. Create a new destination folder at a place of your choice e.g. at `~/git`: `mkdir $HOME/git`
3. Change to this directory: `cd ~/git`
4. Fetch the project sourcefiles by running `git clone https://github.com/stlink-org/stlink.git`


### Building

#### Installation:
Expand All @@ -120,21 +127,19 @@ or execute (Debian-based systems only): `apt-get install gcc build-essential cma

As an option you may also install to an individual user-defined folder e.g `$HOME` with `make install DESTDIR=$HOME`.


#### Removal:
#### Removal:

1. Run `make uninstall` to perform a clean uninstall of the package from the system.
2. Run `make clean` to clean the build-folder within the project source and remove all compiled and linked files and libraries.


### Cross-Building for Windows

Install the following packages from your package repository:

* `mingw-w64`
* `mingw-w64-common`
* `mingw-w64-i686-dev`
* `mingw-w64-x86-64-dev`
- `mingw-w64`
- `mingw-w64-common`
- `mingw-w64-i686-dev`
- `mingw-w64-x86-64-dev`

After following the steps for installation above, proceed with from the build dircetory itself:

Expand All @@ -144,7 +149,6 @@ $ sudo sh ./cmake/packaging/windows/generate_binaries.sh

The generated zip-packages can be found in the subdirectory `./build/dist`.


### Set device access permissions and the role of udev

By default most distributions don't allow access to USB devices.
Expand All @@ -162,44 +166,42 @@ $ sudo udevadm trigger

udev will now create device node files, e.g. `/dev/stlinkv3_XX`, `/dev/stlinkv2_XX`, `/dev/stlinkv1_XX`.


### Special note on the use of STLink/V1 programmers (legacy):

As the STLINKV1's SCSI emulation is somehow broken, the best advice possibly is to tell your operating system to completely ignore it.<br />
Choose one of the following options _before_ connecting the device to your computer:

* `modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i`
* _OR_
1. `echo "options usb-storage quirks=483:3744:i" >> /etc/modprobe.conf`
2. `modprobe -r usb-storage && modprobe usb-storage`
* _OR_
1. `cp stlink_v1.modprobe.conf /etc/modprobe.d`
2. `modprobe -r usb-storage && modprobe usb-storage`

- `modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i`
- _OR_
1. `echo "options usb-storage quirks=483:3744:i" >> /etc/modprobe.conf`
2. `modprobe -r usb-storage && modprobe usb-storage`
- _OR_
1. `cp stlink_v1.modprobe.conf /etc/modprobe.d`
2. `modprobe -r usb-storage && modprobe usb-storage`

## macOS

### Common requirements

The best and recommended way is to install a package manager for open source software,
either [homebrew](https://brew.sh) or [MacPorts](https://www.macports.org/).

Then install the following dependencies from the package repository:

* `git`
* `gcc` or `llvm` (for clang) (C-compiler)
* `cmake`
* `libusb`
* `gtk+3` or `gtk3` (_optional_, needed for `stlink-gui`)
- `git`
- `gcc` or `llvm` (for clang) (C-compiler)
- `cmake`
- `libusb`
- `gtk+3` or `gtk3` (_optional_, needed for `stlink-gui`)

To do this with only one simple command, type:

* for homebrew:
- with gcc: `sudo brew install git gcc cmake libusb gtk+3` or
- with clang: `sudo brew install git llvm cmake libusb gtk+3` or
* for MacPorts:
- with gcc: `sudo port install git gcc10 cmake libusb gtk3` or
- with clang: `sudo port install git llvm-10 cmake libusb gtk3`

- for homebrew:
- with gcc: `sudo brew install git gcc cmake libusb gtk+3` or
- with clang: `sudo brew install git llvm cmake libusb gtk+3` or
- for MacPorts:
- with gcc: `sudo port install git gcc10 cmake libusb gtk3` or
- with clang: `sudo port install git llvm-10 cmake libusb gtk3`

### Installation

Expand All @@ -208,7 +210,6 @@ To do this with only one simple command, type:
3. Change to this directory: `cd ~/git`
4. Fetch the project sourcefiles by running `git clone https://github.com/stlink-org/stlink.git`


### Building

1. Change into the project source directory: `cd stlink`
Expand All @@ -217,23 +218,21 @@ To do this with only one simple command, type:
4. Run `make debug` to create the _Debug_ target (_optional_)<br />
The debug target is only necessary in order to modify the sources and to run under a debugger.


## Build options

### Build using a different directory for shared libs

To put the compiled shared libs into a different directory during installation,
you can use the cmake option `cmake -DLIB_INSTALL_DIR:PATH="/usr/lib64" ..`.


### Standard installation directories

The cmake build system of this toolset includes `GNUInstallDirs` to define GNU standard installation directories.
This module provides install directory variables as defined by the GNU Coding Standards.

Below are the preset default cmake options, which apply if none of these options are redefined:

* `-DCMAKE_INSTALL_SYSCONFDIR=/etc`
* `-DCMAKE_INSTALL_PREFIX=/usr/local`

- `-DCMAKE_INSTALL_SYSCONFDIR=/etc`
- `-DCMAKE_INSTALL_PREFIX=/usr/local`

Author: nightwalker-87
Loading

0 comments on commit 5e0a502

Please sign in to comment.