diff options
Diffstat (limited to 'libopencm3/README')
| -rw-r--r-- | libopencm3/README | 159 |
1 files changed, 159 insertions, 0 deletions
diff --git a/libopencm3/README b/libopencm3/README new file mode 100644 index 0000000..7323a76 --- /dev/null +++ b/libopencm3/README @@ -0,0 +1,159 @@ +------------------------------------------------------------------------------ +README +------------------------------------------------------------------------------ + +The libopencm3 project aims to create an open-source firmware library for +various ARM Cortex-M3 microcontrollers. + +Currently (at least partly) supported microcontrollers: + + - ST STM32F0xx/F1xx/F2xx/F30x/F37x/F4xx/L1xx series + - Atmel SAM3A/3N/3S/3U/3X series + - NXP LPC1311/13/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) + +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 currently work in progress. Not all subsystems +of the microcontrollers are supported, yet. + +IMPORTANT: The API of the library is NOT yet considered stable! Please do + not rely on it, yet! Changes to function names, macro names etc. + can happen at any time without prior notice! + +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-examples 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 - sourceforge.net/projects/mingw/files/MSYS/Base/msys-core/msys-1.0.11/MSYS-1.0.11.exe + Python - http://www.python.org/ftp/python/2.7/python-2.7.msi (any 2.7 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, so Windows programs such as 'find' won't interfere: + export PATH="/c//Python27:/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 +https://launchpad.net/gcc-arm-embedded + +Other toolchains _should_ work, but have not been nearly as well tested. +Toolchains targetting linux, such as "gcc-arm-linux-gnu" or the like are +_not_ appropriate. + +Building +-------- + + $ make + +If your 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 + +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 + 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 others to no FP flags + Examples: + $ FP_FLAGS="-mfloat-abi=soft" make # No hardfloat + $ FP_FLAGS="-mfloat-abi=hard -mfpu=magic" make # New FPU we don't know of + +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 + +Installation +------------ + + $ make install + +This will install the library into /usr/local. (permissions permitting) + +If you want to install it elsewhere, use the following syntax: + + $ make DESTDIR=/opt/libopencm3 install + +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 multilib +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. 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. + +IRC +--- + + * You can reach us in #libopencm3 on the freenode IRC network. + +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 + http://sourceforge.net/projects/libopencm3/ + |