This post is also available in: cs

Development tools are probably the biggest weakness of the whole STM8 ecosystem. The manufacturer provides the STVD development environment (guide here (in Czech)), which is adequate, but old and no longer developed. Sometimes it is hard to get it running on a particular PC. The Cosmic compiler does work, but the constant license checking is really annoying; … and its error messages didn’t seem very clear to me either.
And I haven’t even mentioned the main point: It doesn’t run on Linux!

tools %%

That is why I created a toolchain that relies on OpenSource tools. If you want to use this toolchain, you need to install these tools:

  1. Development environment
  2. Compiler
  3. Programmer/Flasher — software to upload the program to the chip
  4. Debugger

When I was putting all this together, this page helped me a lot, so you can take a look: https://github.com/hbend1li/stm8_started.

Pre-prepared Installation

I have prepared a teaching image of Devuan Linux, where everything is already set up and installed. So you don’t need to install everything manually, just:

  1. install VirtualBox
  2. install the Extension Pack into VirtualBox
  3. download the prepared image: Devuan-X+MIT.ova and import it.

A few notes about the image:

How to use VirtualBox and the prepared image (in Czech):
MIT-Virtualbox

… but still read the text below so you know how to use it.

Pre-built Packages

Hint

If you have a Linux distribution based on Debian (Ubuntu, Mint, Devuan, …), you don’t need to compile anything complicated. Just use our repository and install the ready-made (precompiled) packages.

Prepared repository:

https://mamut.spseol.cz/debian/

Just enter:

1
2
3
4
5
6
sudo curl -fsSL https://mamut.spseol.cz/debian/mamut-archive-keyring.gpg -o /etc/apt/keyrings/mamut-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/mamut-archive-keyring.gpg] https://mamut.spseol.cz/debian mamut main" | sudo tee /etc/apt/sources.list.d/mamut.list

sudo apt update
sudo apt install make openocd git fzf python3-serial cgdb ccls
sudo apt -t mamut install stm8flash stm8-binutils-gdb stm8newproject sdcc sdcc-libraries glabproject

… and everything you need is installed.

If you use another Linux distribution or a different OS, or you simply want more control over what you install, see the separate article: Installing/Compiling the tools for the STM8 toolchain.

What you actually installed with the prepared packages:

Toolchain

The core of the whole toolchain is a Makefile, complemented by several helper scripts (the .make directory) and a starting source code tree of the project:

https://gitlab.com/spseol/mit-no/STM8S-toolchain

The toolchain can be used on Linux, macOS and Windows. But it is developed and primarily intended for Linux, and that is where it works best.

It is very simple to use: download, unpack or clone the toolchain repository. This gives you a folder with a new project, and inside it you just run make commands (see the overview in Usage).

Projects and SPL Library

The directory structure of individual projects looks like this:

MIT
├── Project-1
│   ├── inc
│   ├── lib
│   └── src
├── Project-blikblik
│   ├── inc
│   ├── lib
│   └── src
├── SPL
│   ├── inc
│   └── src
└── SPLSPL
    ├── inc
    └── src

Make a directory where all your projects will be — in the example above it is MIT. In the same directory there will also be directories named SPL and SPLSPL. In the SPL directories is the Standard Peripheral Library from ST. This library has quite a strange license and therefore I can’t just give it to you. You should find it and download it. Then you also need to apply a patch, which converts the library so it can be used with our SDCC compiler. The whole process is quite a lot of work, … but try typing make spl — maybe it will sort itself out.

Creating a new project

Creating a project can be automated with a set of scripts available in the repository STM8S new project automation. It is the content of the stm8newproject package mentioned above. If you install it, just run the command stm8newproject or stm8newproject.gui.

Further automation is available in the repository GitLab project interactive CLI, which can make creating a new project on GitLab much easier.

Usage

