Improve usability and documentation of the SPI API (ARMmbed#165)

* Make TRANSACTION_QUEUE_SIZE_SPI a proper option instead of a weird macro

* Document DMAUsage constant

* Copy over reworked SPI header

* Spelling -_-

* Document SPI event flags

Author: Jamie Smith

drivers/include/drivers/I2C.h

@@ -396,7 +396,7 @@ class I2C : private NonCopyable<I2C> {
      * @param tx_length The length of TX buffer in bytes.  If 0, no transmission is done.
      * @param rx_buffer The RX buffer, which is used for received data.  May be nullptr if tx_length is 0.
      * @param rx_length The length of RX buffer in bytes  If 0, no reception is done.
-     * @param event     The logical OR of events to modify.  May be I2C_EVENT_ALL, or some combination
+     * @param event     The logical OR of events to subscribe to.  May be I2C_EVENT_ALL, or some combination
      *        of the flags I2C_EVENT_ERROR, I2C_EVENT_ERROR_NO_SLAVE, I2C_EVENT_TRANSFER_COMPLETE, or I2C_EVENT_TRANSFER_EARLY_NACK
      * @param callback  The event callback function
      * @param repeated Set up for a repeated start.  If true, the Mbed processor does not relinquish the bus after

drivers/include/drivers/SPI.h

@@ -18,6 +18,10 @@
             "help": "The maximum number of SPI peripherals used at the same time. Determines RAM allocated for SPI peripheral management. If null, limit determined by hardware.",
             "value": null
         },
+        "spi_transaction_queue_len": {
+            "help": "Size of the asynchronous transaction queue for each SPI peripheral on the processor. 0 means no queueing support.  Only takes effect if the mbed target supports async SPI.",
+            "value": 2
+        },
         "qspi_io0": {
             "help": "QSPI data I/O 0 pin",
             "value": "QSPI_FLASH1_IO0"
@@ -86,5 +90,34 @@
             "help": "OSPI dqs pin",
             "value": "OSPI_FLASH1_DQS"
         }
+    },
+    "target_overrides": {
+        "EFM32GG990F1024":{
+            "spi_transaction_queue_len": 4
+        },
+        "EFR32MG12P332F1024GL125":{
+            "spi_transaction_queue_len": 4
+        },
+        "EFM32GG11B820F2048GL192": {
+            "spi_transaction_queue_len": 4
+        },
+        "RZ_A1XX":{
+            "spi_transaction_queue_len": 16
+        },
+        "RZ_A2XX":{
+            "spi_transaction_queue_len": 16
+        },
+        "TMPM46B":{
+            "spi_transaction_queue_len": 4
+        },
+        "TMPM4G9":{
+            "spi_transaction_queue_len": 4
+        },
+        "TMPM4GR":{
+            "spi_transaction_queue_len": 4
+        },
+        "TMPM4NR":{
+            "spi_transaction_queue_len": 4
+        }
     }
 }

drivers/mbed_lib.json

@@ -137,7 +137,7 @@ void SPI::_do_construct()
     }
     core_util_critical_section_exit();
 
-#if DEVICE_SPI_ASYNCH && TRANSACTION_QUEUE_SIZE_SPI
+#if DEVICE_SPI_ASYNCH && MBED_CONF_DRIVERS_SPI_TRANSACTION_QUEUE_LEN
     // prime the SingletonPtr, so we don't have a problem trying to
     // construct the buffer if asynch operation initiated from IRQ
     _peripheral->transaction_buffer.get();
@@ -291,14 +291,14 @@ void SPI::abort_transfer()
 {
     spi_abort_asynch(&_peripheral->spi);
     unlock_deep_sleep();
-#if TRANSACTION_QUEUE_SIZE_SPI
+#if MBED_CONF_DRIVERS_SPI_TRANSACTION_QUEUE_LEN
     dequeue_transaction();
 #endif
 }
 
 void SPI::clear_transfer_buffer()
 {
-#if TRANSACTION_QUEUE_SIZE_SPI
+#if MBED_CONF_DRIVERS_SPI_TRANSACTION_QUEUE_LEN
     _peripheral->transaction_buffer->reset();
 #endif
 }
