Clean up the SPI files

eriknyquist · eriknyquist · commit 331b2f0152bb · 2016-05-12T11:38:08.000-07:00
Be consistent about commenting style, and
stay below 80 chars where appropriate.
diff --git a/libraries/SPI/src/SPI.cpp b/libraries/SPI/src/SPI.cpp
@@ -13,7 +13,7 @@
 
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  *
  */
 #include "SPI.h"
@@ -48,7 +48,8 @@ void SPIClass::setDataMode(uint8_t dataMode)
 
 void SPIClass::begin()
 {
-    uint32_t flags = interrupt_lock(); // Protect from a scheduler and prevent transactionBegin
+    /* Protect from a scheduler and prevent transactionBegin*/
+    uint32_t flags = interrupt_lock();
     if (!initialized) {
         interruptMode = 0;
         interruptMask[0] = 0;
@@ -60,13 +61,14 @@ void SPIClass::begin()
         lsbFirst = false;
         frameSize = SPI_8_BIT;
 
-        // Set SS to high so a connected chip will be "deselected" by default
-        // TODO - confirm that data register is updated even if pin is set as input
+        /* Set SS to high so a connected chip will be "deselected" by default.
+         * TODO - confirm that data register is updated even if pin is set as
+         * input. */
         digitalWrite(ss_gpio, HIGH);
 
-        // When the SS pin is set as OUTPUT, it can be used as
-        // a general purpose output port (it doesn't influence
-        // SPI operations).
+        /* When the SS pin is set as OUTPUT, it can be used as
+         * a general purpose output port (it doesn't influence
+         * SPI operations). */
         pinMode(ss_gpio, OUTPUT);
 
         /* disable controller */
@@ -81,8 +83,9 @@ void SPIClass::begin()
                 (frameSize << SPI_FSIZE_SHIFT) | (SPI_MODE0 << SPI_MODE_SHIFT);
 
         /* Disable interrupts */
-        /* Enable at least one slave device (mandatory, though SS signals are unused) */
         SPI_M_REG_VAL(spi_addr, IMR) = SPI_DISABLE_INT;
+        /* Enable at least one slave device (mandatory, though
+         * SS signals are unused) */
         SPI_M_REG_VAL(spi_addr, SER) = 0x1;
         /* Enable controller */
         SPI_M_REG_VAL(spi_addr, SPIEN) |= SPI_ENABLE;
@@ -96,16 +99,17 @@ void SPIClass::begin()
         g_APinDescription[SCK].ulPinMode  = SPI_MUX_MODE;
 
     }
-    initialized++; // reference count
+    initialized++; /* reference count */
     interrupt_unlock(flags);
 }
 
 void SPIClass::end() {
-    uint32_t flags = interrupt_lock(); // Protect from a scheduler and prevent transactionBegin
-    // Decrease the reference counter
+    /* Protect from a scheduler and prevent transactionBegin */
+    uint32_t flags = interrupt_lock();
+    /* Decrease the reference counter */
     if (initialized)
         initialized--;
-    // If there are no more references disable SPI
+    /* If there are no more references disable SPI */
     if (!initialized) {
         SPI_M_REG_VAL(spi_addr, SPIEN) &= SPI_DISABLE;
         MMIO_REG_VAL(PERIPH_CLK_GATE_CTRL) &= disable_val;
@@ -142,7 +146,7 @@ void SPIClass::usingInterrupt(uint8_t interruptNumber) {
 }
 
 void SPIClass::notUsingInterrupt(uint8_t interruptNumber) {
-    // Once in mode 8 we can't go back to 0 without a proper reference count
+    /* Once in mode 8 we can't go back to 0 without a proper reference count */
     if (interruptMode == 8)
         return;
 
diff --git a/libraries/SPI/src/SPI.h b/libraries/SPI/src/SPI.h
@@ -19,24 +19,25 @@
 
 #include "SPI_registers.h"
 
-// SPI_HAS_TRANSACTION means SPI has beginTransaction(), endTransaction(),
-// usingInterrupt(), and SPISetting(clock, bitOrder, dataMode)
+/* SPI_HAS_TRANSACTION means SPI has beginTransaction(), endTransaction(),
+ * usingInterrupt(), and SPISetting(clock, bitOrder, dataMode) */
 #define SPI_HAS_TRANSACTION 1
 
-// SPI_HAS_NOTUSINGINTERRUPT means that SPI has notUsingInterrupt() method
+/* SPI_HAS_NOTUSINGINTERRUPT means that SPI has notUsingInterrupt() method */
 #define SPI_HAS_NOTUSINGINTERRUPT 1
 
-// SPI_ATOMIC_VERSION means that SPI has atomicity fixes and what version.
-// This way when there is a bug fix you can check this define to alert users
-// of your code if it uses better version of this library.
-// This also implies everything that SPI_HAS_TRANSACTION as documented above is
-// available too.
+/* SPI_ATOMIC_VERSION means that SPI has atomicity fixes and what version.
+ * This way when there is a bug fix you can check this define to alert users
+ * of your code if it uses better version of this library.
+ * This also implies everything that SPI_HAS_TRANSACTION as documented above is
+ * available too. */
 #define SPI_ATOMIC_VERSION 1
 
-// Uncomment this line to add detection of mismatched begin/end transactions.
-// A mismatch occurs if other libraries fail to use SPI.endTransaction() for
-// each SPI.beginTransaction().  Connect an LED to this pin.  The LED will turn
-// on if any mismatch is ever detected.
+/* Uncomment this line to add detection of mismatched begin/end transactions.
+ * A mismatch occurs if other libraries fail to use SPI.endTransaction() for
+ * each SPI.beginTransaction().  Connect an LED to this pin.  The LED will turn
+ * on if any mismatch is ever detected. */
+
 //#define SPI_TRANSACTION_MISMATCH_LED 5
 
 #ifndef LSBFIRST
@@ -51,10 +52,11 @@
 
 #define SPIDEV_0 0
 #define SPIDEV_1 1
-/* For Arduino Uno compatibility, divider values are doubled to provide equivalent clock rates
- * e.g. SPI_CLOCK_DIV4 will produce a 4MHz clock
- * The Intel Curie has a 32MHz base clock and a min divider of 2, so max SPI clock is 16MHz
- */
+
+/* For Arduino Uno compatibility, divider values are doubled to provide
+ * equivalent clock rates e.g. SPI_CLOCK_DIV4 will produce a 4MHz clock
+ * The Intel Curie has a 32MHz base clock and a min divider of 2, so max
+ * SPI clock is 16MHz */
 #define SPI_CLOCK_DIV4     8
 #define SPI_CLOCK_DIV16   32
 #define SPI_CLOCK_DIV64  128
@@ -69,14 +71,17 @@
 #define SPI_MODE3 0x03
 
 #define NUM_SPIDEVS 2
+
 class SPISettings {
 public:
   SPISettings(uint32_t clock, uint8_t bitOrder, uint8_t dataMode) {
     /* Set frame size, bus mode and transfer mode */
-    ctrl0 = (SPI_8_BIT << SPI_FSIZE_SHIFT) | ((dataMode << SPI_MODE_SHIFT) & SPI_MODE_MASK);
+    ctrl0 = (SPI_8_BIT << SPI_FSIZE_SHIFT)
+            | ((dataMode << SPI_MODE_SHIFT) & SPI_MODE_MASK);
     /* Set SPI Clock Divider */
     baudr = (SPI_BASE_CLOCK / clock) & SPI_CLOCK_MASK;
-    /* Only MSBFIRST supported in hardware, need to swizzle the bits if LSBFIRST selected */
+    /* Only MSBFIRST supported in hardware, need to swizzle the bits if
+     * LSBFIRST selected */
     lsbFirst = (bitOrder == LSBFIRST) ? true : false;
   }
   SPISettings() {
@@ -99,26 +104,26 @@ class SPIClass {
 	  ss_gpio = spidevs[dev][3];
   }
 
-  // Initialize the SPI library
+  /* Initialize the SPI library */
   void begin();
 
-  // If SPI is used from within an interrupt, this function registers
-  // that interrupt with the SPI library, so beginTransaction() can
-  // prevent conflicts.  The input interruptNumber is the number used
-  // with attachInterrupt.  If SPI is used from a different interrupt
-  // (eg, a timer), interruptNumber should be 255.
+  /* If SPI is used from within an interrupt, this function registers
+   * that interrupt with the SPI library, so beginTransaction() can
+   * prevent conflicts.  The input interruptNumber is the number used
+   * with attachInterrupt.  If SPI is used from a different interrupt
+   * (eg, a timer), interruptNumber should be 255. */
   void usingInterrupt(uint8_t interruptNumber);
-  // And this does the opposite.
+  /* And this does the opposite. */
   void notUsingInterrupt(uint8_t interruptNumber);
-  // Note: the usingInterrupt and notUsingInterrupt functions should
-  // not to be called from ISR context or inside a transaction.
-  // For details see:
-  // https://github.com/arduino/Arduino/pull/2381
-  // https://github.com/arduino/Arduino/pull/2449
-
-  // Before using SPI.transfer() or asserting chip select pins,
-  // this function is used to gain exclusive access to the SPI bus
-  // and configure the correct settings.
+  /* Note: the usingInterrupt and notUsingInterrupt functions should
+   * not to be called from ISR context or inside a transaction.
+   * For details see:
+   * https://github.com/arduino/Arduino/pull/2381
+   * https://github.com/arduino/Arduino/pull/2449 */
+
+  /* Before using SPI.transfer() or asserting chip select pins,
+   * this function is used to gain exclusive access to the SPI bus
+   * and configure the correct settings. */
   inline void beginTransaction(SPISettings settings) {
       if (interruptMode > 0) {
           if (interruptMode < 8) {
@@ -152,7 +157,7 @@ class SPIClass {
       SPI_M_REG_VAL(spi_addr, SPIEN) |= SPI_ENABLE;
   }
 
-  // Write to the SPI bus (MOSI pin) and also receive (MISO pin)
+  /* Write to the SPI bus (MOSI pin) and also receive (MISO pin) */
   inline uint8_t transfer(uint8_t data) {
     setFrameSize(SPI_8_BIT);
     if (lsbFirst)
@@ -217,8 +222,8 @@ class SPIClass {
       }
   }
 
-  // After performing a group of transfers and releasing the chip select
-  // signal, this function allows others to access the SPI bus
+  /* After performing a group of transfers and releasing the chip select
+   * signal, this function allows others to access the SPI bus */
   inline void endTransaction(void) {
 #ifdef SPI_TRANSACTION_MISMATCH_LED
       if (!inTransactionFlag) {
@@ -231,31 +236,35 @@ class SPIClass {
       if (interruptMode > 0) {
           if (interruptMode < 8) {
               if (interruptMode & 1)
-                  CLEAR_ARC_MASK(SS_GPIO_8B0_BASE_ADDR + SS_GPIO_INTMASK, interruptMask[0]);
+                  CLEAR_ARC_MASK(SS_GPIO_8B0_BASE_ADDR + SS_GPIO_INTMASK,
+                                  interruptMask[0]);
               if (interruptMode & 2)
-                  CLEAR_ARC_MASK(SS_GPIO_8B1_BASE_ADDR + SS_GPIO_INTMASK, interruptMask[1]);
+                  CLEAR_ARC_MASK(SS_GPIO_8B1_BASE_ADDR + SS_GPIO_INTMASK,
+                                  interruptMask[1]);
               if (interruptMode & 4)
-                  CLEAR_MMIO_MASK(SOC_GPIO_BASE_ADDR + SOC_GPIO_INTMASK,  interruptMask[2]);
+                  CLEAR_MMIO_MASK(SOC_GPIO_BASE_ADDR + SOC_GPIO_INTMASK,
+                                  interruptMask[2]);
           } else {
               interrupts();
           }	
       }
   }
 
-  // Disable the SPI bus
+  /* Disable the SPI bus */
   void end();
 
-  // This function is deprecated.  New applications should use
-  // beginTransaction() to configure SPI settings.
+  /* This function is deprecated.  New applications should use
+   * beginTransaction() to configure SPI settings. */
   inline void setBitOrder(uint8_t bitOrder) {
-    /* Only MSBFIRST supported in hardware, need to swizzle the bits if LSBFIRST selected */
+    /* Only MSBFIRST supported in hardware, need to swizzle the bits if
+     * LSBFIRST selected */
     lsbFirst = (bitOrder == LSBFIRST) ? true : false;
   }
-  // This function is deprecated.  New applications should use
-  // beginTransaction() to configure SPI settings.
+  /* This function is deprecated.  New applications should use
+   * beginTransaction() to configure SPI settings. */
   void setDataMode(uint8_t dataMode);
-  // This function is deprecated.  New applications should use
-  // beginTransaction() to configure SPI settings.
+  /* This function is deprecated.  New applications should use
+   * beginTransaction() to configure SPI settings. */
   void setClockDivider(uint8_t clockDiv);
 
 private:
@@ -264,8 +273,8 @@ class SPIClass {
   uint32_t enable_val;
   uint32_t disable_val;
   uint32_t initialized;
-  uint32_t interruptMode;    // 0=none, 1-7=mask, 8=global
-  uint32_t interruptMask[3]; // which interrupts to mask
+  uint32_t interruptMode;    /* 0=none, 1-7=mask, 8=global */
+  uint32_t interruptMask[3]; /* which interrupts to mask */
   #ifdef SPI_TRANSACTION_MISMATCH_LED
   uint32_t inTransactionFlag;
   #endif
diff --git a/libraries/SPI/src/SPI_registers.h b/libraries/SPI/src/SPI_registers.h
@@ -13,7 +13,7 @@
 
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  *
  */
 #ifndef _SPI_REGISTERS_H_
@@ -25,44 +25,47 @@
 #define SPI_M_REG_VAL(base, reg) MMIO_REG_VAL_FROM_BASE(base, (reg))
 
 /* SoC SPI device register offsets  */
-#define     CTRL0                       (0x00)              /* SoC SPI Control Register 1 */
-#define     SPIEN                       (0x08)              /* SoC SPI Enable Register */
-#define     SER                         (0x10)              /* SoC SPI Slave Enable Register */
-#define     BAUDR                       (0x14)              /* SoC SPI Baud Rate Select */
-#define     TXFL                        (0x20)              /* SoC SPI Transmit FIFO Level Register */
-#define     RXFL                        (0x24)              /* SoC SPI Receive FIFO Level Register */
-#define     SR                          (0x28)              /* SoC SPI Status Register */
-#define     IMR                         (0x2C)              /* SoC SPI Interrupt Mask Register */
-#define     DR                          (0x60)              /* SoC SPI Data Register */
+#define     CTRL0                 (0x00) /* SoC SPI Control */
+#define     SPIEN                 (0x08) /* SoC SPI Enable */
+#define     SER                   (0x10) /* SoC SPI Slave Enable */
+#define     BAUDR                 (0x14) /* SoC SPI Baud Rate Select */
+#define     TXFL                  (0x20) /* SoC SPI Transmit FIFO Level */
+#define     RXFL                  (0x24) /* SoC SPI Receive FIFO Level */
+#define     SR                    (0x28) /* SoC SPI Status Register */
+#define     IMR                   (0x2C) /* SoC SPI Interrupt Mask */
+#define     DR                    (0x60) /* SoC SPI Data */
 
 /* SPI specific macros */
-#define     SPI_DISABLE_INT             (0x0)               /* Disable SoC SPI Interrupts */
-#define     SPI_ENABLE                  (0x1)               /* Enable SoC SPI Device */
-#define     SPI_DISABLE                 (0x0)               /* Disable SoC SPI Device */
-#define     SPI_STATUS_BUSY             (0x1)               /* Busy status */
+#define     SPI_DISABLE_INT       (0x0)  /* Disable SoC SPI Interrupts */
+#define     SPI_ENABLE            (0x1)  /* Enable SoC SPI Device */
+#define     SPI_DISABLE           (0x0)  /* Disable SoC SPI Device */
+#define     SPI_STATUS_BUSY       (0x1)               /* Busy status */
 
-#define     SPI_8_BIT                   (7)                 /*  8-bit frame size */
-#define     SPI_16_BIT                  (15)                /* 16-bit frame size */
-#define     SPI_24_BIT                  (23)                /* 24-bit frame size */
-#define     SPI_32_BIT                  (31)                /* 32-bit frame size */
+#define     SPI_8_BIT             (7)    /*  8-bit frame size */
+#define     SPI_16_BIT            (15)   /* 16-bit frame size */
+#define     SPI_24_BIT            (23)   /* 24-bit frame size */
+#define     SPI_32_BIT            (31)   /* 32-bit frame size */
 
-#define     SPI_MODE_MASK               (0xC0)              /* CPOL = bit 7, CPHA = bit 6 on CTRL0 */
-#define     SPI_MODE_SHIFT              (6)
-#define     SPI_FSIZE_MASK              (0x1F0000)          /* Valid frame sizes: 1- 32 bits */
-#define     SPI_FSIZE_SHIFT             (16)
-#define     SPI_CLOCK_MASK              (0xFFFE)            /* Clock divider: any even value in the ragnge 2-65534 */
+#define     SPI_MODE_MASK         (0xC0) /* CPOL=bit 7, CPHA=bit 6 on CTRL0 */
+#define     SPI_MODE_SHIFT        (6)
+#define     SPI_FSIZE_MASK        (0x1F0000) /* Valid frame sizes: 1-32 bits */
+#define     SPI_FSIZE_SHIFT       (16)
+#define     SPI_CLOCK_MASK        (0xFFFE)  /* Clock divider: any even value
+                                             * in the ragnge 2-65534 */
 
-#define     SPI_FIFO_DEPTH              (8UL)
+#define     SPI_FIFO_DEPTH        (8UL)
 
 #define     ENABLE_SPI_MASTER_0   (0x1 << 14)
 #define     DISABLE_SPI_MASTER_0  (~ENABLE_SPI_MASTER_0)
 #define     ENABLE_SPI_MASTER_1   (0x1 << 15)
 #define     DISABLE_SPI_MASTER_1  (~ENABLE_SPI_MASTER_1)
 
-#define     SPI_BASE_CLOCK              (CLOCK_SPEED*1000*1000) /* CLOCK_SPEED in MHz */
+                                   /* CLOCK_SPEED in MHz */
+#define     SPI_BASE_CLOCK        (CLOCK_SPEED*1000*1000)
 
 /* Utility function to reverse the bit order of a 32-bit word */
-static inline uint32_t arc32_bit_reverse(register uint32_t src, register uint32_t count) 
+static inline uint32_t arc32_bit_reverse(register uint32_t src,
+                                         register uint32_t count)
 {
     register uint32_t dst = 0;
     /* Copy the specified number of least-significant bits from src to dst,
@@ -85,4 +88,4 @@ static inline uint32_t arc32_bit_reverse(register uint32_t src, register uint32_
 #define SPI_REVERSE_24(b) arc32_bit_reverse((b), 24)
 #define SPI_REVERSE_32(b) arc32_bit_reverse((b), 32)
 
-#endif // _SPI_REGISTERS_H_
+#endif /* _SPI_REGISTERS_H_ */
