OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [freertos-6.1.1/] [Demo/] [lwIP_AVR32_UC3/] [DRIVERS/] [USART/] [usart.h] - Blame information for rev 583

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 583 jeremybenn
/*This file is prepared for Doxygen automatic documentation generation.*/
2
/*! \file *********************************************************************
3
 *
4
 * \brief USART driver for AVR32 UC3.
5
 *
6
 * This file contains basic functions for the AVR32 USART, with support for all
7
 * modes, settings and clock speeds.
8
 *
9
 * - Compiler:           IAR EWAVR32 and GNU GCC for AVR32
10
 * - Supported devices:  All AVR32 devices with a USART module can be used.
11
 * - AppNote:
12
 *
13
 * \author               Atmel Corporation: http://www.atmel.com \n
14
 *                       Support and FAQ: http://support.atmel.no/
15
 *
16
 ******************************************************************************/
17
 
18
/* Copyright (c) 2007, Atmel Corporation All rights reserved.
19
 *
20
 * Redistribution and use in source and binary forms, with or without
21
 * modification, are permitted provided that the following conditions are met:
22
 *
23
 * 1. Redistributions of source code must retain the above copyright notice,
24
 * this list of conditions and the following disclaimer.
25
 *
26
 * 2. Redistributions in binary form must reproduce the above copyright notice,
27
 * this list of conditions and the following disclaimer in the documentation
28
 * and/or other materials provided with the distribution.
29
 *
30
 * 3. The name of ATMEL may not be used to endorse or promote products derived
31
 * from this software without specific prior written permission.
32
 *
33
 * THIS SOFTWARE IS PROVIDED BY ATMEL ``AS IS'' AND ANY EXPRESS OR IMPLIED
34
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
35
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY AND
36
 * SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT,
37
 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
38
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
39
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
40
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
41
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
42
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
43
 */
44
 
45
 
46
#ifndef _USART_H_
47
#define _USART_H_
48
 
49
#include <avr32/io.h>
50
#include "compiler.h"
51
 
52
 
53
/*! \name Return Values
54
 */
55
//! @{
56
#define USART_SUCCESS           0 //!< Successful completion.
57
#define USART_FAILURE          -1 //!< Failure because of some unspecified reason.
58
#define USART_INVALID_INPUT     1 //!< Input value out of range.
59
#define USART_INVALID_ARGUMENT -1 //!< Argument value out of range.
60
#define USART_TX_BUSY           2 //!< Transmitter was busy.
61
#define USART_RX_EMPTY          3 //!< Nothing was received.
62
#define USART_RX_ERROR          4 //!< Transmission error occurred.
63
#define USART_MODE_FAULT        5 //!< USART not in the appropriate mode.
64
//! @}
65
 
66
//! Default time-out value (number of attempts).
67
#define USART_DEFAULT_TIMEOUT   10000
68
 
69
/*! \name Parity Settings
70
 */
71
//! @{
72
#define USART_EVEN_PARITY       AVR32_USART_MR_PAR_EVEN   //!< Use even parity on character transmission.
73
#define USART_ODD_PARITY        AVR32_USART_MR_PAR_ODD    //!< Use odd parity on character transmission.
74
#define USART_SPACE_PARITY      AVR32_USART_MR_PAR_SPACE  //!< Use a space as parity bit.
75
#define USART_MARK_PARITY       AVR32_USART_MR_PAR_MARK   //!< Use a mark as parity bit.
76
#define USART_NO_PARITY         AVR32_USART_MR_PAR_NONE   //!< Don't use a parity bit.
77
#define USART_MULTIDROP_PARITY  AVR32_USART_MR_PAR_MULTI  //!< Parity bit is used to flag address characters.
78
//! @}
79
 
80
/*! \name Operating Modes
81
 */
82
//! @{
83
#define USART_MODE_NORMAL       AVR32_USART_MR_MODE_NORMAL      //!< Normal RS232 mode.
84
#define USART_MODE_RS485        AVR32_USART_MR_MODE_RS485       //!< RS485 mode.
85
#define USART_MODE_HW_HSH       AVR32_USART_MR_MODE_HARDWARE    //!< RS232 mode with hardware handshaking.
86
#define USART_MODE_MODEM        AVR32_USART_MR_MODE_MODEM       //!< Modem mode.
87
#define USART_MODE_ISO7816_T0   AVR32_USART_MR_MODE_ISO7816_T0  //!< ISO7816, T = 0 mode.
88
#define USART_MODE_ISO7816_T1   AVR32_USART_MR_MODE_ISO7816_T1  //!< ISO7816, T = 1 mode.
89
#define USART_MODE_IRDA         AVR32_USART_MR_MODE_IRDA        //!< IrDA mode.
90
#define USART_MODE_SW_HSH       AVR32_USART_MR_MODE_SOFTWARE    //!< RS232 mode with software handshaking.
91
//! @}
92
 
