source: SVN/rincon/u-boot/cpu/ixp/npe/include/IxUART.h @ 55

Last change on this file since 55 was 55, checked in by Tim Harvey, 2 years ago

rincon: added latest u-boot source

restored form server backup

Signed-off-by: Tim Harvey <tharvey@…>

File size: 9.6 KB
Line 
1/**
2 * @file IxUART.h
3 *
4 * @date 12-OCT-01
5 *
6 * @brief Public header for the Intel IXP400 internal UART, generic driver.
7 *
8 * Design Notes:
9 * This driver allows you to perform the following functions:
10 *      Device Initialization,
11 *      send/receive characters.
12 *
13 * Perform Uart IOCTL for the following:
14 *      Set/Get the current baud rate,
15 *      set parity,
16 *      set the number of Stop bits,
17 *      set the character Length (5,6,7,8),
18 *      enable/disable Hardware flow control.
19 *
20 * Only Polled mode is supported for now.
21 *   
22 *
23 * @par
24 * IXP400 SW Release version 2.0
25 *
26 * -- Copyright Notice --
27 *
28 * @par
29 * Copyright 2001-2005, Intel Corporation.
30 * All rights reserved.
31 *
32 * @par
33 * Redistribution and use in source and binary forms, with or without
34 * modification, are permitted provided that the following conditions
35 * are met:
36 * 1. Redistributions of source code must retain the above copyright
37 *    notice, this list of conditions and the following disclaimer.
38 * 2. Redistributions in binary form must reproduce the above copyright
39 *    notice, this list of conditions and the following disclaimer in the
40 *    documentation and/or other materials provided with the distribution.
41 * 3. Neither the name of the Intel Corporation nor the names of its contributors
42 *    may be used to endorse or promote products derived from this software
43 *    without specific prior written permission.
44 *
45 * @par
46 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
47 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
48 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
49 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
50 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
51 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
52 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
53 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
54 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
55 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
56 * SUCH DAMAGE.
57 *
58 * @par
59 * -- End of Copyright Notice --
60*/
61
62/**
63 * @defgroup IxUARTAccAPI IXP400 UART Access (IxUARTAcc) API
64 *
65 * @brief IXP400 UARTAcc Driver Public API
66 *
67 * @{
68 */
69
70
71/* Defaults */
72
73/**
74 * @defgroup DefaultDefines Defines for Default Values
75 *
76 * @brief Default values which can be used for UART configuration
77 *
78 * @sa ixUARTDev
79 */
80
81/**
82 * @def IX_UART_DEF_OPTS
83 *
84 * @brief The default hardware options to set the UART to -
85 * no flow control, 8 bit word, 1 stop bit, no parity
86 *
87 * @ingroup DefaultDefines
88 */
89#define IX_UART_DEF_OPTS (CLOCAL | CS8)
90
91/**
92 * @def IX_UART_DEF_XMIT
93 *
94 * @brief The default UART FIFO size - must be no bigger than 64
95 *
96 * @ingroup DefaultDefines
97 */
98#define IX_UART_DEF_XMIT 64
99
100/**
101 * @def IX_UART_DEF_BAUD
102 *
103 * @brief The default UART baud rate - 9600
104 *
105 * @ingroup DefaultDefines
106 */
107#define IX_UART_DEF_BAUD 9600
108
109/**
110 * @def IX_UART_MIN_BAUD
111 *
112 * @brief The minimum UART baud rate - 9600
113 *
114 * @ingroup DefaultDefines
115 */
116#define IX_UART_MIN_BAUD 9600
117
118/**
119 * @def IX_UART_MAX_BAUD
120 *
121 * @brief The maximum UART baud rate - 926100
122 *
123 * @ingroup DefaultDefines
124 */
125#define IX_UART_MAX_BAUD 926100
126
127/**
128 * @def IX_UART_XTAL
129 *
130 * @brief The UART clock speed
131 *
132 * @ingroup DefaultDefines
133 */
134#define IX_UART_XTAL 14745600
135
136
137
138/* IOCTL commands (Request codes) */
139
140/**
141 * @defgroup IoctlCommandDefines Defines for IOCTL Commands
142 *
143 * @brief IOCTL Commands (Request codes) which can be used
144 *        with @ref ixUARTIoctl
145 */
146
147
148/**
149 * @ingroup IoctlCommandDefines
150 *
151 * @def IX_BAUD_SET
152 *
153 * @brief Set the baud rate
154 */
155#define IX_BAUD_SET     0
156
157/**
158 * @ingroup IoctlCommandDefines
159 *
160 * @def IX_BAUD_GET
161 *
162 * @brief Get the baud rate
163 */
164#define IX_BAUD_GET     1
165
166/**
167 * @ingroup IoctlCommandDefines
168 * @def IX_MODE_SET
169 * @brief Set the UART mode of operation
170 */
171#define IX_MODE_SET     2
172
173/**
174 * @ingroup IoctlCommandDefines
175 *
176 * @def IX_MODE_GET
177 *
178 * @brief Get the current UART mode of operation
179 */
180#define IX_MODE_GET     3
181
182/**
183 * @ingroup IoctlCommandDefines
184 *
185 * @def IX_OPTS_SET
186 *
187 * @brief Set the UART device options
188 */
189#define IX_OPTS_SET     4
190
191/**
192 * @ingroup IoctlCommandDefines
193 *
194 * @def IX_OPTS_GET
195 *
196 * @brief Get the UART device options
197 */
198#define IX_OPTS_GET     5
199
200/**
201 * @ingroup IoctlCommandDefines
202 *
203 * @def IX_STATS_GET
204 *
205 * @brief Get the UART statistics
206 */
207#define IX_STATS_GET    6
208
209
210/* POSIX style ioctl arguments */
211
212/**
213 * @defgroup IoctlArgDefines Defines for IOCTL Arguments
214 *
215 * @brief POSIX style IOCTL arguments which can be used
216 *        with @ref ixUARTIoctl
217 *
218 * @sa ixUARTMode
219 */
220
221
222/**
223 * @ingroup IoctlArgDefines
224 *
225 * @def CLOCAL
226 *
227 * @brief Software flow control
228 */
229#ifdef CLOCAL
230#undef CLOCAL
231#endif
232#define CLOCAL          0x1
233
234/**
235 * @ingroup IoctlArgDefines
236 *
237 * @def CREAD
238 *
239 * @brief Enable interrupt receiver
240 */
241#ifdef CREAD
242#undef CREAD
243#endif
244#define CREAD           0x2
245
246/**
247 * @ingroup IoctlArgDefines
248 *
249 * @def CSIZE
250 *
251 * @brief Characters size
252 */
253#ifdef CSIZE
254#undef CSIZE
255#endif
256#define CSIZE           0xc
257
258/**
259 * @ingroup IoctlArgDefines
260 *
261 * @def CS5
262 *
263 * @brief 5 bits
264 */
265#ifdef CS5
266#undef CS5
267#endif
268#define CS5             0x0
269
270/**
271 * @ingroup IoctlArgDefines
272 *
273 * @def CS6
274 *
275 * @brief 6 bits
276 */
277#ifdef CS6
278#undef CS6
279#endif
280#define CS6             0x4
281
282/**
283 * @ingroup IoctlArgDefines
284 *
285 * @def CS7
286 *
287 * @brief 7 bits
288 */
289#ifdef CS7
290#undef CS7
291#endif
292#define CS7             0x8
293
294/**
295 * @ingroup IoctlArgDefines
296 *
297 * @def CS8
298 *
299 * @brief 8 bits
300 */
301#ifdef CS8
302#undef CS8
303#endif
304#define CS8             0xc
305
306/**
307 * @ingroup IoctlArgDefines
308 *
309 * @def STOPB
310 *
311 * @brief Send two stop bits (else one)
312 */
313#define STOPB           0x20
314
315/**
316 * @ingroup IoctlArgDefines
317 *
318 * @def PARENB
319 *
320 * @brief Parity detection enabled (else disabled)
321 */
322#ifdef PARENB
323#undef PARENB
324#endif
325#define PARENB          0x40
326
327/**
328 * @ingroup IoctlArgDefines
329 *
330 * @def PARODD
331 *
332 * @brief Odd parity  (else even)
333 */
334#ifdef PARODD
335#undef PARODD
336#endif
337#define PARODD          0x80
338
339/**
340 * @enum ixUARTMode
341 * @brief The mode to set to UART to.
342 */
343typedef enum
344{
345    INTERRUPT=0,        /**< Interrupt mode */
346    POLLED,             /**< Polled mode */
347    LOOPBACK            /**< Loopback mode */
348} ixUARTMode;
349
350/**
351 * @struct ixUARTStats
352 * @brief Statistics for the UART.
353 */
354typedef struct
355{
356    UINT32  rxCount;
357    UINT32  txCount;   
358    UINT32  overrunErr;
359    UINT32  parityErr;
360    UINT32  framingErr;
361    UINT32  breakErr;
362} ixUARTStats;
363
364/**
365 * @struct ixUARTDev
366 * @brief Device descriptor for the UART.
367 */
368typedef struct
369{
370    UINT8 *addr;        /**< device base address */
371    ixUARTMode mode;    /**< interrupt, polled or loopback */
372    int baudRate;       /**< baud rate */
373    int freq;           /**< UART clock frequency */     
374    int options;        /**< hardware options */
375    int fifoSize;       /**< FIFO xmit size */
376
377    ixUARTStats   stats;        /**< device statistics */
378} ixUARTDev;
379
380/**
381 * @ingroup IxUARTAccAPI
382 *
383 * @fn IX_STATUS ixUARTInit(ixUARTDev* pUART)
384 *
385 * @param pUART @ref ixUARTDev [in] - pointer to UART structure describing our device.
386 *
387 * @brief Initialise the UART. This puts the chip in a quiescent state.
388 *
389 * @pre The base address for the UART must contain a valid value.
390 *      Also the baud rate and hardware options must contain sensible values
391 *      otherwise the defaults will be used as defined in ixUART.h
392 *
393 * @post UART is initialized and ready to send and receive data.
394 *
395 * @note This function should only be called once per device.
396 *
397 * @retval IX_SUCCESS - UART device successfully initialised.
398 * @retval IX_FAIL - Critical error, device not initialised.
399 ***************************************************************************/
400PUBLIC IX_STATUS ixUARTInit(ixUARTDev* pUART);
401
402/**
403 * @ingroup IxUARTAccAPI
404 *
405 * @fn IX_STATUS ixUARTPollOutput(ixUARTDev* pUART, int outChar)
406 *
407 * @param pUART @ref ixUARTDev [out] - pointer to UART structure describing our device.
408 * @param outChar int [out] - character to transmit.
409 *
410 * @brief Transmit a character in polled mode.
411 *
412 * @pre UART device must be initialised.
413 *
414 * @retval IX_SUCCESS - character was successfully transmitted.
415 * @retval IX_FAIL - output buffer is full (try again).
416 ***************************************************************************/
417PUBLIC IX_STATUS ixUARTPollOutput(ixUARTDev* pUART, int outChar);
418
419/**
420 * @ingroup IxUARTAccAPI
421 *
422 * @fn IX_STATUS ixUARTPollInput(ixUARTDev* pUART, char *inChar)
423 *
424 * @param pUART @ref ixUARTDev [in] - pointer to UART structure describing our device.
425 * @param *inChar char [in] - character read from the device.
426 *
427 * @brief Receive a character in polled mode.
428 *
429 * @pre UART device must be initialised.
430 *
431 * @retval IX_SUCCESS - character was successfully read.
432 * @retval IX_FAIL - input buffer empty (try again).
433 ***************************************************************************/
434PUBLIC IX_STATUS ixUARTPollInput(ixUARTDev* pUART, char *inChar);
435
436/**
437 * @ingroup IxUARTAccAPI
438 *
439 * @fn IX_STATUS ixUARTIoctl(ixUARTDev* pUART, int cmd, void* arg)
440 *
441 * @param pUART @ref ixUARTDev [in] - pointer to UART structure describing our device.
442 * @param cmd int [in] - an ioctl request code.
443 * @param arg void* [in] - optional argument used to set the device mode,
444 *       baud rate, and hardware options.
445 *
446 * @brief Perform I/O control routines on the device.
447 *
448 * @retval IX_SUCCESS - requested feature was set/read successfully.
449 * @retval IX_FAIL - error setting/reading the requested feature.
450 *
451 * @sa IoctlCommandDefines
452 * @sa IoctlArgDefines
453 ***************************************************************************/   
454PUBLIC IX_STATUS ixUARTIoctl(ixUARTDev* pUART, int cmd, void* arg);
455
456/**
457 * @} defgroup IxUARTAcc
458 */
Note: See TracBrowser for help on using the repository browser.