2009-07-15 20:07:00 +00:00
|
|
|
------------------------------------------------------------------------------
|
|
|
|
README
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
|
2010-12-30 02:09:35 +00:00
|
|
|
The libopencm3 project aims to create an open-source firmware library for
|
|
|
|
various ARM Cortex-M3 microcontrollers.
|
2009-07-15 22:01:41 +00:00
|
|
|
|
2010-12-30 02:09:35 +00:00
|
|
|
Currently (at least partly) supported microcontrollers:
|
|
|
|
|
2011-11-01 18:55:43 +00:00
|
|
|
- ST STM32F1 series
|
|
|
|
- ST STM32F2 series
|
|
|
|
- ST STM32F4 series
|
2010-12-30 02:09:35 +00:00
|
|
|
- NXP LPC1311/13/42/43
|
|
|
|
|
|
|
|
The library is written completely from scratch based on the vendor datasheets,
|
2010-01-15 12:40:43 +00:00
|
|
|
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
|
2010-12-30 02:09:35 +00:00
|
|
|
code to a microcontroller can be done using the OpenOCD ARM JTAG software.
|
2010-01-15 12:40:43 +00:00
|
|
|
|
2011-11-01 19:09:12 +00:00
|
|
|
|
2010-01-15 12:38:02 +00:00
|
|
|
Status and API
|
|
|
|
--------------
|
|
|
|
|
2010-12-30 02:09:35 +00:00
|
|
|
The libopencm3 project is currently work in progress. Not all subsystems
|
|
|
|
of the microcontrollers are supported, yet.
|
2010-01-15 12:38:02 +00:00
|
|
|
|
|
|
|
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!
|
2009-07-15 22:01:41 +00:00
|
|
|
|
2013-06-11 00:48:31 +00:00
|
|
|
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.
|
|
|
|
|
2013-01-23 21:21:27 +00:00
|
|
|
Prerequisites
|
|
|
|
-------------
|
|
|
|
|
[build] Remove PyYAML dependency
This converts all the YAML files to JSON files, as json parsing is built
into python instead of being a separate library requiring installation.
YAML is a superset of JSON, but putting comments in is not quite as obvious
as it is in yaml.
The following glue was used to convert yaml to json:
python -c 'import sys, yaml, json; json.dump(yaml.load(sys.stdin), sys.stdout, indent=4)' < $1 > $2
Clearly I haven't tested this on every single platform, and this
doesn't address the large blobs of yaml in the lpc4300 scripts directory,
only the cortex NVIC generation process.
I've tested a few IRQ driven example apps, and I've checked the generated
output of some known cases like the LM3s that has explicit gaps, and they are
all generated correctly.
2013-09-06 23:43:39 +00:00
|
|
|
Building requires python. (Some code is generated)
|
2013-01-23 21:21:27 +00:00
|
|
|
|
[build] Remove PyYAML dependency
This converts all the YAML files to JSON files, as json parsing is built
into python instead of being a separate library requiring installation.
YAML is a superset of JSON, but putting comments in is not quite as obvious
as it is in yaml.
The following glue was used to convert yaml to json:
python -c 'import sys, yaml, json; json.dump(yaml.load(sys.stdin), sys.stdout, indent=4)' < $1 > $2
Clearly I haven't tested this on every single platform, and this
doesn't address the large blobs of yaml in the lpc4300 scripts directory,
only the cortex NVIC generation process.
I've tested a few IRQ driven example apps, and I've checked the generated
output of some known cases like the LM3s that has explicit gaps, and they are
all generated correctly.
2013-09-06 23:43:39 +00:00
|
|
|
For Ubuntu/Fedora, you already have everything you need.
|
2011-11-01 19:09:12 +00:00
|
|
|
|
2013-03-31 16:32:07 +00:00
|
|
|
For Windows
|
2013-06-10 16:42:21 +00:00
|
|
|
Download and install:
|
2013-03-31 16:32:07 +00:00
|
|
|
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)
|
|
|
|
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.
|
|
|
|
|
2009-07-15 22:01:41 +00:00
|
|
|
Building
|
|
|
|
--------
|
|
|
|
|
|
|
|
$ make
|
|
|
|
|
2009-07-15 23:23:48 +00:00
|
|
|
You may want to override the toolchain (e.g., arm-elf or arm-none-eabi):
|
|
|
|
|
|
|
|
$ PREFIX=arm-none-eabi make
|
|
|
|
|
2009-07-16 16:33:32 +00:00
|
|
|
For a more verbose build you can use
|
|
|
|
|
|
|
|
$ make V=1
|
|
|
|
|
2013-06-10 16:42:21 +00:00
|
|
|
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
|
2009-07-15 22:01:41 +00:00
|
|
|
|
2010-01-15 12:33:58 +00:00
|
|
|
Example projects
|
|
|
|
----------------
|
|
|
|
|
2013-04-20 02:33:32 +00:00
|
|
|
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:
|
2010-12-29 18:49:59 +00:00
|
|
|
|
2013-04-20 02:33:32 +00:00
|
|
|
https://github.com/libopencm3/libopencm3-examples
|
2010-01-15 12:33:58 +00:00
|
|
|
|
2009-07-15 22:01:41 +00:00
|
|
|
Installation
|
|
|
|
------------
|
|
|
|
|
|
|
|
$ make install
|
|
|
|
|
2012-07-04 21:45:14 +00:00
|
|
|
This will install the library into /usr/local. (permissions permitting)
|
2009-07-15 22:01:41 +00:00
|
|
|
|
2012-07-04 21:45:14 +00:00
|
|
|
If you want to install it elsewhere, use the following syntax:
|
2009-07-15 22:01:41 +00:00
|
|
|
|
2012-07-04 21:45:14 +00:00
|
|
|
$ make DESTDIR=/opt/libopencm3 install
|
2010-12-31 17:29:15 +00:00
|
|
|
|
2012-07-04 21:45:14 +00:00
|
|
|
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.
|
2009-07-15 22:01:41 +00:00
|
|
|
|
2011-11-01 19:09:12 +00:00
|
|
|
|
2010-03-05 22:39:06 +00:00
|
|
|
Coding style and development guidelines
|
|
|
|
---------------------------------------
|
2009-07-15 22:01:41 +00:00
|
|
|
|
2010-03-05 22:39:06 +00:00
|
|
|
See HACKING.
|
2009-07-15 22:01:41 +00:00
|
|
|
|
|
|
|
|
|
|
|
License
|
|
|
|
-------
|
|
|
|
|
2012-03-02 10:23:11 +00:00
|
|
|
The libopencm3 code is released under the terms of the GNU Lesser General
|
|
|
|
Public License (LGPL), version 3 or later.
|
2009-07-15 22:01:41 +00:00
|
|
|
|
2012-03-02 10:23:11 +00:00
|
|
|
See COPYING.GPL3 and COPYING.LGPL3 for details.
|
2009-07-15 22:01:41 +00:00
|
|
|
|
2013-06-11 00:48:31 +00:00
|
|
|
IRC
|
|
|
|
---
|
|
|
|
|
|
|
|
* You can reach us in #libopencm3 on the freenode IRC network.
|
2009-07-15 22:01:41 +00:00
|
|
|
|
|
|
|
Mailing lists
|
|
|
|
-------------
|
|
|
|
|
|
|
|
* Developer mailing list (for patches and discussions):
|
2011-11-01 19:09:12 +00:00
|
|
|
https://lists.sourceforge.net/lists/listinfo/libopencm3-devel
|
2009-07-15 22:01:41 +00:00
|
|
|
|
|
|
|
* Commits mailing list (receives one mail per 'git push'):
|
2011-11-01 19:09:12 +00:00
|
|
|
https://lists.sourceforge.net/lists/listinfo/libopencm3-commits
|
2009-07-15 22:01:41 +00:00
|
|
|
|
|
|
|
|
|
|
|
Website
|
|
|
|
-------
|
|
|
|
|
2011-11-01 19:09:12 +00:00
|
|
|
http://libopencm3.org
|
|
|
|
http://sourceforge.net/projects/libopencm3/
|
2010-03-05 22:38:11 +00:00
|
|
|
|