git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2246 35acf78f-673a-0410-8e92-d51de3d6d3f4

14 files changed, 498 insertions, 165 deletions

diff --git a/os/hal/include/spi.h b/os/hal/include/spi.h
index e6fbe7c90..fee5742d1 100644
--- a/os/hal/include/spi.h
+++ b/os/hal/include/spi.h
@@ -39,7 +39,7 @@
 /*===========================================================================*/

 

 /**

- * @brief   Enables the @p spiWait() API.

+ * @brief   Enables the "wait" APIs.

  * @note    Disabling this option saves both code and data space.

  */

 #if !defined(SPI_USE_WAIT) || defined(__DOXYGEN__)

@@ -112,9 +112,10 @@ typedef enum {
 /**

  * @brief   Emits a train of clock pulses on the SPI bus.

  * @details This asynchronous function starts the emission of a train of

- *          clock pulses without asserting any slave, while this is not

- *          usually required by the SPI protocol it is required by

- *          initialization procedure of MMC/SD cards in SPI mode.

+ *          clock pulses without asserting any slave.

+ * @note    This functionality is not usually required by the SPI protocol

+ *          but it is required by initialization procedure of MMC/SD cards

+ *          in SPI mode.

  * @post    At the end of the operation the configured callback is invoked.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

@@ -209,6 +210,51 @@ typedef enum {
   spi_lld_receive(spip, n, rxbuf);                                          \

 }

 

+#if SPI_USE_WAIT || defined(__DOXYGEN__)

+/**

+ * @brief   Awakens the thread waiting for operation completion, if any.

+ * @note    This macro is meant to be used in the low level drivers

+ *          implementation only.

+ *

+ * @param[in] spip      pointer to the @p SPIDriver object

+ *

+ * @notapi

+ */

+#define _spi_wakeup(spip) {                                                 \

+  if ((spip)->spd_thread != NULL) {                                         \

+    Thread *tp = (spip)->spd_thread;                                        \

+    (spip)->spd_thread = NULL;                                              \

+    tp->p_u.rdymsg = RDY_RESET;                                             \

+    chSchReadyI(tp);                                                        \

+  }                                                                         \

+}

+

+/**

+ * @brief   Waits for operation completion.

+ * @details This function waits for the driver to complete the current

+ *          operation.

+ * @pre     An operation must be running while the function is invoked.

+ * @post    On exit the SPI driver is ready to accept more commands.

+ * @note    No more than one thread can wait on a SPI driver using

+ *          this function.

+ *

+ * @param[in] spip      pointer to the @p SPIDriver object

+ *

+ * @sclass

+ */

+#define spiWaitS(spip) {                                                    \

+  chDbgAssert((spip)->spd_thread == NULL,                                   \

+              "spiWaitS(), #1", "already waiting");                         \

+  (spip)->spd_thread = chThdSelf();                                         \

+  chSchGoSleepS(THD_STATE_SUSPENDED);                                       \

+}

+#else /* !SPI_USE_WAIT */

+

+/* No wakeup when wait functions are disabled.*/

+#define _spi_wakeup(spip)

+

+#endif /* !SPI_USE_WAIT */

+

 /*===========================================================================*/

 /* External declarations.                                                    */

 /*===========================================================================*/

@@ -228,8 +274,12 @@ extern "C" {
   void spiSend(SPIDriver *spip, size_t n, const void *txbuf);

   void spiReceive(SPIDriver *spip, size_t n, void *rxbuf);

 #if SPI_USE_WAIT

-  void _spi_wakeup(SPIDriver *spip, mag_t msg);

-  msg_t spiWait(SPIDriver *spip);

+  void spiWait(SPIDriver *spip);

+  void spiSynchronizeWait(SPIDriver *spip, size_t n);

+  void spiIgnoreWait(SPIDriver *spip, size_t n);

+  void spiExchangeWait(SPIDriver *spip, size_t n, const void *txbuf, void *rxbuf);

+  void spiSendWait(SPIDriver *spip, size_t n, const void *txbuf);

+  void spiReceiveWait(SPIDriver *spip, size_t n, void *rxbuf);

 #endif /* SPI_USE_WAIT */

 #if SPI_USE_MUTUAL_EXCLUSION

   void spiAcquireBus(SPIDriver *spip);

diff --git a/os/hal/platforms/STM32/spi_lld.c b/os/hal/platforms/STM32/spi_lld.c
index c12b410c8..bb69f8c5f 100644
--- a/os/hal/platforms/STM32/spi_lld.c
+++ b/os/hal/platforms/STM32/spi_lld.c
@@ -57,30 +57,43 @@ SPIDriver SPID3;
 /* Driver local functions.                                                   */

 /*===========================================================================*/

 

-static void spi_stop(SPIDriver *spip) {

-

-  /* Stops RX and TX DMA channels.*/

-  dmaChannelDisable(spip->spd_dmarx);

-  dmaChannelDisable(spip->spd_dmatx);

+/**

+ * @brief   Stops the SPI DMA channels.

+ *

+ * @param[in] spip      pointer to the @p SPIDriver object

+ */

+#define dma_stop(spip) {                                                    \

+  dmaChannelDisable(spip->spd_dmatx);                                       \

+  dmaChannelDisable(spip->spd_dmarx);                                       \

+}

 

-  chSysLockFromIsr();

-  chSchReadyI(spip->spd_thread);

-  chSysUnlockFromIsr();

+/**

+ * @brief   Starts the SPI DMA channels.

+ *
+ * @param[in] spip      pointer to the @p SPIDriver object

+ */

+#define dma_start(spip) {                                                   \

+  dmaChannelEnable((spip)->spd_dmarx);                                      \

+  dmaChannelEnable((spip)->spd_dmatx);                                      \

 }

 

