154 lines
4.8 KiB
Plaintext
154 lines
4.8 KiB
Plaintext
------------------------------------------------------------------------------
|
|
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 STM32F1 series
|
|
- ST STM32F2 series
|
|
- ST STM32F4 series
|
|
- NXP LPC1311/13/42/43
|
|
|
|
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, and a python YAML module. (Some code is generated)
|
|
|
|
For Ubuntu
|
|
$ [sudo] apt-get install python-yaml
|
|
|
|
For Fedora
|
|
$ [sudo] yum install PyYAML
|
|
|
|
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 (use installer to get the right registry keys for PyYAML)
|
|
PyYAML - http://pyyaml.org/download/pyyaml/PyYAML-3.10.win32-py2.7.exe
|
|
arm-none-eabi 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.
|
|
|
|
Building
|
|
--------
|
|
|
|
$ make
|
|
|
|
You may want to override the toolchain (e.g., arm-elf or arm-none-eabi):
|
|
|
|
$ PREFIX=arm-none-eabi 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
|
|
|
|
If you want to attempt to install into your toolchain, use this:
|
|
|
|
$ make DETECT_TOOLCHAIN=1 install
|
|
|
|
Note: If you install this into your toolchain, you don't need to pass
|
|
any extra -L or -I flags into your projects. However, this also means
|
|
you must NOT pass any -L or -I flags that point into the toolchain. This
|
|
_will_ confuse the linker. (ie, for summon-arm-toolchain, do NOT pass
|
|
-L/home/user/sat/lib) Common symptoms of confusing
|
|
the linker are hard faults caused by branches into arm code.
|
|
You can use objdump to check for this in your final elf.
|
|
|
|
|
|
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/
|
|
|