93
 
94
/*! \name Channel Modes
95
 */
96
//! @{
97
#define USART_NORMAL_CHMODE     AVR32_USART_MR_CHMODE_NORMAL      //!< Normal communication.
98
#define USART_AUTO_ECHO         AVR32_USART_MR_CHMODE_ECHO        //!< Echo data.
99
#define USART_LOCAL_LOOPBACK    AVR32_USART_MR_CHMODE_LOCAL_LOOP  //!< Local loopback.
100
#define USART_REMOTE_LOOPBACK   AVR32_USART_MR_CHMODE_REMOTE_LOOP //!< Remote loopback.
101
//! @}
102
 
103
/*! \name Stop Bits Settings
104
 */
105
//! @{
106
#define USART_1_STOPBIT         AVR32_USART_MR_NBSTOP_1   //!< Use 1 stop bit.
107
#define USART_1_5_STOPBITS      AVR32_USART_MR_NBSTOP_1_5 //!< Use 1.5 stop bits.
108
#define USART_2_STOPBITS        AVR32_USART_MR_NBSTOP_2   //!< Use 2 stop bits (for more, just give the number of bits).
109
//! @}
110
 
111
 
112
//! Input parameters when initializing RS232 and similar modes.
113
typedef struct
114
{
115
  //! Set baudrate of the USART.
116
  unsigned long baudrate;
117
 
118
  //! Number of bits to transmit as a character (5 to 9).
119
  unsigned char charlength;
120
 
121
  //! How to calculate the parity bit: \ref USART_EVEN_PARITY, \ref USART_ODD_PARITY,
122
  //! \ref USART_SPACE_PARITY, \ref USART_MARK_PARITY, \ref USART_NO_PARITY or
123
  //! \ref USART_MULTIDROP_PARITY.
124
  unsigned char paritytype;
125
 
126
  //! Number of stop bits between two characters: \ref USART_1_STOPBIT,
127
  //! \ref USART_1_5_STOPBITS, \ref USART_2_STOPBITS or any number from 3 to 257
128
  //! which will result in a time guard period of that length between characters.
129
  unsigned short stopbits;
130
 
131
  //! Run the channel in testmode: \ref USART_NORMAL_CHMODE, \ref USART_AUTO_ECHO,
132
  //! \ref USART_LOCAL_LOOPBACK or \ref USART_REMOTE_LOOPBACK.
133
  unsigned char channelmode;
134
} usart_options_t;
135
 
136
//! Input parameters when initializing ISO7816 modes.
137
typedef struct
138
{
139
  //! Set the frequency of the ISO7816 clock.
140
  unsigned long iso7816_hz;
141
 
142
  //! The number of ISO7816 clock ticks in every bit period (1 to 2047, 0 = disable clock).
143
  //! Bit rate = \ref iso7816_hz / \ref fidi_ratio.
144
  unsigned short fidi_ratio;
145
 
146
  //! Inhibit Non Acknowledge:\n
147
  //!   - 0: the NACK is generated;\n
148
  //!   - 1: the NACK is not generated.
149
  //!
150
  //! \note This bit will be used only in ISO7816 mode, protocol T = 0 receiver.
151
  int inhibit_nack;
152
 
153
  //! Disable successive NACKs.
154
  //! Successive parity errors are counted up to the value in the \ref max_iterations field.
155
  //! These parity errors generate a NACK on the ISO line. As soon as this value is reached,
156
  //! no addititional NACK is sent on the ISO line. The ITERATION flag is asserted.
157
  int dis_suc_nack;
158
 
159
  //! Max number of repetitions (0 to 7).
160
  unsigned char max_iterations;
161
 
162
  //! Bit order in transmitted characters:\n
163
  //!   - 0: LSB first;\n
164
  //!   - 1: MSB first.
165
  int bit_order;
166
} iso7816_options_t;
167
 