@@ -320,7 +320,7 @@ int SPI::set_dma_usage(DMAUsage usage)
 
 int SPI::queue_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t &callback, int event)
 {
-#if TRANSACTION_QUEUE_SIZE_SPI
+#if MBED_CONF_DRIVERS_SPI_TRANSACTION_QUEUE_LEN
     transaction_t t;
 
     t.tx_buffer = const_cast<void *>(tx_buffer);
@@ -373,7 +373,7 @@ void SPI::unlock_deep_sleep()
     }
 }
 
-#if TRANSACTION_QUEUE_SIZE_SPI
+#if MBED_CONF_DRIVERS_SPI_TRANSACTION_QUEUE_LEN
 
 void SPI::start_transaction(transaction_t *data)
 {
@@ -400,7 +400,7 @@ void SPI::irq_handler_asynch(void)
         unlock_deep_sleep();
         _callback.call(event & SPI_EVENT_ALL);
     }
-#if TRANSACTION_QUEUE_SIZE_SPI
+#if MBED_CONF_DRIVERS_SPI_TRANSACTION_QUEUE_LEN
     if (event & (SPI_EVENT_ALL | SPI_EVENT_INTERNAL_TRANSFER_COMPLETE)) {
         // SPI peripheral is free (event happened), dequeue transaction
         dequeue_transaction();

drivers/source/SPI.cpp

@@ -1,6 +1,8 @@
-
-/** \addtogroup hal */
-/** @{*/
+/**
+ * @file
+ * \addtogroup hal
+ * @{
+ */
 /* mbed Microcontroller Library
  * Copyright (c) 2014-2015 ARM Limited
  * SPDX-License-Identifier: Apache-2.0
@@ -24,12 +26,15 @@
 
 #define DMA_ERROR_OUT_OF_CHANNELS (-1)
 
+/**
+ * @brief Enumeration of possible DMA usage hints
+ */
 typedef enum {
-    DMA_USAGE_NEVER,
-    DMA_USAGE_OPPORTUNISTIC,
-    DMA_USAGE_ALWAYS,
-    DMA_USAGE_TEMPORARY_ALLOCATED,
-    DMA_USAGE_ALLOCATED
+    DMA_USAGE_NEVER, ///< Never use DMA
+    DMA_USAGE_OPPORTUNISTIC, ///< Use DMA if possible but deallocate DMA resources when not being used.
+    DMA_USAGE_ALWAYS, ///< Always use DMA when possible
+    DMA_USAGE_TEMPORARY_ALLOCATED, // Seems to be used as an internal state indicator for "we need to deallocate these channels."
+    DMA_USAGE_ALLOCATED // Seems to be used as an internal state indicator for "we have allocated DMA channels."
 } DMAUsage;
 
 #ifdef __cplusplus

hal/include/hal/dma_api.h

@@ -27,11 +27,35 @@
 
 #if DEVICE_SPI
 
+/**
+ * @defgroup hal_SPIEvents SPI Events Macros
+ *
+ * @{
+ */
+
+/**
+ * Indicates that some kind of error occurred when starting the transfer.
+ */
 #define SPI_EVENT_ERROR       (1 << 1)
+
+/**
+ * Indicates that the transfer completed successfully.
+ */
 #define SPI_EVENT_COMPLETE    (1 << 2)
+
+/**
+ * Indicates an Rx overflow: the interrupt system or DMA controller was not able to
+ * keep up with the flow of bytes from the SPI peripheral and data was lost.
+ */
 #define SPI_EVENT_RX_OVERFLOW (1 << 3)
+
+/**
+ * Union of all of the above events.
+ */
 #define SPI_EVENT_ALL         (SPI_EVENT_ERROR | SPI_EVENT_COMPLETE | SPI_EVENT_RX_OVERFLOW)
 
+/// @}
+
 #define SPI_EVENT_INTERNAL_TRANSFER_COMPLETE (1 << 30) // Internal flag to report that an event occurred
 
 #define SPI_FILL_WORD         (0xFFFF)

hal/include/hal/spi_api.h

@@ -32,8 +32,6 @@
 
 
 
-#define TRANSACTION_QUEUE_SIZE_SPI 16
-
 
 
 

targets/TARGET_RENESAS/TARGET_RZ_A1XX/TARGET_GR_LYCHEE/device.h

@@ -32,8 +32,6 @@
 
 
 
-#define TRANSACTION_QUEUE_SIZE_SPI 16
-
 
 
 

targets/TARGET_RENESAS/TARGET_RZ_A1XX/TARGET_RZ_A1H/device.h

@@ -25,8 +25,6 @@
 
 
 
-#define TRANSACTION_QUEUE_SIZE_SPI 16
-
 
 
 

targets/TARGET_RENESAS/TARGET_RZ_A2XX/TARGET_GR_MANGO/device.h

@@ -16,7 +16,6 @@
 #ifndef MBED_DEVICE_H
 #define MBED_DEVICE_H
 
-#define TRANSACTION_QUEUE_SIZE_SPI 	4
 #define DEVICE_ID_LENGTH            32
 
 #include "objects.h"

targets/TARGET_TOSHIBA/TARGET_TMPM46B/device.h

@@ -19,7 +19,6 @@
 #ifndef MBED_DEVICE_H
 #define MBED_DEVICE_H
 
-#define TRANSACTION_QUEUE_SIZE_SPI      4
 #define DEVICE_ID_LENGTH                32
 
 #include <stddef.h>

targets/TARGET_TOSHIBA/TARGET_TMPM4G9/device.h

@@ -17,7 +17,6 @@
 #ifndef MBED_DEVICE_H
 #define MBED_DEVICE_H
 
-#define TRANSACTION_QUEUE_SIZE_SPI      4
 #define DEVICE_ID_LENGTH                32
 
 #include <stddef.h>

targets/TARGET_TOSHIBA/TARGET_TMPM4GR/device.h

@@ -17,7 +17,6 @@
 #ifndef MBED_DEVICE_H
 #define MBED_DEVICE_H
 
-#define TRANSACTION_QUEUE_SIZE_SPI      4
 #define DEVICE_ID_LENGTH                32
 
 #include <stddef.h>

targets/TARGET_TOSHIBA/TARGET_TMPM4NR/device.h

@@ -1211,8 +1211,7 @@
         ],
         "macros": [
             "USE_HAL_DRIVER",
-            "USE_FULL_LL_DRIVER",
-            "TRANSACTION_QUEUE_SIZE_SPI=2"
+            "USE_FULL_LL_DRIVER"
         ],
         "bootloader_supported": true,
         "config": {
@@ -6573,8 +6572,7 @@
         ],
         "core": "Cortex-M3",
         "macros_add": [
-            "EFM32GG990F1024",
-            "TRANSACTION_QUEUE_SIZE_SPI=4"
+            "EFM32GG990F1024"
         ],
         "supported_toolchains": [
             "GCC_ARM"
@@ -6688,8 +6686,7 @@
         ],
         "core": "Cortex-M4F",
         "macros_add": [
-            "EFR32MG12P332F1024GL125",
-            "TRANSACTION_QUEUE_SIZE_SPI=4"
+            "EFR32MG12P332F1024GL125"
         ],
         "supported_toolchains": [
             "GCC_ARM"
@@ -6798,8 +6795,7 @@
         ],
         "core": "Cortex-M4F",
         "macros_add": [
-            "EFM32GG11B820F2048GL192",
-            "TRANSACTION_QUEUE_SIZE_SPI=4"
+            "EFM32GG11B820F2048GL192"
         ],
         "supported_toolchains": [
             "GCC_ARM"

targets/targets.json

@@ -126,3 +126,9 @@ conf
 transactional
 errored
 natively
+enqueued
+enqueue
+MSBit
+LSBit
+busses
+STMicro