Everything is controlled with the make program. In the project directory you just run the following commands:

  • make spl — downloads and prepares libraries
  • make — compiles the project
  • make flash — uploads the program to the chip (when make debug is running, the program is only compiled and the debugger uploads it to the chip)
  • make clean — deletes everything that was compiled
  • make rebuild — deletes everything and compiles again
  • make debug — debugging with one command: compiles, uploads, stops at main() and opens cgdb

The toolchain can do more… just keep reading or see the project README.

I should also mention that my colleague Wykys has also created a toolchain, which is much simpler and therefore easier to read:

https://gitlab.com/wykys/stm8-tools

Development Environment

I use Vim or rather Neovim. Not everyone likes this environment though, so as an editor and development environment I recommend VScodium/VScode.

Installation is described here.

For features like code completion, go-to-definition, or inline error highlighting you need an LSP server. I recommend using ccls instead of the C/C++ extension from Microsoft. The C/C++ extension does not always behave correctly with embedded platforms, while ccls works reliably, IMHO.

ccls is optional. When compiling, the toolchain creates the file compile_commands.json itself, from which ccls learns the compiler flags and the paths to header files, so you don’t have to configure anything by hand. On Debian and derived distributions you install it from the ccls package (it is in the command in Pre-built Packages); for other systems the installation is described here.

Then install the ccls extension in VSCode/Codium — in VSCode from the Marketplace, in VSCodium from Open VSX.

Alternative: clangd

An alternative to ccls is the LSP server clangd, which also works quite well. It uses the same compile_commands.json file. The clangd extension is on the Marketplace for VSCode and on Open VSX for VSCodium. On Debian you install it from the clangd package.

Compilation — SDCC

Watch out for SDCC version

SDCC version 4.5.0 is unusable for the STM8 platform. See the details in SDCC installation.

