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

7 files changed, 283 insertions, 94 deletions

diff --git a/ports/ARM7-LPC214x/lpc214x_serial.c b/ports/ARM7-LPC214x/lpc214x_serial.c
index 62c602dfd..e36512049 100644
--- a/ports/ARM7-LPC214x/lpc214x_serial.c
+++ b/ports/ARM7-LPC214x/lpc214x_serial.c
@@ -17,6 +17,13 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.

 */

 

+/**

+ * @file ports/ARM7-LPC214x/lpc214x_serial.c

+ * @brief LPC214x Serial driver code.

+ * @addtogroup LPC214x_SERIAL

+ * @{

+ */

+

 #include <ch.h>

 

 #include "lpc214x.h"

@@ -24,14 +31,27 @@
 #include "lpc214x_serial.h"

 #include "board.h"

 

+#if USE_LPC214x_UART0 || defined(__DOXYGEN__)

+/** @brief UART0 serial driver identifier.*/

 FullDuplexDriver COM1;

+

 static uint8_t ib1[SERIAL_BUFFERS_SIZE];

 static uint8_t ob1[SERIAL_BUFFERS_SIZE];

+#endif

 

+#if USE_LPC214x_UART1 || defined(__DOXYGEN__)

+/** @brief UART1 serial driver identifier.*/

 FullDuplexDriver COM2;

+

 static uint8_t ib2[SERIAL_BUFFERS_SIZE];

 static uint8_t ob2[SERIAL_BUFFERS_SIZE];

+#endif

 