168
//! Input parameters when initializing ISO7816 modes.
169
typedef struct
170
{
171
  //! Set the frequency of the SPI clock.
172
  unsigned long baudrate;
173
 
174
  //! Number of bits to transmit as a character (5 to 9).
175
  unsigned char charlength;
176
 
177
  //! Run the channel in testmode: \ref USART_NORMAL_CHMODE, \ref USART_AUTO_ECHO,
178
  //! \ref USART_LOCAL_LOOPBACK or \ref USART_REMOTE_LOOPBACK.
179
  unsigned char channelmode;
180
 
181
  //! Which SPI mode to use when transmitting.
182
  unsigned char spimode;
183
} usart_spi_options_t;
184
 
185
 
186
 
187
 
188
 
189
//------------------------------------------------------------------------------
190
/*! \name Initialization Functions
191
 */
192
//! @{
193
 
194
/*! \brief Resets the USART and disables TX and RX.
195
 *
196
 * \param usart Base address of the USART instance.
197
 */
198
extern void usart_reset(volatile avr32_usart_t *usart);
199
 
200
/*! \brief Sets up the USART to use the standard RS232 protocol.
201
 *
202
 * \param usart   Base address of the USART instance.
203
 * \param opt     Options needed to set up RS232 communication (see \ref usart_options_t).
204
 * \param pba_hz  USART module input clock frequency (PBA clock, Hz).
205
 *
206
 * \retval USART_SUCCESS        Mode successfully initialized.
207
 * \retval USART_INVALID_INPUT  One or more of the arguments is out of valid range.
208
 */
209
extern int usart_init_rs232(volatile avr32_usart_t *usart, const usart_options_t *opt, long pba_hz);
210
 
211
/*! \brief Sets up the USART to use hardware handshaking.
212
 *
213
 * \param usart   Base address of the USART instance.
214
 * \param opt     Options needed to set up RS232 communication (see \ref usart_options_t).
215
 * \param pba_hz  USART module input clock frequency (PBA clock, Hz).
216
 *
217
 * \retval USART_SUCCESS        Mode successfully initialized.
218
 * \retval USART_INVALID_INPUT  One or more of the arguments is out of valid range.
219
 *
220
 * \note \ref usart_init_rs232 does not need to be invoked before this function.
221
 */
222
extern int usart_init_hw_handshaking(volatile avr32_usart_t *usart, const usart_options_t *opt, long pba_hz);
223
 
224
/*! \brief Sets up the USART to use the IrDA protocol.
225
 *
226
 * \param usart       Base address of the USART instance.
227
 * \param opt         Options needed to set up RS232 communication (see \ref usart_options_t).
228
 * \param pba_hz      USART module input clock frequency (PBA clock, Hz).
229
 * \param irda_filter Counter used to distinguish received ones from zeros.
230
 *
231
 * \retval USART_SUCCESS        Mode successfully initialized.
232
 * \retval USART_INVALID_INPUT  One or more of the arguments is out of valid range.
233
 */
234
extern int usart_init_IrDA(volatile avr32_usart_t *usart, const usart_options_t *opt,
235
                           long pba_hz, unsigned char irda_filter);
236
 
237
/*! \brief Sets up the USART to use the modem protocol, activating dedicated inputs/outputs.
238
 *
239
 * \param usart   Base address of the USART instance.
240
 * \param opt     Options needed to set up RS232 communication (see \ref usart_options_t).
241
 * \param pba_hz  USART module input clock frequency (PBA clock, Hz).
242
 *
243
 * \retval USART_SUCCESS        Mode successfully initialized.
244
 * \retval USART_INVALID_INPUT  One or more of the arguments is out of valid range.
245
 */
246
extern int usart_init_modem(volatile avr32_usart_t *usart, const usart_options_t *opt, long pba_hz);
247
 
248
/*! \brief Sets up the USART to use the RS485 protocol.
249
 *
250
 * \param usart       Base address of the USART instance.
251
 * \param opt         Options needed to set up RS232 communication (see \ref usart_options_t).
252
 * \param pba_hz      USART module input clock frequency (PBA clock, Hz).
253
 *
254
 * \retval USART_SUCCESS        Mode successfully initialized.
255
 * \retval USART_INVALID_INPUT  One or more of the arguments is out of valid range.
256
 */
257
extern int usart_init_rs485(volatile avr32_usart_t *usart, const usart_options_t *opt, long pba_hz);
258
 
