libopencm3 / libopencm3-template

Simple empty template to base your poject on

README

The libopencm3 project aims to create an open-source firmware library for various ARM Cortex-M microcontrollers.

Currently (at least partly) supported microcontrollers:

• ST STM32 F0xx/F1xx/F2xx/F30x/F37x/F4xx/F7xx/H7xx series
• ST STM32 G0xx G4xx L0xx L1xx L4xx series
• Atmel SAM3A/3N/3S/3U/3X series, as well as SAMDxx and friends
• NXP LPC1311/13/17/42/43
• Stellaris LM3S series (discontinued, without replacement)
• TI (Tiva) LM4F series (continuing as TM4F, pin and peripheral compatible)
• EFM32 Gecko series (only core support)
• Freescale Vybrid VF6xx
• Qorvo (formerly ActiveSemi) PAC55XX
• Synwit SWM050
• Nordic NRF51x and NRF52x

The library is written completely from scratch based on the vendor datasheets, programming manuals, and application notes. The code is meant to be used with a GCC toolchain for ARM (arm-elf or arm-none-eabi), flashing of the code to a microcontroller can be done using the OpenOCD ARM JTAG software.

Status and API

The libopencm3 project is (and presumably, always will be) a work in progress. Not all subsystems of all microcontrollers are supported, yet, though some parts have more complete support than others.

Prior to version 0.8.0, the api was largely in flux. Attempts were made to provide backwards compatibility, but this was not always considered critical.

From 0.8.0 to 1.0, we'll atempt to follow semver, but EXPECT CHANGES, as we attempt to clear up old APIs and remove deprecated functions. The 0.8.0 tag was placed to provide the "old stable" point before all the new code started landing.

preview code often lands in the "wildwest-N" branches that appear and disappear in the repository. Pull requests marked as "merged-dev" will be in this branch, and will be closed when they merge to master. This is useful for bigger interdependent patch sets, and also allows review of merge conflicts in public.

From 1.0, expect to follow semver, with functions (and defines!) being deprecated for a release before being removed.

TIP: Include this repository as a Git submodule in your project to make sure your users get the right version of the library to compile your project. For how that can be done refer to the libopencm3-template repository.

Prerequisites

Building requires Python (some code is generated).

For Ubuntu/Fedora:

• An arm-none-eabi/arm-elf toolchain.

For Windows:

Download and install:

