diff options
| author | Marti Bolivar <mbolivar@leaflabs.com> | 2011-06-11 19:25:29 -0400 |
|---|---|---|
| committer | Marti Bolivar <mbolivar@leaflabs.com> | 2011-06-11 20:05:33 -0400 |
| commit | 0c2b3c667bf157dc2344e3dbc2aae0e11e37387b (patch) | |
| tree | 3008ee192c80f17f640ebdeb870442e78415ce6b /docs/source/libmaple | |
| parent | d4b576fcadecf66b7b754af7d204bb6f3b4a9830 (diff) | |
| download | librambutan-0c2b3c667bf157dc2344e3dbc2aae0e11e37387b.tar.gz librambutan-0c2b3c667bf157dc2344e3dbc2aae0e11e37387b.zip | |
Remove reST documentation, attendant updates.
The documentation covers topics not specifically relevant to libmaple,
so it doesn't make sense for it to be part of the libmaple source
distribution.
Delete the docs/ tree, and prepare libmaple for use with the new
leaflabs-docs repo, which will contain the docs from now on.
* README: update to reflect this change
* support/doxygen/Doxyfile: This is the old docs/Doxyfile
* Makefile: Add a doxygen target
* wirish/comm/HardwareSerial.h: fix reference to docs/. The comment
informing maintainers that the HardwareSerial interface is
documented by hand refers to the docs/ tree, which no longer exists.
Update it to refer to the separate leaflabs-docs repository.
* support/scripts/copy-to-ide: No longer build the documentation
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.). |