diff options
| -rw-r--r-- | .gitignore | 4 | ||||
| -rw-r--r-- | CREDITS | 13 | ||||
| -rw-r--r-- | HACKING | 8 | ||||
| -rw-r--r-- | README | 66 | ||||
| -rw-r--r-- | docs/Makefile | 4 | ||||
| -rw-r--r-- | docs/README | 15 | ||||
| -rw-r--r-- | docs/README-building.txt | 39 | ||||
| -rw-r--r-- | docs/README-maintainers.txt | 14 | ||||
| -rw-r--r-- | docs/source/_templates/indexcontent.html | 13 | ||||
| -rw-r--r-- | docs/source/bootloader.rst | 4 | ||||
| -rw-r--r-- | docs/source/conf.py | 2 | ||||
| -rw-r--r-- | docs/source/epilog.rst | 3 | ||||
| -rw-r--r-- | docs/source/faq.rst | 4 | ||||
| -rw-r--r-- | docs/source/lang/api/hardwarespi.rst | 3 | ||||
| -rw-r--r-- | docs/source/lang/cpp/arithmetic.rst | 2 | ||||
| -rw-r--r-- | docs/source/libmaple/api/dma.rst | 10 | ||||
| -rw-r--r-- | docs/source/libmaple/api/gpio.rst | 7 | ||||
| -rw-r--r-- | docs/source/libmaple/api/nvic.rst | 2 | ||||
| -rw-r--r-- | docs/source/libmaple/api/util.rst | 2 | ||||
| -rw-r--r-- | docs/source/libmaple/overview.rst | 2 |
20 files changed, 115 insertions, 102 deletions
@@ -1,6 +1,7 @@ build/ doxygen/xml/ doxygen/html/ +doxygen/doxygen_sqlite3.db main.cpp libmaple.layout tags @@ -10,3 +11,6 @@ TAGS arm cscope* .gdbinit + +# Don't ignore this file itself +!.gitignore @@ -1,16 +1,13 @@ - This is at least a partial credits-file of people that have - contributed to libmaple (it was originally drawn from the - commit logs, so it e.g. leaves out contributions that didn't - come in the form of patches). It's formatted the same way as - the Linux kernel CREDITS: sorted by name and formatted for - easy processing. + This is at least a partial credits-file of people that have contributed + to libmaple and librambutan (it was originally drawn from the commit + logs, so it e.g. leaves out contributions that didn't come in the form + of patches). It's formatted the same way as the Linux kernel CREDITS: + sorted by name and formatted for easy processing. The fields are: name (N), email (E), web-address (W), description (D). Feel free to add any other fields present in the Linux CREDITS file. - LeafLabs - ---------- N: Marti Bolivar @@ -1,6 +1,6 @@ Read this before submitting patches: - http://leaflabs.com/docs/libmaple/contributing.html + http://docs.rambutan.cc/projects/librambutan/en/master/libmaple/contributing.html In particular, patches without sign-off lines will not be accepted. @@ -8,9 +8,9 @@ If your patch is formatted very differently from the libmaple style, you may find the astyle options file in contrib/astylerc useful for auto-formatting it roughly in the libmaple style. -LeafLabs is a small shop. Please help us merge your patches -efficiently by getting formatting nits etc. out of the way before -submitting. +We are a small collection of volunteers. Please help us merge your +patches efficiently by getting formatting nits etc. out of the way +before submitting. When writing your patch, feel free to add yourself to the CREDITS file. If you can't write your name in ASCII (or choose not to @@ -1,23 +1,33 @@ - _ _ _ _ - | (_) |__ _ __ ___ __ _ _ __ | | ___ - | | | '_ \| '_ ` _ \ / _` | '_ \| |/ _ \ - | | | |_) | | | | | | (_| | |_) | | __/ - |_|_|_.__/|_| |_| |_|\__,_| .__/|_|\___| - |_| by LeafLabs! - leaflabs.com + _ _ _ _ _ + | (_) |__ _ __ __ _ _ __ ___ | |__ _ _| |_ __ _ _ __ + | | | '_ \| '__/ _` | '_ ` _ \| '_ \| | | | __/ _` | '_ \ + | | | |_) | | | (_| | | | | | | |_) | |_| | || (_| | | | | + |_|_|_.__/|_| \__,_|_| |_| |_|_.__/ \__,_|\__\__,_|_| |_| The latest version of this repository can be found here: - https://github.com/leaflabs/libmaple + https://github.com/rambutan32/librambutan IMPORTANT: read HACKING _before_ submitting patches. General information ------------------------------------------------------------------------------ -libmaple is a library for programming ST's STM32 line of Cortex M3 +librambutan is a fork of Leaflab's libmaple firmware libraries. As of 2015 +Leaflabs is not actively maintaining libmaple and the original Maple series +hardware is End Of Life. For the foreseeable future the name 'libmaple' will +continue to be used in documentation and filenames for backwards compatability. +You can get the latest information about the Rambutan project at: + + https://forums.rambutan.cc + +The original libmaple can be found at: + + https://github.com/leaflabs/libmaple + +librambutan is a library for programming ST's STM32 line of Cortex M3 microcontrollers. It has a pure C layer, libmaple proper, which does most of the work, and a C++ layer, Wirish, which provides high-level convenience functions and a Wiring/Arduino-compatible interface. @@ -26,36 +36,28 @@ libmaple is designed for portability, and currently runs on a variety of STM32F1 performance and value line MCUs, with experimental support for STM32F2 MCUs. -Using libmaple +Using librambutan ------------------------------------------------------------------------------ -The easiest way to use libmaple is in concert with the Maple IDE. -Maple IDE, a sister project from LeafLabs, is an Arduino IDE fork -usable for programming Maple boards, which includes libmaple and a -compilation and upload toolchain: +A HOWTO on setting up this library for use from the command line in a Unix +environment is available here: - http://leaflabs.com/docs/maple-ide-install.html + http://docs.rambutan.cc/projects/librambutan/en/master/unix-toolchain.html -Additionally, a HOWTO on setting up this library for use from the -command line in a Unix environment is available here: - - http://leaflabs.com/docs/unix-toolchain.html +At a minimum you will need the gcc-arm-none-eabi toolchain on your path, +including the newlib libc and the libstdc++ libraries. Documentation, Etc. ------------------------------------------------------------------------------ -HTML documentation for the latest release of libmaple/Maple IDE is -available here: - - http://leaflabs.com/docs/ +Hosted HTML documentation for several versions of librambutan are available at: -libmaple is well documented via Doxygen comments. The HTML -documentation referenced above (which also includes the Doxygen -output) is automatically generated from the source files in the -leaflabs-docs repository. In order to obtain the leaflabs-docs -repository, visit: + http://docs.rambutan.cc/projects/librambutan/en/master/ - http://github.com/leaflabs/leaflabs-docs/ +libmaple is well documented via Doxygen comments. The HTML documentation +referenced above (which also includes the Doxygen output) is automatically +generated from the source files in the docs directory. See the READMEs there +for details. Repository Layout ------------------------------------------------------------------------------ @@ -66,8 +68,7 @@ Repository Layout /contrib/ - Community-contributed resources. LeafLabs doesn't maintain the - contents of this directory, so it may get stale. + Community-contributed resources. /examples/ @@ -86,7 +87,8 @@ Repository Layout /LICENSE - Licensing and copyright information. + Licensing and copyright information. librambutan is (mostly) under an MIT + license. /main.cpp.example diff --git a/docs/Makefile b/docs/Makefile index 5255525..8b35b93 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,4 +1,4 @@ -# Makefile for LeafLabs documentation (automatically generated by +# Makefile for librambutan documentation (automatically generated by # Sphinx). # You can set these variables from the command line. @@ -130,5 +130,5 @@ doctest: "results in $(BUILDDIR)/doctest/output.txt." doxygen: - @echo "Wrong! You need to run this from within libmaple!" + @echo "Wrong! You need to run this from the top level!" false diff --git a/docs/README b/docs/README index 60fb888..cdfe0ae 100644 --- a/docs/README +++ b/docs/README @@ -1,14 +1,14 @@ -This repository contains source files used to generate the -documentation for LeafLabs' libmaple and Maple IDE projects [*]. The -HTML documentation generated from these sources is available online: +This directory contains source files used to generate the documentation for +librambutan. The HTML documentation generated from these sources is available +online: - http://leaflabs.com/docs/ + http://docs.rambutan.cc/projects/librambutan/en/master The above URL is the recommended way for users to read the documentation. The docs for the latest release are always available there. -Older versions are here: +Ancient libmaple versions are here: http://static.leaflabs.com/pub/leaflabs/maple-docs/ @@ -17,8 +17,3 @@ The file README-building.txt explains how to build the HTML docs. The file README-maintainers.txt contains important information for maintainers of the documentation (e.g. how to add docs for a new board, how to cut a release version of the docs, etc.). - -[*] libmaple and Maple IDE themselves are in separate repositories: - - https://github.com/leaflabs/libmaple - https://github.com/leaflabs/maple-ide diff --git a/docs/README-building.txt b/docs/README-building.txt index 6846bf7..b763f84 100644 --- a/docs/README-building.txt +++ b/docs/README-building.txt @@ -1,8 +1,7 @@ -This file explains how to build the HTML documentation. As such, it's -probably only useful to LeafLabs developers. Users can read the HTML -for the latest release here: +This file explains how to build the HTML documentation. Users can quickly read +the HTML for the latest release here: - http://leaflabs.com/docs/ + http://docs.rambutan.cc/projects/librambutan/en/master/ Install Dependencies -------------------- @@ -11,8 +10,7 @@ First, you will need to install some dependencies (Doxygen, Sphinx, and Breathe). 1. Much of the documentation is pulled out of the libmaple source - code's Doxygen comments, so you need a recent-ish version of - Doxygen in your PATH: + code's Doxygen comments, so you need Doxygen in your PATH: http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc @@ -22,21 +20,32 @@ and Breathe). These are your choices for how to install Sphinx: - - From source or .egg: - http://pypi.python.org/pypi/Sphinx#downloads + - From a Linux package manager, eg: + $ sudo apt-get install python-sphinx + + - From an OS X package manager, like MacPorts or homebrew. + + - Via pip: + $ sudo pip install Sphinx - Via easy_install: $ sudo easy_install -U Sphinx + - From source or .egg: + http://pypi.python.org/pypi/Sphinx#downloads + You need Sphinx version >= 1.0.6. 3. We use a Sphinx plugin called Breathe to parse Doxygen's XML output into a form usable by Sphinx. (More about Breathe: http://michaeljones.github.com/breathe/). - LeafLabs sometimes patches Breathe for the purposes of building our + The more recent versions of Breathe seem to have all the features necessary + to build these docs, so you can install the distribution version (breathe-doc). + + Alternatively, LeafLabs sometimes patches Breathe for the purposes of building docs, so clone the LeafLabs Breathe tree from GitHub (somewhere - else on your system, NOT in the leaflabs-docs repo): + else on your system, NOT in the librambutan repo): - LeafLabs developers, clone with push permissions: $ git clone git@github.com:leaflabs/breathe.git @@ -44,7 +53,7 @@ and Breathe). - Everyone else, clone without them: $ git clone git://github.com/leaflabs/breathe.git -4. After that's done, set environment variable BREATHE_HOME to point to + After that's done, set environment variable BREATHE_HOME to point to Breathe. Something like this in Bash: $ export BREATHE_HOME=/path/to/breathe/repo/ @@ -59,14 +68,14 @@ produce Doxygen XML output, then you can generate the final HTML docs. 1. Before the first time you run Sphinx (and any time the Doxygen comments in the libmaple source code are changed), you'll need to - re-run doxygen on libmaple. + re-run doxygen on the top level of librambutan. - $ cd /path/to/top/level + $ cd /path/to/top/level/librambutan $ make doxygen Doxygen will yell at you a lot; it's generally safe to ignore it. -2. Finally, you can build the HTML (in the leaflabs-docs repository): +2. Finally, you can build the HTML: $ cd /path/to/docs $ make html @@ -93,7 +102,7 @@ comments lives in source/. The directory source/_static/ is for static content (like style sheets); source/_templates/ is meant to contain Sphinx templates. -Read more about Sphinx and use the existing leaflabs-docs source for +Read more about Sphinx and use the existing source for examples when writing new docs. The directory tmpl/ contains template ReST files you should sometimes use when creating a page that follows a pattern (like a libmaple API page), in order to keep the style diff --git a/docs/README-maintainers.txt b/docs/README-maintainers.txt index 48e8e5c..959c5e8 100644 --- a/docs/README-maintainers.txt +++ b/docs/README-maintainers.txt @@ -1,14 +1,10 @@ This file contains information useful for the documentation's -maintainers. As such, it's probably only useful to LeafLabs -developers. Users can read the HTML for the latest release here: +maintainers. Users can read the HTML for the latest release here: - http://leaflabs.com/docs/ + http://docs.rambutan.cc/projects/librambutan/en/master/ -Things you can learn how to do from this file: - -- Cut a release version -- Fix errors in/otherwise maintain the current docs release -- Add docs for a new board +This file is out of date (libmaple era). librambutan uses readthedocs.org to +auto-build documentation. Building Documentation for a Release ------------------------------------ @@ -184,7 +180,7 @@ It needs to be updated RIGHT AWAY, you say? Here's what you do: - Distribute the updated docs. These are world-visible here: - http://static.leaflabs.com/pub/leaflabs/maple-docs/ + http://docs.rambutan.cc/ Adding a New Board ------------------ diff --git a/docs/source/_templates/indexcontent.html b/docs/source/_templates/indexcontent.html index d1bb65b..2d1c8f9 100644 --- a/docs/source/_templates/indexcontent.html +++ b/docs/source/_templates/indexcontent.html @@ -14,22 +14,23 @@ <!-- Content --> {% block body %} -<h1>Hi!</h1> +<h1>Hi There!</h1> -This is the documentation for the LeafLabs Maple boards, version {{ -release }}. +This is the documentation for librambutan, a libre firmware library for STM32 +ARM microcontrollers. If browsing on the docs.rambutan.cc website, you can +select the version/branch from the box in the lower right-hand corner. <h2>Read This First</h2> Having problems? Check out <a href="{{ pathto("troubleshooting") }}">Troubleshooting</a> and the <a href="{{ pathto("faq") }}">FAQ</a>. Can't find what you want -here? Look on the <a href="http://wiki.leaflabs.com/">LeafLabs -wiki</a>. +here? Head back up to the <a href="https://docs.rambutan.cc/">project-wide +docs</a>. </p> <p>See the <a href="{{ pathto("whats-new") }}">What's New</a> page for -changes that are new in {{ release }}.</p> +changes that are new in '{{ release }}'.</p> <h2>Contents at a Glance</h2> diff --git a/docs/source/bootloader.rst b/docs/source/bootloader.rst index 228207d..bff9bb7 100644 --- a/docs/source/bootloader.rst +++ b/docs/source/bootloader.rst @@ -613,8 +613,8 @@ In order to follow these instructions, you will need: - A binary of the bootloader you want to upload (see below). - Hardware for communicating between the Maple and your computer over serial. -- `Python <http://python.org>`_, version 2.5 or higher. -- The `PySerial <http://pyserial.sourceforge.net/>`_ library (this +- Python_, version 2.5 or higher. +- The PySerial_ library (this must be installed separately; it is not part of the Python standard library). diff --git a/docs/source/conf.py b/docs/source/conf.py index 50badda..247edbf 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -268,7 +268,7 @@ if os.path.isdir(doxygen_xml_maybe): doxygen_xml_dir = doxygen_xml_maybe else: print("FAIL: doxygen hasn't been run yet in this repository; " - "see ../README") + "see README-building.txt") sys.exit(-1) breathe_projects = {'libmaple' : doxygen_xml_dir} diff --git a/docs/source/epilog.rst b/docs/source/epilog.rst index 0c1a091..3078639 100644 --- a/docs/source/epilog.rst +++ b/docs/source/epilog.rst @@ -12,7 +12,8 @@ .. _Git: http://git-scm.com/ .. _dfu-util: http://wiki.openmoko.org/wiki/Dfu-util .. _easy_install: http://packages.python.org/distribute/easy_install.html -.. _Leaflabs Maple: http://leaflabs.com/docs/hardware/maple-mini.html +.. _Leaflabs Maple: http://leaflabs.com/docs/hardware/maple.html .. _Leaflabs Maple RET6: http://leaflabs.com/docs/hardware/maple-ret6.html .. _Leaflabs Maple Mini: http://leaflabs.com/docs/hardware/maple-mini.html .. _Leaflabs Maple Native Beta: http://leaflabs.com/docs/hardware/maple-native-beta.html +.. _Maple's master pin map: http://static.leaflabs.com/pub/leaflabs/maple-docs/latest/hardware/maple.html#master-pin-map diff --git a/docs/source/faq.rst b/docs/source/faq.rst index bd155ae..b255f52 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -59,8 +59,8 @@ correspond to the pin you want to write to. If you don't know what that means, don't worry. We'll go through an example here. Let's say you want to write to pin 4 on the Maple. In order to find -out the port and bit number, take look at the Maple's :ref:`master pin -map <maple-pin-map-master>` next to "D4". You'll see that in the +out the port and bit number, take look at the `Maple's master pin +map`_ next to "D4". You'll see that in the "GPIO" column, there's "PB5". That's short for "**P**\ ort **B**, bit **5**". So the GPIO port is "B", and the bit is "5". (If you're not on the Maple, you can find your board's pin map :ref:`from here diff --git a/docs/source/lang/api/hardwarespi.rst b/docs/source/lang/api/hardwarespi.rst index a44a65f..4d720ac 100644 --- a/docs/source/lang/api/hardwarespi.rst +++ b/docs/source/lang/api/hardwarespi.rst @@ -42,7 +42,8 @@ function (an example is given below). .. FIXME [Breathe] Output doesn't include the class; fix & submit pull req -.. doxygenfunction:: HardwareSPI::begin +.. doxygenfunction:: HardwareSPI::begin(void) +.. doxygenfunction:: HardwareSPI::begin(SPIFrequency, uint32, uint32) .. note:: If you are using SPI port 3 (on a board that supports it; not all do); you'll need to call :ref:`lang-disabledebugports` diff --git a/docs/source/lang/cpp/arithmetic.rst b/docs/source/lang/cpp/arithmetic.rst index cef3954..b7cb5f6 100644 --- a/docs/source/lang/cpp/arithmetic.rst +++ b/docs/source/lang/cpp/arithmetic.rst @@ -110,7 +110,7 @@ types are approximate): ``short``, "0 --- 65,535", "-32,768 --- 32,767", 2 ``int``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 ``long``, "0 --- 4,294,967,295", "-2,147,483,648 --- 2,147,483,647", 4 - ``long long``, "0 --- 1.8*10\ :sup:`19`\ " (approx.), "-9.2*10\ :sup:`18` --- 9.2*10\ :sup:`18` (approx.)", 8 + ``long long``, "0 --- 1.8*10\ :sup:`19`\ (approx.)", "-9.2*10\ :sup:`18` --- 9.2*10\ :sup:`18` (approx.)", 8 See Also diff --git a/docs/source/libmaple/api/dma.rst b/docs/source/libmaple/api/dma.rst index 286b6d6..4ce298d 100644 --- a/docs/source/libmaple/api/dma.rst +++ b/docs/source/libmaple/api/dma.rst @@ -34,6 +34,10 @@ Devices Functions --------- +.. NB: Some of these functions have multiple definitions, in which case the + complete function signature needs to be specified to disambiguate or breathe + will choke ("Unable to resolve multiple matches for function"...) + .. doxygenfunction:: dma_init .. doxygenfunction:: dma_setup_transfer .. doxygenfunction:: dma_set_num_transfers @@ -43,12 +47,12 @@ Functions .. doxygenfunction:: dma_get_irq_cause .. doxygenfunction:: dma_enable .. doxygenfunction:: dma_disable -.. doxygenfunction:: dma_set_mem_addr +.. doxygenfunction:: dma_set_mem_addr(dma_dev *, dma_tube, __io void *) .. doxygenfunction:: dma_set_per_addr .. doxygendefine:: dma_channel_regs .. doxygendefine:: dma_is_channel_enabled -.. doxygenfunction:: dma_get_isr_bits -.. doxygenfunction:: dma_clear_isr_bits +.. doxygenfunction:: dma_get_isr_bits(dma_dev *, dma_tube) +.. doxygenfunction:: dma_clear_isr_bits(dma_dev *, dma_tube) Register Map Base Pointers -------------------------- diff --git a/docs/source/libmaple/api/gpio.rst b/docs/source/libmaple/api/gpio.rst index 9e8e5c7..5f631d5 100644 --- a/docs/source/libmaple/api/gpio.rst +++ b/docs/source/libmaple/api/gpio.rst @@ -42,14 +42,17 @@ Functions .. doxygenfunction:: gpio_init .. doxygenfunction:: gpio_init_all -.. doxygenfunction:: gpio_set_mode +.. doxygenfunction:: gpio_set_mode(gpio_dev *, uint8, gpio_pin_mode) .. doxygenfunction:: gpio_exti_port .. doxygenfunction:: gpio_write_bit .. doxygenfunction:: gpio_read_bit .. doxygenfunction:: gpio_toggle_bit .. doxygenfunction:: afio_init -.. doxygenfunction:: afio_exti_select + +.. c:macro:: afio_exti_select(exti, port) + + Macro for `exti_select((exti), (port))`. .. _gpio-h-afio-remap: .. doxygenfunction:: afio_remap diff --git a/docs/source/libmaple/api/nvic.rst b/docs/source/libmaple/api/nvic.rst index 505e36e..815da2b 100644 --- a/docs/source/libmaple/api/nvic.rst +++ b/docs/source/libmaple/api/nvic.rst @@ -49,7 +49,7 @@ Functions .. doxygenfunction:: nvic_globalirq_disable .. doxygenfunction:: nvic_irq_enable .. doxygenfunction:: nvic_irq_disable -.. doxygenfunction:: nvic_irq_disable_all +.. doxygenfunction:: nvic_irq_disable_all(void) .. doxygenfunction:: nvic_sys_reset Register Maps diff --git a/docs/source/libmaple/api/util.rst b/docs/source/libmaple/api/util.rst index 54377c0..2f6e080 100644 --- a/docs/source/libmaple/api/util.rst +++ b/docs/source/libmaple/api/util.rst @@ -50,5 +50,5 @@ If an assertion fails, execution is halted at the point of the failed assertion. When libmaple has been configured properly (Wirish performs this configuration by default), the built-in LED throbs in a smooth pattern to signal the failed assertion (using -:c:func:`throb()`), and the file and line where the assert failed are +``throb()``), and the file and line where the assert failed are transmitted to the user as detailed in :ref:`lang-assert`. diff --git a/docs/source/libmaple/overview.rst b/docs/source/libmaple/overview.rst index 006f1d8..4f0db1b 100644 --- a/docs/source/libmaple/overview.rst +++ b/docs/source/libmaple/overview.rst @@ -467,7 +467,7 @@ do a read-modify-write sequence on the DMA_CCR_PL bits like so:: Of course, before doing that, you should check to make sure there's not already a device-level function for performing the same task! (In -this case, there is. It's called :c:func:`dma_set_priority()`; see +this case, there is. It's called ``dma_set_priority()``; see :ref:`libmaple-dma`.) For instance, **none of the above code is portable** to STM32F4, which uses DMA streams instead of channels for this purpose. |