• msys - http://sourceforge.net/projects/mingw/files/MSYS/Base/msys-core/msys-1.0.11/MSYS-1.0.11.exe
• Python - https://www.python.org/downloads/windows/ (any release)
• arm-none-eabi/arm-elf toolchain (for example this one https://launchpad.net/gcc-arm-embedded)

Run msys shell and set the path without standard Windows paths (adjusting to your version of Python), so Windows programs such as 'find' won't interfere:

export PATH="/c//Program Files/Python 3.9:/c/ARMToolchain/bin:/usr/local/bin:/usr/bin:/bin"

After that you can navigate to the folder where you've extracted libopencm3 and build it.

Toolchain

The most heavily tested toolchain is "gcc-arm-embedded" This used to be available at https://launchpad.net/gcc-arm-embedded

Other toolchains should work, but they have not been nearly as well tested. Toolchains targeting Linux, such as "gcc-arm-linux-gnu" or the like are not appropriate.

NOTE: GCC version 6 or later is required, as we're using attributes on enumerators to help mark deprecations.

Building

$ make

If you have an arm-elf toolchain (uncommon) you may want to override the toolchain prefix (arm-none-eabi is the default)

$ PREFIX=arm-elf make

For a more verbose build you can use

$ make V=1

You can reduce the build time by specifying a particular MCU series

$ make TARGETS='stm32/f1 stm32/f4'

Supported targets can be listed using:

$ make list-targets

Fine-tuning the build

The build may be fine-tuned with a limited number of parameters, by specifying them as environment variables, for example:

$ VARIABLE=value make

• FP_FLAGS - Control the floating-point ABI

  If the Cortex-M core supports a hard float ABI, it will be compiled with the best floating-point support by default. In cases where this is not desired, the behavior can be specified by setting FP_FLAGS.

  Currently, M4F cores default to -mfloat-abi=hard -mfpu=fpv4-sp-d16, and M7 cores defaults to double precision -mfloat-abi=hard -mfpu=fpv5-d16 if available, and single precision -mfloat-abi=hard -mfpu=fpv5-sp-d16 otherwise. Other architectures use no FP flags, in otherwords, traditional softfp.

  You may find which FP_FLAGS you can use in a particular architecture in the readme.txt file shipped with the gcc-arm-embedded package.

  Examples:

    $ FP_FLAGS="-mfloat-abi=soft" make               # No hardfloat
    $ FP_FLAGS="-mfloat-abi=hard -mfpu=magic" make   # New FPU we don't know of
  

• CFLAGS - Add to or supersede compiler flags

  If the library needs to be compiled with additional flags, they can be passed to the build system via the environment variable CFLAGS. The contents of CFLAGS will be placed after all flags defined by the build system, giving the user a way to override any default if necessary.

  Examples:

    $ CFLAGS="-fshort-wchar" make    # Compile lib with 2 byte wide wchar_t
  

Example projects

The libopencm3 community has written and is maintaining a huge collection of examples, displaying the capabilities and uses of the library. You can find all of them in the libopencm3-examples repository:

https://github.com/libopencm3/libopencm3-examples

If you just wish to test your toolchain and build environment, a collection of mini blink projects is available too. This covers many more boards, but, as the name suggests, only demonstrates blinking LEDs.

https://github.com/libopencm3/libopencm3-miniblink

Installation

Simply pass -I and -L flags to your own project. See the libopencm3-template repository for a template repository using this library as a Git submodule, the most popular method of use. The libopencm3-examples is another example of this.

It is strongly advised that you do not attempt to install this library to any path inside your toolchain itself. While this means you don't have to include any -I or -L flags in your projects, it is very easy to confuse a multi-library linker from picking the right versions of libraries. Common symptoms are hardfaults caused by branches into ARM code. You can use arm-none-eabi-objdump to check for this in your final ELF file. You have been warned.

Coding style and development guidelines

See HACKING.

License

The libopencm3 code is released under the terms of the GNU Lesser General Public License (LGPL), version 3 or later.

See COPYING.GPL3 and COPYING.LGPL3 for details.

Community

• Our
• Our IRC channel on the libera.chat IRC network is called #libopencm3

Mailing lists

• Developer mailing list (for patches and discussions): https://lists.sourceforge.net/lists/listinfo/libopencm3-devel

• Commits mailing list (receives one mail per git push): https://lists.sourceforge.net/lists/listinfo/libopencm3-commits

Website

• http://libopencm3.org - contains daily autogenerated API documentation

libopencm3-template's Issues

clone and go fails at step 5

The clone and go instruction work fine for steps 1 - 4.
On step 5 I get the following :

mpe@ubuntu:~/mpe$ make -C my-project
make: Entering directory '/home/mpe/mpe/my-project'
CC my-project.c
my-project.c:2:10: fatal error: api-asm.h: No such file or directory
#include "api-asm.h"
^~~~~~~~~~~
compilation terminated.
../rules.mk:126: recipe for target 'bin/my-project.o' failed
make: *** [bin/my-project.o] Error 1
make: Leaving directory '/home/mpe/mpe/my-project'

The OS is Ubuntu 16.04.2
The ARM tools are installed, and libopencm3 build without any problems.
From just looking at the directories, everything looks to be right.
The directories specified in the Makefile look correct too.

No rule to make target '.bin'

Got an error after cleaning some of code.
What I did:

1. git clone and update submodules
2. removed my-common-files/ dir
3. rewrote main.c to only contain empty main function.
4. rewrote Makefile, changing basic things.
5. Build lib in libopencm3/ with make.
6. Build in stm/ (old my-project) and got an error.

  CC	main.c
  GENLNK  stm32f103c8t6
  LD	stm32
  LD	.elf
make: *** No rule to make target '.bin', needed by 'all'.  Stop.

Here is how my Makefile looks like:

PROJECT = stm32
BUILD_DIR = bin

CFILES = main.c

# TODO - you will need to edit these two lines!
DEVICE=stm32f103c8t6
OOCD_FILE = board/stm32f103c8t6discovery.cfg

# You shouldn't have to edit anything below here.
VPATH += $(SHARED_DIR)
INCLUDES += $(patsubst %,-I%, . $(SHARED_DIR))
OPENCM3_DIR=../libopencm3

include $(OPENCM3_DIR)/mk/genlink-config.mk
include ../rules.mk
include $(OPENCM3_DIR)/mk/genlink-rules.mk

Can suppose I'm not the only one getting this error. Getting this error on multiple devices and OS. Hope I'm just missing some basic knowledge and it is not a bug.

create a C++ example

How to enable printf with float argument?

In the libopencm3-examples repository there is a usart_printf example. When compiling the examples this printf("float: %f", 3.21f); works as expected.

Using this repository (libopencm3-template), the printf("float: %f", 3.21f); doesn't do anything (skips the line). Some searching did reveal you should add LDFLAGS += -u _printf_float to the make file. This didn't
work for me. Any pointers on how to make this work?

update:
Got it working, added LDFLAGS += -u _printf_float to the Makefile. Not sure what went wrong the first time.

Additional Problem with Template

KARLP: (I added this to the closed issue....but added it here also since I wasn't sure if a closed issue would be 'seeable' by you and others).

Thanks much. That helped get me past the 1st step (make -C libopencm3)
Now, however, it's failing on the 2nd step (make -C my-project)

Here are the error messages (and I think it's still a python vs python3 issue);

JR-iMac5K :: ~/myproject ‹master*› » make -C my-project
env: python: No such file or directory
env: python: No such file or directory
env: python: No such file or directory
env: python: No such file or directory
env: python: No such file or directory
../libopencm3/mk/genlink-config.mk:47: No match for the FPU flags
../libopencm3/mk/genlink-config.mk:52: stm32f407vgt6 not found in ../libopencm3/ld/devices.data
../libopencm3/mk/genlink-config.mk:63: ../libopencm3/lib/libopencm3_.a library variant for the selected device does not exist.
CC my-project.c
arm-none-eabi-gcc: error: missing argument to '-mcpu='
make: *** [bin/my-project.o] Error 1

Again - any help would be greatly appreciated!

libopencm3 and libopencm3-template have different PREFIX syntax

The former appends - to the end of it, the latter doesn't.

flashing of a template project without verbose option fails

There's a superfluous silencer $(Q) placed in the makefile

libopencm3-template/rules.mk

Line 156 in ef986d2

$(Q)$(OOCD) -f $(OOCD_FILE) \

that causes an @ character to be placed in front of the openocd command

$ make -n flash
printf " FLASH\tyour-project.elf\n"
(echo "halt; program /home/dem/Code/your-project/my-project/your-project.elf verify reset" | nc -4 localhost 4444 2>/dev/null) ||
@openocd -f ../board/bluepill.cfg
-c "program /home/dem/Code/your-project/my-project/your-project.elf verify reset exit"
2>/dev/null

which makes make flash fail unless the verbose option is added.

$ make flash
CC my-project.c
CC ../my-common-code/api.c
GENLNK stm32f103c8t6
LD your-project.elf
FLASH your-project.elf
../rules.mk:147: recipe for target 'your-project.flash' failed
make: *** [your-project.flash] Error 127

$ make V=1 flash
CC my-project.c
arm-none-eabi-gcc -Os -std=c99 -ggdb3 -mcpu=cortex-m3 -mthumb -msoft-float -fno-common -ffunction-sections -fdata-sections -Wextra -Wshadow -Wno-unused-variable -Wimplicit-function-declaration -Wredundant-decls -Wstrict-prototypes -Wmissing-prototypes -MD -Wall -Wundef -I. -I../my-common-code -I. -I../libopencm3/include -I. -I../my-common-code -I. -I../libopencm3/include -DSTM32F1 -DSTM32F103C8T6 -I../libopencm3/include -o bin/my-project.o -c my-project.c
CC ../my-common-code/api.c
arm-none-eabi-gcc -Os -std=c99 -ggdb3 -mcpu=cortex-m3 -mthumb -msoft-float -fno-common -ffunction-sections -fdata-sections -Wextra -Wshadow -Wno-unused-variable -Wimplicit-function-declaration -Wredundant-decls -Wstrict-prototypes -Wmissing-prototypes -MD -Wall -Wundef -I. -I../my-common-code -I. -I../libopencm3/include -I. -I../my-common-code -I. -I../libopencm3/include -DSTM32F1 -DSTM32F103C8T6 -I../libopencm3/include -o bin/api.o -c ../my-common-code/api.c
GENLNK stm32f103c8t6
arm-none-eabi-gcc -E -mcpu=cortex-m3 -mthumb -msoft-float -DSTM32F1 -DSTM32F103C8T6 -D_ROM=64K -D_RAM=20K -D_ROM_OFF=0x08000000 -D_RAM_OFF=0x20000000 -P -E ../libopencm3/ld/linker.ld.S > generated.stm32f103c8t6.ld
LD your-project.elf
arm-none-eabi-gcc -Tgenerated.stm32f103c8t6.ld -L../libopencm3/lib -nostartfiles -mcpu=cortex-m3 -mthumb -msoft-float -specs=nano.specs -Wl,--gc-sections -L../libopencm3/lib bin/my-project.o bin/api.o -lopencm3_stm32f1 -Wl,--start-group -lc -lgcc -lnosys -Wl,--end-group -o your-project.elf
FLASH your-project.elf
(echo "halt; program /home/dem/Code/your-project/my-project/your-project.elf verify reset" | nc -4 localhost 4444 2>/dev/null) ||
openocd -f ../board/bluepill.cfg
-c "program /home/dem/Code/your-project/my-project/your-project.elf verify reset exit" \

Open On-Chip Debugger 0.10.0
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
adapter speed: 1000 kHz
adapter_nsrst_delay: 100
none separate
0x2000
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : clock speed 950 kHz
Info : STLINK v2 JTAG v17 API v2 SWIM v4 VID 0x0483 PID 0x3748
Info : using stlink api v2
Info : Target voltage: 3.229062
Info : STM32F103C8T6.cpu: hardware has 6 breakpoints, 4 watchpoints
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x08000430 msp: 0x20005000
** Programming Started **
auto erase enabled
Info : device id = 0x20036410
Info : flash size = 128kbytes
wrote 2048 bytes from file /home/dem/Code/your-project/my-project/your-project.elf in 0.548013s (3.650 KiB/s)
** Programming Finished **
** Verify Started **
target halted due to breakpoint, current mode: Thread
xPSR: 0x61000000 pc: 0x2000002e msp: 0x20005000
verified 1232 bytes in 0.380016s (3.166 KiB/s)
** Verified OK **
** Resetting Target **
shutdown command invoked

Provide an easier way to specify custom linker script.

Issue: Currently in the Makefile both DEVICE and LDSCRIPT cannot be specified at the same time. This makes it difficult to have different linker script while keep all the other flags same.

This is especially true for bootloader projects and/or projects that will have to work with a custom bootloader.

It will be nice to have a way to use a custom linker script while keeping all the other settings as is.

Initial make fails with error about Python

Following the build instructions in the README I get the following error:

make: Entering directory '/home/brian/projects/libopencm3_test/libopencm3'
  GENHDR  include/libopencm3/stm32/f0/irq.json
/usr/bin/env: ‘python’: No such file or directory
make: *** [Makefile:59: include/libopencm3/stm32/f0/irq.json.genhdr] Error 127
make: Leaving directory '/home/brian/projects/libopencm3_test/libopencm3'

I wonder whether this is due to the build process depending on Python2 which is now obsolute. Python3 executables tend to be called python3 whereas Python2 were just called python. (It is a shame that distros haven't yet changed the default name / alias for python=>python3.)

I see there are many scripts that have #!/usr/bin/env python. Updating each of these to use python3 advances the build but still failures:

make[1]: arm-none-eabi-gcc: No such file or directory

It looks like the cross compiler installed on my system differs (in location?) from that expected by the build system. Maybe the README should describe this dependancy?

Add flash option using st-flash

When running make flash I get this error:

  FLASH	awesomesauce.elf
make: *** [../rules.mk:159: awesomesauce.flash] Error 1

From what I understand, there's probably something related to openocd. However, I use st-flash:
st-flash write $(PROJECT).bin 0x8000000

It would be nice to have this option in the makefile.

Template not working in OSX (Monterey)

Hi. If somebody could help/provide some guidance on this issue it would be greatly appreciated.

I've been trying to deploy/use this template in a Mac environment and it doesn't work due to problems with the makefile.

When executing the 1st command (from the README.md file): make -C libopencm3
it errors out with: GENHDR include/libopencm3/stm32/f0/irq.json
env: python: No such file or directory

and the file actually does exist at ~/myproject/libopencm3/include/libopencm3/stm32/f0

I followed the README.md instructions and entered this command in my home (~) directory:
git clone --recurse-submodules https://github.com/libopencm3/libopencm3-template.git myproject

I could really use some help here.

Thanks!