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.

4 files changed, 464 insertions, 167 deletions

diff --git a/wirish/comm/HardwareSPI.cpp b/wirish/comm/HardwareSPI.cpp
index 20090f5..54b7ab3 100644
--- a/wirish/comm/HardwareSPI.cpp
+++ b/wirish/comm/HardwareSPI.cpp
@@ -23,118 +23,268 @@
  *****************************************************************************/
 
 /**
- * @brief HardwareSPI "wiring-like" api for SPI
+ * @author Marti Bolivar <mbolivar@leaflabs.com>
+ * @brief Wirish SPI implementation.
  */
 
-/* NOTES:
- *
- * Speeds:
- * -----------------------------------
- * Interface num:     SPI1        SPI2
- * Bus                APB2        APB1
- * -----------------------------------
- * Prescaler         Frequencies
- * -----------------------------------
- * 2:                  N/A  18 000 000
- * 4:           18 000 000   9 000 000
- * 8:            9 000 000   4 500 000
- * 16:           4 500 000   2 250 000
- * 32:           2 250 000   1 125 000
- * 64:           1 125 000     562 500
- * 128:            562 500     281 250
- * 256:            281 250     140 625
- *
- * TODO: Do the complementary PWM outputs mess up SPI2?
- * */
+#include "HardwareSPI.h"
+
+#include "timer.h"
+#include "util.h"
 
 #include "wirish.h"
-#include "spi.h"
-#include "HardwareSPI.h"
+#include "boards.h"
 
-static const uint32 prescaleFactors[MAX_SPI_FREQS] = {
-    SPI_PRESCALE_2,               // SPI_18MHZ
-    SPI_PRESCALE_4,               // SPI_9MHZ
-    SPI_PRESCALE_8,               // SPI_4_5MHZ
-    SPI_PRESCALE_16,              // SPI_2_25MHZ
-    SPI_PRESCALE_32,              // SPI_1_125MHZ
-    SPI_PRESCALE_64,              // SPI_562_500KHZ
-    SPI_PRESCALE_128,             // SPI_281_250KHZ
-    SPI_PRESCALE_256,             // SPI_140_625KHZ
-};
+static void enable_device(spi_dev *dev,
+                          bool as_master,
+                          SPIFrequency frequency,
+                          spi_cfg_flag endianness,
+                          spi_mode mode);
 
-/**
- * @brief Initialize a SPI peripheral
- * @param freq frequency to run at, must one of the following values:
- *           - SPI_18MHZ
- *           - SPI_9MHZ
- *           - SPI_4_5MHZ
- *           - SPI_2_25MHZ
- *           - SPI_1_125MHZ
- *           - SPI_562_500KHZ
- *           - SPI_281_250KHZ
- *           - SPI_140_625KHZ
- * @param endianness endianness of the data frame, must be either LSBFIRST
- *           or MSBFIRST
- * @param mode SPI standard CPOL and CPHA levels
+/*
+ * Constructor, public methods
  */