-static void spi_start_wait(SPIDriver *spip) {

+/**

+ * @brief   Shared end-of-transfer service routine.

+ *

+ * @param[in] spip      pointer to the @p SPIDriver object

+ */

+static void serve_interrupt(SPIDriver *spip) {

 

-  chSysLock();

+  /* Stops everything.*/

+  dma_stop(spip);

 

-  /* DMAs start.*/

-  dmaChannelEnable(spip->spd_dmarx);

-  dmaChannelEnable(spip->spd_dmatx);

+  /* If a callback is defined then invokes it.*/

+  if (spip->spd_config->spc_endcb)

+    spip->spd_config->spc_endcb(spip);

 

-  /* Wait for completion event.*/

-  spip->spd_thread = currp;

-  chSchGoSleepS(THD_STATE_SUSPENDED);

-  spip->spd_thread = NULL;

-  chSysUnlock();

+  /* Wakeup the waiting thread if any, note that the following macro is

+     empty if the SPI_USE_WAIT option is disabled.*/

+  _spi_wakeup(spip);

 }

 

 /*===========================================================================*/

@@ -97,10 +110,10 @@ CH_IRQ_HANDLER(DMA1_Ch2_IRQHandler) {
 

   CH_IRQ_PROLOGUE();

 

-  spi_stop(&SPID1);

   if ((STM32_DMA1->ISR & DMA_ISR_TEIF2) != 0) {

     STM32_SPI_SPI1_DMA_ERROR_HOOK();

   }

+  serve_interrupt(&SPID1);

   dmaClearChannel(STM32_DMA1, STM32_DMA_CHANNEL_2);

 

   CH_IRQ_EPILOGUE();

@@ -132,10 +145,10 @@ CH_IRQ_HANDLER(DMA1_Ch4_IRQHandler) {
 

   CH_IRQ_PROLOGUE();

 

-  spi_stop(&SPID2);

   if ((STM32_DMA1->ISR & DMA_ISR_TEIF4) != 0) {

     STM32_SPI_SPI2_DMA_ERROR_HOOK();

   }

+  serve_interrupt(&SPID2);

   dmaClearChannel(STM32_DMA1, STM32_DMA_CHANNEL_4);

 

   CH_IRQ_EPILOGUE();

@@ -167,10 +180,10 @@ CH_IRQ_HANDLER(DMA2_Ch1_IRQHandler) {
 

   CH_IRQ_PROLOGUE();

 

-  spi_stop(&SPID3);

   if ((STM32_DMA2->ISR & DMA_ISR_TEIF1) != 0) {

     STM32_SPI_SPI3_DMA_ERROR_HOOK();

   }

+  serve_interrupt(&SPID3);

   dmaClearChannel(STM32_DMA2, STM32_DMA_CHANNEL_1);

 

   CH_IRQ_EPILOGUE();

@@ -365,9 +378,9 @@ void spi_lld_unselect(SPIDriver *spip) {
 

 /**

  * @brief   Ignores data on the SPI bus.

- * @details This function transmits a series of idle words on the SPI bus and

- *          ignores the received data. This function can be invoked even

- *          when a slave select signal has not been yet asserted.

+ * @details This asynchronous function starts the transmission of a series of

+ *          idle words on the SPI bus and ignores the received data.

+ * @post    At the end of the operation the configured callback is invoked.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

  * @param[in] n         number of words to be ignored

@@ -382,14 +395,16 @@ void spi_lld_ignore(SPIDriver *spip, size_t n) {
                   spip->spd_dmaccr | DMA_CCR1_TCIE);

   dmaChannelSetup(spip->spd_dmatx, n, &dummytx,

                   spip->spd_dmaccr | DMA_CCR1_DIR);

-  spi_start_wait(spip);

+  dma_start(spip);

 }

 

 /**

  * @brief   Exchanges data on the SPI bus.

- * @details This function performs a simultaneous transmit/receive operation.

- * @note The buffers are organized as uint8_t arrays for data sizes below or

- *       equal to 8 bits else it is organized as uint16_t arrays.

+ * @details This asynchronous function starts a simultaneous transmit/receive

+ *          operation.

+ * @post    At the end of the operation the configured callback is invoked.

+ * @note    The buffers are organized as uint8_t arrays for data sizes below or

+ *          equal to 8 bits else it is organized as uint16_t arrays.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

  * @param[in] n         number of words to be exchanged

@@ -405,11 +420,13 @@ void spi_lld_exchange(SPIDriver *spip, size_t n,
                   spip->spd_dmaccr | DMA_CCR1_TCIE | DMA_CCR1_MINC);

   dmaChannelSetup(spip->spd_dmatx, n, txbuf,

                   spip->spd_dmaccr | DMA_CCR1_DIR | DMA_CCR1_MINC);

-  spi_start_wait(spip);

+  dma_start(spip);

 }

 

 /**

- * @brief   Sends data ever the SPI bus.

+ * @brief   Sends data over the SPI bus.

+ * @details This asynchronous function starts a transmit operation.

+ * @post    At the end of the operation the configured callback is invoked.

  * @note    The buffers are organized as uint8_t arrays for data sizes below or

  *          equal to 8 bits else it is organized as uint16_t arrays.

  *

@@ -426,11 +443,13 @@ void spi_lld_send(SPIDriver *spip, size_t n, const void *txbuf) {
                   spip->spd_dmaccr | DMA_CCR1_TCIE);

   dmaChannelSetup(spip->spd_dmatx, n, txbuf,

                   spip->spd_dmaccr | DMA_CCR1_DIR | DMA_CCR1_MINC);

-  spi_start_wait(spip);

+  dma_start(spip);

 }

 

 /**

  * @brief   Receives data from the SPI bus.

+ * @details This asynchronous function starts a receive operation.

+ * @post    At the end of the operation the configured callback is invoked.

  * @note    The buffers are organized as uint8_t arrays for data sizes below or

  *          equal to 8 bits else it is organized as uint16_t arrays.

  *

@@ -447,7 +466,7 @@ void spi_lld_receive(SPIDriver *spip, size_t n, void *rxbuf) {
                   spip->spd_dmaccr | DMA_CCR1_TCIE | DMA_CCR1_MINC);

   dmaChannelSetup(spip->spd_dmatx, n, &dummytx,

                   spip->spd_dmaccr | DMA_CCR1_DIR);

-  spi_start_wait(spip);

+  dma_start(spip);

 }

 

 #endif /* CH_HAL_USE_SPI */

diff --git a/os/hal/platforms/STM32/spi_lld.h b/os/hal/platforms/STM32/spi_lld.h
index 4989712a9..fcca37c27 100644
--- a/os/hal/platforms/STM32/spi_lld.h
+++ b/os/hal/platforms/STM32/spi_lld.h
@@ -161,45 +161,90 @@
 /*===========================================================================*/

 

 /**

- * @brief Driver configuration structure.

+ * @brief   Type of a structure representing an SPI driver.

+ */

+typedef struct SPIDriver SPIDriver;

+

+/**

+ * @brief   SPI notification callback type.

+ *

+ * @param[in] spip      pointer to the @p SPIDriver object triggering the

+ *                      callback

+ */

+typedef void (*spicallback_t)(SPIDriver *spip);

+

+/**

+ * @brief   Driver configuration structure.

  */

 typedef struct {

-  /** @brief The chip select line port.*/

+  /**

+   * @brief Operation complete callback.

+   */

+  spicallback_t         spc_endcb;

+  /* End of the mandatory fields.*/

+  /**

+   * @brief The chip select line port.

+   */

   ioportid_t            spc_ssport;

-  /** @brief The chip select line pad number.*/

+  /**

+   * @brief The chip select line pad number.

+   */

   uint16_t              spc_sspad;

-  /** @brief SPI initialization data.*/

+  /**

+   * @brief SPI initialization data.

+   */

   uint16_t              spc_cr1;

 } SPIConfig;

 

 /**

- * @brief Structure representing a SPI driver.

+ * @brief   Structure representing a SPI driver.

  */

-typedef struct {

-  /** @brief Driver state.*/

+struct SPIDriver{

+  /**

+   * @brief Driver state.

+   */

   spistate_t            spd_state;

+#if SPI_USE_WAIT || defined(__DOXYGEN__)

+  /**

+   * @brief Waiting thread.

+   */

+  Thread                *spd_thread;

+#endif /* SPI_USE_WAIT */

 #if SPI_USE_MUTUAL_EXCLUSION || defined(__DOXYGEN__)

 #if CH_USE_MUTEXES || defined(__DOXYGEN__)

-  /** @brief Mutex protecting the bus.*/

+  /**

+   * @brief Mutex protecting the bus.

+   */

   Mutex                 spd_mutex;

 #elif CH_USE_SEMAPHORES

   Semaphore             spd_semaphore;

 #endif

 #endif /* SPI_USE_MUTUAL_EXCLUSION */

-  /** @brief Current configuration data.*/

+  /**

+   * @brief Current configuration data.

+   */

   const SPIConfig       *spd_config;

+#if defined(SPI_DRIVER_EXT_FIELDS)

+  SPI_DRIVER_EXT_FIELDS

+#endif

   /* End of the mandatory fields.*/

-  /** @brief Thread waiting for I/O completion.*/

-  Thread                *spd_thread;

-  /** @brief Pointer to the SPIx registers block.*/

+  /**

+   * @brief Pointer to the SPIx registers block.

+   */

   SPI_TypeDef           *spd_spi;

-  /** @brief Pointer to the receive DMA channel registers block.*/

+  /**

+   * @brief Pointer to the receive DMA channel registers block.

+   */

   stm32_dma_channel_t   *spd_dmarx;

-  /** @brief Pointer to the transmit DMA channel registers block.*/

+  /**

+   * @brief Pointer to the transmit DMA channel registers block.

+   */

   stm32_dma_channel_t   *spd_dmatx;

-  /** @brief DMA priority bit mask.*/

+  /**

+   * @brief DMA priority bit mask.\

+   */

   uint32_t              spd_dmaccr;

-} SPIDriver;

+};

 

 /*===========================================================================*/

 /* Driver macros.                                                            */

diff --git a/os/hal/platforms/STM32/uart_lld.h b/os/hal/platforms/STM32/uart_lld.h
index 7cac040ce..7af1cc32c 100644
--- a/os/hal/platforms/STM32/uart_lld.h
+++ b/os/hal/platforms/STM32/uart_lld.h
@@ -198,24 +198,42 @@ typedef void (*uartecb_t)(UARTDriver *uartp, uartflags_t e);
  * @note    It could be empty on some architectures.

  */

 typedef struct {

-  /** @brief End of transmission buffer callback.*/

+  /**

+   * @brief End of transmission buffer callback.

+   */

   uartcb_t                  uc_txend1;

-  /** @brief Physical end of transmission callback.*/

+  /**

+   * @brief Physical end of transmission callback.

+   */

   uartcb_t                  uc_txend2;

-  /** @brief Receive buffer filled callback.*/

+  /**

+   * @brief Receive buffer filled callback.

+   */

   uartcb_t                  uc_rxend;

-  /** @brief Character received while out if the @p UART_RECEIVE state.*/

-  uartccb_t                 uc_rxchar;

-  /** @brief Receive error callback.*/  

-  uartecb_t                 uc_rxerr;

+  /**

+   * @brief Character received while out if the @p UART_RECEIVE state.

+   */

+  uartcb_t                  uc_rxchar;

+  /**

+   * @brief Receive error callback.

+   */

+  uartcb_t                  uc_rxerr;

   /* End of the mandatory fields.*/

-  /** @brief Bit rate.*/

+  /**

+   * @brief Bit rate.

+   */

   uint32_t                  uc_speed;

-  /** @brief Initialization value for the CR1 register.*/

+  /**

+   * @brief Initialization value for the CR1 register.

+   */

   uint16_t                  uc_cr1;

-  /** @brief Initialization value for the CR2 register.*/

+  /**

+   * @brief Initialization value for the CR2 register.

+   */

   uint16_t                  uc_cr2;

-  /** @brief Initialization value for the CR3 register.*/

+  /**

+   * @brief Initialization value for the CR3 register.

+   */

   uint16_t                  uc_cr3;

 } UARTConfig;

 

@@ -223,31 +241,49 @@ typedef struct {
  * @brief   Structure representing an UART driver.

  */

 struct UARTDriver {

-  /** @brief Driver state.*/

+  /**

+   * @brief Driver state.

+   */

   uartstate_t               ud_state;

-  /** @brief Current configuration data.*/

-  const UARTConfig          *ud_config;

-  /** @brief Transmitter state.*/

+  /**

+   * @brief Transmitter state.

+   */

   uarttxstate_t             ud_txstate;

-  /** @brief Receiver state.*/

+  /**

+   * @brief Receiver state.

+   */

   uartrxstate_t             ud_rxstate;

-  /** @brief UART driver status flags.*/

-  uartflags_t               ud_flags;

+  /**

+   * @brief Current configuration data.

+   */

+  const UARTConfig          *ud_config;

 #if defined(UART_DRIVER_EXT_FIELDS)

   UART_DRIVER_EXT_FIELDS

 #endif

   /* End of the mandatory fields.*/

-  /** @brief Pointer to the USART registers block.*/

+  /**

+   * @brief Pointer to the USART registers block.

+   */

   USART_TypeDef             *ud_usart;

-  /** @brief Pointer to the DMA registers block.*/

+  /**

+   * @brief Pointer to the DMA registers block.

+   */

   stm32_dma_t               *ud_dmap;

-  /** @brief DMA priority bit mask.*/

+  /**

+   * @brief DMA priority bit mask.

+   */

   uint32_t                  ud_dmaccr;

-  /** @brief Receive DMA channel.*/

+  /**

+   * @brief Receive DMA channel.

+   */

   uint8_t                   ud_dmarx;

-  /** @brief Transmit DMA channel.*/

+  /**

+   * @brief Transmit DMA channel.

+   */

   uint8_t                   ud_dmatx;

-  /** @brief Default receive buffer while into @p UART_RX_IDLE state.*/

+  /**

+   * @brief Default receive buffer while into @p UART_RX_IDLE state.

+   */

   volatile uint16_t         ud_rxbuf;

 };

 

diff --git a/os/hal/src/i2c.c b/os/hal/src/i2c.c
index 1a55f53cd..7558d6741 100644
--- a/os/hal/src/i2c.c
+++ b/os/hal/src/i2c.c
@@ -65,8 +65,11 @@ void i2cInit(void) {
  */

 void i2cObjectInit(I2CDriver *i2cp) {

 

-  i2cp->i2c_state    = I2C_STOP;

-  i2cp->i2c_config   = NULL;

+  i2cp->i2c_state  = I2C_STOP;

+  i2cp->i2c_config = NULL;

+#if defined(I2C_DRIVER_EXT_INIT_HOOK)

+  I2C_DRIVER_EXT_INIT_HOOK(i2cp);

+#endif

 }

 

 /**

diff --git a/os/hal/src/pwm.c b/os/hal/src/pwm.c
index f4af775e3..978149ff6 100644
--- a/os/hal/src/pwm.c
+++ b/os/hal/src/pwm.c
@@ -67,6 +67,9 @@ void pwmObjectInit(PWMDriver *pwmp) {
 

   pwmp->pd_state    = PWM_STOP;

   pwmp->pd_config   = NULL;

+#if defined(PWM_DRIVER_EXT_INIT_HOOK)

+  PWM_DRIVER_EXT_INIT_HOOK(pwmp);

+#endif

 }

 

 /**

diff --git a/os/hal/src/spi.c b/os/hal/src/spi.c
index 75589c736..414eb61db 100644
--- a/os/hal/src/spi.c
+++ b/os/hal/src/spi.c
@@ -77,6 +77,10 @@ void spiObjectInit(SPIDriver *spip) {
 #endif

 #endif /* SPI_USE_MUTUAL_EXCLUSION */

   spip->spd_config = NULL;

+  /* Optional, user-defined initializer.*/

+#if defined(SPI_DRIVER_EXT_INIT_HOOK)

+  SPI_DRIVER_EXT_INIT_HOOK(spip);

+#endif

 }

 

 /**

@@ -165,9 +169,10 @@ void spiUnselect(SPIDriver *spip) {
 /**

  * @brief   Emits a train of clock pulses on the SPI bus.

  * @details This asynchronous function starts the emission of a train of

- *          clock pulses without asserting any slave, while this is not

- *          usually required by the SPI protocol it is required by

- *          initialization procedure of MMC/SD cards in SPI mode.

+ *          clock pulses without asserting any slave.

+ * @note    This functionality is not usually required by the SPI protocol

+ *          but it is required by initialization procedure of MMC/SD cards

+ *          in SPI mode.

  * @post    At the end of the operation the configured callback is invoked.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

@@ -179,13 +184,12 @@ void spiUnselect(SPIDriver *spip) {
  */

 void spiSynchronize(SPIDriver *spip, size_t n) {

 

-  chDbgCheck((spip != NULL) && (n > 0), "spiIgnore");

+  chDbgCheck((spip != NULL) && (n > 0), "spiSynchronize");

 

   chSysLock();

   chDbgAssert(spip->spd_state == SPI_READY,

               "spiSynchronize(), #1",

               "not ready");

-

   spiSynchronizeI(spip, n);

   chSysUnlock();

 }

@@ -240,7 +244,7 @@ void spiExchange(SPIDriver *spip, size_t n, const void *txbuf, void *rxbuf) {
   chSysLock();

   chDbgAssert(spip->spd_state == SPI_SELECTED,

               "spiExchange(), #1",

-              "not active");

+              "not selected");

   spiExchangeI(spip, n, txbuf, rxbuf);

   chSysUnlock();

 }

@@ -268,7 +272,7 @@ void spiSend(SPIDriver *spip, size_t n, const void *txbuf) {
   chSysLock();

   chDbgAssert(spip->spd_state == SPI_SELECTED,

               "spiSend(), #1",

-              "not active");

+              "not selected");

   spiSendI(spip, n, txbuf);

   chSysUnlock();

 }

@@ -296,45 +300,28 @@ void spiReceive(SPIDriver *spip, size_t n, void *rxbuf) {
   chSysLock();

   chDbgAssert(spip->spd_state == SPI_SELECTED,

               "spiReceive(), #1",

-              "not active");

+              "not selected");

   spiReceiveI(spip, n, rxbuf);

   chSysUnlock();

 }

 

 #if SPI_USE_WAIT || defined(__DOXYGEN__)

 /**

- * @brief   Awakens the thread waiting for operation completion, if any.

- *

- * @param[in] spip      pointer to the @p SPIDriver object

- *

- * @notapi
- */

-void _spi_wakeup(SPIDriver *spip) {

-

-  if (spip->spd_thread != NULL) {

-    Thread *tp = spip->spd_thread;

-    spip->spd_thread = NULL;

-    tp->p_u.rdymsg = RDY_RESET;

-    chSchReadyI(tp);

-  }

-}

-

-/**

- * @brief   Wait for operation completion.

+ * @brief   Waits for operation completion.

  * @details This function waits for the driver to complete the current

  *          operation, if an operation is not running when the function is

  *          invoked then it immediately returns.

+ * @pre     In order to use this function the option @p SPI_USE_WAIT must be

+ *          enabled.

+ * @post    On exit the SPI driver is ready to accept more commands.

  * @note    No more than one thread can wait on a SPI driver using

  *          this function.

- *
+ *

  * @param[in] spip      pointer to the @p SPIDriver object

- * @return              The wait status.

- * @retval RDY_OK       There was not operation running when the function

- *                      has been invoked.

- * @retval RDY_RESET    The operation completed.

+ *

+ * @api

  */

-msg_t spiWait(SPIDriver *spip) {

-  msg_t msg;

+void spiWait(SPIDriver *spip) {

 

   chDbgCheck(spip != NULL, "spiWait");

 

@@ -343,20 +330,167 @@ msg_t spiWait(SPIDriver *spip) {
               (spip->spd_state == SPI_SELECTED) ||

               (spip->spd_state == SPI_ACTIVE) ||

               (spip->spd_state == SPI_SYNC),

-              "spiUnselect(), #1",

+              "spiWait(), #1",

               "invalid state");

-  chDbgAssert(spip->spd_thread == NULL, "spiWait(), #3", "already waiting");

-  if ((spip->spd_state == SPI_ACTIVE) || (spip->spd_state == SPI_SYNC)) {

-    spip->spd_thread = chThdSelf();

-    chSchGoSleepS(spip->spd_thread, THD_STATE_SUSPENDED);

-    msg = chThdSelf()->p_u.rdymsg;

-  }

-  else

-    msg = RDY_OK;

+  if ((spip->spd_state == SPI_ACTIVE) || (spip->spd_state == SPI_SYNC))

+    spiWaitS(spip);

+  chSysUnlock();

+}

+

+/**

+ * @brief   Emits a train of clock pulses on the SPI bus.

+ * @details This synchronous function performs the emission of a train of

+ *          clock pulses without asserting any slave.

+ * @pre     In order to use this function the option @p SPI_USE_WAIT must be

+ *          enabled.

+ * @post    At the end of the operation the configured callback is invoked.

+ * @note    This functionality is not usually required by the SPI protocol

+ *          but it is required by initialization procedure of MMC/SD cards

+ *          in SPI mode.

+ *

+ * @param[in] spip      pointer to the @p SPIDriver object

+ * @param[in] n         number of words to be clocked. The number of pulses

+ *                      is equal to the number of words multiplied to the

+ *                      configured word size in bits.

+ *

+ * @api

+ */

+void spiSynchronizeWait(SPIDriver *spip, size_t n) {

+

+  chDbgCheck((spip != NULL) && (n > 0), "spiSynchronizeWait");

+

+  chSysLock();

+  chDbgAssert(spip->spd_state == SPI_READY,

+              "spiSynchronizeWait(), #1",

+              "not ready");

+  spiSynchronizeI(spip, n);

+  spiWaitS(spip);

   chSysUnlock();

-  return msg;

 }

 

+/**

+ * @brief   Ignores data on the SPI bus.

+ * @details This synchronous function performs the transmission of a series of

+ *          idle words on the SPI bus and ignores the received data.

+ * @pre     A slave must have been selected using @p spiSelect() or

+ *          @p spiSelectI().

+ * @pre     In order to use this function the option @p SPI_USE_WAIT must be

+ *          enabled.

+ * @post    At the end of the operation the configured callback is invoked.

+ *

+ * @param[in] spip      pointer to the @p SPIDriver object

+ * @param[in] n         number of words to be ignored

+ *

+ * @api

+ */

+void spiIgnoreWait(SPIDriver *spip, size_t n) {

+

+  chDbgCheck((spip != NULL) && (n > 0), "spiIgnoreWait");

+

+  chSysLock();

+  chDbgAssert(spip->spd_state == SPI_SELECTED,

+              "spiIgnoreWait(), #1",

+              "not selected");

+  spiIgnoreI(spip, n);

+  spiWaitS(spip);

+  chSysUnlock();

+}

+

+/**

+ * @brief   Exchanges data on the SPI bus.

+ * @details This synchronous function performs a simultaneous transmit/receive

+ *          operation.

+ * @pre     A slave must have been selected using @p spiSelect() or

+ *          @p spiSelectI().

+ * @pre     In order to use this function the option @p SPI_USE_WAIT must be

+ *          enabled.

+ * @post    At the end of the operation the configured callback is invoked.

+ * @note    The buffers are organized as uint8_t arrays for data sizes below

+ *          or equal to 8 bits else it is organized as uint16_t arrays.

+ *

+ * @param[in] spip      pointer to the @p SPIDriver object

+ * @param[in] n         number of words to be exchanged

+ * @param[in] txbuf     the pointer to the transmit buffer

+ * @param[out] rxbuf    the pointer to the receive buffer

+ *

+ * @api

+ */

+void spiExchangeWait(SPIDriver *spip, size_t n,

+                     const void *txbuf, void *rxbuf) {

+

+  chDbgCheck((spip != NULL) && (n > 0) && (rxbuf != NULL) && (txbuf != NULL),

+             "spiExchangeWait");

+

+  chSysLock();

+  chDbgAssert(spip->spd_state == SPI_SELECTED,

+              "spiExchangeWait(), #1",

+              "not selected");

+  spiExchangeI(spip, n, txbuf, rxbuf);

+  spiWaitS(spip);

+  chSysUnlock();

+}

+

+/**

+ * @brief   Sends data over the SPI bus.

+ * @details This synchronous function performs a transmit operation.

+ * @pre     A slave must have been selected using @p spiSelect() or

+ *          @p spiSelectI().

+ * @pre     In order to use this function the option @p SPI_USE_WAIT must be

+ *          enabled.

+ * @post    At the end of the operation the configured callback is invoked.

+ * @note    The buffers are organized as uint8_t arrays for data sizes below

+ *          or equal to 8 bits else it is organized as uint16_t arrays.

+ *

+ * @param[in] spip      pointer to the @p SPIDriver object

+ * @param[in] n         number of words to send

+ * @param[in] txbuf     the pointer to the transmit buffer

+ *

+ * @api

+ */

+void spiSendWait(SPIDriver *spip, size_t n, const void *txbuf) {

+

+  chDbgCheck((spip != NULL) && (n > 0) && (txbuf != NULL),

+             "spiSendWait");

+

+  chSysLock();

+  chDbgAssert(spip->spd_state == SPI_SELECTED,

+              "spiSendWait(), #1",

+              "not selected");

+  spiSendI(spip, n, txbuf);

+  spiWaitS(spip);

+  chSysUnlock();

+}

+

+/**

+ * @brief   Receives data from the SPI bus.

+ * @details This synchronous function performs a receive operation.

+ * @pre     A slave must have been selected using @p spiSelect() or

+ *          @p spiSelectI().

+ * @pre     In order to use this function the option @p SPI_USE_WAIT must be

+ *          enabled.

+ * @post    At the end of the operation the configured callback is invoked.

+ * @note    The buffers are organized as uint8_t arrays for data sizes below

+ *          or equal to 8 bits else it is organized as uint16_t arrays.

+ *

+ * @param[in] spip      pointer to the @p SPIDriver object

+ * @param[in] n         number of words to receive

+ * @param[out] rxbuf    the pointer to the receive buffer

+ *

+ * @api

+ */

+void spiReceiveWait(SPIDriver *spip, size_t n, void *rxbuf) {

+

+  chDbgCheck((spip != NULL) && (n > 0) && (rxbuf != NULL),

+             "spiReceiveWait");

+

+  chSysLock();

+  chDbgAssert(spip->spd_state == SPI_SELECTED,

+              "spiReceiveWait(), #1",

+              "not selected");

+  spiReceiveI(spip, n, rxbuf);

+  spiWaitS(spip);

+  chSysUnlock();

+}

 #endif /* SPI_USE_WAIT */

 

 #if SPI_USE_MUTUAL_EXCLUSION || defined(__DOXYGEN__)

diff --git a/os/hal/src/uart.c b/os/hal/src/uart.c
index e984655d4..a2b21f6c8 100644
--- a/os/hal/src/uart.c
+++ b/os/hal/src/uart.c
@@ -69,6 +69,10 @@ void uartObjectInit(UARTDriver *uartp) {
   uartp->ud_txstate = UART_TX_IDLE;

   uartp->ud_rxstate = UART_RX_IDLE;

   uartp->ud_config  = NULL;

+  /* Optional, user-defined initializer.*/

+#if defined(UART_DRIVER_EXT_INIT_HOOK)

+  UART_DRIVER_EXT_INIT_HOOK(uartp);

+#endif

 }

 

 /**

diff --git a/os/hal/templates/halconf.h b/os/hal/templates/halconf.h
index 321fa3830..dda173a31 100644
--- a/os/hal/templates/halconf.h
+++ b/os/hal/templates/halconf.h
@@ -35,11 +35,6 @@
 #ifndef _HALCONF_H_

 #define _HALCONF_H_

 

-/*

- * Enable the following line in order to include a mcu-related

- * settings file. This file can be used to include platform specific

- * header files or to override the low level drivers settings.

- */

 #include "mcuconf.h"

 

 /*===========================================================================*/

@@ -154,7 +149,16 @@
 #endif

 

 /**

- * @brief   Enables the mutual exclusion APIs on the SPI bus.

+ * @brief   Enables the "wait" APIs.

+ * @note    Disabling this option saves both code and data space.

+ */

+#if !defined(SPI_USE_WAIT) || defined(__DOXYGEN__)

+#define SPI_USE_WAIT                TRUE

+#endif

+

+/**

+ * @brief   Enables the @p spiAcquireBus() and @p spiReleaseBus() APIs.

+ * @note    Disabling this option saves both code and data space.

  */

 #if !defined(SPI_USE_MUTUAL_EXCLUSION) || defined(__DOXYGEN__)

 #define SPI_USE_MUTUAL_EXCLUSION    TRUE

diff --git a/os/hal/templates/spi_lld.c b/os/hal/templates/spi_lld.c
index 19af51488..d2a9f9557 100644
--- a/os/hal/templates/spi_lld.c
+++ b/os/hal/templates/spi_lld.c
@@ -110,9 +110,9 @@ void spi_lld_unselect(SPIDriver *spip) {
 

 /**

  * @brief   Ignores data on the SPI bus.

- * @details This function transmits a series of idle words on the SPI bus and

- *          ignores the received data. This function can be invoked even

- *          when a slave select signal has not been yet asserted.

+ * @details This asynchronous function starts the transmission of a series of

+ *          idle words on the SPI bus and ignores the received data.

+ * @post    At the end of the operation the configured callback is invoked.

  *

  * @param[in] spip      pointer to the @p SPIDriver object

  * @param[in] n         number of words to be ignored

@@ -125,7 +125,9 @@ void spi_lld_ignore(SPIDriver *spip, size_t n) {
 

 /**

  * @brief   Exchanges data on the SPI bus.

- * @details This function performs a simultaneous transmit/receive operation.

+ * @details This asynchronous function starts a simultaneous transmit/receive

+ *          operation.

+ * @post    At the end of the operation the configured callback is invoked.

  * @note    The buffers are organized as uint8_t arrays for data sizes below or

  *          equal to 8 bits else it is organized as uint16_t arrays.

  *

@@ -142,7 +144,9 @@ void spi_lld_exchange(SPIDriver *spip, size_t n,
 }

 

 /**

- * @brief   Sends data ever the SPI bus.

+ * @brief   Sends data over the SPI bus.

+ * @details This asynchronous function starts a transmit operation.

+ * @post    At the end of the operation the configured callback is invoked.

  * @note    The buffers are organized as uint8_t arrays for data sizes below or

  *          equal to 8 bits else it is organized as uint16_t arrays.

  *

@@ -158,6 +162,8 @@ void spi_lld_send(SPIDriver *spip, size_t n, const void *txbuf) {
 

 /**

  * @brief   Receives data from the SPI bus.

+ * @details This asynchronous function starts a receive operation.

+ * @post    At the end of the operation the configured callback is invoked.

  * @note    The buffers are organized as uint8_t arrays for data sizes below or

  *          equal to 8 bits else it is organized as uint16_t arrays.

  *

diff --git a/os/hal/templates/spi_lld.h b/os/hal/templates/spi_lld.h
index 2aa63b455..582b56678 100644
--- a/os/hal/templates/spi_lld.h
+++ b/os/hal/templates/spi_lld.h
@@ -46,6 +46,10 @@
 /* Driver data structures and types.                                         */

 /*===========================================================================*/

 

+/**

+ * @brief   Type of a structure representing an SPI driver.

+ */

+typedef struct SPIDriver SPIDriver;

 

 /**

  * @brief   SPI notification callback type.

@@ -65,6 +69,7 @@ typedef struct {
    * @brief Operation complete callback.
    */

   spicallback_t         spc_endcb;

+  /* End of the mandatory fields.*/

 } SPIConfig;

 

 /**

@@ -72,7 +77,7 @@ typedef struct {
  * @note    Implementations may extend this structure to contain more,

  *          architecture dependent, fields.

  */

-typedef struct {

+struct SPIDriver {

   /**

    * @brief Driver state.

    */

@@ -97,8 +102,11 @@ typedef struct {
    * @brief Current configuration data.

    */

   const SPIConfig       *spd_config;

+#if defined(SPI_DRIVER_EXT_FIELDS)

+  SPI_DRIVER_EXT_FIELDS

+#endif

   /* End of the mandatory fields.*/

-} SPIDriver;

+};

 

 /*===========================================================================*/

 /* Driver macros.                                                            */

diff --git a/os/hal/templates/uart_lld.h b/os/hal/templates/uart_lld.h
index 4b80633dc..0b9a934f2 100644
--- a/os/hal/templates/uart_lld.h
+++ b/os/hal/templates/uart_lld.h
@@ -87,15 +87,25 @@ typedef void (*uartecb_t)(UARTDriver *uartp, uartflags_t e);
  *          architecture dependent, fields.

  */

 typedef struct {

-  /** @brief End of transmission buffer callback.*/

+  /**

+   * @brief End of transmission buffer callback.

+   */

   uartcb_t                  uc_txend1;

-  /** @brief Physical end of transmission callback.*/

+  /**

+   * @brief Physical end of transmission callback.

+   */

   uartcb_t                  uc_txend2;

-  /** @brief Receive buffer filled callback.*/

+  /**

+   * @brief Receive buffer filled callback.

+   */

   uartcb_t                  uc_rxend;

-  /** @brief Character received while out if the @p UART_RECEIVE state.*/

+  /**

+   * @brief Character received while out if the @p UART_RECEIVE state.

+   */

   uartcb_t                  uc_rxchar;

-  /** @brief Receive error callback.*/  

+  /**

+   * @brief Receive error callback.

+   */

   uartcb_t                  uc_rxerr;

   /* End of the mandatory fields.*/

 } UARTConfig;

diff --git a/readme.txt b/readme.txt
index b5304e069..26ac0e130 100644
--- a/readme.txt
+++ b/readme.txt
@@ -93,18 +93,24 @@
   2.0.3).

 - FIX: Fixed a documentation error regarding the ADC driver function

   adcStartConversion() (bug 3039890)(backported to 2.0.3).

-- NEW: Added an ADC_DRIVER_EXT_FIELDS macro to the ADCDriver structure

-  in order to be able to insert extra fields.

-- NEW: Added an PWM_DRIVER_EXT_FIELDS macro to the PWMDriver structure

-  in order to be able to insert extra fields.

-- NEW: Added an UART_DRIVER_EXT_FIELDS macro to the UARTDriver structure

-  in order to be able to insert extra fields.

-- NEW: More assertions added to the kernel.

-- NEW: New kernel hooks: SYSTEM_TICK_EVENT_HOOK(), SYSTEM_HALT_HOOK().

-- NEW: Added board files for the Olimex STM32-H103.

-- NEW: New kernel APIs chSysGetIdleThread() and chThdGetTicks(), the new

-  APIs are simple macros so there is no footprint overhead.

-- NEW: New I2C device driver model (not complete and no implementations yet).

+- NEW: New I2C driver model (not complete and no implementations yet).

+- NEW: New SPI driver model, the new model supports both synchronous and

+  asynchronous APIs and, in general, simplifies the implementation of the

+  low level driver. The API changed so be careful, for each old API there

+  is not a signature-equivalent one with a different name, as example the

+  old spiSend() now is named spiSendWait() because it is part of the

+  synchronous set.

+- NEW: Added pwmEnableChannelI() and pwmDisableChannelI() APIs to the PWM

+  driver in order to allow channel reprogramming from within callbacks or

+  interrupt handlers. The new APIs are implemented as macros so there is

+  no footprint overhead.

+- NEW: Added adcStartConversionI() and adcStopConversionI() APIs to the ADC

+  driver in order to allow the driver control from within callbacks or

+  interrupt handlers. Made the adcWaitConversion() API optional, this allows

+  to save some space in Flash/RAM if it is not required.

+- NEW: Added driver fields and initialization hooks for the callback-based

+  drivers. The hooks are named XXX_DRIVER_EXT_FIELDS and

+  XXX_DRIVER_EXT_INIT_HOOK().

 - NEW: Added to the UART driver the capability to return the number of

   not yet transferred frames when stopping an operation.

 - NEW: Added more compile-time checks to the various STM32 device drivers.

@@ -112,14 +118,11 @@
 - NEW: Added a simple STM32 CAN demo under ./testhal/STM32/CAN.

 - NEW: Added a simple STM32 PWM demo under ./testhal/STM32/PWM.

 - NEW: Added a simple STM32 SPI demo under ./testhal/STM32/SPI.

-- NEW: Added pwmEnableChannelI() and pwmDisableChannelI() APIs to the PWM

-  driver in order to allow channel reprogramming from within callbacks or

-  other interrupt handlers. The new APIs are implemented as macros so there

-  is no footprint overhead.

-- NEW: Added adcStartConversionI() and adcStopConversionI() APIs to the ADC

-  driver in order to allow the driver control from within callbacks or other

-  interrupt handlers. Made the adcWaitConversion() API optional, this allows

-  to save some space in Flash/RAM if it is not required.

+- NEW: More assertions added to the kernel for improved bug fixing.

+- NEW: New kernel hooks: SYSTEM_TICK_EVENT_HOOK(), SYSTEM_HALT_HOOK().

+- NEW: Added board files for the Olimex STM32-H103.

+- NEW: New kernel APIs chSysGetIdleThread() and chThdGetTicks(), the new

+  APIs are simple macros so there is no footprint overhead.

 - NEW: Added a generic BaseFileStream interface for future File System

   implementations or integrations (untested and not sure if it will stay or

   change).

@@ -130,7 +133,7 @@
   semaphores.

 - OPT: The fix to the bug 3075544 considerably improved the threads creation

   benchmarks score.

-- OPT: Speed optimizations to the STM32 SPI driver, improved latency.

+- OPT: Speed optimizations to the STM32 SPI driver, greatly improved latency.

 - OPT: Speed optimizations to the STM32 ADC driver.

 - CHANGE: The API chThdInit() has been renamed to chThdCreateI() in order to

   make clear it is usable from interrupt handlers.

diff --git a/todo.txt b/todo.txt
index 60defbe45..680db8062 100644
--- a/todo.txt
+++ b/todo.txt
@@ -14,14 +14,22 @@ Within 2.1.x (hopefully)
                 verifiable.

 * Rework STM32 drivers to use friendly IRQ names and centralized DMA macros.

 * I-class functions for the ADC/PWM drivers.

+* All the device driver structures must have a fields extension macro and

+  initializer hook.

 * All the device driver callbacks must have the driver pointer as first

   parameter.

-X All the device driver structures must have a fields extension macro.

+* Change the SPI driver to be able to work asynchronously with callbacks,

+  keep the synchronous APIs available as option.

+* Update the STM32 SPI driver.

+- Update the AT91SAM7 SPI driver.

+- Update the LPC214x SPI driver.

+- Write an SPI driver for LPC1xxx.

+- Make the ADC, I2C and UART drivers have the same "wait" semantic like

+  the new SPI driver model.

 X Resist doing more changes and optimizations in the kernel, fixes only.

 X File System infrastructure.

 X General HAL improvements.

-X I2C device driver class support.

-- Evaluate making SPI and CAN drivers callback-based.

+X I2C device driver class support and at least one implementation.

 - MAC driver for STM32F105/STM32F107 (hardware missing).

 - Device drivers for STM8 (SPI, ADC, PWM, bring it on par with STM32).

 - Support for more compilers (ARMCMx only initially).