diff options
| author | Marti Bolivar <mbolivar@leaflabs.com> | 2011-04-25 16:07:38 -0400 |
|---|---|---|
| committer | Marti Bolivar <mbolivar@leaflabs.com> | 2011-04-25 16:07:38 -0400 |
| commit | d6bb86b9e458bbf4f5a376caf05b2bc796a53aea (patch) | |
| tree | ea01275fd4b3f48fb627abd2be5c1611047bdb58 /docs | |
| parent | d64c13caf100c7fa638596bd568cce3ce2ffce0a (diff) | |
| download | librambutan-d6bb86b9e458bbf4f5a376caf05b2bc796a53aea.tar.gz librambutan-d6bb86b9e458bbf4f5a376caf05b2bc796a53aea.zip | |
0.0.10 documentation checkpoint.
Merging in the standalone refactor docs, etc. The individual libmaple
API pages are going to need to get redone.
Diffstat (limited to 'docs')
50 files changed, 1507 insertions, 337 deletions
diff --git a/docs/Doxyfile b/docs/Doxyfile index 9bf02fc..5fbb079 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -608,7 +608,7 @@ INPUT_ENCODING = UTF-8 # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 -FILE_PATTERNS = *.h +FILE_PATTERNS = *.h *.c # The RECURSIVE tag can be used to turn specify whether or not subdirectories # should be searched for input files as well. Possible values are YES and NO. @@ -1372,7 +1372,10 @@ INCLUDE_FILE_PATTERNS = # instead of the = operator. PREDEFINED = __attribute__()= \ - __cplusplus + __cplusplus \ + STM32_MEDIUM_DENSITY + STM32_HIGH_DENSITY + STM32_XL_DENSITY # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/docs/source/_static/img/libmaple-screenshot-small.png b/docs/source/_static/img/libmaple-screenshot-small.png Binary files differdeleted file mode 100644 index f2be783..0000000 --- a/docs/source/_static/img/libmaple-screenshot-small.png +++ /dev/null diff --git a/docs/source/adc.rst b/docs/source/adc.rst index 6bbbac2..b943808 100644 --- a/docs/source/adc.rst +++ b/docs/source/adc.rst @@ -71,11 +71,10 @@ Recommended Reading ------------------- * `Wikipedia article on Analog-to-digital converter <http://en.wikipedia.org/wiki/Analog-to-digital_converter>`_ + * `Arduino Analog Input Tutorial <http://arduino.cc/en/Tutorial/AnalogInputPins>`_ -* STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) - * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) +* STMicro documentation: + * `Application Note on ADC Modes (pdf) <http://www.st.com/stonline/products/literature/an/16840.pdf>`_ * `Application Note on ADC Oversampling (pdf) <http://www.st.com/stonline/products/literature/an/14183.pdf>`_ diff --git a/docs/source/compatibility.rst b/docs/source/arduino-compatibility.rst index eb28ad2..e6852a0 100644 --- a/docs/source/compatibility.rst +++ b/docs/source/arduino-compatibility.rst @@ -1,6 +1,6 @@ .. highlight:: cpp -.. _compatibility: +.. _arduino-compatibility: ============================= Maple-Arduino Compatibility @@ -41,18 +41,19 @@ means that programs aren't much larger (or are even smaller). Header Numbering and Incompatibilities -------------------------------------- -.. FIXME generalize Maple-specific information +.. FIXME [Maple-specific values] The numbering of headers is different; on the Maple each GPIO has a -unique number: D0, D1, D2, all the way up to D37 (actually, there are +unique number: 0, 1, 2, all the way up to 37 (actually, there are :ref:`a few more <jtag>`...). On the Arduino, the analog pins are numbered separately (A0-A5) from the digital pins (D0\ -D13). The incompatible hardware differences are: -* **I2C port**: on most Arduinos, the |i2c| port is Analog Input 4 - (SDA) and Analog Input 5 (SCL); on the Maple, |i2c| port 1 is D5 - (SCL) and D9 (SDA), and |i2c| port 2 is D29 (SCL) and D30 (SDA). +* :ref:`I2C <i2c>` **port**: on most Arduinos, the |i2c| port is Analog + Input 4 (SDA) and Analog Input 5 (SCL); on the Maple, |i2c| port 1 + is D5 (SCL) and D9 (SDA), and |i2c| port 2 is D29 (SCL) and D30 + (SDA). It should be possible to skywire, sacrificing signal quality (due to increased capacitance). Alternatively, |i2c| can be bit-banged @@ -61,9 +62,7 @@ The incompatible hardware differences are: * :ref:`PWM <pwm>` **on D10**: all the other standard Arduino PWM headers have PWM functionality on the Maple (D2,D3,D6,D9,D11), but - not D10. We did our best! It may be possible to reroute this - peripheral internally using low level configuration, but we haven't - looked in to it. + not D10. * **No External Voltage Reference**: The Arduino has an AREF pin which allows the use of an external ADC voltage reference; the Maple has @@ -98,15 +97,15 @@ differences, most of which are improvements: modes with a single call to ``pinMode()``: ``OUTPUT``, ``OUTPUT_OPEN_DRAIN``, ``INPUT_FLOATING``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``. Additionally, the PWM pins (labeled "PWM" on the - Maple's silkscreen) can be configured in ``PWM`` and - ``PWM_OPEN_DRAIN`` modes, and the analog input pins (labeled "AIN") - can be configured in ``INPUT_ANALOG`` mode. See the :ref:`GPIO - documentation <gpio>` for more information. + silkscreen) can be configured in ``PWM`` and ``PWM_OPEN_DRAIN`` + modes, and the analog input pins (labeled "AIN") can be configured + in ``INPUT_ANALOG`` mode. See the :ref:`GPIO documentation <gpio>` + for more information. * :ref:`Serial port <lang-serial>` **syntax**: like the `Arduino Mega <http://arduino.cc/en/Main/ArduinoBoardMega>`_, the Maple has multiple :ref:`USART ports <lang-serial>`. By default, ``Serial`` - is not mapped to any of them, use ``Serial1`` through ``Serial3`` + is not mapped to any of them. Use ``Serial1`` through ``Serial3`` instead. * **16-bit** :ref:`PWM <pwm>`: Arduino boards support 8-bit PWM, which @@ -229,7 +228,8 @@ function. - Check for ported library functionality. We intend to port all of the core and popular libraries (like Wire, Ethernet, and the LCD screen - driver), but this task is not yet finished. (Patches are welcome!) + driver), but this task is not yet finished. (:ref:`Patches are + welcome! <libmaple-contributing>`). - Check for peripheral conflicts; changing the configuration of timers and bus speeds for a feature on one header may impact all the diff --git a/docs/source/arm-gcc.rst b/docs/source/arm-gcc.rst index 7ecb5d4..e97bb2f 100644 --- a/docs/source/arm-gcc.rst +++ b/docs/source/arm-gcc.rst @@ -5,7 +5,7 @@ GCC for Maple ============= This document provides notes on using of ``arm-none-eabi-gcc``, the -`CodeSourcery <http://codesourcery.com>`_ version of the GNU `GCC +`CodeSourcery <http://www.codesourcery.com/>`_ version of the GNU `GCC <http://gcc.gnu.org/>`_ compilers used for the Maple boards. It is not intended as a reference manual for GCC; such manuals are available `elsewhere <http://gcc.gnu.org/>`_. diff --git a/docs/source/bootloader.rst b/docs/source/bootloader.rst index 917a1b7..85b2674 100644 --- a/docs/source/bootloader.rst +++ b/docs/source/bootloader.rst @@ -13,7 +13,7 @@ Flash memory and only runs when the chip is reset). git clone git://github.com/leaflabs/maple-bootloader.git -**Visit the github development project**: http://github.com/leaflabs/maple-bootloader +**Visit the github development project**: https://github.com/leaflabs/maple-bootloader .. contents:: Contents :local: @@ -34,7 +34,7 @@ likely only interesting to a few. If you just want to get the rough idea, skim this article. If you want to start hacking on the bootloader, get in touch with us to get even more info on how this all works. And finally, you can always `check out the code at github -<http://github.com/leaflabs/libmaple>`_! +<https://github.com/leaflabs/libmaple>`_! Arduino ------- diff --git a/docs/source/errata.rst b/docs/source/errata.rst deleted file mode 100644 index 657abd9..0000000 --- a/docs/source/errata.rst +++ /dev/null @@ -1,140 +0,0 @@ -.. _errata: - -======== - Errata -======== - -This page is a collection of known issues and warnings for each -revision of the Maple board. The failure modes aren't design errors, -but are easy ways to break or damage your board permanently. For a -list of differences between the Maple and Arduinos, see the -:ref:`compatibility reference <compatibility>`. - -The errata are grouped by Maple version ("Rev"). Rev 5 is currently -on sale. If you are unsure which version you own, the :ref:`Maple -hardware page <maple-hardware-identify-rev>` has pictures and -descriptions of each version. - -.. contents:: Contents - :local: - -Maple Rev 5 ------------ - -Known issues: - -* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the - corresponding "AIN" is missing from its silkscreen. - -* **GPIO 39-43 not configured**: this is really more of a software - "TODO" item. Some of the JTAG header pins are numbered 39-43. These - STM32 pins are indeed fully functional :ref:`GPIO <gpio>` when a - :ref:`JTAG <jtag>` device is not connected, but we have not enabled - them in software and thus they can not be accessed with the regular - :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. - -Potential failure modes: - -* **High voltage on non-tolerant pins**: not all header pins are 5V - compatible; so e.g. connecting certain serial devices in the wrong - way could over-voltage the pins. The :ref:`Pin-Mapping Mega Table - <pin-mapping-mega-table>` details which pins are 5V-tolerant. - -Maple Rev 3 ------------ - -Known issues: - -* **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010 - have questionable RESET and BUT buttons. - - What seems to have happened is that the flux remover we used to - clean the boards before shipping eroded the plastic internals, which - resulted in intermittent functionality. All buttons on all shipped - boards did function in testing, but some may have been unreliable in - regular use. - - If you have this problem, we will be happy to ship you new buttons - if you think you can re-solder them yourself, or you can ship us - your board and we will swap out that part. - - For reference, the button part number is KMR211GLFS and the flux - remover we used is "Precision Electronics Cleaner" from RadioShack, - which is "Safe on most plastics" and contains Dipropylene glycol - monomethyl ether, hydrotreated heavy naphtha, dipropylene glycol - methyl ether acetate (really?), and carbon dioxide. - -* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on - USART2 (:ref:`Serial2 <lang-serial>`), have resistors in-line - between the STM32 and the headers. These resistors increase the - impedance of the lines for ADC reads and affect the open drain GPIO - functionality of the pins. - - These resistors were accidentally copied over from older Arduino USB - designs, where they appear to protect the USB-Serial converter from - TTL voltage on the headers. - -* **GPIO 39-43 not configured**: this is really more of a software - "TODO" item. Some of the JTAG header pins are numbered 39-43. These - STM32 pins are indeed fully functional :ref:`GPIO <gpio>` when the a - :ref:`JTAG <jtag>` device is not connected, but we have not enabled - them in software and thus they can not be accessed with the regular - :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. - -* **Silkscreen Errors**: the silkscreen on the bottom indicated PWM - functionality on pin 25 and listen the external header GND pin as - number 38 (actually 38 is connected to the BUT button). We manually - sharpied over both of these mistakes. - -* **PWM Marketing Mistake**: We originally sold the Maple advertising - 22 channels of 16-bit hardware PWM; actually the Maple only has 15. - -Potential failure modes: - -* **TTL voltage on non-tolerant pins**: not all header pins are 5V - compatible; connecting certain serial devices in the wrong way could - over voltage the pins. The :ref:`Pin-Mapping Mega Table - <pin-mapping-mega-table>` details which pins are 5V-tolerant. - -Maple Rev 1 ------------ - -Known issues: - -* **ADC noise**: generally very high, in particular when the USB port - is being used for communications (including keep-alive pings when - connected to a computer). - - This issue was resolved in Rev 3 with a 4-layer design and a - geometrically isolated ADC V\ :sub:`ref` plane. - -* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on - USART2 (:ref:`Serial2 <lang-serial>`), have resistors in-line - between the STM32 and the headers. These resistors increase the - impedance of the lines for ADC reads and affect the open drain GPIO - functionality of the pins. - - These resistors were accidentally copied over from older Arduino USB - designs, where they appear to protect the USB-Serial converter from - TTL voltage on the headers. - -* **Silkscreen Differences**: the pin numbering scheme on Rev 1 is - different from Rev 3, and thus Rev 3 software is difficult to use - with Rev 1 boards. Notably, the analog input bank is labeled A0-A4 - on Rev 1 but 15-20 on Rev 3, and the extra header bank does not have - a pinout table on the bottom. - -* **No BUT Button**: the BUT button, useful for serial bootloading, - was only added in Rev 3. As a workaround, you can directly short the - appropriate MCU pin to Vcc; see `this forum posting - <http://forums.leaflabs.com/topic.php?id=32#post-126>`_. - -* **PWM Marketing Mistake**: We originally sold the Maple advertising - 22 channels of 16-bit hardware PWM; actually the Maple only has 15. - -Potential failure modes: - -* **TTL voltage on non-tolerant pins**: not all header pins are 5v - compatible; connecting certain serial devices in the wrong way could - over voltage the pins. The :ref:`Pin-Mapping Mega Table - <pin-mapping-mega-table>` details which pins are 5V-tolerant. diff --git a/docs/source/gpio.rst b/docs/source/gpio.rst index 5daf43c..0f9f4df 100644 --- a/docs/source/gpio.rst +++ b/docs/source/gpio.rst @@ -3,7 +3,7 @@ GPIO ==== -.. FIXME generalize this maple-specific information +.. FIXME [Maple-specific values] The Maple features 38 ready-to-use general purpose input/output (GPIO) pins for digital input/output, numbered D0 through D37. These numbers diff --git a/docs/source/hardware/maple.rst b/docs/source/hardware/maple.rst index 874ee82..44a5238 100644 --- a/docs/source/hardware/maple.rst +++ b/docs/source/hardware/maple.rst @@ -8,6 +8,30 @@ Maple .. contents:: Contents :local: +Technical Specifications +------------------------ + + * MCU: **STM32F103RBT6**, a 32-bit ARM Cortex M3 microprocessor + * Clock Speed: **72 MHz** + * Operating Voltage: 3.3V + * Input Voltage (recommended): 3V-12V + * 39 Digital I/O Pins (:ref:`GPIO <gpio>`) + * 16 Analog Input Pins + * 12-bit **ADC** resolution (:ref:`ADC <adc>`) + * 15 **PWM** pins at 16-bit resolution (:ref:`PWM <pwm>`) + * Dedicated **USB** port for programming and communications (:ref:`USB<usb>`) + * External **JTAG** interface (:ref:`USB <jtag>`) + * **128 Flash** and **20KB SRAM** + * 64 Channel nested vector interrupt handler (including external interrupt on GPIOs) + * Integrated **SPI** (:ref:`SPI<spi>`) + * Integrated **I2C** (:ref:`I2C<i2c>`) + * 7 Channels of Direct Memory Access (**DMA**) + * 3 **USART** divices (:ref:`USART <usart>`) + * Four 4-channel **timers** (:ref:`Timers <timers>`) + * Supplies up to 800mA @ 3.3v + * Support for low power and sleep modes (<500uA) + * Dimensions are 2.05″x2.1″ + .. _maple-hardware-identify-rev: Identifying your Rev @@ -16,17 +40,22 @@ Identifying your Rev We went through three versions ("Revs") of the Maple hardware: Rev 1, Rev 3, and Rev 5 [#frev2_4]_; Rev 5, the final design, is currently on sale. The following sections will help you to help you identify your -Rev. Known issues are listed in the :ref:`errata <errata>`. +Rev. Known issues are listed in the :ref:`errata <maple-errata>`. -Rev 1 +Rev 5 ^^^^^ -A small number of Maple Rev 1 boards went on sale in late 2009. They -have a light red silkscreen and a single pixelated leaf as a logo. +These boards went on sale in November 2010. They have white buttons, +and "r5" in small print near the "LeafLabs Maple" text next to the +"infinity leaf" logo. The Maple Rev 5 repositioned the double header +on the right hand side to better fit 0.1 inch pitch breadboard. This +necessitated the removal of pins 21 and 22 from the double header; +they are still available, but don't have any headers installed on +them. -.. figure:: /_static/img/maple_rev1.png +.. figure:: /_static/img/maple_rev5.png :align: center - :alt: Maple Rev 1 + :alt: Maple Rev 5 Rev 3 ^^^^^ @@ -40,20 +69,15 @@ It also includes a built-in LiPo battery charger. :align: center :alt: Maple Rev 3 -Rev 5 +Rev 1 ^^^^^ -These boards went on sale in November 2010. They have white buttons, -and "r5" in small print near the "LeafLabs Maple" text next to the -"infinity leaf" logo. The Maple Rev 5 repositioned the double header -on the right hand side to better fit 0.1 inch pitch breadboard. This -necessitated the removal of pins 21 and 22 from the double header; -they are still available, but don't have any headers installed on -them. +A small number of Maple Rev 1 boards went on sale in late 2009. They +have a light red silkscreen and a single pixelated leaf as a logo. -.. figure:: /_static/img/maple_rev5.png +.. figure:: /_static/img/maple_rev1.png :align: center - :alt: Maple Rev 5 + :alt: Maple Rev 1 .. _hardware-maple-powering: @@ -99,8 +123,150 @@ at the command line with :: $ git clone git://github.com/leaflabs/maple.git +.. _maple-errata: + +Errata +------ + +This section lists known issues and warnings for each revision of the +Maple board. The failure modes aren't design errors, but are easy ways +to break or damage your board permanently. For a list of differences +between the Maple and Arduinos, see the :ref:`Arduino Compatibility +reference <arduino-compatibility>`. + +The errata are grouped by Maple version ("Rev"). + +Maple Rev 5 +^^^^^^^^^^^ + +Known issues: + +* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the + corresponding "AIN" is missing from its silkscreen. + +* **GPIO 39-43 not configured**: this is really more of a software + "TODO" item. Some of the JTAG header pins are numbered 39-43. These + STM32 pins are indeed fully functional :ref:`GPIO <gpio>` when a + :ref:`JTAG <jtag>` device is not connected, but we have not enabled + them in software and thus they can not be accessed with the regular + :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. + +Potential failure modes: + +* **High voltage on non-tolerant pins**: not all header pins are 5V + compatible; so e.g. connecting certain serial devices in the wrong + way could over-voltage the pins. The :ref:`Pin-Mapping Mega Table + <pin-mapping-mega-table>` details which pins are 5V-tolerant. + +Maple Rev 3 +^^^^^^^^^^^ + +Known issues: + +* **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010 + have questionable RESET and BUT buttons. + + What seems to have happened is that the flux remover we used to + clean the boards before shipping eroded the plastic internals, which + resulted in intermittent functionality. All buttons on all shipped + boards did function in testing, but some may have been unreliable in + regular use. + + If you have this problem, we will be happy to ship you new buttons + if you think you can re-solder them yourself, or you can ship us + your board and we will swap out that part. + + For reference, the button part number is KMR211GLFS and the flux + remover we used is "Precision Electronics Cleaner" from RadioShack, + which is "Safe on most plastics" and contains Dipropylene glycol + monomethyl ether, hydrotreated heavy naphtha, dipropylene glycol + methyl ether acetate (really?), and carbon dioxide. + +* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on + USART2 (:ref:`Serial2 <lang-serial>`), have resistors in-line + between the STM32 and the headers. These resistors increase the + impedance of the lines for ADC reads and affect the open drain GPIO + functionality of the pins. + + These resistors were accidentally copied over from older Arduino USB + designs, where they appear to protect the USB-Serial converter from + TTL voltage on the headers. + +* **GPIO 39-43 not configured**: this is really more of a software + "TODO" item. Some of the JTAG header pins are numbered 39-43. These + STM32 pins are indeed fully functional :ref:`GPIO <gpio>` when the a + :ref:`JTAG <jtag>` device is not connected, but we have not enabled + them in software and thus they can not be accessed with the regular + :ref:`lang-pinmode` or :ref:`lang-digitalwrite` functions. + +* **Silkscreen Errors**: the silkscreen on the bottom indicated PWM + functionality on pin 25 and listen the external header GND pin as + number 38 (actually 38 is connected to the BUT button). We manually + sharpied over both of these mistakes. + +* **PWM Marketing Mistake**: We originally sold the Maple advertising + 22 channels of 16-bit hardware PWM; actually the Maple only has 15. + +Potential failure modes: + +* **TTL voltage on non-tolerant pins**: not all header pins are 5V + compatible; connecting certain serial devices in the wrong way could + over voltage the pins. The :ref:`Pin-Mapping Mega Table + <pin-mapping-mega-table>` details which pins are 5V-tolerant. + +Maple Rev 1 +^^^^^^^^^^^ + +Known issues: + +* **ADC noise**: generally very high, in particular when the USB port + is being used for communications (including keep-alive pings when + connected to a computer). + + This issue was resolved in Rev 3 with a 4-layer design and a + geometrically isolated ADC V\ :sub:`ref` plane. + +* **Resistors on pins 0 and 1**: these header pins, which are RX/TX on + USART2 (:ref:`Serial2 <lang-serial>`), have resistors in-line + between the STM32 and the headers. These resistors increase the + impedance of the lines for ADC reads and affect the open drain GPIO + functionality of the pins. + + These resistors were accidentally copied over from older Arduino USB + designs, where they appear to protect the USB-Serial converter from + TTL voltage on the headers. + +* **Silkscreen Differences**: the pin numbering scheme on Rev 1 is + different from Rev 3, and thus Rev 3 software is difficult to use + with Rev 1 boards. Notably, the analog input bank is labeled A0-A4 + on Rev 1 but 15-20 on Rev 3, and the extra header bank does not have + a pinout table on the bottom. + +* **No BUT Button**: the BUT button, useful for serial bootloading, + was only added in Rev 3. As a workaround, you can directly short the + appropriate MCU pin to Vcc; see `this forum posting + <http://forums.leaflabs.com/topic.php?id=32#post-126>`_. + +* **PWM Marketing Mistake**: We originally sold the Maple advertising + 22 channels of 16-bit hardware PWM; actually the Maple only has 15. + +Potential failure modes: + +* **TTL voltage on non-tolerant pins**: not all header pins are 5v + compatible; connecting certain serial devices in the wrong way could + over voltage the pins. The :ref:`Pin-Mapping Mega Table + <pin-mapping-mega-table>` details which pins are 5V-tolerant. + +Recommended Reading +------------------- + +* STMicro documentation for STM32F103RB microcontroller: + + * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) + * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) + * `Programming Manual <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ (assembly language and register reference) + .. rubric:: Footnotes .. [#frev2_4] Revs 2 and 4 were prototypes that didn't pass internal testing. - diff --git a/docs/source/i2c.rst b/docs/source/i2c.rst index e2a7a04..15190a8 100644 --- a/docs/source/i2c.rst +++ b/docs/source/i2c.rst @@ -1,20 +1,8 @@ .. _i2c: -===== |i2c| ===== -.. FIXME update this documentation once you write the Wire library on -.. top of libmaple i2c. - -.. FIXME generalize Maple-specific documentation - -.. note:: - - The |i2c| interface is currently only available from the 'refactor' - branch of the github `libmaple - <http://github.com/leaflabs/libmaple>`_ repository. - |i2c| is a crude and easy-to-hack serial protocol that requires only two wires/channels for communication between many devices. Every message passed on the bus is between a *master* (who initiates the @@ -26,6 +14,8 @@ Higher level functionality, such as reading a particular register value, is achieved by writing to set the memory location then reading to pull out the data. +.. FIXME [Maple-specific values] + Note that the master/slave designation is on a message-by-message basis. The Maple can act as both a master (messages initiated by user code) and slave device (responding to requests via configurable @@ -37,8 +27,8 @@ interrupt handlers) at the same time. Hardware/Circuit Design ----------------------- -The Maple has two |i2c| ports. Port 1 (i2c1) has SDA on header D9 and -SCL on D5; Port 2 (i2c2) has SDA on D30 and SCL on D29. +The Maple has two |i2c| ports. Port 1 (I2C1) has SDA on header D9 and +SCL on D5; Port 2 (I2C2) has SDA on D30 and SCL on D29. The Maple reliably communicates with up to a 400kHz clock speed; this doesn't translate into a 400kbps data rate except in extreme cases @@ -60,16 +50,15 @@ oscilloscope to debug any issues. Function Reference ------------------ -The function API for |i2c| is not finished! See the `source code -<https://github.com/leaflabs/libmaple/blob/refactor/libmaple/i2c.h>`_ -for now. +Currently, only low-level support in :ref:`libmaple-i2c` exists. A +Wiring-style library is planned for a future release. SMBus ----- The STM32 microcontroller has hardware support for SMBus; we simply -have not written software for it. The SMBAL line for i2c1 is on header -D4 and for i2c2 is on D31. +have not written software for it. The SMBAL line for I2C1 is on header +D4 and for I2C2 is on D31. .. _i2c-recommended-reading: diff --git a/docs/source/index.rst b/docs/source/index.rst index 1d1a5be..9db5ff0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,11 +3,13 @@ Maple Documentation Contents ============================ +.. FIXME [Maple-specific values] errata page links to Maple + Welcome! This is the Maple documentation index. If you just bought a Maple, you probably want to head to the :ref:`quickstart <maple-quickstart>`. If you're having problems, check out the -:ref:`troubleshooting <troubleshooting>` and :ref:`known problems -<errata>` pages. +:ref:`troubleshooting <troubleshooting>` :ref:`known problems +<maple-errata>` pages. Have fun! @@ -32,12 +34,12 @@ Have fun! Language <language> Libraries <libraries> - Arduino Compatibility <compatibility> + Arduino Compatibility <arduino-compatibility> libmaple <libmaple> Bootloader <bootloader> Troubleshooting <troubleshooting> - Known Problems <errata> Notes on GCC's ARM target <arm-gcc> + Complete Language Index <language-index> .. _index-hardware: @@ -73,15 +75,3 @@ Have fun! .. hardware/maple-mini.rst .. hardware/maple-native.rst - -.. _index-reference: - -**Reference:** - -.. toctree:: - :maxdepth: 1 - - Technical Specifications <specs> - Complete Language Index <language-index> - - diff --git a/docs/source/lang/cpp/arithmetic.rst b/docs/source/lang/cpp/arithmetic.rst index 7e8c3fc..26e2811 100644 --- a/docs/source/lang/cpp/arithmetic.rst +++ b/docs/source/lang/cpp/arithmetic.rst @@ -117,11 +117,8 @@ See Also -------- - The individual sizes (in bits) of various available types are - defined in `libmaple_types.h - <http://github.com/leaflabs/libmaple/blob/master/libmaple/libmaple_types.h>`_\ - . + defined in :ref:`libmaple_types.h <libmaple-libmaple_types>`. - :ref:`sizeof <lang-sizeof>`\ () - .. include:: cc-attribution.txt diff --git a/docs/source/language-index.rst b/docs/source/language-index.rst index 531e72c..a064b3e 100644 --- a/docs/source/language-index.rst +++ b/docs/source/language-index.rst @@ -10,6 +10,9 @@ API references for documented libmaple functionality. The "C++ for Maple" pages are intended as a minimal reference/refresher for programmers familiar with the Arduino language. +**Looking for something else?** The low-level :ref:`libmaple library +interfaces <libmaple>` are documented separately. + .. _index-language-index-cpp: .. _index-language-index-api: diff --git a/docs/source/language.rst b/docs/source/language.rst index ea841f5..111a1f1 100644 --- a/docs/source/language.rst +++ b/docs/source/language.rst @@ -28,14 +28,14 @@ Maple Language Reference The following table summarizes the available core language features. A more exhaustive index is available at the :ref:`language-index`. +.. FIXME mention Maple Native supports malloc(), free(), operator +.. new(), and operator delete(), when that is a true thing to say. + **Looking for something else?** - See the :ref:`libraries` for extra built-in libraries for dealing with different kinds of hardware. -.. FIXME mention Maple Native supports malloc(), free(), operator -.. new(), and operator delete(), when that is a true thing to say. - - If you're looking for something from the C standard library (like ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler <arm-gcc>` used to compile your programs is configured to link @@ -43,6 +43,9 @@ A more exhaustive index is available at the :ref:`language-index`. use of any of its header files. However, dynamic memory allocation (``malloc()``, etc.) is not available. +- If you're looking for low-level details, see the :ref:`libmaple + <libmaple>` reference page. + +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ | Structure | Variables | Functions | | | | | @@ -273,7 +276,7 @@ Unimplemented Arduino Features ------------------------------ The following Wiring/Arduino features are currently unimplemented on -the Maple. However, they will be present in future versions: +the Maple. - `tone() <http://www.arduino.cc/en/Reference/Tone>`_ - `noTone() <http://www.arduino.cc/en/Reference/NoTone>`_ @@ -299,16 +302,18 @@ programming ideas and C++. Note for C/C++ Hackers ---------------------- -This is a note for programmers comfortable with C or C++ (although, -you C programmers should remember that `C++ is not a superset of C -<http://en.wikipedia.org/wiki/Compatibility_of_C_and_C%2B%2B>`_) who -want a better understanding of the differences between C++ and the -Wiring language. The good news is that the differences are relatively -few; Wiring is just a thin wrapper around C++. +This is a note for programmers comfortable with C or C++ who want a +better understanding of the differences between C++ and the Wiring +language. -Some potentially better news is that the Maple can be programmed using -a :ref:`standard Unix toolchain <unix-toolchain>`, so if you'd rather -stick with :command:`gcc`, :command:`make`, and friends, you can. +The good news is that the differences are relatively few; Wiring is +just a thin wrapper around C++. Some potentially better news is that +the Maple can be programmed using a :ref:`standard Unix toolchain +<unix-toolchain>`, so if you'd rather stick with :command:`gcc`, +:command:`make`, and friends, you can. If you're using the Unix +toolchain and want to skip past the Wiring conveniences and get +straight to registers, you are encouraged to move on to the +:ref:`libmaple` documentation. A *sketch* is the IDE's notion of a project; it consists of one or more files written in the Wiring language, which is mostly the same as @@ -334,9 +339,9 @@ work. As of |today|, Maple only has 20 KB RAM, anyway, so it's doubtful that static allocation is not what you want. The Wiring language also does not require you to define your own -``main`` method (in fact, it forbids you from doing so). Instead, you -are required to define two functions, ``setup`` and ``loop``, with -type signatures :: +``main`` method (in fact, we currently forbid you from doing so). +Instead, you are required to define two functions, ``setup`` and +``loop``, with type signatures :: void setup(void); void loop(void); @@ -351,26 +356,33 @@ parses the result to produce a list of all functions defined in the global scope. (We borrow this stage from the Arduino IDE, which in turn borrows it from Wiring. It uses regular expressions to parse C++, which is, of course, `Bad and Wrong -<http://www.retrologic.com/jargon/B/Bad-and-Wrong.html>`_. An -upcoming rewrite of the IDE performs this preprocessing step -correctly, using a real parser. Until then, you have our apologies.) -The order in which the individual sketch files are concatenated is not -defined; it is unwise to write code that depends on a particular -ordering. +<http://www.retrologic.com/jargon/B/Bad-and-Wrong.html>`_. In the +future, we'll do this correctly, using a better parser. Until then, +you have our apologies.) The order in which the individual sketch +files are concatenated is not defined; it is unwise to write code that +depends on a particular ordering. The concatenated sketch files are then appended onto a file which includes `WProgram.h -<http://github.com/leaflabs/libmaple/blob/master/wirish/WProgram.h>`_ +<https://github.com/leaflabs/libmaple/blob/master/wirish/WProgram.h>`_ (which includes the wirish and libmaple libraries, and declares ``setup()`` and ``loop()``), and then provides declarations for all the function definitions found in the previous step. At this point, -we have a file that is a valid C++ translation unit, but lacks a -``main()`` method. The final step of compilation provides this -method, which behaves roughly like:: +we have a file that is a valid C++ translation unit, but lacks +``main()``. The final step of compilation provides ``main()``, which +behaves roughly like:: int main(void) { + // Call libmaple's built-in initialization routines + init(); + + // Perform the user's initialization setup(); - while (true) loop(); + + // Call user loop() forever. + while (true) { + loop(); + } } (The truth is a little bit more complicated, but not by much). @@ -441,20 +453,19 @@ Which could plausibly be turned into the final source file :: } int main() { + init(); setup(); while (true) loop(); } -(Recall that it's legal C++ for a function to be declared multiple -times, as long as it's defined exactly once). - - Recommended Reading ------------------- * `newlib Documentation <http://sourceware.org/newlib/>`_ -* STMicro documentation for STM32F103RB microcontroller: - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) +* :ref:`libmaple Documentation <libmaple>` + +* ST documentation: + * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) * `Programming Manual <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ (assembly language and register reference) diff --git a/docs/source/libmaple.rst b/docs/source/libmaple.rst index 9faca03..375e821 100644 --- a/docs/source/libmaple.rst +++ b/docs/source/libmaple.rst @@ -5,37 +5,35 @@ ``libmaple`` ============ -.. image:: /_static/img/libmaple-screenshot-small.png - :align: center - :alt: libmaple screenshot - -`LeafLabs libmaple <libmaple-libmaple>`_ is the low level library we -have developed for for the ARM Cortex-M3 chips manufactured by -STMicroelectronics used in the Maple boards (the `STM32F103x`_ -series). We found the generic peripheral libraries too painful to -build on top of, and reimplemented the functionality we needed in a -simpler (and less general) form. - -.. _libmaple-libmaple: http://github.com/leaflabs/libmaple -.. _STM32F103x: http://www.st.com/stonline/stappl/productcatalog/app?path=/pages/stcom/PcStComPartNumberSearch.searchPartNumber&search=stm32f103 - -This library is transparently included in the `Maple IDE -<http://leaflabs.com/docs/maple-ide/>`_, but we develop it separately -using good old Unix command line tools and release it for advanced -users who might chafe at the "sketch" programming model of the -IDE. Included are some examples, a Makefile, and the compatibility -wrappers and code to imitate the Arduino programming library. - -**Check out the latest source**:: - - git clone git://github.com/leaflabs/libmaple.git - -.. TODO after finishing refactor: create, style, and host a pure -.. Doxygen libmaple reference docs. This implies determining a stable -.. API. - -.. **Table of contents:** - -.. .. toctree:: -.. :maxdepth: 2 +LeafLabs' libmaple (`source code on Github +<https://github.com/leaflabs/libmaple>`_) is the library we have +developed for the `STM32 <http://www.st.com/stonline>`_ line of ARM Cortex M3 +microcontrollers. Its high-level interfaces are :ref:`largely +compatible <arduino-compatibility>` with the AVR libraries written for +the `Arduino <http://arduino.cc>`_ and `Wiring +<http://wiring.org.co/>`_ development boards. + +libmaple is split into two pieces: a lower level layer written in pure +C, which we call *libmaple proper* (in the `libmaple/ +<https://github.com/leaflabs/libmaple/tree/master/libmaple>`_ +directory of the source repository), and the Wiring-style C++ API +written on top of it, called *Wirish* (in `wirish/ +<https://github.com/leaflabs/libmaple/tree/master/wirish>`_). + +libmaple is bundled with the :ref:`Maple IDE <ide>`. However, we +develop it separately, and :ref:`release it standalone +<unix-toolchain>` for advanced users who might chafe at the "sketch" +programming model of the IDE. + +As always, :ref:`patches are welcome <libmaple-contributing>`. + +**Contents:** + +.. toctree:: + :maxdepth: 1 + + libmaple/overview + libmaple/apis + libmaple/contributing + libmaple/coding-standard diff --git a/docs/source/libmaple/api/adc.rst b/docs/source/libmaple/api/adc.rst new file mode 100644 index 0000000..8817055 --- /dev/null +++ b/docs/source/libmaple/api/adc.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..fd57944 --- /dev/null +++ b/docs/source/libmaple/api/bitband.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..9a697c7 --- /dev/null +++ b/docs/source/libmaple/api/bkp.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..038753b --- /dev/null +++ b/docs/source/libmaple/api/dac.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..a0d013a --- /dev/null +++ b/docs/source/libmaple/api/delay.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..1512d0c --- /dev/null +++ b/docs/source/libmaple/api/dma.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..2909aa7 --- /dev/null +++ b/docs/source/libmaple/api/exti.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..6f2f9d3 --- /dev/null +++ b/docs/source/libmaple/api/flash.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..cecfc99 --- /dev/null +++ b/docs/source/libmaple/api/fsmc.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..2cfec23 --- /dev/null +++ b/docs/source/libmaple/api/gpio.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..14dd304 --- /dev/null +++ b/docs/source/libmaple/api/i2c.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..3911ece --- /dev/null +++ b/docs/source/libmaple/api/iwdg.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..d4f28f0 --- /dev/null +++ b/docs/source/libmaple/api/libmaple.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..bbea2c1 --- /dev/null +++ b/docs/source/libmaple/api/libmaple_types.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..b94dc31 --- /dev/null +++ b/docs/source/libmaple/api/nvic.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..82e4864 --- /dev/null +++ b/docs/source/libmaple/api/pwr.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..81dc604 --- /dev/null +++ b/docs/source/libmaple/api/rcc.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..a014fa4 --- /dev/null +++ b/docs/source/libmaple/api/ring_buffer.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..78cc7eb --- /dev/null +++ b/docs/source/libmaple/api/scb.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..b0c7e86 --- /dev/null +++ b/docs/source/libmaple/api/spi.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..2784540 --- /dev/null +++ b/docs/source/libmaple/api/stm32.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..5ec906c --- /dev/null +++ b/docs/source/libmaple/api/systick.rst @@ -0,0 +1,12 @@ +.. highlight:: c +.. _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 new file mode 100644 index 0000000..3acbf4f --- /dev/null +++ b/docs/source/libmaple/api/timer.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..26e6b9c --- /dev/null +++ b/docs/source/libmaple/api/usart.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..50ffe76 --- /dev/null +++ b/docs/source/libmaple/api/util.rst @@ -0,0 +1,12 @@ +.. 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 new file mode 100644 index 0000000..f493406 --- /dev/null +++ b/docs/source/libmaple/apis.rst @@ -0,0 +1,14 @@ +.. _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 new file mode 100644 index 0000000..23d20f8 --- /dev/null +++ b/docs/source/libmaple/coding-standard.rst @@ -0,0 +1,412 @@ +.. _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 new file mode 100644 index 0000000..724605b --- /dev/null +++ b/docs/source/libmaple/contributing.rst @@ -0,0 +1,113 @@ +.. _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 new file mode 100644 index 0000000..9bce564 --- /dev/null +++ b/docs/source/libmaple/overview.rst @@ -0,0 +1,342 @@ +.. highlight:: c + +.. _libmaple-overview: + +Overview +======== + +This page is a general overview of the low-level aspects of libmaple +proper. It provides a general perspective of the library's goals and +design. Examples are given from the libmaple 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/stonline/products/literature/rm/13902.pdf>`_. +RM0008 is the single most important tool in your toolbox. It is the +authoritative documentation for the capabilities and low-level +programming interfaces of ST's line of ARM Cortex M3 microcontrollers. + +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 `USARTs <http://leaflabs.com/docs/usart.html>`_ have +data registers; (some of the) the `timers +<http://leaflabs.com/docs/timers.html>`_ have capture/compare +registers, the `GPIOs <http://leaflabs.com/docs/gpio.html>`_ 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_union regs; + rcc_clk_id clk_id; + timer_type type; + voidFuncPtr 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 ((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 ((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 ((xxx_reg_map*)0xDEADBEEF) + #define XXX2_BASE ((xxx_reg_map*)0xF00DF00D) + ... + #define XXXn_BASE ((xxx_reg_map*)0x13AF1AB5) + +Here's a concrete example from ``adc.h``:: + + /** ADC1 register map base pointer. */ + #define ADC1_BASE ((adc_reg_map*)0x40012400) + /** ADC2 register map base pointer. */ + #define ADC2_BASE ((adc_reg_map*)0x40012800) + /** ADC3 register map base pointer. */ + #define ADC3_BASE ((adc_reg_map*)0x40013C00) + +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->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.). diff --git a/docs/source/maple-ide-install.rst b/docs/source/maple-ide-install.rst index 5c79d41..beba54d 100644 --- a/docs/source/maple-ide-install.rst +++ b/docs/source/maple-ide-install.rst @@ -41,9 +41,9 @@ correct version for your operating system: The package bundles together a compiler, an upload utility, a software library, and a simple GUI text editor. All this software is `free and -open <http://fsf.org/>`_; we are grateful to the `Arduino +open <http://www.fsf.org/>`_; we are grateful to the `Arduino <http://arduino.cc/>`_, `CodeSourcery -<http://www.codesourcery.com/>`_, `GNU <http://gnu.org/>`_, and +<http://www.codesourcery.com/>`_, `GNU <http://www.gnu.org/>`_, and `OpenMoko <http://openmoko.com/>`_ developers, as well as many others, who allow us to reuse their software. diff --git a/docs/source/pwm.rst b/docs/source/pwm.rst index 1a8f4df..1144d55 100644 --- a/docs/source/pwm.rst +++ b/docs/source/pwm.rst @@ -26,7 +26,7 @@ documentation <timers>` for more information. Note that unlike the Arduino, the Maple does not have PWM functionality on pin D10; all other pins are :ref:`compatible -<compatibility>`. +<arduino-compatibility>`. The following table shows which timer can generate which PWM outputs. See the :ref:`pin mapping table <pin-mapping-mega-table>` to diff --git a/docs/source/specs.rst b/docs/source/specs.rst deleted file mode 100644 index 4972a83..0000000 --- a/docs/source/specs.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _specs: - -.. _specs-Technical-Specifications: - -================================ -Maple's Technical Specifications -================================ - - * STM32 F103RB: a **32-bit** ARM Cortex M3 microprocessor - * Clock Speed: **72 MHz** - * Operating Voltage: 3.3V - * Input Voltage (recommended): 3.0V-12V - * 39 Digital I/O Pins (:ref:`GPIO <gpio>`) - * 16 Analog Input Pins - * 12-bit **ADC** resolution (:ref:`ADC <adc>`) - * 15 **PWM** pins at 16-bit resolution (:ref:`PWM <pwm>`) - * Dedicated **USB** port for programming and communications (:ref:`USB<usb>`) - * External **JTAG** interface (:ref:`USB <jtag>`) - * **128 Flash** and **20KB SRAM** - * 64 Channel nested vector interrupt handler (including external interrupt on GPIO’s) - * Integrated **SPI** (:ref:`SPI<spi>`) - * Integrated **I2C** (:ref:`I2C<i2c>`) - * 7 Channels of Direct Memory Access (DMA) - * 3 **USART** divices (:ref:`USART <usart>`) - * Four 4-channel Timers (:ref:`Timers <timers>`) - * Supplies up to 800mA @ 3.3v - * Support for low power and sleep modes (<500uA) - * Dimensions are 2.05″x2.1″ - diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 9146ebe..2151171 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -40,17 +40,17 @@ My 5v peripheral doesn't work! (I2C, SPI, USART, etc) ----------------------------------------------------- Yup, the Maple is a 3.3v board. You may need to use a level -converter. See the :ref:`compatibility <compatibility>`, :ref:`GPIO -<gpio>`, or other :ref:`hardware specific documentation -<index-hardware>` for more information. +converter. See the :ref:`Arduino Compatibility +<arduino-compatibility>`, :ref:`GPIO <gpio>`, or other :ref:`hardware +specific documentation <index-hardware>` for more information. The reset and D38/serial buttons don't seem to work reliably! ------------------------------------------------------------- -A few rev3 boards shipped in May-June 2010 may have had unreliable -buttons; see the :ref:`errata page <errata>` for details. `We're -happy to replace these for you <http://leaflabs.com/contact>`_\ ! - +A few Maple Rev3 boards shipped in May-June 2010 may have had +unreliable buttons; see the :ref:`errata page <maple-errata>` for +details. `We're happy to replace these for you +<http://leaflabs.com/contact>`_\ ! .. _troubleshooting-ide-install: diff --git a/docs/source/unix-toolchain.rst b/docs/source/unix-toolchain.rst index a173146..8b81e75 100644 --- a/docs/source/unix-toolchain.rst +++ b/docs/source/unix-toolchain.rst @@ -9,7 +9,9 @@ This is a tutorial for using the Maple with a standard Unix toolchain (``make``, ``gcc``, etc.). It's not necessary to do this in order to program the Maple; you can always :ref:`install the Maple IDE -<maple-ide-install>` instead. +<maple-ide-install>` instead. This document is intended for users who +are comfortable using C or C++ and would like to use :ref:`libmaple` +directly. You'll need a Maple board, a Mini-B USB cable, a functional computer, and root (or Administrator) access to that computer. This guide @@ -100,7 +102,7 @@ in `Python <http://python.org>`_, and requires the `PySerial $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up This step is fairly straightforward: do a git clone of the `libmaple -repository <http://github.com/leaflabs/libmaple>`_ to some directory, +repository <https://github.com/leaflabs/libmaple>`_ to some directory, then download and extract the ARM compiler toolchain. The :file:`arm/bin/` directory will need to be added to ``PATH``; you @@ -169,9 +171,9 @@ You will need the following tools\ [#fpackman]_ to get started: <http://wiki.openmoko.org/wiki/Dfu-util#Mac>`_. If you're in a hurry, you can steal a dfu-util binary from a program - called `Openmoko Flasher - <http://www.handheld-linux.com/wiki.php?page=Openmoko%20Flasher>`_. To - do this, first `download Openmoko Flasher + called `OpenMoko Flasher + <http://www.handheld-linux.com/wiki.php?page=OpenMoko%20Flasher>`_. To + do this, first `download OpenMoko Flasher <http://projects.goldelico.com/p/omflasher/downloads/>`_, then copy the OpenMoko application into your :file:`/Applications` folder (or wherever you like). Let's pretend you saved the .app to the directory @@ -292,11 +294,11 @@ If it all works out, you should end up seeing something like this:: 21824 200 552 22576 5830 build/maple.out Flash build -Woo! It worked. The ``dec`` field at the end gives the total program -size in bytes. The long listing of object files above the ``Final -Size`` helps to identify bloated code. As you write larger projects, -you may find that they use too much space. If that happens, the -file-by-file listing will help you track down the culprits. +The ``dec`` field at the end gives the total program size in +bytes. The long listing of object files above the ``Final Size`` helps +to identify bloated code. As you write larger projects, you may find +that they use too much space. If that happens, the file-by-file +listing will help you track down the culprits. .. _toolchain-upload: diff --git a/docs/source/usb.rst b/docs/source/usb.rst index 0468618..f040034 100644 --- a/docs/source/usb.rst +++ b/docs/source/usb.rst @@ -34,7 +34,7 @@ second problem is the use of :ref:`perpetual bootloader mode Recommended Reading ------------------- -* `USB in a Nutshell <http://www.beyondlogic.org/usbnutshell/usb1.htm>`_, an overview from Beyond Logic +* `USB in a Nutshell <http://www.beyondlogic.org/usbnutshell/usb1.shtml>`_, an overview from Beyond Logic * `USB made simple <http://www.usbmadesimple.co.uk/>`_, an illustrated series of articles on USB * The `USB 2.0 Specification <http://www.usb.org/developers/docs/>`_ (`direct link <http://www.usb.org/developers/docs/usb_20_021411.zip>`_) * `Embedded USB - a brief tutorial <http://www.computer-solutions.co.uk/info/Embedded_tutorials/usb_tutorial.htm>`_ |
