diff options
Diffstat (limited to 'docs/source/libmaple')
29 files changed, 0 insertions, 1183 deletions
diff --git a/docs/source/libmaple/api/adc.rst b/docs/source/libmaple/api/adc.rst deleted file mode 100644 index 8817055..0000000 --- a/docs/source/libmaple/api/adc.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-adc: - -``adc.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: adc.h diff --git a/docs/source/libmaple/api/bitband.rst b/docs/source/libmaple/api/bitband.rst deleted file mode 100644 index fd57944..0000000 --- a/docs/source/libmaple/api/bitband.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-bitband: - -``bitband.h`` -============= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: bitband.h diff --git a/docs/source/libmaple/api/bkp.rst b/docs/source/libmaple/api/bkp.rst deleted file mode 100644 index 9a697c7..0000000 --- a/docs/source/libmaple/api/bkp.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-bkp: - -``bkp.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: bkp.h diff --git a/docs/source/libmaple/api/dac.rst b/docs/source/libmaple/api/dac.rst deleted file mode 100644 index 038753b..0000000 --- a/docs/source/libmaple/api/dac.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-dac: - -``dac.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: dac.h diff --git a/docs/source/libmaple/api/delay.rst b/docs/source/libmaple/api/delay.rst deleted file mode 100644 index a0d013a..0000000 --- a/docs/source/libmaple/api/delay.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-delay: - -``delay.h`` -=========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: delay.h diff --git a/docs/source/libmaple/api/dma.rst b/docs/source/libmaple/api/dma.rst deleted file mode 100644 index 1512d0c..0000000 --- a/docs/source/libmaple/api/dma.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-dma: - -``dma.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: dma.h diff --git a/docs/source/libmaple/api/exti.rst b/docs/source/libmaple/api/exti.rst deleted file mode 100644 index 2909aa7..0000000 --- a/docs/source/libmaple/api/exti.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-exti: - -``exti.h`` -========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: exti.h diff --git a/docs/source/libmaple/api/flash.rst b/docs/source/libmaple/api/flash.rst deleted file mode 100644 index 6f2f9d3..0000000 --- a/docs/source/libmaple/api/flash.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-flash: - -``flash.h`` -=========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: flash.h diff --git a/docs/source/libmaple/api/fsmc.rst b/docs/source/libmaple/api/fsmc.rst deleted file mode 100644 index cecfc99..0000000 --- a/docs/source/libmaple/api/fsmc.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-fsmc: - -``fsmc.h`` -========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: fsmc.h diff --git a/docs/source/libmaple/api/gpio.rst b/docs/source/libmaple/api/gpio.rst deleted file mode 100644 index 2cfec23..0000000 --- a/docs/source/libmaple/api/gpio.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-gpio: - -``gpio.h`` -========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: gpio.h diff --git a/docs/source/libmaple/api/i2c.rst b/docs/source/libmaple/api/i2c.rst deleted file mode 100644 index 14dd304..0000000 --- a/docs/source/libmaple/api/i2c.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-i2c: - -``i2c.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: i2c.h diff --git a/docs/source/libmaple/api/iwdg.rst b/docs/source/libmaple/api/iwdg.rst deleted file mode 100644 index 3911ece..0000000 --- a/docs/source/libmaple/api/iwdg.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-iwdg: - -``iwdg.h`` -========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: iwdg.h diff --git a/docs/source/libmaple/api/libmaple.rst b/docs/source/libmaple/api/libmaple.rst deleted file mode 100644 index d4f28f0..0000000 --- a/docs/source/libmaple/api/libmaple.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-libmaple: - -``libmaple.h`` -============== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: libmaple.h diff --git a/docs/source/libmaple/api/libmaple_types.rst b/docs/source/libmaple/api/libmaple_types.rst deleted file mode 100644 index bbea2c1..0000000 --- a/docs/source/libmaple/api/libmaple_types.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-libmaple_types: - -``libmaple_types.h`` -==================== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: libmaple_types.h diff --git a/docs/source/libmaple/api/nvic.rst b/docs/source/libmaple/api/nvic.rst deleted file mode 100644 index b94dc31..0000000 --- a/docs/source/libmaple/api/nvic.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-nvic: - -``nvic.h`` -========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: nvic.h diff --git a/docs/source/libmaple/api/pwr.rst b/docs/source/libmaple/api/pwr.rst deleted file mode 100644 index 82e4864..0000000 --- a/docs/source/libmaple/api/pwr.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-pwr: - -``pwr.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: pwr.h diff --git a/docs/source/libmaple/api/rcc.rst b/docs/source/libmaple/api/rcc.rst deleted file mode 100644 index 81dc604..0000000 --- a/docs/source/libmaple/api/rcc.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-rcc: - -``rcc.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: rcc.h diff --git a/docs/source/libmaple/api/ring_buffer.rst b/docs/source/libmaple/api/ring_buffer.rst deleted file mode 100644 index a014fa4..0000000 --- a/docs/source/libmaple/api/ring_buffer.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-ring_buffer: - -``ring_buffer.h`` -================= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: ring_buffer.h diff --git a/docs/source/libmaple/api/scb.rst b/docs/source/libmaple/api/scb.rst deleted file mode 100644 index 78cc7eb..0000000 --- a/docs/source/libmaple/api/scb.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-scb: - -``scb.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: scb.h diff --git a/docs/source/libmaple/api/spi.rst b/docs/source/libmaple/api/spi.rst deleted file mode 100644 index b0c7e86..0000000 --- a/docs/source/libmaple/api/spi.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-spi: - -``spi.h`` -========= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: spi.h diff --git a/docs/source/libmaple/api/stm32.rst b/docs/source/libmaple/api/stm32.rst deleted file mode 100644 index 2784540..0000000 --- a/docs/source/libmaple/api/stm32.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-stm32: - -``stm32.h`` -=========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: stm32.h diff --git a/docs/source/libmaple/api/systick.rst b/docs/source/libmaple/api/systick.rst deleted file mode 100644 index fa959f2..0000000 --- a/docs/source/libmaple/api/systick.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. highlight:: c - -.. FIXME [0.1.0] move these to the right places once Breathe is fast -.. enough to use for libmaple proper - -.. _libmaple-systick_disable: - -.. _libmaple-systick_resume: - -.. _libmaple-systick: - -``systick.h`` -============= - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: systick.h diff --git a/docs/source/libmaple/api/timer.rst b/docs/source/libmaple/api/timer.rst deleted file mode 100644 index 3acbf4f..0000000 --- a/docs/source/libmaple/api/timer.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-timer: - -``timer.h`` -=========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: timer.h diff --git a/docs/source/libmaple/api/usart.rst b/docs/source/libmaple/api/usart.rst deleted file mode 100644 index 26e6b9c..0000000 --- a/docs/source/libmaple/api/usart.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-usart: - -``usart.h`` -=========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: usart.h diff --git a/docs/source/libmaple/api/util.rst b/docs/source/libmaple/api/util.rst deleted file mode 100644 index 50ffe76..0000000 --- a/docs/source/libmaple/api/util.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlight:: c -.. _libmaple-util: - -``util.h`` -========== - -[Stub] support. - -Library Documentation ---------------------- - -.. doxygenfile:: util.h diff --git a/docs/source/libmaple/apis.rst b/docs/source/libmaple/apis.rst deleted file mode 100644 index f493406..0000000 --- a/docs/source/libmaple/apis.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _libmaple-apis: - -APIs -==== - -This is the master index for libmaple proper's APIs. - -**Contents** - -.. toctree:: - :maxdepth: 1 - :glob: - - api/* diff --git a/docs/source/libmaple/coding-standard.rst b/docs/source/libmaple/coding-standard.rst deleted file mode 100644 index 23d20f8..0000000 --- a/docs/source/libmaple/coding-standard.rst +++ /dev/null @@ -1,412 +0,0 @@ -.. _libmaple-coding-standard: - -Coding Standard -=============== - -This page documents the coding standard for :ref:`libmaple`. It's -intended as a guide for how you should structure any code you would -like included into the LeafLabs releases of libmaple. - -LeafLabs team members are required to follow these when producing new -code. Community contributors to libmaple are strongly encouraged to -do so; following these rules will greatly increase the probability -that your patches will be folded in. - -In general, follow this guide unless there's a very good reason not -to. Laziness doesn't count as a good reason. Most, if not all, of -these decisions are entirely arbitrary, but it's important for -readability that we be consistent. (If you notice an inconsistency, -you should fix it). - -Note that the file ``.dir-locals.el`` in the libmaple root directory -already ensures that many of these standards are followed by default -in Emacs (but not on Windows, where it would need to be named -``_dir_locals.el``, and no way, man). There's also some elisp -scattered about this file which will provide you additional help. - -Vim customizations to do the same thing would be nice! - -.. contents:: Contents - :local: - -License -------- - -.. highlight:: scheme - -Put an MIT license at the beginning of the file (look at any of our -source files for an example). Copyright should go either to you or to -LeafLabs, LLC. - -Emacs: if you don't like seeing the license, you should use elide-head -(which will hide it for you). You can use the following:: - - (require 'elide-head) - (setq programming-mode-hooks '(c-mode-hook c++-mode-hook)) - (add-to-list 'elide-head-headers-to-hide - '("The MIT License" . "DEALINGS IN\n [*] THE SOFTWARE")) - (add-to-list 'elide-head-headers-to-hide - '("The MIT License" . "DEALINGS IN THE\n...SOFTWARE")) - (dolist (hook programming-mode-hooks) - (add-hook hook (lambda () (elide-head)))) - -Whitespace ----------- - -- 4 space indents (set in ``.dir-locals.el``). - -- Unix newlines. Some exceptions are currently grandfathered in; these - will go away in time. - -- No tab characters (set in ``.dir-locals.el``). - -- No trailing whitespace. For help getting this (and no tab - characters) done automatically in Emacs, you can use - `code-fascism.el <https://github.com/mbolivar/code-fascism>`_. - -- Files end in exactly one newline. The presence of a newline at EOF - is already done by ``c-require-final-newline`` in recent versions of - Emacs. - -- Exactly two newlines separate source paragraphs (you do separate - your code into paragraphs, don't you?). - -- The first line in a function is non-blank. - -.. highlight:: cpp - -- Exactly one space after ``if``, ``else``, ``for``, and ``while``, - before the following ``{`` or ``(``. One space before ``else``, - after the preceding ``}``. For example:: - - // This is good; we like this: - if (foo) { - while (quux) { - bar(); - } - } else { - baz(); - } - - // THIS IS BAD! DON'T DO THIS: - if(foo){ - while(quux){ - bar(); - } - }else{ - baz(); - } - -- Exactly one space in between binary arithmetic, logical, and - comparison operators and their operands. Examples:: - - // This is good: - int x = a + b * (c - d); - if (x != 0 && a > 7) { - SerialUSB.println(x); - } - - // THIS IS BAD! - int x = a+b*(c-d); - if (x!=0 && a>7) { - SerialUSB.println(x); - } - - // This is good: - uint32 adc_data = ADC1_BASE->DR; - SerialUSB.println(adc_data); - - // THIS IS BAD! - uint32 adc_data = ADC1_BASE -> DR; - SerialUSB . println(adc_data); - -- No space between a unary operator and its operand. Examples:: - - // Good: - x++; - - // BAD! - x ++; - - // Good: - y = -x; - - // BAD! - y = - x; - -- If you need to break up a long line: - - * Prefer to break up long expressions after a binary operator. Example:: - - // Good: - if (some_really_long_conditional_wow_this_really_goes_on_forever || - maybe_something_else_could_happen_too) { - ... - } - - // BAD! - if (some_really_long_conditional_wow_this_really_goes_on_forever - || maybe_something_else_could_happen_too) { - ... - } - - * When breaking up a function's arguments over multiple lines, align - the arguments on subsequent lines with the first argument. - Example:: - - // Good: - return_type value_i_got = function_with_a_really_long_name(argument1, - argument2, - argument3); - - // BAD! - return_type value_i_got = function_with_a_really_long_name(argument1, - argument2, - argument3); - - // BAD! - return_type value_i_got = function_with_a_really_long_name(argument1, - argument2, - argument3); - -- In function invocations, no space in between the function name and - the opening parenthesis. Example:: - - // Good: - SerialUSB.println("Hello, world!"); - - // BAD! - SerialUSB.println ("Hello, world!"); - -- Don't indent C code within a conditionally-compiled ``extern "C"`` - block. Example:: - - // Good: - #ifdef __cplusplus - extern "C"{ - #endif - - void some_c_function(void); - - #ifdef __cplusplus - } // extern "C" - #endif - - // BAD! - #ifdef __cplusplus - extern "C"{ - #endif - - void some_c_function(void); - - #ifdef __cplusplus - } // extern "C" - #endif - - Emacs does the "bad" behavior by default, which can be very - annoying. You can turn this off with :: - - (defun c-mode-inextern-lang-hook () - (setcdr (assq 'inextern-lang c-offsets-alist) '-)) - (add-hook 'c-mode-hook c-mode-inextern-lang-hook) - -Comments --------- - -.. highlight:: c++ - -- Multi-line comments are pretty flexible. Any of these is fine:: - - /* Comment starts here. - * Continued lines have a '*' before them. - * The comment can end after the last line. - */ - - /* Comment starts here. - * The comment can end on the same line. */ - - /* - * You can also place a newline after the opening "/*". - */ - -- Doxygen comments are multi-line comments that begin with ``/**`` - instead. - -- Single-line comments are up to you. - -Braces ------- - -- Mostly `1TBS - <http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS>`_. The - only difference is that the opening brace of a function's definition - occurs exactly one space character after the closing parenthesis in - that function's parameter list. Example:: - - void func(void) { - ... - } - -Naming conventions ------------------- - -We'll handle the usual casing/underscore debate as follows. - -- First, ``Dont_Mix_Like_This``, because ``It_Looks_Really_Ugly``, ok? - [There's been some debate about this, and some exceptions are - already grandfathered in, so in order to settle it, let's call this - a "recommendation" instead of "requirement".] - -- Variables: Use underscores to separate words in C identifiers:: - - int some_example_name; - - User-facing C++ variables should be camel cased - (``thisIsAnExample``, ``boardPWMPins``, etc.), for consistency with - the Arduino style. It's probably a good idea for you to case - non-user facing C++ variables in the C style; this will help - disambiguate what's part of the Wirish API and what's not. - -- Classes: Pascal case. So ``ThisIsAClassName``, but ``thisIsNot``, - ``this_is_not``, and ``Dont_You_DareTryANYTHING_STUPID``. - -- Functions: C functions are all lowercase, and words are separated by - underscores. C++ method names are camel cased. - -- Structs: Usually like variables (``adc_dev``, ``adc_reg_map``, - etc.), but it's not crucial. Don't feel obliged to put ``_t`` at - the end of the type name; we don't. - -- Macros and constants: all caps, separated by underscores. C++ - variables with the ``const`` qualifier generally aren't considered - "constants" for the purposes of this rule; i.e., they are cased - according to the rules for variables. We make an exception for - ``PIN_MAP``, because it's the central Wirish data structure. - -- foo.h gets ``#ifdef``\ 'ed to ``_FOO_H_``. - -- Acronyms: The case of letters in an acronym is determined by the - case of the first letter in the acronym, which is determined by - following the above rules. Examples:: - - // Good: - void usb_func() { ... } - void frob_usb_disc() { ... } - class SomethingUSB { - void usbInit(); - void initUSB(); - }; - - // BAD: - class BadUsb { ... }; // say "GoodUSB" instead - void swizzle_USB_disc() { ... } // say "swizzle_usb_disc" instead - -Documentation -------------- - -- Doxygen comments on every user-facing function and type. - Additionally, individually document the fields and enumerator values - of nontrivial user-facing structs and enums. See any register map - type's definition for an example. - -- For libmaple proper, you don't need comments for each register bit - definition, since that's just repeating information better obtained - by reading ST RM0008. - -- Doxygen comments generally only belong on types, functions, - etc. that are part of the public user-facing API. This generally - means that if there's ReST documentation for it under libmaple's - ``docs/source/``, it needs Doxygen comments, and that ReST should - use Breathe to pull that Doxygen comment out. (For more information - on this, see libmaple file ``docs/README``). - - There are some exceptions to this rule since Breathe isn't totally - mature yet and Sphinx's C++ domain is still in flux. In these - cases, document the code "manually" in ReST. - - This should be avoided if at all possible, since it creates a - maintenance burden of documenting things in two places at once, and - makes it easier for documentation to go stale. - - If you do have to document something manually, put a comment in the - source file informing future maintainers about it, so they'll pay - extra attention when making changes. - -- When adding peripheral support, it would be nice if you put - longer-form comments into the libmaple ``notes/`` directory, with a - comment in the corresponding .h file referring to it. See the - :ref:`dac.h <libmaple-dac>` source for an example. - - This lets us keep the source files relatively free of "introductory" - material, while allowing new readers a convenient starting point. - These longer-form notes also have a habit of turning into official, - user-facing documentation. - -- **For libmaple proper**, the convention is to document any - user-facing function at the point where it is defined. In - particular, this means you should document an externally-linked - function defined in a .c file in that .c file, not in the header - file where it is declared to the user. - - **For Wirish**, the convention is to put the documentation in the - header file where the function is declared. - -General Formatting ------------------- - -.. highlight:: scheme - -- Keep it 80-column clean. - - Emacs users: this means that the largest column number is 79. You - should turn on column number mode to help you out:: - - (column-number-mode 1) - - You can get more help from `lineker-mode - <http://www.helsinki.fi/~sjpaavol/programs/lineker.el>`_. Just put - lineker.el somewhere in your load-path, and:: - - (require 'lineker) - (dolist (hook '(c-mode-hook c++-mode-hook)) - (add-hook hook (lambda () (lineker-mode 1)))) - -.. highlight:: cpp - -Language Features ------------------ - -In libmaple proper, aim for C99 compatibility. Some GCC extensions -are OK, but `don't get crazy <http://www.youtube.com/watch?v=jZkdcYlOn5M>`_. - -Explicitly approved GCC extensions: - - * `asm volatile <http://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_ - - * `Nested functions <http://gcc.gnu.org/onlinedocs/gcc/Nested-Functions.html>`_ - -In Wirish, generally be very conservative when using C++ features that -aren't part of C. We are forced to use C++ for Arduino compatibility -(and the general Arduino style of conflating objects and libraries), -but it's an angry beast, and we don't want to provoke it. **The -mantra is "C with classes"**. - -Explicitly approved C++ features: - - * Initializers that aren't constant; e.g. the ``gpio_dev*`` values - in a ``PIN_MAP``. - - * Default arguments: e.g., the timeout argument in - :ref:`lang-waitforbuttonpress`. - -Explicitly forbidden C++ features: - - * Templates - -Conditionally allowed C++ features: - - * Operator overloading: Never allowed when it's just for style. - Probably fine when you're implementing a class that models a - mathematical structure, and you'd like to implement - e.g. ``operator+()``. - diff --git a/docs/source/libmaple/contributing.rst b/docs/source/libmaple/contributing.rst deleted file mode 100644 index bb4d550..0000000 --- a/docs/source/libmaple/contributing.rst +++ /dev/null @@ -1,113 +0,0 @@ -.. _libmaple-contributing: - -Contributing to libmaple -======================== - -First of all, thanks! Community contributions are what makes open -source great. - -If your patch is minor (you've found a typo, you've added a new -function, etc.), feel free to just make a `forum post -<http://forums.leaflabs.com>`_ describing your changes. - -If your changes are larger (you wrote a new library, you added support -for a new peripheral, etc.), we'd prefer you submit a pull request on -GitHub or send us a nicely-formatted patch via email. - -.. contents:: Contents - :local: - -.. _libmaple-faq-patches-preparing: - -Preparing Your Patch --------------------- - -Before submitting a patch, please make sure it complies with the -:ref:`coding standard <libmaple-coding-standard>`. Consistent style throughout -the source tree is an important implementation objective for us, and a -patch that doesn't comply with the coding standard we've set forth is -likely to be sent back until it follows the standard. - -We would prefer if you release each new file you submit under the `MIT -license <http://www.opensource.org/licenses/mit-license.php>`_. See -e.g. `bkp.h -<https://github.com/leaflabs/libmaple/blob/master/libmaple/bkp.h#L1>`_ -for an example, and the coding standard for more details. Code -released under the `Lesser GPL -<http://www.gnu.org/copyleft/lesser.html>`_ may be accepted for -Wirish, but will almost certainly be rejected for libmaple proper. We -will not accept patches released under the `GPL -<http://www.gnu.org/licenses/gpl.html>`_. - -**We're not against the GPL**! It just doesn't suit our purposes for -libmaple. If you're interested in a GPLed library for ST -microcontrollers, check out `libopenstm32 -<http://www.hermann-uwe.de/blog/libopenstm32-a-free-software-firmware-library-for-stm32-arm-cortex-m3-microcontrollers>`_. -Also note that :ref:`libraries <libraries>` released under the GPL are -fine, we just don't want any core libmaple or Wirish code to be GPLed. - -.. _libmaple-faq-patches-github: - -Submitting Via GitHub Pull Request (Preferred) ----------------------------------------------- - -The most convenient way for you to contribute patches is to submit a -pull request on `GitHub <https://github.com>`_. Github provides -excellent code review interfaces, which will make it easy for us at -LeafLabs to communicate with you (and each other) about your patch. -It also makes it easy for us to merge your patch into the libmaple -source tree when the time comes. - -The steps to submit a pull request are as follows: - -1. If you don't already have one, get a `GitHub account - <https://github.com/plans>`_ (free). - -2. Fork libmaple, then clone your fork to the computer you code on. - GitHub provides detailed instructions on `forking and cloning a - repository <http://help.github.com/fork-a-repo/>`_. - -3. Push your commits to your GitHub libmaple fork (see instructions - linked in Step 2 for a step-by-step walkthrough on how to do this). - -4. `Submit a pull request <http://help.github.com/pull-requests/>`_ to - the LeafLabs version of libmaple. - -.. _libmaple-faq-patches-email: - -Submitting Via Email --------------------- - -If you're unfamiliar with Git or would prefer not to use GitHub, you -can always send us a patch via email at info@leaflabs.com. We'd love -it if you used the `Linux kernel patch format -<http://linux.yyz.us/patch-format.html>`_, but please at least include -the following information in your email: - -1. How you generated your patch (arguments to ``diff``, etc.) - -2. What git branch/commit or libmaple version your patch applies to - -3. A one-line summary of your changes, along with any other details - you think we should know. - -4. A sign-off line certifying your `developer certificate of origin - <http://elinux.org/Developer_Certificate_Of_Origin>`_. - -That said, we'd really prefer a pull request. If you'd like to learn -more about Git, we recommend the following resources: - -* `The Git Community Book <http://book.git-scm.com/index.html>`_: A - collaboratively edited book on Git. - -* `Pro Git <http://progit.org/book/>`_: despite its title, this is a - fairly beginner-friendly source of information. - -* `Understanding Git Conceptually - <http://www.eecs.harvard.edu/~cduan/technical/git/>`_: a good, - introductory tutorial on Git's fundamental concepts. - -* `Git for Computer Scientists - <http://eagain.net/articles/git-for-computer-scientists/>`_: if - you're comfortable with directed acyclic graphs, this resource - explains Git's functionality in graph-theoretic terms. diff --git a/docs/source/libmaple/overview.rst b/docs/source/libmaple/overview.rst deleted file mode 100644 index d18bfe2..0000000 --- a/docs/source/libmaple/overview.rst +++ /dev/null @@ -1,336 +0,0 @@ -.. highlight:: c - -.. _libmaple-overview: - -Overview -======== - -This page is a general overview of libmaple proper. It provides a -general perspective of the library's goals and design. Examples are -given from libmaple's sources. - -.. contents:: Contents - :local: - -Design Goals ------------- - -The central goal of the libmaple project is to provide a pleasant, -consistent set of interfaces for dealing with the various peripherals -on the STM32 line. - -Let's start with the basics. If you're interested in low-level details -on the STM32, then you're going to spend a lot of quality time wading -through `ST RM0008 -<http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/REFERENCE_MANUAL/CD00171190.pdf>`_. -That document is the single most important tool in your toolbox. It -is the authoritative documentation for the capabilities and register -interfaces of the STM32 line. - -Perhaps you haven't read it in detail, but maybe you've at least -thumbed through a few of the sections, trying to gain some -understanding of what's going on. If you've done that (and if you -haven't, just take our word for it), then you know that underneath the -covers, *everything* is controlled by messing with bits in the -seemingly endless collections of registers specific to every -peripheral. The :ref:`USARTs <usart>` have data registers; (some of -the) the :ref:`timers <timers>` have capture/compare registers, the -:ref:`GPIOs <gpio>` have output data registers, etc. - -For the most part, Wirish does everything it can to hide this truth -from you. That's because when you really just want to get your robot -to fly, your LEDs to blink, or your `FM synthesizer -<https://github.com/Ixox/preen>`_ to, well, `synthesize -<http://xhosxe.free.fr/IxoxFMSynth.mp3>`_, you probably couldn't care -less about messing with registers. - -That's fine! In fact, it's our explicit goal for Wirish to be good -enough that most people never need to know libmaple proper even -exists. We want to make programming our boards as easy as possible, -after all. But the day may come when you want to add a library for an -as-yet unsupported peripheral, or you want to do something we didn't -anticipate, or you'd like to squeeze a little more speed out of a -critical section in your program. Or maybe you're just curious! - -If anything in the above paragraph describes you, then you'll find -that you need a way to translate your knowledge of RM0008 into -software. We imagine (if you're anything like us) you want to spend -the least amount of time you possibly can doing that -translation. Ideally, once you've finished your design, you want some -way to start reading and writing code right away, without having to -bushwhack your way through a thicket of clunky APIs. - -The central abstractions we've chosen to accomplish the above goals -are *register maps* and *devices*. Register maps are just structs -which encapsulate the layout of the IO-mapped memory regions -corresponding to a peripheral's registers. Devices encapsulate a -peripheral's register map as well as any other necessary information -needed to operate on it. Peripheral support routines generally -operate on devices rather than register maps. - -Devices -------- - -At the highest level, you'll be dealing with *devices*, where a -"device" is a general term for any particular piece of hardware you -might encounter. So, for example, an analog to digital converter is a -device. So is a USART. So is a GPIO port. In this section, we'll -consider some hypothetical "xxx" device. - -The first thing you need to know is that the header file for dealing -with xxx devices is, naturally enough, called ``xxx.h``. So if you -want to interface with the :ref:`ADCs <adc>`, just ``#include -"adc.h"``. - -Inside of ``xxx.h``, there will be a declaration for a ``struct -xxx_dev`` type. This type encapsulates all of the information we keep -track of for that xxx. So, for example, in ``adc.h``, there's a -``struct adc_dev``:: - - /** ADC device type. */ - typedef struct adc_dev { - adc_reg_map *regs; /**< Register map */ - rcc_clk_id clk_id; /**< RCC clock information */ - } adc_dev; - -The ADCs aren't particularly complicated. All we keep track of for an -ADC device is a pointer to its register map (which keeps track of all -of its registers' bits; see :ref:`below <libmaple-overview-regmaps>` -for more details), and an identifying piece of information which tells -the RCC (reset and clock control) interface how to turn the ADC on and -reset its registers to their default values. - -The timers on the STM32 line are more involved than the ADCs, so a -``timer_dev`` has to keep track of a bit more information:: - - /** Timer device type */ - typedef struct timer_dev { - timer_reg_map regs; /**< Register map */ - rcc_clk_id clk_id; /**< RCC clock information */ - timer_type type; /**< Timer's type */ - voidFuncPtr handlers[]; /**< User IRQ handlers */ - } timer_dev; - -However, as you can see, both ADC and timer devices are named -according to a single scheme, and store similar information. - -``xxx.h`` will also declare pointers to the actual devices you need to -deal with, called ``XXX1``, ``XXX2``, etc. (or just ``XXX``, if -there's only one) [#fgpio]_. For instance, on the Maple's -microcontroller (the STM32F103RBT6), there are two ADCs. -Consequently, in ``adc.h``, there are declarations for dealing with -ADC devices one and two:: - - extern const adc_dev *ADC1; - extern const adc_dev *ADC2; - -In general, each device needs to be initialized before it can be used. -libmaple provides this initialization routine for each peripheral -``xxx``; its name is ``xxx_init()``. These initialization routines -turn on the clock to a device, and restore its register values to -their default settings. Here are a few examples:: - - /* From dma.h */ - void dma_init(dma_dev *dev); - - /* From gpio.h */ - void gpio_init(gpio_dev *dev); - void gpio_init_all(void); - -Note that, sometimes, there will be an additional initialization -routine for all available peripherals of a certain kind. - -Many peripherals also need additional configuration before they can be -used. These functions are usually called something along the lines of -``xxx_enable()``, and often take additional arguments which specify a -particular configuration for the peripheral. Some examples:: - - /* From usart.h */ - void usart_enable(usart_dev *dev); - - /* From i2c.h */ - void i2c_master_enable(i2c_dev *dev, uint32 flags); - -After you've initialized, and potentially enabled, your peripheral, it -is now time to begin using it. The file ``xxx.h`` contains other -convenience functions for dealing with xxx devices. For instance, -here are a few from ``adc.h``:: - - void adc_set_sample_rate(const adc_dev *dev, adc_smp_rate smp_rate); - uint32 adc_read(const adc_dev *dev, uint8 channel); - -We aim to enable libmaple's users to interact with peripherals through -devices as much as possible, rather than having to break the -abstraction and consider individual registers. However, there will -always be a need for low-level access. To allow for that, libmaple -provides *register maps* as a consistent set of names and abstractions -for dealing with registers and their bits. - -.. _libmaple-overview-regmaps: - -Register Maps -------------- - -A *register map* is just a C struct which names and provides access to -a peripheral's registers. These registers are usually mapped to -contiguous regions of memory (though at times unusable or reserved -regions exist between a peripheral's registers). Here's an example -register map, from ``dac.h`` (``__io`` is just libmaple's way of -saying ``volatile`` when referring to register values):: - - /** DAC register map. */ - typedef struct dac_reg_map { - __io uint32 CR; /**< Control register */ - __io uint32 SWTRIGR; /**< Software trigger register */ - __io uint32 DHR12R1; /**< Channel 1 12-bit right-aligned data - holding register */ - __io uint32 DHR12L1; /**< Channel 1 12-bit left-aligned data - holding register */ - __io uint32 DHR8R1; /**< Channel 1 8-bit left-aligned data - holding register */ - __io uint32 DHR12R2; /**< Channel 2 12-bit right-aligned data - holding register */ - __io uint32 DHR12L2; /**< Channel 2 12-bit left-aligned data - holding register */ - __io uint32 DHR8R2; /**< Channel 2 8-bit left-aligned data - holding register */ - __io uint32 DHR12RD; /**< Dual DAC 12-bit right-aligned data - holding register */ - __io uint32 DHR12LD; /**< Dual DAC 12-bit left-aligned data - holding register */ - __io uint32 DHR8RD; /**< Dual DAC 8-bit left-aligned data holding - register */ - __io uint32 DOR1; /**< Channel 1 data output register */ - __io uint32 DOR2; /**< Channel 2 data output register */ - } dac_reg_map; - - -There are two things to notice here. First, if RM0008 names a -register ``DAC_FOO``, then ``dac_reg_map`` has a field named ``FOO``. -So, the Channel 1 12-bit right-aligned data register (RM0008: -DAC_DHR12R1) is the ``DHR12R1`` field in a ``dac_reg_map``. Second, -if RM0008 describes a register as "Foo bar register", the -documentation for the corresponding field has the same description. -This consistency makes it easy to search for a particular register, -and, if you see one used in a source file, to feel sure about what's -going on just based on its name. - -So let's say you've included ``xxx.h``, and you want to mess with some -particular register. What's the name of the ``xxx_reg_map`` variable -you want? That depends on if there's more than one xxx or not. If -there's only one xxx, then libmaple guarantees there will be a -``#define`` that looks like like this:: - - #define XXX_BASE ((struct xxx_reg_map*)0xDEADBEEF) - -That is, you're guaranteed there will be a pointer to the (only) -``xxx_reg_map`` you want, and it will be called -``XXX_BASE``. (``0xDEADBEEF`` is the register map's *base address*, or -the fixed location in memory where the register map begins). Here's a -concrete example from ``dac.h``:: - - #define DAC_BASE ((struct dac_reg_map*)0x40007400) - -How can you use these? This is perhaps best explained by example. - -* In order to write 2048 to the channel 1 12-bit left-aligned data - holding register (RM0008: DAC_DHR12L1), you could write:: - - DAC_BASE->DHR12L1 = 2048; - -* In order to read the DAC control register, you could write:: - - uint32 cr = DAC_BASE->CR; - -The microcontroller takes care of converting reads and writes from a -register's IO-mapped memory regions into reads and writes to the -corresponding hardware registers. - -That covers the case where there's a single xxx peripheral. If -there's more than one (say, if there are *n*), then ``xxx.h`` provides -the following:: - - #define XXX1_BASE ((struct xxx_reg_map*)0xDEADBEEF) - #define XXX2_BASE ((struct xxx_reg_map*)0xF00DF00D) - ... - #define XXXn_BASE ((struct xxx_reg_map*)0x13AF1AB5) - -Here are some examples from ``adc.h``:: - - #define ADC1_BASE ((struct adc_reg_map*)0x40012400) - #define ADC2_BASE ((struct adc_reg_map*)0x40012800) - -In order to read from the ADC1's regular data register (where the -results of ADC conversion are stored), you might write:: - - uint32 converted_result = ADC1_BASE->DR; - -Register Bit Definitions ------------------------- - -In ``xxx.h``, there will also be a variety of #defines for dealing -with interesting bits in the xxx registers, called *register bit -definitions*. These are named according to the scheme -``XXX_REG_FIELD``, where "``REG``" refers to the register, and -"``FIELD``" refers to the bit or bits in ``REG`` that are special. - -.. TODO image of the bit layout of a DMA_CCR register - -Again, this is probably best explained by example. Each Direct Memory -Access (DMA) controller's register map has a certain number of channel -configuration registers (RM0008: DMA_CCRx). In each of these channel -configuration registers, bit 14 is called the ``MEM2MEM`` bit, and -bits 13 and 12 are the priority level (``PL``) bits. Here are the -register bit definitions for those fields:: - - /* From dma.h */ - - #define DMA_CCR_MEM2MEM_BIT 14 - #define DMA_CCR_MEM2MEM BIT(DMA_CCR_MEM2MEM_BIT) - #define DMA_CCR_PL (0x3 << 12) - #define DMA_CCR_PL_LOW (0x0 << 12) - #define DMA_CCR_PL_MEDIUM (0x1 << 12) - #define DMA_CCR_PL_HIGH (0x2 << 12) - #define DMA_CCR_PL_VERY_HIGH (0x3 << 12) - -Thus, to check if the ``MEM2MEM`` bit is set in DMA controller 1's -channel configuration register 2 (RM0008: DMA_CCR2), you can write:: - - if (DMA1_BASE->CCR2 & DMA_CCR_MEM2MEM) { - /* MEM2MEM is set */ - } - -Certain register values occupy multiple bits. For example, the -priority level (PL) of a DMA channel is determined by bits 13 and 12 -of the corresponding channel configuration register. As shown above, -libmaple provides several register bit definitions for masking out the -individual PL bits and determining their meaning. For example, to -check the priority level of a DMA transfer, you can write:: - - switch (DMA1_BASE->CCR2 & DMA_CCR_PL) { - case DMA_CCR_PL_LOW: - /* handle low priority case */ - case DMA_CCR_PL_MEDIUM: - /* handle medium priority case */ - case DMA_CCR_PL_HIGH: - /* handle high priority case */ - case DMA_CCR_PL_VERY_HIGH: - /* handle very high priority case */ - } - -Of course, before doing that, you should check to make sure there's -not already a device-level function for performing the same task! - -What Next? ----------- - -After you've read this page, you can proceed to the :ref:`libmaple API -listing <libmaple-apis>`. From there, you can read documentation and -follow links to the current source code for those files on `libmaple's -GitHub page <https://github.com/leaflabs/libmaple>`_. - -.. rubric:: Footnotes - -.. [#fgpio] For consistency with RM0008, GPIO ports are given letters - instead of numbers (``GPIOA`` and ``GPIOB`` instead of - ``GPIO1`` and ``GPIO2``, etc.). |