-void HardwareSPI::begin(SPIFrequency freq, uint32 endianness, uint32 mode) {
-    uint32 spi_num    = this->spi_num;
-    uint32 prescale;
-
-    if ((freq >= MAX_SPI_FREQS)     ||
-        !((endianness == LSBFIRST)  ||
-          (endianness == MSBFIRST)) ||
-        (mode >= 4)) {
+
+HardwareSPI::HardwareSPI(uint32 spi_num) {
+    switch (spi_num) {
+    case 1:
+        this->spi_d = SPI1;
+        break;
+    case 2:
+        this->spi_d = SPI2;
+        break;
+#ifdef STM32_HIGH_DENSITY
+    case 3:
+        this->spi_d = SPI3;
+        break;
+#endif
+    default:
+        ASSERT(0);
+    }
+}
+
+void HardwareSPI::begin(SPIFrequency frequency, uint32 bitOrder, uint32 mode) {
+    if (mode >= 4) {
+        ASSERT(0);
         return;
     }
+    spi_cfg_flag end = bitOrder == MSBFIRST ? SPI_FRAME_MSB : SPI_FRAME_LSB;
+    spi_mode m = (spi_mode)mode;
+    enable_device(this->spi_d, true, frequency, end, m);
+}
 
-    if (spi_num == 1) {
-        /* SPI1 is too fast for 140625  */
-        if (freq == SPI_140_625KHZ) {
-            return;
-        }
+void HardwareSPI::begin(void) {
+    this->begin(SPI_1_125MHZ, MSBFIRST, 0);
+}
 
-        /* Turn off PWM on shared pins */
-        timer_set_mode(TIMER3, 2, TIMER_DISABLED);
-        timer_set_mode(TIMER3, 1, TIMER_DISABLED);
+void HardwareSPI::beginSlave(uint32 bitOrder, uint32 mode) {
+    if (mode >= 4) {
+        ASSERT(0);
+        return;
     }
+    spi_cfg_flag end = bitOrder == MSBFIRST ? SPI_FRAME_MSB : SPI_FRAME_LSB;
+    spi_mode m = (spi_mode)mode;
+    enable_device(this->spi_d, false, (SPIFrequency)0, end, m);
+}
 
-    endianness = (endianness == LSBFIRST) ? SPI_LSBFIRST : SPI_MSBFIRST;
-    prescale = (spi_num == 1) ?
-        prescaleFactors[freq + 1] :
-        prescaleFactors[freq];
+void HardwareSPI::beginSlave(void) {
+    this->beginSlave(MSBFIRST, 0);
+}
+
+void HardwareSPI::end(void) {
+    if (!spi_is_enabled(this->spi_d)) {
+        return;
+    }
 
-    spi_init(spi_num, prescale, endianness, mode);
+    // Follows RM0008's sequence for disabling a SPI in master/slave
+    // full duplex mode.
+    while (spi_is_rx_nonempty(this->spi_d)) {
+        // FIXME [0.1.0] remove this once you have an interrupt based driver
+        volatile uint16 rx __attribute__((unused)) = spi_rx_reg(this->spi_d);
+    }
+    while (!spi_is_tx_empty(this->spi_d))
+        ;
+    while (spi_is_busy(this->spi_d))
+        ;
+    spi_peripheral_disable(this->spi_d);
 }
 
-/**
- * @brief Initialize a SPI peripheral with a default speed of 1.125
- *      MHZ, MSBFIRST, mode 0
- */
-void HardwareSPI::begin(void) {
-   begin(SPI_1_125MHZ, MSBFIRST, 0);
+uint8 HardwareSPI::read(void) {
+    uint8 buf[1];
+    this->read(buf, 1);
+    return buf[0];
 }
 
-/**
- * @brief send a byte out the spi peripheral
- * @param data byte to send
+void HardwareSPI::read(uint8 *buf, uint32 len) {
+    uint32 rxed = 0;
+    while (rxed < len) {
+        while (!spi_is_rx_nonempty(this->spi_d))
+            ;
+        buf[rxed++] = (uint8)spi_rx_reg(this->spi_d);
+    }
+}
+
+void HardwareSPI::write(uint8 byte) {
+    this->write(&byte, 1);
+}
+
+void HardwareSPI::write(const uint8 *data, uint32 length) {
+    uint32 txed = 0;
+    while (txed < length) {
+        txed += spi_tx(this->spi_d, data + txed, length - txed);
+    }
+}
+
+uint8 HardwareSPI::transfer(uint8 byte) {
+    this->write(byte);
+    return this->read();
+}
+
+/*
+ * Deprecated functions
  */
+
 uint8 HardwareSPI::send(uint8 data) {
-   return spi_tx_byte(this->spi_num, data);
+    uint8 buf[] = {data};
+    return this->send(buf, 1);
 }
 
 uint8 HardwareSPI::send(uint8 *buf, uint32 len) {
-   return spi_tx(this->spi_num, buf, len);
+    if (len == 0) {
+        return 0;
+    }
+    uint32 txed = 0;
+    uint8 ret = 0;              // shut up, GCC
+    while (txed < len) {
+        this->write(buf[txed++]);
+        ret = this->read();
+    }
+    return ret;
 }
 
-/**
- * @brief read a byte from the spi peripheral
- * @return byte in the buffer
- */
 uint8 HardwareSPI::recv(void) {
-   return spi_rx(this->spi_num);
+    return this->read();
 }
 
-HardwareSPI::HardwareSPI(uint32 spi_num) {
-   this->spi_num = spi_num;
+/*
+ * Auxiliary functions
+ */
+
+static void configure_gpios(spi_dev *dev, bool as_master);
+static spi_baud_rate determine_baud_rate(spi_dev *dev, SPIFrequency freq);
+
+/* Enables the device in master or slave full duplex mode.  If you
+ * change this code, you must ensure that appropriate changes are made
+ * to HardwareSPI::end(). */
+static void enable_device(spi_dev *dev,
+                          bool as_master,
+                          SPIFrequency freq,
+                          spi_cfg_flag endianness,
+                          spi_mode mode) {
+    spi_baud_rate baud = determine_baud_rate(dev, freq);
+    uint32 cfg_flags = (endianness | SPI_DFF_8_BIT | SPI_SW_SLAVE |
+                        (as_master ? SPI_SOFT_SS : 0));
+
+    spi_init(dev);
+    configure_gpios(dev, as_master);
+    if (as_master) {
+        spi_master_enable(dev, baud, mode, cfg_flags);
+    } else {
+        spi_slave_enable(dev, mode, cfg_flags);
+    }
+}
+
+static void disable_pwm(const stm32_pin_info *i) {
+    if (i->timer_device) {
+        timer_set_mode(i->timer_device, i->timer_channel, TIMER_DISABLED);
+    }
+}
+
+typedef struct spi_pins {
+    uint8 nss;
+    uint8 sck;
+    uint8 miso;
+    uint8 mosi;
+} spi_pins;
+
+static void configure_gpios(spi_dev *dev, bool as_master) {
+    const spi_pins spi_pin_config[] = {
+        {BOARD_SPI1_NSS_PIN,
+         BOARD_SPI1_SCK_PIN,
+         BOARD_SPI1_MISO_PIN,
+         BOARD_SPI1_MOSI_PIN},
+        {BOARD_SPI2_NSS_PIN,
+         BOARD_SPI2_SCK_PIN,
+         BOARD_SPI2_MISO_PIN,
+         BOARD_SPI2_MOSI_PIN},
+#ifdef STM32_HIGH_DENSITY
+        {BOARD_SPI3_NSS_PIN,
+         BOARD_SPI3_SCK_PIN,
+         BOARD_SPI3_MISO_PIN,
+         BOARD_SPI3_MOSI_PIN},
+#endif
+    };
+
+    const spi_pins *pins;
+
+    switch (dev->clk_id) {
+    case RCC_SPI1:
+        pins = &spi_pin_config[0];
+        break;
+    case RCC_SPI2:
+        pins = &spi_pin_config[1];
+        break;
+#ifdef STM32_HIGH_DENSITY
+    case RCC_SPI3:
+        pins = &spi_pin_config[2];
+        break;
+#endif
+    default:
+        ASSERT(0);
+        return;
+    }
+
+    const stm32_pin_info *nssi = &PIN_MAP[pins->nss];
+    const stm32_pin_info *scki = &PIN_MAP[pins->sck];
+    const stm32_pin_info *misoi = &PIN_MAP[pins->miso];
+    const stm32_pin_info *mosii = &PIN_MAP[pins->mosi];
+
+    disable_pwm(nssi);
+    disable_pwm(scki);
+    disable_pwm(misoi);
+    disable_pwm(mosii);
+
+    spi_gpio_cfg(as_master,
+                 nssi->gpio_device,
+                 nssi->gpio_bit,
+                 scki->gpio_device,
+                 scki->gpio_bit,
+                 misoi->gpio_bit,
+                 mosii->gpio_bit);
+}
+
+static const spi_baud_rate baud_rates[MAX_SPI_FREQS] __FLASH__ = {
+    SPI_BAUD_PCLK_DIV_2,
+    SPI_BAUD_PCLK_DIV_4,
+    SPI_BAUD_PCLK_DIV_8,
+    SPI_BAUD_PCLK_DIV_16,
+    SPI_BAUD_PCLK_DIV_32,
+    SPI_BAUD_PCLK_DIV_64,
+    SPI_BAUD_PCLK_DIV_128,
+    SPI_BAUD_PCLK_DIV_256,
+};
+
+/*
+ * Note: This assumes you're on a LeafLabs-style board
+ * (CYCLES_PER_MICROSECOND == 72, APB2 at 72MHz, APB1 at 36MHz).
+ */
+static spi_baud_rate determine_baud_rate(spi_dev *dev, SPIFrequency freq) {
+    if (rcc_dev_clk(dev->clk_id) == RCC_APB2 && freq == SPI_140_625KHZ) {
+        /* APB2 peripherals are too fast for 140.625 KHz */
+        ASSERT(0);
+        return (spi_baud_rate)~0;
+    }
+    return (rcc_dev_clk(dev->clk_id) == RCC_APB2 ?
+            baud_rates[freq + 1] :
+            baud_rates[freq]);
 }
diff --git a/wirish/comm/HardwareSPI.h b/wirish/comm/HardwareSPI.h
index 7241d0b..3a6def5 100644
--- a/wirish/comm/HardwareSPI.h
+++ b/wirish/comm/HardwareSPI.h
@@ -3,60 +3,188 @@
  *
  * Copyright (c) 2010 Perry Hung.
  *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use, copy,
+ * modify, merge, publish, distribute, sublicense, and/or sell copies
+ * of the Software, and to permit persons to whom the Software is
  * furnished to do so, subject to the following conditions:
  *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
  *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
- * THE SOFTWARE.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
  *****************************************************************************/
 
 /**
- * @brief HardwareSPI definitions
+ * @file HardwareSPI.h
+ * @brief High-level SPI interface
+ *
+ * This is a "bare essentials" polling driver for now.
  */
 
+/* TODO [0.1.0] Remove deprecated methods. */
+
+#include "libmaple_types.h"
+#include "spi.h"
+
+#include "boards.h"
+
 #ifndef _HARDWARESPI_H_
 #define _HARDWARESPI_H_
 
 /**
- * Defines the possible SPI communication speeds.
+ * @brief Defines the possible SPI communication speeds.
  */
 typedef enum SPIFrequency {
     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_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. */
+#define MAX_SPI_FREQS 8
+
+#if CYCLES_PER_MICROSECOND != 72
+/* TODO [0.2.0?] something smarter than this */
+#warn "Unexpected clock speed; SPI frequency calculation will be incorrect"
+#endif
+
+/**
+ * @brief Wirish SPI interface.
+ *
+ * This implementation uses software slave management, so the caller
+ * is responsible for controlling the slave select line.
+ */
 class HardwareSPI {
- private:
-    uint32 spi_num;
+public:
+    /**
+     * @param spiPortNumber Number of the SPI port to manage.
+     */
+    HardwareSPI(uint32 spiPortNumber);
+
+    /**
+     * @brief Turn on a SPI port and set its GPIO pin modes for use as master.
+     *
+     * SPI port is enabled in full duplex mode, with software slave management.
+     *
+     * @param frequency Communication frequency
+     * @param bitOrder Either LSBFIRST (little-endian) or MSBFIRST (big-endian)
+     * @param mode SPI mode to use, one of SPI_MODE_0, SPI_MODE_1,
+     *             SPI_MODE_2, and SPI_MODE_3.
+     */
+    void begin(SPIFrequency frequency, uint32 bitOrder, uint32 mode);
 
- public:
-    HardwareSPI(uint32 spi_num);
+    /**
+     * @brief Equivalent to begin(SPI_1_125MHZ, MSBFIRST, 0).
+     */
     void begin(void);
-    void begin(SPIFrequency freq, uint32 endianness, uint32 mode);
+
+    /**
+     * @brief Turn on a SPI port and set its GPIO pin modes for use as a slave.
+     *
+     * SPI port is enabled in full duplex mode, with software slave management.
+     *
+     * @param bitOrder Either LSBFIRST (little-endian) or MSBFIRST(big-endian)
+     * @param mode SPI mode to use
+     */
+    void beginSlave(uint32 bitOrder, uint32 mode);
+
+    /**
+     * @brief Equivalent to beginSlave(MSBFIRST, 0).
+     */
+    void beginSlave(void);
+
+    /**
+     * @brief Disables the SPI port, but leaves its GPIO pin modes unchanged.
+     */
+    void end(void);
+
+    /**
+     * @brief Return the next unread byte.
+     *
+     * If there is no unread byte waiting, this function will block
+     * until one is received.
+     */
+    uint8 read(void);
+
+    /**
+     * @brief Read length bytes, storing them into buffer.
+     * @param buffer Buffer to store received bytes into.
+     * @param length Number of bytes to store in buffer.  This
+     *               function will block until the desired number of
+     *               bytes have been read.
+     */
+    void read(uint8 *buffer, uint32 length);
+
+    /**
+     * @brief Transmit a byte.
+     * @param data Byte to transmit.
+     */
+    void write(uint8 data);
+
+    /**
+     * @brief Transmit multiple bytes.
+     * @param buffer Bytes to transmit.
+     * @param length Number of bytes in buffer to transmit.
+     */
+    void write(const uint8 *buffer, uint32 length);
+
+    /**
+     * @brief Transmit a byte, then return the next unread byte.
+     *
+     * This function transmits before receiving.
+     *
+     * @param data Byte to transmit.
+     * @return Next unread byte.
+     */
+    uint8 transfer(uint8 data);
+
+    /* -- The following methods are deprecated --------------------------- */
+
+    /**
+     * @brief Deprecated.
+     *
+     * Use HardwareSPI::transfer() instead.
+     *
+     * @see HardwareSPI::transfer()
+     */
     uint8 send(uint8 data);
+
+    /**
+     * @brief Deprecated.
+     *
+     * Use HardwareSPI::write() in combination with
+     * HardwareSPI::read() (or HardwareSPI::transfer()) instead.
+     *
+     * @see HardwareSPI::write()
+     * @see HardwareSPI::read()
+     * @see HardwareSPI::transfer()
+     */
     uint8 send(uint8 *data, uint32 length);
+
+    /**
+     * @brief Deprecated.
+     *
+     * Use HardwareSPI::read() instead.
+     *
+     * @see HardwareSPI::read()
+     */
     uint8 recv(void);
+private:
+    spi_dev *spi_d;
 };
 
 #endif
diff --git a/wirish/comm/HardwareSerial.cpp b/wirish/comm/HardwareSerial.cpp
index d6c7e82..5c9bff6 100644
--- a/wirish/comm/HardwareSerial.cpp
+++ b/wirish/comm/HardwareSerial.cpp
@@ -24,69 +24,86 @@
 
 /**
  * @file HardwareSerial.cpp
- *
- * @brief Wiring-like serial api
+ * @brief Wirish serial port implementation.
  */
 
-#include "wirish.h"
-#include "HardwareSerial.h"
-#include "usart.h"
 #include "gpio.h"
-#include "timers.h"
+#include "timer.h"
+
+#include "HardwareSerial.h"
+#include "boards.h"
 
-HardwareSerial Serial1(USART1, 4500000UL, GPIOA_BASE,  9,10, TIMER1, 2);
-HardwareSerial Serial2(USART2, 2250000UL, GPIOA_BASE,  2, 3, TIMER2, 3);
-HardwareSerial Serial3(USART3, 2250000UL, GPIOB_BASE, 10,11, TIMER_INVALID, 0);
-// TODO: High density device ports
+#define TX1 BOARD_USART1_TX_PIN
+#define RX1 BOARD_USART1_RX_PIN
+#define TX2 BOARD_USART2_TX_PIN
+#define RX2 BOARD_USART2_RX_PIN
+#define TX3 BOARD_USART3_TX_PIN
+#define RX3 BOARD_USART3_RX_PIN
+#if defined STM32_HIGH_DENSITY && !defined(BOARD_maple_RET6)
+#define TX4 BOARD_UART4_TX_PIN
+#define RX4 BOARD_UART4_RX_PIN
+#define TX5 BOARD_UART5_TX_PIN
+#define RX5 BOARD_UART5_RX_PIN
+#endif
 
-HardwareSerial::HardwareSerial(uint8 usart_num,
-                               uint32 max_baud,
-                               GPIO_Port *gpio_port,
+// TODO Put these magic numbers into boards.h #defines
+HardwareSerial Serial1(USART1, TX1, RX1, 72000000UL);
+HardwareSerial Serial2(USART2, TX2, RX2, 36000000UL);
+HardwareSerial Serial3(USART3, TX3, RX3, 36000000UL);
+#if defined(STM32_HIGH_DENSITY) && !defined(BOARD_maple_RET6)
+HardwareSerial Serial4(UART4,  TX4, RX4, 36000000UL);
+HardwareSerial Serial5(UART5,  TX5, RX5, 36000000UL);
+#endif
+
+HardwareSerial::HardwareSerial(usart_dev *usart_device,
                                uint8 tx_pin,
                                uint8 rx_pin,
-                               timer_dev_num timer_num,
-                               uint8 compare_num) {
-    this->usart_num = usart_num;
-    this->max_baud = max_baud;
-    this->gpio_port = gpio_port;
+                               uint32 clock_speed) {
+    this->usart_device = usart_device;
+    this->clock_speed = clock_speed;
     this->tx_pin = tx_pin;
     this->rx_pin = rx_pin;
-    this->timer_num = timer_num;
-    this->compare_num = compare_num;
 }
 
 uint8 HardwareSerial::read(void) {
-    return usart_getc(usart_num);
+    return usart_getc(usart_device);
 }
 
 uint32 HardwareSerial::available(void) {
-    return usart_data_available(usart_num);
+    return usart_data_available(usart_device);
 }
 
 void HardwareSerial::write(unsigned char ch) {
-    usart_putc(usart_num, ch);
+    usart_putc(usart_device, ch);
 }
 
 void HardwareSerial::begin(uint32 baud) {
-    if (baud > max_baud) {
+    ASSERT(baud <= usart_device->max_baud);
+
+    if (baud > usart_device->max_baud) {
         return;
     }
 
-    gpio_set_mode(gpio_port, tx_pin, GPIO_MODE_AF_OUTPUT_PP);
-    gpio_set_mode(gpio_port, rx_pin, GPIO_MODE_INPUT_FLOATING);
+    const stm32_pin_info *txi = &PIN_MAP[tx_pin];
+    const stm32_pin_info *rxi = &PIN_MAP[rx_pin];
+
+    gpio_set_mode(txi->gpio_device, txi->gpio_bit, GPIO_AF_OUTPUT_PP);
+    gpio_set_mode(rxi->gpio_device, rxi->gpio_bit, GPIO_INPUT_FLOATING);
 
-    if (timer_num != TIMER_INVALID) {
-        /* turn off any pwm if there's a conflict on this usart */
-        timer_set_mode(timer_num, compare_num, TIMER_DISABLED);
+    if (txi->timer_device != NULL) {
+        /* Turn off any PWM if there's a conflict on this GPIO bit. */
+        timer_set_mode(txi->timer_device, txi->timer_channel, TIMER_DISABLED);
     }
 
-    usart_init(usart_num, baud);
+    usart_init(usart_device);
+    usart_set_baud_rate(usart_device, clock_speed, baud);
+    usart_enable(usart_device);
 }
 
 void HardwareSerial::end(void) {
-    usart_disable(usart_num);
+    usart_disable(usart_device);
 }
 
 void HardwareSerial::flush(void) {
-    usart_reset_rx(usart_num);
+    usart_reset_rx(usart_device);
 }
diff --git a/wirish/comm/HardwareSerial.h b/wirish/comm/HardwareSerial.h
index aad8aa7..934db23 100644
--- a/wirish/comm/HardwareSerial.h
+++ b/wirish/comm/HardwareSerial.h
@@ -24,41 +24,34 @@
 
 /**
  * @file HardwareSerial.h
- *
- * @brief Wirish interface to hardware serial communications.
+ * @brief Wirish serial port interface.
  */
 
 #ifndef _HARDWARESERIAL_H_
 #define _HARDWARESERIAL_H_
 
-#include "timers.h"
+#include "libmaple_types.h"
+#include "usart.h"
 
 #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. */
+/*
+ * IMPORTANT:
+ *
+ * This class documented "by hand" (i.e., not using Doxygen) in:
+ *
+ *   libmaple/docs/source/lang/api/serial.rst
+ *
+ * If you alter the public HardwareSerial interface, you MUST update
+ * the documentation accordingly.
+ */
 
 class HardwareSerial : public Print {
- private:
-    uint8 usart_num;
-    uint32 max_baud;
-    GPIO_Port *gpio_port;
-    uint8 tx_pin;
-    uint8 rx_pin;
-    timer_dev_num timer_num;
-    uint8 compare_num;
- public:
-    HardwareSerial(uint8 usart_num,
-                   uint32 max_baud,
-                   GPIO_Port *gpio_port,
+public:
+    HardwareSerial(usart_dev *usart_device,
                    uint8 tx_pin,
                    uint8 rx_pin,
-                   timer_dev_num timer_num,
-                   uint8 compare_num);
+                   uint32 clock_speed);
     void begin(uint32 baud);
     void end(void);
     uint32 available(void);
@@ -66,10 +59,19 @@ class HardwareSerial : public Print {
     void flush(void);
     virtual void write(unsigned char);
     using Print::write;
+private:
+    usart_dev *usart_device;
+    uint8 tx_pin;
+    uint8 rx_pin;
+    uint32 clock_speed;
 };
+
 extern HardwareSerial Serial1;
 extern HardwareSerial Serial2;
 extern HardwareSerial Serial3;
-// TODO: high density device ports
+#if defined(STM32_HIGH_DENSITY) && !defined(BOARD_maple_RET6)
+extern HardwareSerial Serial4;
+extern HardwareSerial Serial5;
 #endif
 
+#endif