How-to manual Installing a toolchain for Cortex-M3/STM32 on GNU/Linux Version 1.0.4, 2020-10-28 This work by Peter Seng is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License. Based on a work of Johan Simonsson and Geoffrey McRae. Page 1 of 45 Disclaimer of Warranty THERE IS NO WARRANTY FOR THE CONTENT, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE CONTENT “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE CONTENT IS WITH YOU. SHOULD THE CONTENT PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. Limitation of Liability IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE CONTENT AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE CONTENT (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAM), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Page 2 of 45 Contents 1 About...............................................................4 6.1 Doxygen................................................33 2 Hardware.........................................................4 6.2 Git..........................................................33 3 Software..........................................................4 6.3 Terminal emulation...............................33 4 Basic tools.......................................................5 7 IDE................................................................34 4.1 OpenOCD................................................5 7.1 Eclipse...................................................34 4.1.1 Download, build and install............5 7.1.1 Copy Template...............................34 4.1.2 Install JTAG device.........................6 7.1.2 Install.............................................34 4.1.3 Configure.........................................7 7.1.3 Create project................................35 4.2 Serial bootloader.....................................9 7.1.4 Configure workspace.....................35 4.2.1 stm32flash.......................................9 7.1.5 Configure project...........................35 4.2.2 Flash loader demonstrator...............9 7.1.6 Configure external tools................36 4.3 GCC toolchain.......................................10 7.1.7 Configure debugger.......................36 4.3.1 Repository install, Linux Mint17/18 7.1.7.1 Hardware reset.......................36 only...........................................................10 7.1.7.2 Software reset........................37 4.3.2 External install (e.g. Linux Mint 20) 7.1.8 Configure Make Target Window...38 ..................................................................10 7.1.9 Code analysis setup.......................39 4.3.3 Check installation..........................11 7.1.10 Setup Perspectives.......................39 5 Basic project.................................................12 7.1.11 First debug steps..........................39 5.1 0002_Test_Template.............................12 7.1.12 Eclipse setup files........................40 5.1.1 Libraries........................................12 7.1.13 Clone project...............................40 5.1.1.1 Install StdPeriph_Lib_V3.5.0 12 7.1.14 Hints............................................40 5.1.1.2 Install USB library and 8 Target device type setup................................41 StdPeriph_Lib_V3.6.1.........................12 9 Bugs and Workarounds.................................41 5.1.1.3 Content...................................13 9.1 GCC toolchain.......................................41 5.1.2 Basic Makefiles.............................13 9.2 IDE-eclipse............................................41 5.1.2.1 Common Makefile.................13 9.2.1 Juno release...................................41 5.1.2.2 Libs Makefile.........................16 9.3 OpenOCD..............................................42 5.1.3 Linker Script..................................16 9.3.1 STM32F103RET...........................42 5.1.4 Startup Code..................................20 9.3.2 Single step failure..........................42 5.1.5 Final steps......................................24 9.4 MCU......................................................42 5.1.5.1 Source main.c........................24 9.4.1 I2C peripheral................................42 5.1.5.2 Source Makefile.....................25 10 To do's.........................................................42 5.1.5.3 Final Makefile........................26 11 Credits and Reference.................................42 5.2 Build project..........................................26 12 Revision history..........................................43 5.3 Check results.........................................26 13 Appendix.....................................................44 5.4 Flash and run.........................................28 13.1 Cortex-M3...........................................44 5.5 Read protection.....................................28 13.1.1 Intro's...........................................44 5.6 Debug....................................................29 13.1.2 Architecture.................................44 5.7 Automate Flash.....................................30 13.1.3 MCU............................................44 5.7.1 Production programming...............32 13.2 Links....................................................45 6 Additional Tools............................................33 Page 3 of 45 1 About this manual describes how to install a toolchain for Cortex-M3 on GNU/Linux (installed and tested on Ubuntu 10.04, Ubuntu 12.04, LinuxMint 17, Linux Mint 20). All packages used, except the GCC toolchain, are open source. For this part a free, unlimited and up to date version of “Sourcery CodeBench” or “GNU Tools for ARM Embedded Processors” (both based on the GNU tools) are used in order to ease the install and build procedure. LinuxMint17 includes the full GCC toolchain in it's repository, LinuxMint20 not. Most content of this manual is based on the knowledge and the excellent how-to pages of Johan Simonsson at http://fun-tech.se/stm32/ (1) and Geoffrey McRae (2). Consider this manual as a summary and extension of these guides. If any questions arise, please first have a look at these pages where much more aspects are touched and explained. For better reading of this document command inputs and outputs via a terminal window are formated like this. The content of source files is enclosed in frames. Hint: PDF documents do not contain tab formatting marks and empty lines. So it is not possible to copy source code out of a PDF document by copy and paste without loss of this information. The content of this manual may not be up to date. So before downloading and installing any package, please check if the mentioned packages are still up to date. If newer packages exist and it is sensible to use them please adapt the instructions to these conditions. Much thanks and lot's of greetings to all those people developing and improving these artful tools running on GNU/Linux. After nearly one year of coding, using the toolset for hours most days, it has proven to be reliable, comfortable and very satisfying. Any improvements necessary will be documented in future versions of this manual. Any comments welcome, please mail to: [email protected] The current version of this manual is available at : http://www.seng.de 2 Hardware Hardware used: • Olimex “ARM-USB-OCD-H”. USB ARM JTAG device with one additional RS-232 port. The device is based on the FTDI “FT2232H” chip. • Olimex “STM32-H103”. Header board for “STM32F103RBT6”. The microcontroller integrates 128KB Flash, 20KB RAM, 3xUART, … • STM32F103RET6 (512KB Flash, 64KB RAM) mounted on “STM32-H103” board. The example code in this manual is adapted to STM32F103RBT6 with comments for the ...RET6. 3 Software The toolchain consists of following packages: • OpenOCD • stm32flash by Geoffrey McRae (2) • GCC toolchain for build and debug • STM32F10x standard peripheral library • Project template and makefile by Geoffrey McRae (2) • Eclipse IDE and some utitlities • (Git) • (Doxygen) Page 4 of 45 4 Basic tools This chapter is about installing the basic toolchain. 4.1 OpenOCD Open On-Chip Debugger is the part of software that is needed to enable the JTAG-hardware (“ARM- USB-OCD-H”) to flash and debug the microcontroller, it is the software interface to GDB. When using Linux Mint 20 install OpenOCD using the repository and continue at 4.1.2 Else OpenOCD downloads and documentation can be found at: http://openocd.org/documentation/ http://sourceforge.net/projects/openocd/files/openocd/ 4.1.1 Download, build and install Create a temporary directory: mkdir ~/temp/stm32/ -p cd ~/temp/stm32/ Download the documentation using one of the above mentioned links. Think about a structure to store the documentation of this toolchain in. Be aware to get the manual version that fits to the program version. Down see how to install the software out of a repository.