259
/*! \brief Sets up the USART to use the ISO7816 T=0 or T=1 smartcard protocols.
260
 *
261
 * \param usart   Base address of the USART instance.
262
 * \param opt     Options needed to set up ISO7816 communication (see \ref iso7816_options_t).
263
 * \param t       ISO7816 mode to use (T=0 or T=1).
264
 * \param pba_hz  USART module input clock frequency (PBA clock, Hz).
265
 *
266
 * \retval USART_SUCCESS        Mode successfully initialized.
267
 * \retval USART_INVALID_INPUT  One or more of the arguments is out of valid range.
268
 */
269
extern int usart_init_iso7816(volatile avr32_usart_t *usart, const iso7816_options_t *opt, int t, long pba_hz);
270
 
271
/*! \brief Sets up the USART to use the SPI mode as master.
272
 *
273
 * \param usart   Base address of the USART instance.
274
 * \param opt     Options needed to set up SPI mode (see \ref usart_spi_options_t).
275
 * \param pba_hz  USART module input clock frequency (PBA clock, Hz).
276
 *
277
 * \retval USART_SUCCESS        Mode successfully initialized.
278
 * \retval USART_INVALID_INPUT  One or more of the arguments is out of valid range.
279
 */
280
extern int usart_init_spi_master(volatile avr32_usart_t *usart, const usart_spi_options_t *opt, long pba_hz);
281
 
282
 
283
/*! \brief Sets up the USART to use the SPI mode as slave.
284
 *
285
 * \param usart   Base address of the USART instance.
286
 * \param opt     Options needed to set up SPI mode (see \ref usart_spi_options_t).
287
 * \param pba_hz  USART module input clock frequency (PBA clock, Hz).
288
 *
289
 * \retval USART_SUCCESS        Mode successfully initialized.
290
 * \retval USART_INVALID_INPUT  One or more of the arguments is out of valid range.
291
 */
292
extern int usart_init_spi_slave(volatile avr32_usart_t *usart, const usart_spi_options_t *opt, long pba_hz);
293
 
294
//! @}
295
 
296
//------------------------------------------------------------------------------
297
/*! \brief Selects slave chip.
298
 *
299
 * \param usart   Base address of the USART instance.
300
 *
301
 * \return Status.
302
 *   \retval USART_SUCCESS             Success.
303
 */
304
extern int usart_spi_selectChip(volatile avr32_usart_t *usart);
305
 
306
/*! \brief Unselects slave chip.
307
 *
308
 * \param usart   Base address of the USART instance.
309
 *
310
 * \return Status.
311
 *   \retval USART_SUCCESS             Success.
312
 *   \retval USART_FAILURE             Time out.
313
 */
314
extern int usart_spi_unselectChip(volatile avr32_usart_t *usart);
315
 
316
//------------------------------------------------------------------------------
317
/*! \name Read and Reset Error Status Bits
318
 */
319
//! @{
320
 
321
/*! \brief Resets the error status.
322
 *
323
 * This function resets the status bits indicating that a parity error,
324
 * framing error or overrun has occurred. The RXBRK bit, indicating
325
 * a start/end of break condition on the RX line, is also reset.
326
 *
327
 * \param usart Base address of the USART instance.
328
 */
329
#if __GNUC__
330
__attribute__((__always_inline__))
331
#endif
332
extern __inline__ void usart_reset_status(volatile avr32_usart_t *usart)
333
{
334
  usart->cr |= AVR32_USART_CR_RSTSTA_MASK;
335
}
336
 
337
/*! \brief Checks if a parity error has occurred since last status reset.
338
 *
339
 * \param usart Base address of the USART instance.
340
 *
341
 * \return \c 1 if a parity error has been detected, otherwise \c 0.
342
 */
343
#if __GNUC__
344
__attribute__((__always_inline__))
345
#endif
346
extern __inline__ int usart_parity_error(volatile avr32_usart_t *usart)
347
{
348
  return (usart->csr & AVR32_USART_CSR_PARE_MASK) != 0;
349
}
350
 
351
/*! \brief Checks if a framing error has occurred since last status reset.
352
 *
353
 * \param usart Base address of the USART instance.
354
 *
355
 * \return \c 1 if a framing error has been detected, otherwise \c 0.
356
 */
357
#if __GNUC__
358
__attribute__((__always_inline__))
359
#endif
360
extern __inline__ int usart_framing_error(volatile avr32_usart_t *usart)
361
{
362
  return (usart->csr & AVR32_USART_CSR_FRAME_MASK) != 0;
363
}
364
 
