Merge branch 'master' into debug-serialusb.

Chose debug-serialusb version in cases of conflict.

Conflicts:
	libmaple/usb/usb_callbacks.c

12 files changed, 224 insertions, 70 deletions

diff --git a/wirish/HardwareTimer.cpp b/wirish/HardwareTimer.cpp
index 92c6adf..354663e 100644
--- a/wirish/HardwareTimer.cpp
+++ b/wirish/HardwareTimer.cpp
@@ -221,7 +221,6 @@ HardwareTimer* getTimer(timer_dev_num timerNum) {
         return &Timer8;
 #endif
     default:
-        ASSERT(0);
         return 0;
     }
 }
diff --git a/wirish/HardwareTimer.h b/wirish/HardwareTimer.h
index c72175f..4034b1f 100644
--- a/wirish/HardwareTimer.h
+++ b/wirish/HardwareTimer.h
@@ -89,7 +89,7 @@ class HardwareTimer {
      *
      * Note that there is some function call overhead associated with
      * using this method, so using it in concert with
-     * HardwareTimer::resume() is not a robust way to align multiple
+     * HardwareTimer::pause() is not a robust way to align multiple
      * timers to the same count value.
      *
      * @see HardwareTimer::pause()
@@ -103,7 +103,7 @@ class HardwareTimer {
     uint16 getPrescaleFactor();
 
     /**
-     * Set the timer prescale.
+     * Set the timer's prescale factor.
      *
      * The prescaler acts as a clock divider to slow down the rate at
      * which the counter increments.
@@ -155,7 +155,7 @@ class HardwareTimer {
      * Set the current timer count.
      *
      * Note that there is some function call overhead associated with
-     * callign this method, so using it is not a robust way to get
+     * calling this method, so using it is not a robust way to get
      * multiple timers to share a count value.
      *
      * @param val The new count value to set.  If this value exceeds
@@ -184,10 +184,6 @@ class HardwareTimer {
     /**
      * Set the given channel of this timer to the given mode.
      *
-     * Note: Timer1.setChannel1Mode(TIMER_PWM) may not work as
-     * expected; if you want PWM functionality on a channel make sure
-     * you don't set it to something else!
-     *
      * @param channel Timer channel, from 1 to 4
      * @param mode Mode to set
      */
@@ -228,24 +224,24 @@ class HardwareTimer {
      */
     uint16 getCompare(int channel);
 
-    /** Like getCompare(1) */
+    /** Equivalent to getCompare(1) */
     uint16 getCompare1();
 
-    /** Like getCompare(2) */
+    /** Equivalent to getCompare(2) */
     uint16 getCompare2();
 
-    /** Like getCompare(3) */
+    /** Equivalent to getCompare(3) */
     uint16 getCompare3();
 
-    /** Like getCompare(4) */
+    /** Equivalent to getCompare(4) */
     uint16 getCompare4();
 
     /**
      * Sets the compare value for the given channel.
      *
      * When the counter reaches this value the interrupt for this
-     * channel will fire if channel 1 mode is TIMER_OUTPUTCOMPARE and
-     * an interrupt is attached.
+     * channel will fire if the channel mode is TIMER_OUTPUTCOMPARE
+     * and an interrupt is attached.
      *
      * By default, this only changes the relative offsets between
      * events on a single timer ("phase"); they don't control the
@@ -259,32 +255,33 @@ class HardwareTimer {
      * few microseconds.
      *
      * @param channel the channel whose compare to set, from 1 to 4.
-     * @param val The compare value to set.  If greater than this
-     *            timer's overflow value, it will be truncated to the
-     *            overflow value.
+     * @param compare The compare value to set.  If greater than this
+     *                timer's overflow value, it will be truncated to
+     *                the overflow value.
      *
      * @see TimerMode
      * @see HardwareTimer::setChannelMode()
+     * @see HardwareTimer::attachInterrupt()
      */
     void setCompare(int channel, uint16 compare);
 
     /**
-     * Like setCompare(1, compare).
+     * Equivalent to setCompare(1, compare).
      */
     void setCompare1(uint16 compare);
 
     /**
-     * Like setCompare(2, compare).
+     * Equivalent to setCompare(2, compare).
      */
     void setCompare2(uint16 compare);
 
     /**
-     * Like setCompare(3, compare).
+     * Equivalent to setCompare(3, compare).
      */
     void setCompare3(uint16 compare);
 
     /**
-     * Like setCompare(4, compare).
+     * Equivalent to setCompare(4, compare).
      */
     void setCompare4(uint16 compare);
 
@@ -313,25 +310,25 @@ class HardwareTimer {
     void attachInterrupt(int channel, voidFuncPtr handler);
 
     /**
-     * Like attachCompareInterrupt(1, handler).
+     * Equivalent to attachCompareInterrupt(1, handler).
      * @see HardwareTimer::attachCompareInterrupt()
      */
     void attachCompare1Interrupt(voidFuncPtr handler);
 
     /**
-     * Like attachCompareInterrupt(2, handler).
+     * Equivalent to attachCompareInterrupt(2, handler).
      * @see HardwareTimer::attachCompareInterrupt()
      */
     void attachCompare2Interrupt(voidFuncPtr handler);
 
     /**
-     * Like attachCompareInterrupt(3, handler).
+     * Equivalent to attachCompareInterrupt(3, handler).
      * @see HardwareTimer::attachCompareInterrupt()
      */
     void attachCompare3Interrupt(voidFuncPtr handler);
 
     /**
-     * Like attachCompareInterrupt(4, handler).
+     * Equivalent to attachCompareInterrupt(4, handler).
      * @see HardwareTimer::attachCompareInterrupt()
      */
     void attachCompare4Interrupt(voidFuncPtr handler);
@@ -346,25 +343,25 @@ class HardwareTimer {
     void detachInterrupt(int channel);
 
     /**
-     * Like detachInterrupt(1).
+     * Equivalent to detachInterrupt(1).
      * @see HardwareTimer::detachInterrupt()
      */
     void detachCompare1Interrupt(void);
 
     /**
-     * Like detachInterrupt(2).
+     * Equivalent to detachInterrupt(2).
      * @see HardwareTimer::detachInterrupt()
      */
     void detachCompare2Interrupt(void);
 
     /**
-     * Like detachInterrupt(3).
+     * Equivalent to detachInterrupt(3).
      * @see HardwareTimer::detachInterrupt()
      */
     void detachCompare3Interrupt(void);
 
     /**
-     * Like detachInterrupt(4).
+     * Equivalent to detachInterrupt(4).
      * @see HardwareTimer::detachInterrupt()
      */
     void detachCompare4Interrupt(void);
@@ -394,6 +391,22 @@ extern HardwareTimer Timer5;
 extern HardwareTimer Timer8;
 #endif
 
+/**
+ * Get one of the pre-instantiated HardwareTimer instances, given a
+ * timer device number.
+ *
+ * Be careful not to pass an actual number to this function.  For
+ * example, getTimer(1) will not return Timer1.  Use a real
+ * timer_dev_num, e.g. TIMER1, TIMER2, etc.
+ *
+ * @param timerNum the timer device number, e.g. TIMER1.
+ *
+ * @return Pointer to the HardwareTimer instance corresponding to the
+ * given timer device number.  If timerNum is TIMER_INVALID, returns a
+ * null pointer.
+ *
+ * @see timer_dev_num
+ */
 HardwareTimer* getTimer(timer_dev_num timerNum);
 
 #endif
diff --git a/wirish/comm/HardwareSPI.h b/wirish/comm/HardwareSPI.h
index 03d1ea1..7241d0b 100644
--- a/wirish/comm/HardwareSPI.h
+++ b/wirish/comm/HardwareSPI.h
@@ -29,18 +29,23 @@
 #ifndef _HARDWARESPI_H_
 #define _HARDWARESPI_H_
 
+/**
+ * Defines the possible SPI communication speeds.
+ */
 typedef enum SPIFrequency {
-    SPI_18MHZ       = 0,
-    SPI_9MHZ        = 1,
-    SPI_4_5MHZ      = 2,
-    SPI_2_25MHZ     = 3,
-    SPI_1_125MHZ    = 4,
-    SPI_562_500KHZ  = 5,
-    SPI_281_250KHZ  = 6,
-    SPI_140_625KHZ  = 7,
-    MAX_SPI_FREQS   = 8,
+    SPI_18MHZ       = 0, /**< 18 MHz */
+    SPI_9MHZ        = 1, /**< 9 MHz */
+    SPI_4_5MHZ      = 2, /**< 4.5 MHz */
+    SPI_2_25MHZ     = 3, /**< 2.25 MHZ */
+    SPI_1_125MHZ    = 4, /**< 1.125 MHz */
+    SPI_562_500KHZ  = 5, /**< 562.500 KHz */
+    SPI_281_250KHZ  = 6, /**< 281.250 KHz */
+    SPI_140_625KHZ  = 7, /**< 140.625 KHz */
+    MAX_SPI_FREQS   = 8, /**< The number of SPI frequencies. */
 } SPIFrequency;
 
+/* Documented by hand in docs/source/lang/api/hardwarespi.rst; if you
+   make any changes, make sure to update this document. */
 class HardwareSPI {
  private:
     uint32 spi_num;
diff --git a/wirish/comm/HardwareSerial.h b/wirish/comm/HardwareSerial.h
index f67f09a..aad8aa7 100644
--- a/wirish/comm/HardwareSerial.h
+++ b/wirish/comm/HardwareSerial.h
@@ -35,6 +35,13 @@
 
 #include "Print.h"
 
+/* NB: this class documented "by hand" (i.e., not using Doxygen) in:
+
+     libmaple/docs/source/lang/serial.rst
+
+   If you alter the public HardwareSerial interface, you must update
+   the documentation accordingly. */
+
 class HardwareSerial : public Print {
  private:
     uint8 usart_num;
@@ -52,7 +59,7 @@ class HardwareSerial : public Print {
                    uint8 rx_pin,
                    timer_dev_num timer_num,
                    uint8 compare_num);
-    void begin(uint32);
+    void begin(uint32 baud);
     void end(void);
     uint32 available(void);
     uint8 read(void);
diff --git a/wirish/ext_interrupts.h b/wirish/ext_interrupts.h
index e68d973..304e267 100644
--- a/wirish/ext_interrupts.h
+++ b/wirish/ext_interrupts.h
@@ -35,7 +35,7 @@
 #define _EXT_INTERRUPTS_H_
 
 /**
- * The kind transition on an external pin which should trigger an
+ * The kind of transition on an external pin which should trigger an
  * interrupt.
  */
 typedef enum ExtIntTriggerMode_ {
@@ -57,13 +57,16 @@ extern "C"{
  *
  *  The interrupt will be triggered on a given transition on the pin,
  *  as specified by the mode parameter.  The handler runs in interrupt
- *  context.
+ *  context.  The new handler will replace whatever handler is
+ *  currently registered for the pin, if any.
  *
  *  @param pin Maple pin number
  *  @param handler Function to run upon external interrupt trigger.
+ *  The handler should take no arguments, and have void return type.
  *  @param mode Type of transition to trigger on, e.g. falling, rising, etc.
  *
  *  @sideeffect Registers a handler
+ *  @see detachInterrupt()
  */
 void attachInterrupt(uint8 pin, voidFuncPtr handler, ExtIntTriggerMode mode);
 
@@ -71,6 +74,7 @@ void attachInterrupt(uint8 pin, voidFuncPtr handler, ExtIntTriggerMode mode);
  * @brief Disable any registered external interrupt.
  * @param pin Maple pin number
  * @sideeffect unregisters external interrupt handler
+ * @see attachInterrupt()
  */
 void detachInterrupt(uint8 pin);
 
@@ -82,7 +86,7 @@ void detachInterrupt(uint8 pin);
  *
  * @see noInterrupts()
  */
-static inline __attribute__((always_inline)) void interrupts() {
+static ALWAYS_INLINE void interrupts() {
     nvic_globalirq_enable();
 }
 
@@ -96,7 +100,7 @@ static inline __attribute__((always_inline)) void interrupts() {
  *
  * @see interrupts()
  */
-static inline __attribute__((always_inline)) void noInterrupts() {
+static ALWAYS_INLINE void noInterrupts() {
     nvic_globalirq_disable();
 }
 
diff --git a/wirish/io.h b/wirish/io.h
index 66ba74d..2d22dcd 100644
--- a/wirish/io.h
+++ b/wirish/io.h
@@ -80,8 +80,8 @@ typedef enum WiringPinMode {
               when it is closer to 0v (ground) it is low. If no
               external circuit is pulling the pin voltage to high or
               low, it will tend to randomly oscillate and be very
-              sensitive to noise (eg a breath of air across the pin
-              will cause the state to flip). */
+              sensitive to noise (e.g., a breath of air across the pin
+              might cause the state to flip). */
 
     INPUT_ANALOG, /**< This is a special mode for when the pin will be
                      used for analog (not digital) reads.  Enables ADC
@@ -102,7 +102,7 @@ typedef enum WiringPinMode {
                        the state will be low unless an external device
                        is specifically pulling the pin up to 3.3v, in
                        which case the "gentle" pull down will not
-                       effect the state of the input. */
+                       affect the state of the input. */
 
     INPUT_FLOATING, /**< Synonym for INPUT. */
 
@@ -145,17 +145,21 @@ void digitalWrite(uint8 pin, uint8 value);
  * @return LOW or HIGH.
  * @see pinMode()
  */
-uint32 digitalRead(uint8);
+uint32 digitalRead(uint8 pin);
 
 /**
  * Read an analog value from pin.  This function blocks during ADC
- * conversion.  The pin must have its mode set to INPUT_ANALOG.
+ * conversion, and has 12 bits of resolution.  The pin must have its
+ * mode set to INPUT_ANALOG.  Ignoring function call overhead,
+ * conversion time is 55.5 cycles.
  *
- * @param pin Pin to read from. One of: 0-38 (pin numbers as labeled
- *            on silkscreen), or D0-D38 (symbols for same)
- * @return ADC-converted voltage, in the range 0--4095, inclusive.
+ * @param pin Pin to read from. One of: 0, 1, 2, 3, 10, 11, 12, 13,
+ * 15, 16, 17, 18, 19, 20, 27, 28.
+
+ * @return ADC-converted voltage, in the range 0--4095, inclusive
+ * (i.e. a 12-bit ADC conversion).
+
  * @see pinMode()
- * @see analogReference()
  */
 uint32 analogRead(uint8 pin);
 
diff --git a/wirish/pwm.c b/wirish/pwm.c
index 25a7415..072e4cd 100644
--- a/wirish/pwm.c
+++ b/wirish/pwm.c
@@ -46,5 +46,3 @@ void pwmWrite(uint8 pin, uint16 duty_cycle) {
 
     timer_pwm_write_ccr(ccr, duty_cycle);
 }
-
-
diff --git a/wirish/pwm.h b/wirish/pwm.h
index 6d0ddaf..d0bc9e0 100644
--- a/wirish/pwm.h
+++ b/wirish/pwm.h
@@ -35,15 +35,18 @@
 extern "C"{
 #endif
 
+/**
+ * As a convenience, analogWrite is an alias of pwmWrite to ease
+ * porting Arduino code.  However, period and duty will have to be
+ * recalibrated.
+ */
 #define analogWrite pwmWrite
 
 /**
- * Set the PWM duty.
+ * Set the PWM duty on the given pin.
  *
  * User code is expected to determine and honor the maximum value
- * (based on the configured period). As a convenience, analogWrite is
- * an alias of pwmWrite to ease porting Arduino code, though period
- * and duty will have to be recalibrated
+ * (based on the configured period).
  */
 void pwmWrite(uint8 pin, uint16 duty_cycle);
 
diff --git a/wirish/time.c b/wirish/time.c
index 3a48197..c0a0649 100644
--- a/wirish/time.c
+++ b/wirish/time.c
@@ -43,7 +43,6 @@ void delayMicroseconds(uint32 us) {
 
     /* fudge for function call overhead  */
     us--;
-    int x = 4;
     asm volatile("   mov r0, %[us]          \n\t"
                  "1: subs r0, #1            \n\t"
                  "   bhi 1b                 \n\t"
diff --git a/wirish/time.h b/wirish/time.h
index c3dfe2d..c925f74 100644
--- a/wirish/time.h
+++ b/wirish/time.h
@@ -23,7 +23,8 @@
  *****************************************************************************/
 
 /**
- *  @brief Timing and delay functions.
+ * @file time.h
+ * @brief Timing and delay functions.
  */
 
 #ifndef _TIME_H
@@ -41,12 +42,20 @@ extern "C"{
 
 extern volatile uint32 systick_timer_millis;
 
-/* time in milliseconds since boot  */
+/**
+ * Returns time (in milliseconds) since the beginning of program
+ * execution. On overflow, restarts at 0.
+ * @see micros()
+ */
 static inline uint32 millis(void) {
     return systick_timer_millis;
 }
 
-/* Time in microseconds since boot  */
+/**
+ * Returns time (in microseconds) since the beginning of program
+ * execution.  On overflow, restarts at 0.
+ * @see millis()
+ */
 static inline uint32 micros(void) {
     uint32 ms;
     uint32 cycle_cnt;
@@ -67,7 +76,28 @@ static inline uint32 micros(void) {
     return res;
 }
 
+/**
+ * Delay for at least the given number of milliseconds.
+ *
+ * Interrupts, etc. may cause the actual number of milliseconds to
+ * exceed ms.  However, this function will return no less than ms
+ * milliseconds from the time it is called.
+ *
+ * @param ms the number of milliseconds to delay.
+ * @see delayMicroseconds()
+ */
 void delay(unsigned long ms);
+
+/**
+ * Delay for at least the given number of microseconds.
+ *
+ * Interrupts, etc. may cause the actual number of microseconds to
+ * exceed us.  However, this function will return no less than us
+ * microseconds from the time it is called.
+ *
+ * @param us the number of microseconds to delay.
+ * @see delay()
+ */
 void delayMicroseconds(uint32 us);
 
 #ifdef __cplusplus
diff --git a/wirish/wirish_digital.c b/wirish/wirish_digital.c
index cdd04bf..6f9906d 100644
--- a/wirish/wirish_digital.c
+++ b/wirish/wirish_digital.c
@@ -31,7 +31,7 @@
 
 void pinMode(uint8 pin, WiringPinMode mode) {
     uint8 outputMode;
-    uint32 pwm = 0;
+    boolean pwm = false;
 
     if (pin >= NR_GPIO_PINS) {
         return;
@@ -59,11 +59,11 @@ void pinMode(uint8 pin, WiringPinMode mode) {
         break;
     case PWM:
         outputMode = GPIO_MODE_AF_OUTPUT_PP;
-        pwm = 1;
+        pwm = true;
         break;
     case PWM_OPEN_DRAIN:
         outputMode = GPIO_MODE_AF_OUTPUT_OD;
-        pwm = 1;
+        pwm = true;
         break;
     default:
         ASSERT(0);
diff --git a/wirish/wirish_math.h b/wirish/wirish_math.h
index ae73d61..14614ba 100644
--- a/wirish/wirish_math.h
+++ b/wirish/wirish_math.h
@@ -22,6 +22,11 @@
  * THE SOFTWARE.
  *****************************************************************************/
 
+/**
+ * @file wirish_math.h
+ * @brief Includes cmath; provides Arduino-compatible math routines.
+ */
+
 #ifndef _WIRING_MATH_H_
 #define _WIRING_MATH_H_
 
@@ -29,12 +34,55 @@
 
 #ifdef __cplusplus
 
-void randomSeed(unsigned int);
-long random(long);
-long random(long, long);
+/**
+ * @brief Initialize the pseudo-random number generator.
+ * @param seed the number used to initialize the seed; cannot be zero.
+ */
+void randomSeed(unsigned int seed);
+
+/**
+ * @brief Generate a pseudo-random number with upper bound.
+ * @param max An upper bound on the returned value, exclusive.
+ * @return A pseudo-random number in the range [0,max).
+ * @see randomSeed()
+ */
+long random(long max);
+
+/**
+ * @brief Generate a pseudo-random number with lower and upper bounds.
+ * @param min Lower bound on the returned value, inclusive.
+ * @param max Upper bound on the returned value, exclusive.
+ * @return A pseudo-random number in the range [min, max).
+ * @see randomSeed()
+ */
+long random(long min, long max);
+
+/**
+ * @brief Remap a number from one range to another.
+ *
+ * That is, a value equal to fromStart gets mapped to toStart, a value
+ * of fromEnd to toEnd, and other values are mapped proportionately.
+ *
+ * Does not constrain value to lie within [fromStart, fromEnd].
+ *
+ * If a "start" value is larger than its corresponding "end", the
+ * ranges are reversed, so map(n, 1, 10, 10, 1) would reverse the
+ * range [1,10].
+ *
+ * Negative numbers may appear as any argument.
+ *
+ * @param value the value to map.
+ * @param fromStart the beginning of the value's current range.
+ * @param fromEnd the end of the value's current range.
+ * @param toStart the beginning of the value's mapped range.
+ * @param toEnd the end of the value's mapped range.
+ * @return the mapped value.
+ */
 /* TODO: profile code bloat due to inlining this */
-inline long map(long x, long in_min, long in_max, long out_min, long out_max) {
-    return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
+inline long map(long value, long fromStart, long fromEnd,
+                long toStart, long toEnd) {
+    return (value - fromStart) * (toEnd - toStart) / (fromEnd - fromStart) +
+        toStart;
 }
 
 #define PI          3.1415926535897932384626433832795
@@ -59,4 +107,48 @@ inline long map(long x, long in_min, long in_max, long out_min, long out_max) {
 
 #endif
 
+/* Following are duplicate declarations (with Doxygen comments) for
+ * some of the math.h functions; this is for the convenience of the
+ * Sphinx docs.
+ */
+
+/**
+ * Compute the cosine of an angle, in radians.
+ * @param x The radian measure of the angle.
+ * @return The cosine of x.  This value will be between -1 and 1.
+ */
+double cos(double x);
+
+/**
+ * Compute the sine of an angle, in radians.
+ * @param x The radian measure of the angle.
+ * @return The sine of x.  This value will be between -1 and 1.
+ */
+double sin(double x);
+
+/**
+ * Compute the tangent of an angle, in radians.
+ * @param x The radian measure of the angle.
+ * @return The tangent of x.  There are no limits on the return value
+ * of this function.
+ */
+double tan(double x);
+
+/**
+ * Compute the square root of a number.
+ * @param x The number whose square root to find.  This value cannot
+ * be negative.
+ * @return The square root of x.  The return value is never negative.
+ */
+double sqrt(double x);
+
+/**
+ * Compute an exponentiation.
+ * @param x the base. This value cannot be zero if y <= 0.  This value
+ * cannot be negative if y is not an integral value.
+ * @param y the exponent.
+ * @return x raised to the power y.
+ */
+double pow(double x, double y);
+
 #endif