source: arduino-1-6-7/trunk/fuentes/arduino-ide-amd64/hardware/arduino/avr/firmwares/wifishield/wifiHD/src/SOFTWARE_FRAMEWORK/DRIVERS/SPI/spi.h @ 4837

Last change on this file since 4837 was 4837, checked in by daduve, 2 years ago

Adding new version

File size: 11.9 KB
Line 
1/* This header file is part of the ATMEL AVR-UC3-SoftwareFramework-1.7.0 Release */
2
3/*This file is prepared for Doxygen automatic documentation generation.*/
4/*! \file *********************************************************************
5 *
6 * \brief SPI driver for AVR32 UC3.
7 *
8 * This file defines a useful set of functions for the SPI interface on AVR32
9 * devices.
10 *
11 * - Compiler:           IAR EWAVR32 and GNU GCC for AVR32
12 * - Supported devices:  All AVR32 devices with an SPI module can be used.
13 * - AppNote:
14 *
15 * \author               Atmel Corporation: http://www.atmel.com \n
16 *                       Support and FAQ: http://support.atmel.no/
17 *
18 ******************************************************************************/
19
20/* Copyright (c) 2009 Atmel Corporation. All rights reserved.
21 *
22 * Redistribution and use in source and binary forms, with or without
23 * modification, are permitted provided that the following conditions are met:
24 *
25 * 1. Redistributions of source code must retain the above copyright notice, this
26 * list of conditions and the following disclaimer.
27 *
28 * 2. Redistributions in binary form must reproduce the above copyright notice,
29 * this list of conditions and the following disclaimer in the documentation
30 * and/or other materials provided with the distribution.
31 *
32 * 3. The name of Atmel may not be used to endorse or promote products derived
33 * from this software without specific prior written permission.
34 *
35 * 4. This software may only be redistributed and used in connection with an Atmel
36 * AVR product.
37 *
38 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
39 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
40 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
41 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
42 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
43 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
44 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
46 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
47 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
48 *
49 */
50
51#ifndef _SPI_H_
52#define _SPI_H_
53
54#include <avr32/io.h>
55
56
57//! Time-out value (number of attempts).
58#define SPI_TIMEOUT       10000
59
60
61//! Status codes used by the SPI driver.
62typedef enum
63{
64  SPI_ERROR = -1,
65  SPI_OK = 0,
66  SPI_ERROR_TIMEOUT = 1,
67  SPI_ERROR_ARGUMENT,
68  SPI_ERROR_OVERRUN,
69  SPI_ERROR_MODE_FAULT,
70  SPI_ERROR_OVERRUN_AND_MODE_FAULT
71} spi_status_t;
72
73//! Option structure for SPI channels.
74typedef struct
75{
76  //! The SPI channel to set up.
77  unsigned char reg;
78
79  //! Preferred baudrate for the SPI.
80  unsigned int baudrate;
81
82  //! Number of bits in each character (8 to 16).
83  unsigned char bits;
84
85  //! Delay before first clock pulse after selecting slave (in PBA clock periods).
86  unsigned char spck_delay;
87
88  //! Delay between each transfer/character (in PBA clock periods).
89  unsigned char trans_delay;
90
91  //! Sets this chip to stay active after last transfer to it.
92  unsigned char stay_act;
93
94  //! Which SPI mode to use when transmitting.
95  unsigned char spi_mode;
96
97  //! Disables the mode fault detection.
98  //! With this bit cleared, the SPI master mode will disable itself if another
99  //! master tries to address it.
100  unsigned char modfdis;
101} spi_options_t;
102
103
104/*! \brief Resets the SPI controller.
105 *
106 * \param spi Base address of the SPI instance.
107 */
108extern void spi_reset(volatile avr32_spi_t *spi);
109
110/*! \brief Initializes the SPI in slave mode.
111 *
112 * \param spi       Base address of the SPI instance.
113 * \param bits      Number of bits in each transmitted character (8 to 16).
114 * \param spi_mode  Clock polarity and phase.
115 *
116 * \return Status.
117 *   \retval SPI_OK             Success.
118 *   \retval SPI_ERROR_ARGUMENT Invalid argument(s) passed.
119 */
120extern spi_status_t spi_initSlave(volatile avr32_spi_t *spi,
121                                  unsigned char bits,
122                                  unsigned char spi_mode);
123
124/*! \brief Sets up the SPI in a test mode where the transmitter is connected to
125 *         the receiver (local loopback).
126 *
127 * \param spi Base address of the SPI instance.
128 *
129 * \return Status.
130 *   \retval SPI_OK Success.
131 */
132extern spi_status_t spi_initTest(volatile avr32_spi_t *spi);
133
134/*! \brief Initializes the SPI in master mode.
135 *
136 * \param spi     Base address of the SPI instance.
137 * \param options Pointer to a structure containing initialization options.
138 *
139 * \return Status.
140 *   \retval SPI_OK             Success.
141 *   \retval SPI_ERROR_ARGUMENT Invalid argument(s) passed.
142 */
143extern spi_status_t spi_initMaster(volatile avr32_spi_t *spi, const spi_options_t *options);
144
145/*! \brief Sets up how and when the slave chips are selected (master mode only).
146 *
147 * \param spi         Base address of the SPI instance.
148 * \param variable_ps Target slave is selected in transfer register for every
149 *                    character to transmit.
150 * \param pcs_decode  The four chip select lines are decoded externally. Values
151 *                    0 to 14 can be given to \ref spi_selectChip.
152 * \param delay       Delay in PBA periods between chip selects.
153 *
154 * \return Status.
155 *   \retval SPI_OK             Success.
156 *   \retval SPI_ERROR_ARGUMENT Invalid argument(s) passed.
157 */
158extern spi_status_t spi_selectionMode(volatile avr32_spi_t *spi,
159                                      unsigned char variable_ps,
160                                      unsigned char pcs_decode,
161                                      unsigned char delay);
162
163/*! \brief Selects slave chip.
164 *
165 * \param spi   Base address of the SPI instance.
166 * \param chip  Slave chip number (normal: 0 to 3, extarnally decoded signal: 0
167 *              to 14).
168 *
169 * \return Status.
170 *   \retval SPI_OK             Success.
171 *   \retval SPI_ERROR_ARGUMENT Invalid argument(s) passed.
172 */
173extern spi_status_t spi_selectChip(volatile avr32_spi_t *spi, unsigned char chip);
174
175/*! \brief Unselects slave chip.
176 *
177 * \param spi   Base address of the SPI instance.
178 * \param chip  Slave chip number (normal: 0 to 3, extarnally decoded signal: 0
179 *              to 14).
180 *
181 * \return Status.
182 *   \retval SPI_OK             Success.
183 *   \retval SPI_ERROR_TIMEOUT  Time-out.
184 *
185 * \note Will block program execution until time-out occurs if last transmission
186 *       is not complete. Invoke \ref spi_writeEndCheck beforehand if needed.
187 */
188extern spi_status_t spi_unselectChip(volatile avr32_spi_t *spi, unsigned char chip);
189
190/*! \brief Sets options for a specific slave chip.
191 *
192 * The baudrate field has to be written before transfer in master mode. Four
193 * similar registers exist, one for each slave. When using encoded slave
194 * addressing, reg=0 sets options for slaves 0 to 3, reg=1 for slaves 4 to 7 and
195 * so on.
196 *
197 * \param spi     Base address of the SPI instance.
198 * \param options Pointer to a structure containing initialization options for
199 *                an SPI channel.
200 * \param pba_hz  SPI module input clock frequency (PBA clock, Hz).
201 *
202 * \return Status.
203 *   \retval SPI_OK             Success.
204 *   \retval SPI_ERROR_ARGUMENT Invalid argument(s) passed.
205 */
206extern spi_status_t spi_setupChipReg(volatile avr32_spi_t *spi,
207                                     const spi_options_t *options,
208                                     unsigned int pba_hz);
209
210/*! \brief Enables the SPI.
211 *
212 * \param spi Base address of the SPI instance.
213 */
214extern void spi_enable(volatile avr32_spi_t *spi);
215
216/*! \brief Disables the SPI.
217 *
218 * Ensures that nothing is transferred while setting up buffers.
219 *
220 * \param spi Base address of the SPI instance.
221 *
222 * \warning This may cause data loss if used on a slave SPI.
223 */
224extern void spi_disable(volatile avr32_spi_t *spi);
225
226/*! \brief Tests if the SPI is enabled.
227 *
228 * \param spi Base address of the SPI instance.
229 *
230 * \return \c 1 if the SPI is enabled, otherwise \c 0.
231 */
232extern int spi_is_enabled(volatile avr32_spi_t *spi);
233
234/*! \brief Checks if there is no data in the transmit register.
235 *
236 * \param spi Base address of the SPI instance.
237 *
238 * \return Status.
239 *   \retval 1  No data in TDR.
240 *   \retval 0  Some data in TDR.
241 */
242extern unsigned char spi_writeRegisterEmptyCheck(volatile avr32_spi_t *spi);
243
244/*! \brief Writes one data word in master fixed peripheral select mode or in
245 *         slave mode.
246 *
247 * \param spi   Base address of the SPI instance.
248 * \param data  The data word to write.
249 *
250 * \return Status.
251 *   \retval SPI_OK             Success.
252 *   \retval SPI_ERROR_TIMEOUT  Time-out.
253 *
254 * \note Will block program execution until time-out occurs if transmitter is
255 *       busy and transmit buffer is full. Invoke
256 *       \ref spi_writeRegisterEmptyCheck beforehand if needed.
257 *
258 * \note Once the data has been written to the transmit buffer, the end of
259 *       transmission is not waited for. Invoke \ref spi_writeEndCheck if
260 *       needed.
261 */
262extern spi_status_t spi_write(volatile avr32_spi_t *spi, unsigned short data);
263
264/*! \brief Selects a slave in master variable peripheral select mode and writes
265 *         one data word to it.
266 *
267 * \param spi       Base address of the SPI instance.
268 * \param data      The data word to write.
269 * \param pcs       Slave selector (bit 0 -> nCS line 0, bit 1 -> nCS line 1,
270 *                  etc.).
271 * \param lastxfer  Boolean indicating whether this is the last data word
272 *                  transfer.
273 *
274 * \return Status.
275 *   \retval SPI_OK             Success.
276 *   \retval SPI_ERROR_TIMEOUT  Time-out.
277 *   \retval SPI_ERROR_ARGUMENT Invalid argument(s) passed.
278 *
279 * \note Will block program execution until time-out occurs if transmitter is
280 *       busy and transmit buffer is full. Invoke
281 *       \ref spi_writeRegisterEmptyCheck beforehand if needed.
282 *
283 * \note Once the data has been written to the transmit buffer, the end of
284 *       transmission is not waited for. Invoke \ref spi_writeEndCheck if
285 *       needed.
286 */
287extern spi_status_t spi_variableSlaveWrite(volatile avr32_spi_t *spi,
288                                           unsigned short data,
289                                           unsigned char pcs,
290                                           unsigned char lastxfer);
291
292/*! \brief Checks if all transmissions are complete.
293 *
294 * \param spi Base address of the SPI instance.
295 *
296 * \return Status.
297 *   \retval 1  All transmissions complete.
298 *   \retval 0  Transmissions not complete.
299 */
300extern unsigned char spi_writeEndCheck(volatile avr32_spi_t *spi);
301
302/*! \brief Checks if there is data in the receive register.
303 *
304 * \param spi Base address of the SPI instance.
305 *
306 * \return Status.
307 *   \retval 1  Some data in RDR.
308 *   \retval 0  No data in RDR.
309 */
310extern unsigned char spi_readRegisterFullCheck(volatile avr32_spi_t *spi);
311
312/*! \brief Reads one data word in master mode or in slave mode.
313 *
314 * \param spi   Base address of the SPI instance.
315 * \param data  Pointer to the location where to store the received data word.
316 *
317 * \return Status.
318 *   \retval SPI_OK             Success.
319 *   \retval SPI_ERROR_TIMEOUT  Time-out.
320 *
321 * \note Will block program execution until time-out occurs if no data is
322 *       received or last transmission is not complete. Invoke
323 *       \ref spi_writeEndCheck or \ref spi_readRegisterFullCheck beforehand if
324 *       needed.
325 */
326extern spi_status_t spi_read(volatile avr32_spi_t *spi, unsigned short *data);
327
328/*! \brief Gets status information from the SPI.
329 *
330 * \param spi Base address of the SPI instance.
331 *
332 * \return Status.
333 *   \retval SPI_OK                           Success.
334 *   \retval SPI_ERROR_OVERRUN                Overrun error.
335 *   \retval SPI_ERROR_MODE_FAULT             Mode fault (SPI addressed as slave
336 *                                            while in master mode).
337 *   \retval SPI_ERROR_OVERRUN_AND_MODE_FAULT Overrun error and mode fault.
338 */
339extern unsigned char spi_getStatus(volatile avr32_spi_t *spi);
340
341
342#endif  // _SPI_H_
Note: See TracBrowser for help on using the repository browser.