From 02cc018e83a8333f8458be5d60adc3b8bb9b8d81 Mon Sep 17 00:00:00 2001 From: Andy Brown Date: Sun, 10 Aug 2014 10:48:44 +0100 Subject: [PATCH] update readme for release --- INSTALL.md | 39 +++++++++++++++++++++++++++++++++++++-- LICENSE.md | 2 +- README.md | 18 ++++++++---------- 3 files changed, 46 insertions(+), 13 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 42950384..49ee57ef 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -15,7 +15,7 @@ If you're happy with building from the `master` branch then you can just go righ Prerequisites ------------- -* A compatible arm-none-eabi toolchain. I currently support the Mentor Graphics (formerly CodeSourcery) _Sourcery G++ Lite_ and [ARM launchpad](https://launchpad.net/gcc-arm-embedded) toolchains. Download the most recent EABI version, install it on your system and ensure that it's in your path by attempting to execute one of the commands: +* A compatible arm-none-eabi toolchain. I prefer the [ARM launchpad](https://launchpad.net/gcc-arm-embedded) toolchain because it supports the hardware FPU in the F4 series. I can also confirm that the Mentor Graphics (formerly CodeSourcery) _Sourcery G++ Lite_ toolchain preferred in previous stm32plus releases still works as long as you don't require the hardware FPU. Download the most recent EABI version, install it on your system and ensure that it's in your path by attempting to execute one of the commands: $ arm-none-eabi-g++ arm-none-eabi-g++.exe: no input files @@ -75,6 +75,22 @@ You can build all of the above combinations side-by-side if you so wish by execu scons mode=small mcu=f4 hse=8000000 -j4 float=hard install // small / f4 / 8Mhz scons mode=debug mcu=f4 hse=8000000 -j4 install // debug / f4 / 8Mhz scons mode=debug mcu=f051 hse=8000000 -j4 install // debug / f051 / 8Mhz + + Additional Notes: + The -j option can be passed to scons to do a parallel build. On a multicore + CPU this can greatly accelerate the build. Set to approximately the number + of cores that you have. + + The built library will be placed in the stm32plus/build subdirectory. + + If you specify the install command-line option then that library will be installed + into the location given by INSTALLDIR, which defaults to /usr/local/arm-none-eabi. + The library, headers, and examples will be installed respectively, to the lib, + include, and bin subdirectories of INSTALLDIR. + + It is safe to compile multiple combinations of mode/mcu/hse as the compiled object + code and library are placed in a unique directory name underneath stm32plus/build. + It is likewise safe to install multiple versions of the library and examples. The `-j` option can be passed to scons to do a parallel build. On a multicore CPU this can greatly accelerate the build. Set to approximately the number of cores that you have. @@ -86,4 +102,23 @@ The example projects are designed to run on either the 512/64Kb/72MHz STM32F103, It is the linker script (`Linker.ld`) and the system startup code (`System.c`) that specify these things. For example, if you wanted to change the core clock then you need to look at `System.c` (`SystemCoreClock` is a key variable). If you want to change the memory size then you need to look at `Linker.ld`. The stm32plus library itself is clock-speed and memory-independent. For example, I have used stm32plus with an STM32F429 MCU just by using the F4 build and adjusting my system and linker files to reflect the higher clock speed and memory configuration. -Some examples are not suitable for all MCUs. For example, the STM32F107 does not come with SDIO or FSMC peripherals, and the STM32F103 does not have an ethernet MAC. If an example is not suitable for the MCU that you are targetting then the scons script will skip over it and the Eclipse project will not contain a configuration for it. \ No newline at end of file +Some examples are not suitable for all MCUs. For example, the STM32F107 does not come with SDIO or FSMC peripherals, and the STM32F103 does not have an ethernet MAC. If an example is not suitable for the MCU that you are targetting then the scons script will skip over it and the Eclipse project will not contain a configuration for it. + +#### A note on the net examples + +The network code requires the dynamic heap CRT library functions to be safe for re-entrant use, therefore these examples contain the following code in the `LibraryHacks.cpp` file. When writing your own code it is very important that you include this: + + /* + * The net code needs the heap to re-entrant so we need to ensure that an + * IRQ cannot be raised while the heap structures are updated + */ + + extern "C" { + void __malloc_lock(struct _reent * /* reent */) { + stm32plus::IrqSuspend::suspend(); + } + + void __malloc_unlock(struct _reent * /* reent */) { + stm32plus::IrqSuspend::resume(); + } + } diff --git a/LICENSE.md b/LICENSE.md index d3db1bf6..81349ac8 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ License ======= -Copyright (c) 2011,2012,2013,2014 [Andrew Brown](http://www.andybrown.me.uk) +Copyright (c) 2011-2014 [Andrew Brown](http://www.andybrown.me.uk) All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/README.md b/README.md index adf2d8cd..6b1ae4e8 100644 --- a/README.md +++ b/README.md @@ -66,9 +66,7 @@ Working in Eclipse ------------------ I do all my development in Eclipse Kepler using the CDT and the [GNU ARM Eclipse plugin](http://gnuarmeclipse.livius.net/blog/). The `.project` and `.cproject` files for the main library and all the examples are included. You can use Eclipse's import option on the root checkout directory to bring them all into your workspace in one go. I recommend that you create a _working set_ to contain all the stm32plus projects because there's a lot of them. -I recommend version *1.8.1-201401111229* of the GNU ARM Eclipse plugin with Eclipse Kepler. That's the combination that I use in day-to-day development and the `.project` and `.cproject` will work with that version. - -The example projects are configured to use the external `cs-make` builder. Linux users should change this to 'Internal builder' in the 'C/C++ Build' project properties page. +I have found that the recent updates to the plugin have been stable and non-breaking so you can probably just get the latest version. At the time of writing I am using version *1.10.2.201407190854* of the _Cross Compiler Support_ plugin. How do I report a bug? ====================== @@ -103,15 +101,15 @@ A short walk around the directories A quick guide to flashing using OpenOCD ======================================= -At the time of writing the lastest version of openocd is 0.6.1 and it contains full support for the STM32 connected via JTAG and also via ST-Link (e.g. the STM32F4DISCOVERY and STM32VLDISCOVERY boards). The following guide assumes that you are using either Linux or Windows with a Unix-like shell (cygwin or mingw) and that you have built the binaries. +At the time of writing the lastest version of openocd is 0.8.0 and it contains full support for the STM32 connected via JTAG and also via ST-Link (e.g. the STM32F4DISCOVERY and STM32VLDISCOVERY boards). The following guide assumes that you are using either Linux or Windows with a Unix-like shell (cygwin or mingw) and that you have built the binaries. Flashing the stm32f4discovery board ----------------------------------- `cd` into the openocd directory and run it with the flags required for the discovery board. For me on Windows 7 x64/cygwin this is: - $ bin-x64/openocd-x64-0.6.1.exe -f scripts/board/stm32f4discovery.cfg - Open On-Chip Debugger 0.6.1 (2012-10-07-10:39) + $ bin-x64/openocd-x64-0.8.0.exe -f scripts/board/stm32f4discovery.cfg + Open On-Chip Debugger 0.8.0 (2012-10-07-10:39) Licensed under GNU GPL v2 For bug reports, read http://openocd.sourceforge.net/doc/doxygen/bugs.html @@ -221,8 +219,8 @@ Windows users need to ensure that they can connect to the ST-Link V1 debugger on `cd` into the openocd directory and run it with the flags required for the discovery board. For me on Windows 7 x64/cygwin this is: - $ bin-x64/openocd-x64-0.6.1.exe -f scripts/board/stm32vldiscovery.cfg - Open On-Chip Debugger 0.6.1 (2012-10-07-10:39) + $ bin-x64/openocd-x64-0.8.0.exe -f scripts/board/stm32vldiscovery.cfg + Open On-Chip Debugger 0.8.0 (2012-10-07-10:39) Licensed under GNU GPL v2 For bug reports, read http://openocd.sourceforge.net/doc/doxygen/bugs.html @@ -269,8 +267,8 @@ This is one of the more recent _discovery_ boards from ST and as such it comes e `cd` into the openocd directory and run it with the flags required for the discovery board. For me on Windows 7 x64/cygwin this is: - $ bin-x64/openocd-x64-0.7.0.exe -f scripts/board/stm32f0discovery.cfg - Open On-Chip Debugger 0.7.0 (2013-05-05-10:44) + $ bin-x64/openocd-x64-0.8.0.exe -f scripts/board/stm32f0discovery.cfg + Open On-Chip Debugger 0.8.0 (2013-05-05-10:44) Licensed under GNU GPL v2 For bug reports, read http://openocd.sourceforge.net/doc/doxygen/bugs.html