X-Git-Url: http://git.linex4red.de/pub/lufa.git/blobdiff_plain/5517f96e86b9447780a3e27bb455697f9fc65eea..64fe1cd0b2be01fd7b377736a85c1bd88a5fd429:/LUFA/Drivers/Peripheral/SPI.h

diff --git a/LUFA/Drivers/Peripheral/SPI.h b/LUFA/Drivers/Peripheral/SPI.h
index df69e8214..f22b6d99a 100644
--- 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.