Rename RingBuffer header functions and typedefs from RingBuff_* to RingBuffer_* so...

[pub/lufa.git] / LUFA / Drivers / Peripheral / SPI.h

diff --git a/LUFA/Drivers/Peripheral/SPI.h b/LUFA/Drivers/Peripheral/SPI.h
index df69e82..f22b6d9 100644 (file)
--- a/LUFA/Drivers/Peripheral/SPI.h
+++ b/LUFA/Drivers/Peripheral/SPI.h
@@ -3,7 +3,7 @@
      Copyright (C) Dean Camera, 2010.
 
   dean [at] fourwalledcubicle [dot] com
-      www.fourwalledcubicle.com
+           www.lufa-lib.org
 */
 
 /*
@@ -41,10 +41,33 @@
  *  The following files must be built with any user project that uses this module:
  *    - None
  *
- *  \section Module Description
+ *  \section Sec_ModDescription Module Description
  *  Driver for the hardware SPI port available on most AVR models. This module provides
  *  an easy to use driver for the setup of and transfer of data over the AVR's SPI port.
  *
+ *  \section Sec_ExampleUsage Example Usage
+ *  The following snippet is an example of how this module may be used within a typical
+ *  application.
+ *
+ *  \code
+ *      // Initialise the SPI driver before first use
+ *      SPI_Init(SPI_SPEED_FCPU_DIV_2 | SPI_ORDER_MSB_FIRST | SPI_SCK_LEAD_FALLING |
+ *               SPI_SAMPLE_TRAILING | SPI_MODE_MASTER);
+ *
+ *      // Send several bytes, ignoring the returned data
+ *      SPI_SendByte(0x01);
+ *      SPI_SendByte(0x02);
+ *      SPI_SendByte(0x03);
+ *
+ *      // Receive several bytes, sending a dummy 0x00 byte each time
+ *      uint8_t Byte1 = SPI_ReceiveByte();
+ *      uint8_t Byte2 = SPI_ReceiveByte();
+ *      uint8_t Byte3 = SPI_ReceiveByte();
+ *
+ *      // Send a byte, and store the received byte from the same transaction
+ *      uint8_t ResponseByte = SPI_TransferByte(0xDC);
+ *  \endcode
+ * 
  *  @{
  */
 
@@ -67,6 +90,8 @@
 
        /* Public Interface - May be used in end-application: */
                /* Macros: */
+                       /** \name SPI Prescaler Configuration Masks */
+                       //@{
                        /** SPI prescaler mask for SPI_Init(). Divides the system clock by a factor of 2. */
                        #define SPI_SPEED_FCPU_DIV_2           SPI_USE_DOUBLESPEED
 
@@ -87,31 +112,44 @@
 
                        /** SPI prescaler mask for SPI_Init(). Divides the system clock by a factor of 128. */
                        #define SPI_SPEED_FCPU_DIV_128         ((1 << SPR1) | (1 << SPR0))
+                       //@}
 
+                       /** \name SPI SCK Polarity Configuration Masks */
+                       //@{
                        /** SPI clock polarity mask for SPI_Init(). Indicates that the SCK should lead on the rising edge. */
                        #define SPI_SCK_LEAD_RISING            (0 << CPOL)
 
                        /** SPI clock polarity mask for SPI_Init(). Indicates that the SCK should lead on the falling edge. */
                        #define SPI_SCK_LEAD_FALLING           (1 << CPOL)
+                       //@}
 
+                       /** \name SPI Sample Edge Configuration Masks */
+                       //@{
                        /** SPI data sample mode mask for SPI_Init(). Indicates that the data should sampled on the leading edge. */
                        #define SPI_SAMPLE_LEADING             (0 << CPHA)
 
                        /** SPI data sample mode mask for SPI_Init(). Indicates that the data should be sampled on the trailing edge. */
                        #define SPI_SAMPLE_TRAILING            (1 << CPHA)
-
+                       //@}
+                       
+                       /** \name SPI Data Ordering Configuration Masks */
+                       //@{
                        /** SPI data order mask for SPI_Init(). Indicates that data should be shifted out MSB first. */
                        #define SPI_ORDER_MSB_FIRST            (0 << DORD)
 
                        /** SPI data order mask for SPI_Init(). Indicates that data should be shifted out MSB first. */
                        #define SPI_ORDER_LSB_FIRST            (1 << DORD)
-
+                       //@}
+                       
+                       /** \name SPI Mode Configuration Masks */
+                       //@{
                        /** SPI mode mask for SPI_Init(). Indicates that the SPI interface should be initialized into slave mode. */
                        #define SPI_MODE_SLAVE                 (0 << MSTR)
 
                        /** SPI mode mask for SPI_Init(). Indicates that the SPI interface should be initialized into master mode. */
                        #define SPI_MODE_MASTER                (1 << MSTR)
-
+                       //@}
+                       
                /* Inline Functions: */
                        /** Initialises the SPI subsystem, ready for transfers. Must be called before calling any other
                         *  SPI routines.