365
/*! \brief Checks if an overrun error has occurred since last status reset.
366
 *
367
 * \param usart Base address of the USART instance.
368
 *
369
 * \return \c 1 if a overrun error has been detected, otherwise \c 0.
370
 */
371
#if __GNUC__
372
__attribute__((__always_inline__))
373
#endif
374
extern __inline__ int usart_overrun_error(volatile avr32_usart_t *usart)
375
{
376
  return (usart->csr & AVR32_USART_CSR_OVRE_MASK) != 0;
377
}
378
 
379
//! @}
380
 
381
 
382
//------------------------------------------------------------------------------
383
/*! \name Transmit/Receive Functions
384
 */
385
//! @{
386
 
387
/*! \brief Addresses a receiver.
388
 *
389
 * While in RS485 mode, receivers only accept data addressed to them.
390
 * A packet/char with the address tag set has to precede any data.
391
 * This function is used to address a receiver. This receiver should read
392
 * all the following data, until an address packet addresses another receiver.
393
 *
394
 * \param usart   Base address of the USART instance.
395
 * \param address Address of the target device.
396
 *
397
 * \retval USART_SUCCESS    Address successfully sent (if current mode is RS485).
398
 * \retval USART_MODE_FAULT Wrong operating mode.
399
 */
400
extern int usart_send_address(volatile avr32_usart_t *usart, int address);
401
 
402
/*! \brief Writes the given character to the TX buffer if the transmitter is ready.
403
 *
404
 * \param usart Base address of the USART instance.
405
 * \param c     The character (up to 9 bits) to transmit.
406
 *
407
 * \retval USART_SUCCESS  The transmitter was ready.
408
 * \retval USART_TX_BUSY  The transmitter was busy.
409
 */
410
extern int usart_write_char(volatile avr32_usart_t *usart, int c);
411
 
412
/*! \brief An active wait writing a character to the USART.
413
 *
414
 * \param usart Base address of the USART instance.
415
 * \param c     The character (up to 9 bits) to transmit.
416
 */
417
#if __GNUC__
418
__attribute__((__always_inline__))
419
#endif
420
extern __inline__ void usart_bw_write_char(volatile avr32_usart_t *usart, int c)
421
{
422
  while (usart_write_char(usart, c) != USART_SUCCESS);
423
}
424
 
425
/*! \brief Sends a character with the USART.
426
 *
427
 * \param usart Base address of the USART instance.
428
 * \param c     Character to write.
429
 *
430
 * \retval USART_SUCCESS  The character was written.
431
 * \retval USART_FAILURE  The function timed out before the USART transmitter became ready to send.
432
 */
433
extern int usart_putchar(volatile avr32_usart_t *usart, int c);
434
 
435
/*! \brief Checks the RX buffer for a received character, and stores it at the
436
 *         given memory location.
437
 *
438
 * \param usart Base address of the USART instance.
439
 * \param c     Pointer to the where the read character should be stored
440
 *              (must be at least short in order to accept 9-bit characters).
441
 *
442
 * \retval USART_SUCCESS  The character was read successfully.
443
 * \retval USART_RX_EMPTY The RX buffer was empty.
444
 * \retval USART_RX_ERROR An error was deteceted.
445
 */
446
extern int usart_read_char(volatile avr32_usart_t *usart, int *c);
447
 
448
/*! \brief Waits until a character is received, and returns it.
449
 *
450
 * \param usart Base address of the USART instance.
451
 *
452
 * \return The received character, or \ref USART_FAILURE upon error.
453
 */
454
extern int usart_getchar(volatile avr32_usart_t *usart);
455
 
456
/*! \brief Writes one character string to the USART.
457
 *
458
 * \param usart   Base address of the USART instance.
459
 * \param string  String to be written.
460
 */
461
extern void usart_write_line(volatile avr32_usart_t *usart, const char *string);
462
 
463
/*! \brief Gets and echoes characters until end of line.
464
 *
465
 * \param usart Base address of the USART instance.
466
 *
467
 * \retval USART_SUCCESS  Success.
468
 * \retval USART_FAILURE  ETX character received.
469
 */
470
extern int usart_get_echo_line(volatile avr32_usart_t *usart);
471
 
472
//! @}
473
 
474
 
475
#endif  // _USART_H_

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.