diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/jtag.rst | 12 | ||||
| -rw-r--r-- | docs/source/lang/api/assert.rst | 30 | ||||
| -rw-r--r-- | docs/source/language.rst | 53 | ||||
| -rw-r--r-- | docs/source/timers.rst | 9 | ||||
| -rw-r--r-- | docs/source/troubleshooting.rst | 2 |
5 files changed, 51 insertions, 55 deletions
diff --git a/docs/source/jtag.rst b/docs/source/jtag.rst index 4151a53..0558a29 100644 --- a/docs/source/jtag.rst +++ b/docs/source/jtag.rst @@ -2,9 +2,8 @@ .. _jtag: -====== - JTAG -====== +JTAG +==== .. FIXME [0.1.0] Updated adapter schematic, better information @@ -17,10 +16,9 @@ and hardware peripherals (we use it when working on :ref:`libmaple <libmaple>`) or to flash a new bootloader. Note that the STM32 on the Maple has a built-in low level serial -debugger which could also be used to flash bootloaders, and that the -:ref:`ASSERT <language-assert>` framework allows basic debugging over -a USART serial channel. We expect only fairly advanced users to use -this feature. +debugger which could also be used to flash bootloaders, and +:ref:`lang-assert` allows basic debugging over a USART serial channel. +We expect only fairly advanced users to use this feature. .. contents:: Contents :local: diff --git a/docs/source/lang/api/assert.rst b/docs/source/lang/api/assert.rst new file mode 100644 index 0000000..76330b6 --- /dev/null +++ b/docs/source/lang/api/assert.rst @@ -0,0 +1,30 @@ +.. highlight:: cpp + +.. _lang-assert: + +``ASSERT(...)`` +=============== + +ASSERT() 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 (it's +noticeably different from blinking). The debug information is printed +at 9600 baud and consists of the filename and line number where the +ASSERT() 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. diff --git a/docs/source/language.rst b/docs/source/language.rst index 3ecbe43..be085f2 100644 --- a/docs/source/language.rst +++ b/docs/source/language.rst @@ -12,8 +12,7 @@ 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 +C or C++ programmers may wish to skip to the :ref:`arduino_c_for_c_hackers`. .. contents:: Contents @@ -21,8 +20,7 @@ language and C++ may wish to skip to the .. admonition:: **Looking for Something Else?** - - See the :ref:`libraries` for extra built-in libraries for dealing - with different kinds of hardware. + - See the :ref:`libraries` for extra built-in libraries. - If you're looking for something from the C standard library (like ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler @@ -31,17 +29,17 @@ language and C++ may wish to skip to the use of any of its header files. However, dynamic memory allocation (``malloc()``, etc.) is not available. - - If you're looking for pointers to low-level details, see this page's - :ref:`Recommended Reading <language-recommended-reading>`. + - If you're looking for pointers to low-level details, see + :ref:`libmaple` and this page's :ref:`Recommended Reading + <language-recommended-reading>`. .. _language-lang-docs: Maple Language Reference ------------------------ -The following table summarizes the most important core language -features. An exhaustive index is available at the -:ref:`language-index`. +This table is a summary of the most important language features. See +the :ref:`language-index` for a complete listing. +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ | Structure | Variables | Functions | @@ -68,7 +66,7 @@ features. An exhaustive index is available at the | | | | |* :ref:`continue <lang-continue>` |**Data Types** |* :ref:`analogRead() <lang-analogread>` | | | | | -|* :ref:`return <lang-return>` | The size of each datatype, in bytes, is |* :ref:`pwmWrite() <lang-pwmwrite>` | +|* :ref:`return <lang-return>` | The size of each data type, in bytes, is |* :ref:`pwmWrite() <lang-pwmwrite>` | | | given in parentheses where appropriate. | (:ref:`analogWrite() <lang-analogwrite>` is | |* :ref:`goto <lang-goto>` | | also available, though its use is discouraged) | | | *Note*: The ``word`` type is (deliberately) | | @@ -144,7 +142,7 @@ features. An exhaustive index is available at the | | | | |* :ref:`& reference operator |* :ref:`sizeof() <lang-sizeof>` |* :ref:`bitClear() <lang-bitclear>` | | <lang-pointer>` | | | -| | |* :ref:`bit() <lang-bit>` | +| |* :ref:`ASSERT() <lang-assert>` |* :ref:`bit() <lang-bit>` | | | | | |**Bitwise Operators** | | | | | |**External Interrupts** | @@ -205,35 +203,6 @@ features. An exhaustive index is available at the | | | | +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ -.. _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 @@ -301,7 +270,7 @@ Note for C/C++ Hackers 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. +language. The good news is that the differences are relatively few; Wiring is just a thin wrapper around C++. Some potentially better news is that @@ -378,7 +347,7 @@ behaves roughly like:: // Call user loop() forever. while (true) { - loop(); + loop(); } } diff --git a/docs/source/timers.rst b/docs/source/timers.rst index e23579d..b6c0886 100644 --- a/docs/source/timers.rst +++ b/docs/source/timers.rst @@ -66,11 +66,10 @@ Working with timers and interrupts can be tricky; they are a somewhat "advanced" topic. The following subsections explain some common problems associated with using timers and timer interrupts. -In general: start simple, test with :ref:`ASSERT() <language-assert>`, -and don't try to do too much in your interrupt handlers! Make sure -that what you're trying to do in a handler isn't going to block other -interrupts from firing, if those other interrupts are important for -your program. +In general: start simple, test with :ref:`lang-assert`, and don't try +to do too much in your interrupt handlers! Make sure that what you're +trying to do in a handler isn't going to block other interrupts from +firing, if those other interrupts are important for your program. .. _timers-pwm-conflicts: diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 3174f14..b679b9c 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -18,7 +18,7 @@ The LED is throbbing and my program is stopped! ----------------------------------------------- The LED throbs when there has been a failed software :ref:`assertion -<language-assert>` or some other error. +<lang-assert>` or some other error. There are a few issues with the bootloader which mean you might not be able to upload your program when this happens. You can still |