SDCC - Small Device C Compiler is a compiler for various, more or less known 8-bit architectures. For STM8 it has one major disadvantage: it cannot remove unused (dead) code. What does this mean? Well… if you write everything yourself, it practically means nothing. But if you use some library (such as SPL), you will start to be bothered a lot, because the resulting machine code contains many functions that you compiled only because they were part of the library — not because you wanted to use them. These functions are not called anywhere and so the linker should remove them. And that is exactly what doesn’t happen :-(. As a result, a program that could be about 2-3 kB ends up being 30 kB.

Fortunately there is one hack, which works roughly like this: The SPL library is split into small files (one function per file) and each is compiled as a separate module. These modules are made into a library, which the SDCC linker can already work with correctly. That is why the SPL library appears twice in the directory structure. SPLSPL stands for SPLit SPL and is used exactly for this.

There are other solutions, SDCC-gas and sdccrm, but they are historical: the projects are unmaintained and SPLSPL is more than enough today. For the curious, you can find them in a separate article Dead code removal in SDCC.

SDCC installation for Linux, macOS and Windows is described here.

Flashing

The program is uploaded to the chip through an ST-LINK programmer. The toolchain can do it with three tools, and which one is used depends on the command and the operating system:

  • make flash — OpenOCD on Linux and macOS, STVP on Windows. This is the default choice, which works on all systems.
  • make stm8flash — always stm8flash.
  • make debug — the debugger uploads the program itself, so you don’t need to flash manually.

STVP

STVP is software from the chip manufacturer ST for Windows. It allows access to all parts of microcontroller memory. It has a graphical version and a command-line version. It is the command-line version (STVP_CmdLine.exe) that our toolchain relies on; if you use it on Windows, the make flash command uses it to flash the chip. You just need to have STVP installed.

OpenOCD

Open On-Chip Debugger is a tool for debugging and stepping through a program directly on the chip. openocd can also upload a program to the device memory. It works on Linux, macOS and Windows.

Installation and the script for the flashing itself (which is part of the toolchain) are described here.

stm8flash

Another option is the program stm8flash. We have it in our repository.

https://github.com/vdudouyt/stm8flash

stm8flash is a small command-line tool that communicates with the chip through the SWIM interface of the ST-LINK programmer. For a long time it was the only tool on Linux that could do this; OpenOCD has been able to flash only since 2018, and stm8flash still supports more chips and handles memory better (it can read, verify and write it, including the EEPROM). In the toolchain you use it with the make stm8flash command, which uploads the compiled program (out.ihx). The make stm8flash-unlock command writes values into the option bytes that turn off read-out protection (ROP) — handy when the chip is “locked” and cannot be flashed.

Installation for other systems and building from source code are described here.

Debugging

Communication with the chip: OpenOCD

openocd — Open On-Chip Debugger — is the tool we use to communicate with the chip and start/stop/step through the program. This tool handles communication between the debugger and the chip via the ST-LINK debug interface. Installation is described here.

OpenOCD is run on its own like this:

1
openocd -f .make/stm8s-flash.cfg -f interface/stlink-dap.cfg -f target/stm8s103.cfg -c "init" -c "reset halt"

(The example is for the STM8S103 chip; for other chips the target/*.cfg file changes — stm8s003.cfg, stm8s105.cfg, in general stm8s.cfg.)

Don’t worry, you don’t have to type this every time. It is written in the Makefile, which picks the right target according to the chip, so just call:

1
make openocd

Running OpenOCD on its own is useful only for connecting GDB by hand or for graphical tools such as VSCode, which connect to port 3333.

For debugging you don’t need to start OpenOCD by hand: the make debug command starts it itself and stops it again when debugging ends (details in the article A small STM8-GDB course).

1
make debug

STM8-GDB

GDB (GNU Debugger) is the standard tool for finding bugs in software. It allows you to stop the program, step through it, and look at variables while it runs — or even change them. For the STM8 platform you need the modified STM8-GDB from GNU binutils. Installation is described here.

GDB is a text tool. My recommendation: don’t be put off and use GDB directly, or its lightweight wrapper cgdb. Both tools are described in detail in a separate article (in Czech) A small STM8-GDB course.

In our toolchain, debugging is started with one command:

1
make debug

This command compiles the project, starts OpenOCD, uploads the program to the chip, stops at the beginning of main() and opens cgdb. If you modify the program while debugging, just call make flash in another terminal and the debugger uploads the new program to the chip itself.

A small STM8-GDB course

You can find more detailed information in a separate article (in Czech): A small STM8-GDB course.

GDB mascot

A small STM8-GDB course

All other graphical tools use GDB as a backend. Their advantage and disadvantage is the GUI, which may be more attractive to many people, but on the other hand you may lose some features such as conditional breakpoints.

Debugging in VS Code and VSCodium

Debugging with make debug — breakpoints, stepping, variables and peripheral registers, see A small STM8-GDB course — can also be controlled by clicking in the VSCodium or VS Code editor (installation of the editor is described here). This is done by the STM8 Toolchain Debugger extension. Under the hood it runs the same stm8-gdb and the same OpenOCD as make debug, so everything from A small STM8-GDB course applies here too. The debug console even accepts GDB commands, including sfr and p TIM4->CR1.

The extension is tested on Linux. Everything except STM8 binutils-gdb is tested on macOS as well, so if you manage to get stm8-gdb running there, it will work too. On macOS you only need to install all the dependencies. Windows is neither supported nor tested.

Only one debugger at a time

The ST-LINK can be held by only one program, so you cannot have make debug (cgdb) and debugging in the editor running at the same time.

Installing the extension

For debugging you need the same as for make debug: make, python3, git, SDCC, OpenOCD and stm8-gdb version 15 or newer with Python and DAP support (see Installation) and an ST-LINK. Node.js and npm are not needed.

stm8-gdb is not part of the extension, you must have it installed beforehand. It is a special build of GDB for STM8 (STM8 binutils-gdb), the procedure is in the article Installing/Compiling the tools for the STM8 toolchain.

The extension is called spseol.stm8-toolchain. In the editor you will find it in the Extensions panel by searching for STM8 Toolchain:

The extension can also be installed from a project created from our toolchain, without a marketplace:

1
make vscode

The command packages the extension and installs it into all code and codium editors it finds (make vscode IDES=codium selects just one). Restart the editor after installation.

New project

Open the command palette (Ctrl+Shift+P) and choose STM8: New Project…. In an empty editor window where you do not have any folder open yet, it is enough to click the New STM8 Project button in the Explorer panel. The extension:

  1. asks for the folder for projects (setting stm8.projectsFolder) and for the project name. All projects should live in one folder, because they share the SPL library in ../SPLSPL,
  2. clones the toolchain from GitLab and prepares a git repository with a single commit (the original history of the toolchain stays in the upstream branch),
  3. opens the project. The first build downloads the SPL library, which requires internet.

You choose the target chip by clicking in the bottom status bar (it changes DEVICE_FLASH in the Makefile).

Older project

You update a project created earlier with the STM8: Update Toolchain command. The extension offers it by itself when you open a project with an older toolchain. The same can be done from the terminal with make upgrade, but that target exists only in projects that have already gone through the new toolchain once.

The update replaces .make/ and .vscode/launch.json, adds missing lines to .gitignore and merges your Makefile with the new version: your settings for the chip, frequency and compiler path stay. If your changes collide with the new ones, it leaves conflict markers (<<<<<<<) in the Makefile and the project will not build until you fix them. Source files (src/, inc/) and the README are not changed. Nothing is committed, so you can check the result with git diff. Changes in .make/, Makefile and launch.json must be committed before the update, otherwise the extension refuses it.

Debugging

Press F5 (the STM8 debug configuration). Just like make debug, the extension:

  1. builds the project with debug information (compiler errors show up in the Problems panel),
  2. starts OpenOCD and flashes the program into the chip,
  3. stops the program at the beginning of main().

Then you debug as in other editors: you set a breakpoint by clicking next to the line number, step with the buttons on the toolbar (or F10, F11), and see variables in the side panel, in Watch, and when hovering the mouse over an expression in the code.

The Run and Debug side panel gains an STM8 Peripherals view. It is sfr as a tree: the peripherals of your chip, their registers and bits. Values are read at every stop and whatever changed since the previous stop is highlighted in yellow. By ticking a single-bit field you write the bit; with the pencil on a register or a multi-bit field you enter a new value (decimal, 0x… or 0b…).

Registers whose reading clears flags (UART1->DR, SPI->DR, …) behave the same as in the sfr command: the tree does not read them by itself. You read them with the Read icon. Hovering the mouse over an expression in the code does not read them either.

The bottom status bar has the Build, Flash, Debug buttons and the chip selector.

When something does not work

message what to do
Old toolchain – run STM8: Update Toolchain … the project is old, run STM8: Update Toolchain
stm8-gdb 15 or newer is required / not found in PATH install stm8-gdb following the installation article
No ST-Link found on USB connect the board, on Linux check the udev rules
make debug is running (PID …) close cgdb, only one debugger can run at a time
ST-Link may be in use by another OpenOCD … quit the other OpenOCD (make openocd, another editor window)
… timed out after 30 s the chip does not respond, check the cable and power; the OpenOCD log is in build-*-elf/openocd.log

You will find the GDB output in the Output panel in the STM8 debug channel.

Details about the extension, its settings and limitations are in its README.


Other VScode/Codium extensions

You can play around and try various extensions for VSCode/Codium. You will certainly need to edit the .vscode/launch.json file in the project and correctly link it with stm8-gdb.

Here is a list of a few extensions that might work. There are guides on the internet suggesting they do work. I personally never managed to get it running to my full satisfaction and I stick with my favourite cgdb. If you succeed, please let me know.

Here is also a draft of my .vscode/launch.json for Native Debug.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "gdb-stm8",
            "type": "gdb",
            "request": "attach",
            "executable": "${workspaceRoot}/out.elf",
            "gdbpath": "stm8-gdb",
            "remote": true,
            "target": ":3333",
            "cwd": "${workspaceRoot}",
            "autorun": [
            ]
        }
    ]
}