aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/language.rst
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2011-05-09 16:43:27 -0400
committerMarti Bolivar <mbolivar@leaflabs.com>2011-05-09 16:49:08 -0400
commit19ea6ba4ea3f1ecb9830cf4d3e1366513f4f96e3 (patch)
treea43f7e0fb3650ca54f245b750a078a0e8c356504 /docs/source/language.rst
parent868fb1c273e562a1140abfa948022c9d4f55bccf (diff)
parent1e2e177f6dae62e040c674b617744c73be187062 (diff)
downloadlibrambutan-19ea6ba4ea3f1ecb9830cf4d3e1366513f4f96e3.tar.gz
librambutan-19ea6ba4ea3f1ecb9830cf4d3e1366513f4f96e3.zip
Merge branch 'refactor'
This merges the libmaple refactor work into master. The contents of libmaple proper (/libmaple/) are almost completely incompatible with previous APIs in master. See /docs/source/libmaple/overview.rst for more information on the new design. Wirish incompatibilities are limited to the HardwareTimer class; however, there are several new deprecations, most likely to be removed in 0.1.0.
Diffstat (limited to 'docs/source/language.rst')
-rw-r--r--docs/source/language.rst190
1 files changed, 113 insertions, 77 deletions
diff --git a/docs/source/language.rst b/docs/source/language.rst
index 2ebe03c..3ecbe43 100644
--- a/docs/source/language.rst
+++ b/docs/source/language.rst
@@ -10,6 +10,8 @@ The Maple can be programmed in the `Wiring
<http://www.wiring.org.co/reference/>`_ language, which is the same
language used to program the `Arduino <http://arduino.cc/>`_ boards.
+.. TODO [0.2.0?] Wiring tutorial
+
C or C++ programmers curious about the differences between the Wiring
language and C++ may wish to skip to the
:ref:`arduino_c_for_c_hackers`.
@@ -17,43 +19,29 @@ language and C++ may wish to skip to the
.. contents:: Contents
:local:
-Unique Maple Additions
-----------------------
-
-.. _language-assert:
-
-``ASSERT(...)``
- The ``ASSERT()`` function can be very useful for basic program
- debugging. The function accepts a boolean; for example::
-
- ASSERT(state == WAIT);
+.. admonition:: **Looking for Something Else?**
- zero is false and any other number is true. If the boolean is true
- the assertion passes and the program continues as usual. If it is
- false, the assertion fails: the program is halted, debug
- information is printed to USART2, and the status LED begins to
- throb in intensity (it's noticeably different from blinking). The
- debug information is printed at 9600 baud and consists of the
- filename and line number where the particular assertion failed.
+ - See the :ref:`libraries` for extra built-in libraries for dealing
+ with different kinds of hardware.
- Including assertions in a program increases the program size. When
- using libmaple **from the command line only**, they can be
- disabled by making the definition ::
+ - 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
+ against `newlib <http://sourceware.org/newlib/>`_, and allows the
+ use of any of its header files. However, dynamic memory allocation
+ (``malloc()``, etc.) is not available.
- #define DEBUG_LEVEL DEBUG_NONE
-
- before including either wirish.h or libmaple.h. In this case, all
- assertions will pass without any lost clock cycles. Note that
- this will **not work in the IDE**; even with this definition,
- assertions will still be enabled.
+ - If you're looking for pointers to low-level details, see this page's
+ :ref:`Recommended Reading <language-recommended-reading>`.
.. _language-lang-docs:
Maple Language Reference
------------------------
-The following table summarizes the available core language features.
-A more exhaustive index is available at the :ref:`language-index`.
+The following table summarizes the most important core language
+features. An exhaustive index is available at the
+:ref:`language-index`.
+--------------------------------------------+----------------------------------------------+---------------------------------------------------+
| Structure | Variables | Functions |
@@ -70,13 +58,13 @@ A more exhaustive index is available at the :ref:`language-index`.
| |* :ref:`true <lang-constants-true>` | |* :ref:`togglePin() <lang-togglepin>` |
|* :ref:`for <lang-for>` | :ref:`false <lang-constants-false>` | |
| | |* :ref:`toggleLED() <lang-toggleled>` |
-|* :ref:`switch/case <lang-switchcase>` |* :ref:`BOARD_LED_PIN <lang-constants-led>` | | |
-| | :ref:`BOARD_BUTTON_PIN <lang-constants-but>`|* :ref:`isButtonPressed() <lang-isbuttonpressed>` |
-|* :ref:`while <lang-while>` | | |
-| |* :ref:`Constants |* :ref:`waitForButtonPress() |
-|* :ref:`do...while <lang-dowhile>` | <lang-constants>` (:ref:`integers | <lang-waitforbuttonpress>` |
-| | <lang-constants-integers>`, :ref:`floating | |
-|* :ref:`break <lang-break>` | point <lang-constants-fp>`) |**Analog I/O** |
+|* :ref:`switch/case <lang-switchcase>` |* :ref:`Constants | |
+| | <lang-constants>` (:ref:`integers |* :ref:`isButtonPressed() <lang-isbuttonpressed>` |
+|* :ref:`while <lang-while>` | <lang-constants-integers>`, :ref:`floating | |
+| | point <lang-constants-fp>`) |* :ref:`waitForButtonPress() |
+|* :ref:`do...while <lang-dowhile>` | | <lang-waitforbuttonpress>` |
+| |* :ref:`Board-specific values | |
+|* :ref:`break <lang-break>` | <lang-board-values>` |**Analog I/O** |
| | | |
|* :ref:`continue <lang-continue>` |**Data Types** |* :ref:`analogRead() <lang-analogread>` |
| | | |
@@ -91,7 +79,7 @@ A more exhaustive index is available at the :ref:`language-index`.
| |* :ref:`boolean <lang-boolean>` (1 byte) | |
|* :ref:`{} (curly braces) | |* noTone(): TODO |
| <lang-curly-braces>` |* :ref:`char <lang-char>` (1 byte) | |
-| | |* shiftOut(): TODO |
+| | |* :ref:`shiftOut() <lang-shiftout>` |
|* :ref:`// (single-line comment) |* :ref:`unsigned char | |
| <lang-comments-singleline>` | <lang-unsignedchar>` (1 byte) |* pulseIn(): TODO |
| | | |
@@ -106,7 +94,7 @@ A more exhaustive index is available at the :ref:`language-index`.
|**Arithmetic Operators** | <lang-int>` | |
| | |* :ref:`delayMicroseconds() |
|* :ref:`= <lang-assignment>` |* ``unsigned long`` (4 bytes), synonym for | <lang-delaymicroseconds>` |
-| (assignment operator) | :ref:`unsigned int <lang-unsignedint>` | |
+| (assignment) | :ref:`unsigned int <lang-unsignedint>` | |
| | | |
|* :ref:`+ <lang-arithmetic>` (addition) |* :ref:`long long <lang-longlong>` (8 bytes) |**Math** |
| | | |
@@ -183,13 +171,13 @@ A more exhaustive index is available at the :ref:`language-index`.
| | | |
|* :ref:`++ <lang-increment>` | |* :ref:`Serial <lang-serial>` |
| (increment) | | |
-| | |**Looking for something else?** |
+| | | |
|* :ref:`- - <lang-increment>` | | |
-| (decrement) | | See the :ref:`libraries` page for interfacing with|
-| | | particular types of hardware. Maple links |
-|* :ref:`+= <lang-compoundarithmetic>` | | against `newlib <http://sourceware.org/newlib/>`_ |
-| (compound add) | | and allows the use of any of its functions; see |
-| | | its documentation for more details. |
+| (decrement) | | |
+| | | |
+|* :ref:`+= <lang-compoundarithmetic>` | | |
+| (compound add) | | |
+| | | |
|* :ref:`-= | | |
| <lang-compoundarithmetic>` (compound | | |
| subtract) | | |
@@ -217,6 +205,35 @@ A more exhaustive index is available at the :ref:`language-index`.
| | | |
+--------------------------------------------+----------------------------------------------+---------------------------------------------------+
+.. _language-assert:
+
+``ASSERT(...)``
+---------------
+
+The ``ASSERT()`` function can be very useful for basic program
+debugging. It accepts a boolean; for example::
+
+ ASSERT(state == WAIT);
+
+Zero is false and any other number is true. If the boolean is true, the
+assertion passes and the program continues as usual. If it is false,
+the assertion fails: the program is halted, debug information is
+printed to USART2, and the status LED begins to throb in intensity
+(it's noticeably different from blinking). The debug information is
+printed at 9600 baud and consists of the filename and line number
+where the particular assertion failed.
+
+Including assertions in a program increases the program size. When
+using libmaple **from the command line only**, they can be disabled by
+making the definition ::
+
+ #define DEBUG_LEVEL DEBUG_NONE
+
+before including either wirish.h or libmaple.h. In this case, all
+assertions will pass without any lost clock cycles. Note that this
+will **not work in the IDE**; even with this definition, assertions
+will still be enabled.
+
.. _language-missing-features:
Missing Arduino Features
@@ -256,13 +273,12 @@ 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>`_
- `pulseIn() <http://www.arduino.cc/en/Reference/PulseIn>`_
-- `shiftOut() <http://www.arduino.cc/en/Reference/ShiftOut>`_
- `String <http://arduino.cc/en/Reference/StringObject>`_
-- `tone() <http://www.arduino.cc/en/Reference/Tone>`_
.. _our reference page: http://leaflabs.com/docs/external-interrupts/
@@ -283,16 +299,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
@@ -318,9 +336,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);
@@ -335,26 +353,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).
@@ -425,20 +450,31 @@ 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).
-
+.. _language-recommended-reading:
Recommended Reading
-------------------
+* :ref:`libmaple Documentation <libmaple>`
+* Your board's :ref:`Board Hardware Documentation <index-boards>` page
+* ST Documentation:
+ * Reference Manual `RM0008
+ <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_
+ (PDF). This is the most important reference work on the STM32
+ line, and covers the low-level hardware capabilities and
+ interfaces in great detail.
+ * `Programming Manual
+ <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_
+ (PDF). This is an assembly language and register reference for
+ the STM32 line.
+* ARM Documentation:
+ * `Cortex-M3 Technical Reference Manual, Revision r1p1
+ <http://infocenter.arm.com/help/topic/com.arm.doc.ddi0337e/DDI0337E_cortex_m3_r1p1_trm.pdf>`_
+ (PDF). This ARM manual specifies much of the the Cortex M3
+ Architecture, including instruction timings.
* `newlib Documentation <http://sourceware.org/newlib/>`_
-* 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)