+/**

+ * @brief Error handling routine.

+ * @param[in] err UART LSR register value

+ * @param[in] com communication channel associated to the USART

+ */

 static void SetError(IOREG32 err, FullDuplexDriver *com) {

   dflags_t sts = 0;

 

@@ -48,11 +68,16 @@ static void SetError(IOREG32 err, FullDuplexDriver *com) {
   chSysUnlockFromIsr();

 }

 

-/*

- * Tries hard to clear all the pending interrupt sources, we dont want to

- * go through the whole ISR and have another interrupt soon after.

- */

+/** @cond never*/

 __attribute__((noinline))

+/** @endcond*/

+/**

+ * @brief Common IRQ handler.

+ * @param[in] u pointer to an UART I/O block

+ * @param[in] com communication channel associated to the UART

+ * @note Tries hard to clear all the pending interrupt sources, we dont want to

+ *       go through the whole ISR and have another interrupt soon after.

+ */

 static void ServeInterrupt(UART *u, FullDuplexDriver *com) {

 

   while (TRUE) {

@@ -77,8 +102,8 @@ static void ServeInterrupt(UART *u, FullDuplexDriver *com) {
       break;

     case IIR_SRC_TX:

       {

-#ifdef FIFO_PRELOAD

-        int i = FIFO_PRELOAD;

+#if LPC214x_UART_FIFO_PRELOAD > 0

+        int i = LPC214x_UART_FIFO_PRELOAD;

         do {

           chSysLockFromIsr();

           msg_t b = chOQGetI(&com->sd_oqueue);

@@ -109,31 +134,11 @@ static void ServeInterrupt(UART *u, FullDuplexDriver *com) {
   }

 }

 

-CH_IRQ_HANDLER(UART0IrqHandler) {

-

-  CH_IRQ_PROLOGUE();

-

-  ServeInterrupt(U0Base, &COM1);

-  VICVectAddr = 0;

-

-  CH_IRQ_EPILOGUE();

-}

-

-CH_IRQ_HANDLER(UART1IrqHandler) {

-

-  CH_IRQ_PROLOGUE();

-

-  ServeInterrupt(U1Base, &COM2);

-  VICVectAddr = 0;

-

-  CH_IRQ_EPILOGUE();

-}

-

-#ifdef FIFO_PRELOAD

+#if LPC214x_UART_FIFO_PRELOAD > 0

 static void preload(UART *u, FullDuplexDriver *com) {

 

   if (u->UART_LSR & LSR_THRE) {

-    int i = FIFO_PRELOAD;

+    int i = LPC214x_UART_FIFO_PRELOAD;

     do {

       chSysLockFromIsr();

       msg_t b = chOQGetI(&com->sd_oqueue);

@@ -151,12 +156,25 @@ static void preload(UART *u, FullDuplexDriver *com) {
 }

 #endif

 

-/*

- * Invoked by the high driver when one or more bytes are inserted in the

- * output queue.

+#if USE_LPC214x_UART0 || defined(__DOXYGEN__)

+/**

+ * @brief UART0 IRQ service routine.

+ */

+CH_IRQ_HANDLER(UART0IrqHandler) {

+

+  CH_IRQ_PROLOGUE();

+

+  ServeInterrupt(U0Base, &COM1);

+  VICVectAddr = 0;

+

+  CH_IRQ_EPILOGUE();

+}

+

+/**

+ * @brief Output queue insertion notification from the high driver.

  */

 static void OutNotify1(void) {

-#ifdef FIFO_PRELOAD

+#if LPC214x_UART_FIFO_PRELOAD > 0

 

   preload(U0Base, &COM1);

 #else

@@ -170,13 +188,27 @@ static void OutNotify1(void) {
   u->UART_IER |= IER_THRE;

 #endif

 }

+#endif

 

-/*

- * Invoked by the high driver when one or more bytes are inserted in the

- * output queue.

+#if USE_LPC214x_UART1 || defined(__DOXYGEN__)

+/**

+ * @brief UART1 IRQ service routine.

+ */

+CH_IRQ_HANDLER(UART1IrqHandler) {

+

+  CH_IRQ_PROLOGUE();

+

+  ServeInterrupt(U1Base, &COM2);

+  VICVectAddr = 0;

+

+  CH_IRQ_EPILOGUE();

+}

+

+/**

+ * @brief Output queue insertion notification from the high driver.

  */

 static void OutNotify2(void) {

-#ifdef FIFO_PRELOAD

+#if LPC214x_UART_FIFO_PRELOAD > 0

 

   preload(U1Base, &COM2);

 #else

@@ -187,9 +219,15 @@ static void OutNotify2(void) {
   u->UART_IER |= IER_THRE;

 #endif

 }

+#endif

 

-/*

- * UART setup, must be invoked with interrupts disabled.

+/**

+ * @brief UART setup.

+ * @param[in] u pointer to an UART I/O block

+ * @param[in] speed serial port speed in bits per second

+ * @param[in] lcr the value for the @p LCR register

+ * @param[in] fcr the value for the @p FCR register

+ * @note Must be invoked with interrupts disabled.

  */

 void SetUART(UART *u, int speed, int lcr, int fcr) {

 

@@ -205,21 +243,37 @@ void SetUART(UART *u, int speed, int lcr, int fcr) {
   u->UART_IER = IER_RBR | IER_STATUS;

 }

 

-/*

- * Serial subsystem initialization.

+/**

+ * @brief Serial driver initialization.

+ * @param[in] vector1 IRC vector to be used for UART0

+ * @param[in] vector2 IRC vector to be used for UART1

+ * @note Handshake pads are not enabled inside this function because they

+ *       may have another use, enable them externally if needed.

+ *       RX and TX pads are handled inside.

  */

-void InitSerial(int vector1, int vector2) {

+void lpc2148x_serial_init(int vector1, int vector2) {

 

+#if USE_LPC214x_UART0

   SetVICVector(UART0IrqHandler, vector1, SOURCE_UART0);

-  SetVICVector(UART1IrqHandler, vector2, SOURCE_UART1);

-

-  PCONP = (PCONP & PCALL) | PCUART0 | PCUART1;

-

+  PCONP = (PCONP & PCALL) | PCUART0;

   chFDDInit(&COM1, ib1, sizeof ib1, NULL, ob1, sizeof ob1, OutNotify1);

-  SetUART(U0Base, 38400, LCR_WL8 | LCR_STOP1 | LCR_NOPARITY, FCR_TRIGGER0);

+  SetUART(U0Base,

+          LPC214x_UART_BITRATE,

+          LCR_WL8 | LCR_STOP1 | LCR_NOPARITY,

+          FCR_TRIGGER0);

+  VICIntEnable = INTMASK(SOURCE_UART0);

+#endif

 

+#if USE_LPC214x_UART1

+  SetVICVector(UART1IrqHandler, vector2, SOURCE_UART1);

+  PCONP = (PCONP & PCALL) | PCUART1;

   chFDDInit(&COM2, ib2, sizeof ib2, NULL, ob2, sizeof ob2, OutNotify2);

-  SetUART(U1Base, 38400, LCR_WL8 | LCR_STOP1 | LCR_NOPARITY, FCR_TRIGGER0);

-

+  SetUART(U1Base,

+          LPC214x_UART_BITRATE,

+          LCR_WL8 | LCR_STOP1 | LCR_NOPARITY,

+          FCR_TRIGGER0);

   VICIntEnable = INTMASK(SOURCE_UART0) | INTMASK(SOURCE_UART1);

+#endif

 }

+

+/** @} */

diff --git a/ports/ARM7-LPC214x/lpc214x_serial.h b/ports/ARM7-LPC214x/lpc214x_serial.h
index ce457dadf..ee60a48f4 100644
--- a/ports/ARM7-LPC214x/lpc214x_serial.h
+++ b/ports/ARM7-LPC214x/lpc214x_serial.h
@@ -17,30 +17,75 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.

 */

 

+/**

+ * @file ports/ARM7-LPC214x/lpc214x_serial.h

+ * @brief LPC214x Serial driver macros and structures.

+ * @addtogroup LPC214x_SERIAL

+ * @{

+ */

+

 #ifndef _LPC214x_SERIAL_H_

 #define _LPC214x_SERIAL_H_

 

-/*

- * Configuration parameter, this values defines how many bytes are preloaded

- * in the HW transmit FIFO for each interrupt, the maximum value is 16 the

- * minimum is 2.

- * NOTE: A greater value reduces the number of interrupts generated but can

- *       also increase the worst case interrupt response time.

- * NOTE: You can undefine the following macro and revert to a simpler code

- *       that will generate an interrupt for each output byte,

+/**

+ * @brief Serial buffers size.

+ * @details Configuration parameter, you can change the depth of the queue

+ * buffers depending on the requirements of your application.

+ * @note The default is 128 bytes for both the transmission and receive buffers.

  */

-#define FIFO_PRELOAD 16

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

+#define SERIAL_BUFFERS_SIZE 128

+#endif

 

-/*

- * Configuration parameter, you can change the depth of the queue buffers

- * depending on the requirements of your application.

+/**

+ * @brief Default bit rate.

+ * @details Configuration parameter, at startup the UARTs are configured at

+ * this speed.

+ * @note It is possible to use @p SetUART() in order to change the working

+ *       parameters at runtime.

  */

-#define SERIAL_BUFFERS_SIZE 128

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

+#define LPC214x_UART_BITRATE 38400

+#endif

+

+/**

+ * @brief FIFO preload parameter.

+ * @details Configuration parameter, this values defines how many bytes are

+ * preloaded in the HW transmit FIFO for each interrupt, the maximum value is

+ * 16 the minimum is 2, the value 0 disables the feature.

+ * @note An high value reduces the number of interrupts generated but can

+ *       also increase the worst case interrupt response time because the

+ *       preload loops.

+ * @note The value zero disables the feature and reverts to a simpler code

+ *       that will generate an interrupt for each output byte but is much

+ *       smaller and simpler.

+ */

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

+#define LPC214x_UART_FIFO_PRELOAD 16

+#endif

+

+/**

+ * @brief UART0 driver enable switch.

+ * @details If set to @p TRUE the support for USART1 is included.

+ * @note The default is @p TRUE .

+ */

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

+#define USE_LPC214x_UART0 TRUE 

+#endif

+ 

+/**

+ * @brief UART1 driver enable switch.

+ * @details If set to @p TRUE the support for USART2 is included.

+ * @note The default is @p TRUE.

+ */

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

+#define USE_LPC214x_UART1 TRUE

+#endif

 

 #ifdef __cplusplus

 extern "C" {

 #endif

-  void InitSerial(int vector1, int vector2);

+  void lpc2148x_serial_init(int vector1, int vector2);

   void SetUART(UART *u, int speed, int lcr, int fcr);

   CH_IRQ_HANDLER(UART0IrqHandler);

   CH_IRQ_HANDLER(UART1IrqHandler);

@@ -48,6 +93,10 @@ extern "C" {
 }

 #endif

 

+/** @cond never*/

 extern FullDuplexDriver COM1, COM2;

+/** @endcond*/

 

 #endif /* _LPC214x_SERIAL_H_*/

+

+/** @} */

diff --git a/ports/ARM7-LPC214x/lpc214x_ssp.c b/ports/ARM7-LPC214x/lpc214x_ssp.c
index 145badcf5..ebe29b6e7 100644
--- a/ports/ARM7-LPC214x/lpc214x_ssp.c
+++ b/ports/ARM7-LPC214x/lpc214x_ssp.c
@@ -17,38 +17,55 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.

 */

 

+/**

+ * @file ports/ARM7-LPC214x/lpc214x_ssp.c

+ * @brief LPC214x SSP driver code.

+ * @addtogroup LPC214x_SSP

+ * @{

+ */

+

 #include <ch.h>

 

 #include "lpc214x.h"

 #include "lpc214x_ssp.h"

 

-#ifdef SSP_USE_MUTEX

+#if LPC214x_SSP_USE_MUTEX

 static Semaphore me;

 #endif

 

+/**

+ * @brief Aquires access to the SSP bus.

+ * @note This function also handles the mutual exclusion on the SSP bus if

+ *       the @p LPC214x_SSP_USE_MUTEX option is enabled.

+ */

 void sspAcquireBus(void) {

 

-#ifdef SSP_USE_MUTEX

+#if LPC214x_SSP_USE_MUTEX

   chSemWait(&me);

 #endif

   IO0CLR = 1 << 20;

 }

 

+/**

+ * @brief Releases the SSP bus.

+ * @note This function also handles the mutual exclusion on the SSP bus if

+ *       the @p LPC214x_SSP_USE_MUTEX option is enabled.

+ */

 void sspReleaseBus(void) {

 

   IO0SET = 1 << 20;

-#ifdef SSP_USE_MUTEX

+#if LPC214x_SSP_USE_MUTEX

   chSemSignal(&me);

 #endif

 }

 

-/*

- * Synchronous SSP transfer.

- * @param in pointer to the incoming data buffer, if this parameter is set to

- *           \p NULL then the incoming data is discarded.

- * @param out pointer to the outgoing data buffer, if this parameter is set to

- *           \p NULL then 0xFF bytes will be output.

- * @param n the number of bytes to be transferred

+/**

+ * @brief Synchronous SSP transfer.

+ * @param[in] in pointer to the incoming data buffer, if this parameter is set

+ *               to @p NULL then the incoming data is discarded

+ * @param[out] out pointer to the outgoing data buffer, if this parameter is

+ *                 set to @p NULL then 0xFF bytes will be output

+ * @param[in] n the number of bytes to be transferred

  * @note The transfer is performed in a software loop and is not interrupt

  *       driven for performance reasons, this function should be invoked

  *       by a low priority thread in order to "play nice" with the

@@ -81,10 +98,13 @@ void sspRW(uint8_t *in, uint8_t *out, size_t n) {
   }

 }

 

-/*

- * SSP setup.

+/**

+ * @brief SSP setup.

+ * @param[in] cpsr the value for the @p CPSR register

+ * @param[in] cr0 the value for the @p CR0 register

+ * @param[in] cr1 the value for the @p CR1 register

  */

-void SetSSP(int cpsr, int cr0, int cr1) {

+void lpc214x_ssp_setup(int cpsr, int cr0, int cr1) {

 

   SSP *ssp = SSPBase;

   ssp->SSP_CR1 = 0;

@@ -93,18 +113,20 @@ void SetSSP(int cpsr, int cr0, int cr1) {
   ssp->SSP_CR1 = cr1 | CR1_SSE;

 }

 

-/*

- * SSP subsystem initialization.

+/**

+ * @brief SSP subsystem initialization.

  */

-void InitSSP(void) {

+void lpc214x_ssp_init(void) {

 

   /* Enables the SPI1 clock */

   PCONP = (PCONP & PCALL) | PCSPI1;

 

   /* Clock = PCLK / 2 (fastest). */

-  SetSSP(2, CR0_DSS8BIT | CR0_FRFSPI | CR0_CLOCKRATE(0), 0);

+  lpc214x_ssp_setup(2, CR0_DSS8BIT | CR0_FRFSPI | CR0_CLOCKRATE(0), 0);

 

-#ifdef SSP_USE_MUTEX

+#if LPC214x_SSP_USE_MUTEX

   chSemInit(&me, 1);

 #endif

 }

+

+/** @} */

diff --git a/ports/ARM7-LPC214x/lpc214x_ssp.h b/ports/ARM7-LPC214x/lpc214x_ssp.h
index 55929c2d8..411ef5016 100644
--- a/ports/ARM7-LPC214x/lpc214x_ssp.h
+++ b/ports/ARM7-LPC214x/lpc214x_ssp.h
@@ -17,21 +17,32 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.

 */

 

+/**

+ * @file ports/ARM7-LPC214x/lpc214x_ssp.h

+ * @brief LPC214x SSP driver macros and structures.

+ * @addtogroup LPC214x_SSP

+ * @{

+ */

+

 #ifndef _LPC214x_SSP_H_

 #define _LPC214x_SSP_H_

 

-/*

- * Configuration parameter, if defined this macro enforces mutual exclusion

- * when invoking \p sspAcquireBus() and \p sspReleaseBus().

+/**

+ * @brief SSP bus mutual exclusion control.

+ * @details Configuration parameter, if defined this macro enforces mutual

+ * exclusion when invoking @p sspAcquireBus() and @p sspReleaseBus().

+ * @note The internally used synchronization mechanism is a @p Semaphore.

+ * @todo Make it use Mutexes or Semaphores like the Heap subsystem.

  */

-#define SSP_USE_MUTEX

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

+#define LPC214x_SSP_USE_MUTEX TRUE

+#endif

 

 #ifdef __cplusplus

 }

 #endif

-  void InitSSP(void);

-  void SetSSP(int cpsr, int cr0, int cr1);

-

+  void lpc214x_ssp_init(void);

+  void lpc214x_ssp_setup(int cpsr, int cr0, int cr1);

   void sspAcquireBus(void);

   void sspReleaseBus(void);

   void sspRW(uint8_t *in, uint8_t *out, size_t n);

@@ -40,3 +51,5 @@
 #endif

 

 #endif /* _LPC214x_SSP_H_*/

+

+/** @} */

diff --git a/ports/ARM7-LPC214x/port.dox b/ports/ARM7-LPC214x/port.dox
index 5d7a4a591..efffe45c0 100644
--- a/ports/ARM7-LPC214x/port.dox
+++ b/ports/ARM7-LPC214x/port.dox
@@ -15,3 +15,32 @@
  * @ingroup ARM7

  */

 /** @} */

+

+/**

+ * @defgroup LPC214x_VIC VIC Support

+ * @{

+ * @brief VIC peripheral support.

+ *

+ * @ingroup LPC214x

+ */

+/** @} */

+

+/**

+ * @defgroup LPC214x_SERIAL UART Support

+ * @{

+ * @brief UART peripherals support.

+ * @details The serial driver supports the LPC214x UART peripherals.

+ *

+ * @ingroup LPC214x

+ */

+/** @} */

+

+/**

+ * @defgroup LPC214x_SSP SSP Support

+ * @{

+ * @brief SSP peripheral support.

+ * @details This SPI driver supports the LPC214x SSP peripheral.

+ *

+ * @ingroup LPC214x

+ */

+/** @} */

diff --git a/ports/ARM7-LPC214x/vic.c b/ports/ARM7-LPC214x/vic.c
index 969c4aa3b..739a259c1 100644
--- a/ports/ARM7-LPC214x/vic.c
+++ b/ports/ARM7-LPC214x/vic.c
@@ -17,15 +17,22 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.

 */

 

+/**

+ * @file ports/ARM7-LPC214x/vic.c

+ * @brief LPC214x VIC peripheral support code.

+ * @addtogroup LPC214x_VIC

+ * @{

+ */

+

 #include <ch.h>

 

 #include "lpc214x.h"

 

-/*

- * VIC Initialization.

- * NOTE: Better reset everything in the VIC, it is a HUGE source of trouble.

+/**

+ * @brief VIC Initialization.

+ * @note Better reset everything in the VIC, it is a HUGE source of trouble.

  */

-void InitVIC(void) {

+void lpc214x_vic_init(void) {

   int i;

 

   VIC *vic = VICBase;

@@ -39,8 +46,12 @@ void InitVIC(void) {
   }

 }

 

-/*

- * Set a vector for an interrupt source, the vector is enabled too.

+/**

+ * @brief Initializes a VIC vector.

+ * @details Set a vector for an interrupt source and enables it.

+ * @param[in] handler the pointer to the IRQ service routine

+ * @param[in] vector the vector number

+ * @param[in] source the IRQ source to be associated to the vector

  */

 void SetVICVector(void *handler, int vector, int source) {

 

@@ -48,3 +59,5 @@ void SetVICVector(void *handler, int vector, int source) {
   vicp->VIC_VectAddrs[vector] = (IOREG32)handler;

   vicp->VIC_VectCntls[vector] = (IOREG32)(source | 0x20);

 }

+

+/** @} */

diff --git a/ports/ARM7-LPC214x/vic.h b/ports/ARM7-LPC214x/vic.h
index 2c3fdd32d..a219f4a32 100644
--- a/ports/ARM7-LPC214x/vic.h
+++ b/ports/ARM7-LPC214x/vic.h
@@ -17,16 +17,25 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.

 */

 

+/**

+ * @file ports/ARM7-LPC214x/vic.h

+ * @brief LPC214x VIC peripheral support code.

+ * @addtogroup LPC214x_VIC

+ * @{

+ */

+

 #ifndef _VIC_H_

 #define _VIC_H_

 

 #ifdef __cplusplus

 extern "C" {

 #endif

-  void InitVIC(void);

+  void lpc214x_vic_init(void);

   void SetVICVector(void *handler, int vector, int source);

 #ifdef __cplusplus

 }

 #endif

 

 #endif /* _VIC_H_ */

+

+/** @} */