source: rtems/c/src/lib/libbsp/arm/altera-cyclone-v/hwlib/include/alt_16550_uart.h @ 76386c1

4.115
Last change on this file since 76386c1 was 76386c1, checked in by Sebastian Huber <sebastian.huber@…>, on Aug 26, 2014 at 2:00:44 PM

bsp/altera-cyclone-v: Add DMA support hwlib files

  • Property mode set to 100644
File size: 54.3 KB
Line 
1/*
2 * Altera - SoC UART Manager
3 */
4
5/*****************************************************************************
6 *
7 * Copyright 2013 Altera Corporation. All Rights Reserved.
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions are met:
11 *
12 * 1. Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
14 *
15 * 2. Redistributions in binary form must reproduce the above copyright notice,
16 * this list of conditions and the following disclaimer in the documentation
17 * and/or other materials provided with the distribution.
18 *
19 * 3. The name of the author may not be used to endorse or promote products
20 * derived from this software without specific prior written permission.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR
23 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
24 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO
25 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
27 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
28 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
29 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
30 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
31 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 *
33 *****************************************************************************/
34
35#ifndef __ALT_16550_UART_H__
36#define __ALT_16550_UART_H__
37
38#include "hwlib.h"
39#include "alt_clock_manager.h"
40
41#ifdef __cplusplus
42extern "C"
43{
44#endif
45
46/*!
47 * \addtogroup UART UART Driver API
48 *
49 * This module defines the Universal Asynchronous Receiver/Transmitter (UART)
50 * API for accessing and using the UART resources. The API allows for general
51 * control of a 16550 compatible UART controller.
52 *
53 * This implementation can control the following UARTs:
54 *  * SoCFPGA On-board UARTs
55 *  * Altera 16550 Compatible Soft IP UART
56 *
57 * The following reference materials were used in the design of this API:
58 *  * Synopsys&reg; DesignWare DW_apb_uart Databook v3.10a
59 *
60 * @{
61 */
62
63/*!
64 * \addtogroup UART_BASIC UART Basic
65 *
66 * This group of APIs provides basic access to the UART to initialize,
67 * uninitialize, read, write, and reset the UART.
68 *
69 * @{
70 */
71
72/*!
73 * This type definition enumerates the list of UARTs available on the system.
74 */
75typedef enum ALT_16550_DEVICE_e
76{
77    /*!
78     * This option selects UART0 in the SoC FPGA.
79     */
80    ALT_16550_DEVICE_SOCFPGA_UART0 = 0,
81
82    /*!
83     * This option selects UART1 in the SoC FPGA.
84     */
85    ALT_16550_DEVICE_SOCFPGA_UART1 = 1,
86
87    /*!
88     * This option selects an Altera 16550 Compatible soft IP UART. The memory
89     * location of the device must be provided as part of the initialization.
90     */
91    ALT_16550_DEVICE_ALTERA_16550_UART = 0x100
92}
93ALT_16550_DEVICE_t;
94
95/*!
96 * This structure is used to represent a handle to a specific UART on the
97 * system. The internal members are undocumented and should be not altered
98 * outside of this API.
99 */
100typedef struct ALT_16550_HANDLE_s
101{
102    ALT_16550_DEVICE_t device;
103    void *             location;
104    alt_freq_t         clock_freq;
105    uint32_t           data;
106    uint32_t           fcr;
107}
108ALT_16550_HANDLE_t;
109
110/*!
111 * Performs the initialization steps needed by the UART. This should be the
112 * first API call made when accessing a particular UART
113 *
114 * The default UART setting is 8 databits, no parity, 1 stopbit, and 57600
115 * baud.
116 *
117 * For the SoCFPGA UARTs, The ALT_CLK_L4_SP clock needs to be setup before
118 * initialization.
119 *
120 * \param       device
121 *              The UART device identifier.
122 *
123 * \param       location
124 *              The memory of the location for the given UART. For SoCFPGA
125 *              UARTs, this parameter is ignored.
126 *
127 * \param       clock_freq
128 *              The clock frequency of the serial clock for the given UART.
129 *              For SoCFPGA UARTs, this paramter is ignored.
130 *
131 * \param       handle
132 *              [out] A pointer to a handle that will represent the UART. This
133 *              handle should subsequently be used when calling other UART
134 *              APIs.
135 *
136 * \retval      ALT_E_SUCCESS   The operation was successful.
137 * \retval      ALT_E_ERROR     The operation failed.
138 * \retval      ALT_E_BAD_ARG   The given UART device identifier is invalid.
139 * \retval      ALT_E_BAD_CLK   The required clock is not yet setup.
140 */
141ALT_STATUS_CODE alt_16550_init(ALT_16550_DEVICE_t device,
142                               void * location,
143                               alt_freq_t clock_freq,
144                               ALT_16550_HANDLE_t * handle);
145
146/*!
147 * Performs the uninitialization steps for the UART. This should be the last
148 * API call made to cleanup the UART.
149 *
150 * After calling this function, the handle will need to be initialized again
151 * before being used by calling alt_16550_init().
152 *
153 * \param       handle
154 *              The UART device handle.
155 *
156 * \retval      ALT_E_SUCCESS   The operation was successful.
157 * \retval      ALT_E_ERROR     The operation failed.
158 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
159 */
160ALT_STATUS_CODE alt_16550_uninit(ALT_16550_HANDLE_t * handle);
161
162/*!
163 * Resets the UART to the default configuration. The UART will be reset and
164 * reinitialized.
165 *
166 * \param       handle
167 *              The UART device handle.
168 *
169 * \retval      ALT_E_SUCCESS   The operation was successful.
170 * \retval      ALT_E_ERROR     The operation failed.
171 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
172 */
173ALT_STATUS_CODE alt_16550_reset(ALT_16550_HANDLE_t * handle);
174
175/*!
176 * Starts the UART after all configuration has been completed.
177 *
178 * \param       handle
179 *              The UART device handle.
180 *
181 * \retval      ALT_E_SUCCESS   The operation was successful.
182 * \retval      ALT_E_ERROR     The operation failed.
183 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
184 */
185ALT_STATUS_CODE alt_16550_enable(ALT_16550_HANDLE_t * handle);
186
187/*!
188 * Stops the UART. While UART configuration can be done while enabled, it is
189 * not recommended.
190 *
191 * \param       handle
192 *              The UART device handle.
193 *
194 * \retval      ALT_E_SUCCESS   The operation was successful.
195 * \retval      ALT_E_ERROR     The operation failed.
196 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
197 */
198ALT_STATUS_CODE alt_16550_disable(ALT_16550_HANDLE_t * handle);
199
200/*!
201 * Reads a single character from the UART receiver buffer. This API should
202 * only be used when FIFOs are disabled.
203 *
204 * \param       handle
205 *              The UART device handle.
206 *
207 * \param       item
208 *              [out] Pointer to an output parameter that contains the in
209 *              receiver buffer of the UART.
210 *
211 * \retval      ALT_E_SUCCESS   The operation was successful.
212 * \retval      ALT_E_ERROR     The operation failed.
213 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
214 */
215ALT_STATUS_CODE alt_16550_read(ALT_16550_HANDLE_t * handle,
216                               char * item);
217
218/*!
219 * Writes a single character to the UART transmitter buffer. This API should
220 * only be used when FIFOs are disabled.
221 *
222 * \param       handle
223 *              The UART device handle.
224 *
225 * \param       item
226 *              The character to write to the transmitter buffer of the UART.
227 *
228 * \retval      ALT_E_SUCCESS   The operation was successful.
229 * \retval      ALT_E_ERROR     The operation failed.
230 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
231 */
232ALT_STATUS_CODE alt_16550_write(ALT_16550_HANDLE_t * handle,
233                                char item);
234
235/*!
236 * @}
237 */
238
239/*!
240 * \addtogroup UART_FIFO UART FIFO Interface
241 *
242 * This group of APIs provides access, configuration, and control of the UART
243 * FIFO. The FIFO allows the UART to buffer received data and data to be
244 * transmitted.
245 *
246 * @{
247 */
248
249/*!
250 * This type definition enumerates the receiver FIFO level conditions that
251 * will trigger the receiver FIFO to issue a receiver FIFO full event.
252 */
253typedef enum ALT_16550_FIFO_TRIGGER_RX_e
254{
255    /*!
256     * 1 or more character(s) in the receiver FIFO will trigger an event.
257     */
258    ALT_16550_FIFO_TRIGGER_RX_ANY = 0,
259
260    /*!
261     * 25% or higher capacity usage in the receiver FIFO will trigger an
262     * event.
263     */
264    ALT_16550_FIFO_TRIGGER_RX_QUARTER_FULL = 1,
265
266    /*!
267     * 50% or higher capacity usage in the receiver FIFO will trigger an
268     * event.
269     */
270    ALT_16550_FIFO_TRIGGER_RX_HALF_FULL = 2,
271
272    /*!
273     * 2 characters less than the receiver FIFO capacity will trigger an
274     * event.
275     */
276    ALT_16550_FIFO_TRIGGER_RX_ALMOST_FULL = 3
277}
278ALT_16550_FIFO_TRIGGER_RX_t;
279
280/*!
281 * This type definition enumerates the transmitter FIFO level conditions that
282 * will trigger the transmitter FIFO to issue a transmitter FIFO empty event.
283 */
284typedef enum ALT_16550_FIFO_TRIGGER_TX_e
285{
286    /*!
287     * Transmitter FIFO being completely empty will trigger an event.
288     */
289    ALT_16550_FIFO_TRIGGER_TX_EMPTY = 0,
290
291    /*!
292     * 2 or less character(s) in the transmitter FIFO will trigger an event.
293     */
294    ALT_16550_FIFO_TRIGGER_TX_ALMOST_EMPTY = 1,
295
296    /*!
297     * 25% or less capacity usage in the transmitter FIFO will trigger an
298     * event.
299     */
300    ALT_16550_FIFO_TRIGGER_TX_QUARTER_FULL = 2,
301
302    /*!
303     * 50% or less capacity usage in the transmitter FIFO will trigger an
304     * event.
305     */
306    ALT_16550_FIFO_TRIGGER_TX_HALF_FULL = 3
307}
308ALT_16550_FIFO_TRIGGER_TX_t;
309
310/*!
311 * Enables FIFO on the UART. This will enable both the receiver FIFO and
312 * transmitter FIFO. Both FIFOs will be cleared.
313 *
314 * \param       handle
315 *              The UART device handle.
316 *
317 * \retval      ALT_E_SUCCESS   The operation was successful.
318 * \retval      ALT_E_ERROR     The operation failed.
319 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
320 */
321ALT_STATUS_CODE alt_16550_fifo_enable(ALT_16550_HANDLE_t * handle);
322
323/*!
324 * Disables FIFOs on the UART. This will disable both the receiver FIFO and
325 * transmitter FIFO. Any data left in the FIFOs will be lost.
326 *
327 * \param       handle
328 *              The UART device handle.
329 *
330 * \retval      ALT_E_SUCCESS   The operation was successful.
331 * \retval      ALT_E_ERROR     The operation failed.
332 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
333 */
334ALT_STATUS_CODE alt_16550_fifo_disable(ALT_16550_HANDLE_t * handle);
335
336/*!
337 * Reads the given buffer from the receiver FIFO in the UART.
338 *
339 * The available characters in the FIFO can be determined by a few ways. Users
340 * can determine the number of items by calling alt_16550_fifo_level_get_rx().
341 *
342 * Another way is by using the RX trigger and RX interrupt. First determine the
343 * RX FIFO size by calling alt_16550_fifo_size_get_rx(). Then set the desired
344 * trigger level by calling alt_16550_fifo_trigger_set_rx(). Calculate the
345 * triggering point by applying trigger description on the FIFO size. Enable RX
346 * interrupts by calling alt_16550_int_enable_rx(). When the RX interrupt fires
347 * due to the ALT_16550_INT_STATUS_RX_DATA condition, the calculated triggering
348 * point value can be used to determine the RX FIFO level. If the interrupt
349 * fires due to the ALT_16550_INT_STATUS_RX_TIMEOUT, the RX FIFO can be
350 * completely emptied by repeatedly polling the Line Status
351 * ALT_16550_LINE_STATUS_DR condition by calling alt_16550_line_status_get().
352 * These steps are necessary if the UART does not implement FIFO level query
353 * functionality. As of 13.0sp1, this applies to the Altera 16550 Compatible
354 * Soft UART.
355 *
356 * Reading more data than that which is available can result in invalid data
357 * appearing like valid data.
358 *
359 * The FIFO must first be enabled before calling this function by calling
360 * alt_16550_fifo_enable().
361 *
362 * \param       handle
363 *              The UART device handle.
364 *
365 * \param       buffer
366 *              [out] Pointer to a buffer where the specified count of
367 *              characters from the receiver FIFO will be copied to.
368 *
369 * \param       count
370 *              The count of characters from the receiver FIFO to be copied.
371 *
372 * \retval      ALT_E_SUCCESS   The operation was successful.
373 * \retval      ALT_E_ERROR     The operation failed.
374 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
375 */
376ALT_STATUS_CODE alt_16550_fifo_read(ALT_16550_HANDLE_t * handle,
377                                    char * buffer,
378                                    size_t count);
379
380/*!
381 * Writes the given buffer to the transmitter FIFO in the UART.
382 *
383 * The available space in the FIFO can be determined by a few ways. Users can
384 * determine the number of items by calculating the FIFO capacity minus the
385 * FIFO level. This can be done by calling  alt_16550_fifo_size_get_tx() and
386 * alt_16550_fifo_level_get_tx() respectively.
387 *
388 * Another way is by using the TX trigger and TX interrupt. First determine the
389 * TX FIFO size by calling alt_16550_fifo_size_get_tx(). The set the desired
390 * trigger level by calling alt_16550_fifo_trigger_set_tx(). Calculate the
391 * triggering point by applying the trigger description on the FIFO size.
392 * Enable TX interrupts by calling alt_16550_int_enable_tx(). When the TX
393 * interrupt fires, calculate the empty entries in the FIFO by subtracting the
394 * TX FIFO size and the calculated value. These steps are necessary if the UART
395 * does not implement FIFO level query functionality. As of 13.0sp1, this
396 * applies to the Altera 16550 Compatible Soft UART.
397 *
398 * Writing more data that there is space can result in data lost due to
399 * overflowing.
400 *
401 * The FIFOs must first be enabled before calling this function by calling
402 * alt_16550_fifo_enable().
403 *
404 * \param       handle
405 *              The UART device handle.
406 *
407 * \param       buffer
408 *              Pointer to a buffer from where the specified count of
409 *              characters will be copied to the transmitter FIFO.
410 *
411 * \param       count
412 *              The count of characters from the given buffer to be copied.
413 *
414 * \retval      ALT_E_SUCCESS   The operation was successful.
415 * \retval      ALT_E_ERROR     The operation failed.
416 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
417 */
418ALT_STATUS_CODE alt_16550_fifo_write(ALT_16550_HANDLE_t * handle,
419                                     const char * buffer,
420                                     size_t count);
421
422/*!
423 * Clears the contents of the receiver FIFO. Any characters which were
424 * previously contained in that FIFO will be discarded.
425 *
426 * The FIFOs must first be enabled before calling this function by calling
427 * alt_16550_fifo_enable().
428 *
429 * \param       handle
430 *              The UART device handle.
431 *
432 * \retval      ALT_E_SUCCESS   The operation was successful.
433 * \retval      ALT_E_ERROR     The operation failed.
434 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
435 */
436ALT_STATUS_CODE alt_16550_fifo_clear_rx(ALT_16550_HANDLE_t * handle);
437
438/*!
439 * Clears the contents of the transmitter FIFO. Any characters which were
440 * previously contained in that FIFO will be discarded.
441 *
442 * The FIFOs must first be enabled before calling this function by calling
443 * alt_16550_fifo_enable().
444 *
445 * \param       handle
446 *              The UART device handle.
447 *
448 * \retval      ALT_E_SUCCESS   The operation was successful.
449 * \retval      ALT_E_ERROR     The operation failed.
450 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
451 */
452ALT_STATUS_CODE alt_16550_fifo_clear_tx(ALT_16550_HANDLE_t * handle);
453
454/*!
455 * Clears the contents of the receiver and transmitter FIFO. Any characters
456 * which were previously contained on those FIFOs will be discarded.
457 *
458 * The FIFOs must first be enabled before calling this function by calling
459 * alt_16550_fifo_enable().
460 *
461 * \param       handle
462 *              The UART device handle.
463 *
464 * \retval      ALT_E_SUCCESS   The operation was successful.
465 * \retval      ALT_E_ERROR     The operation failed.
466 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
467 */
468ALT_STATUS_CODE alt_16550_fifo_clear_all(ALT_16550_HANDLE_t * handle);
469
470/*!
471 * Queries the size of the receiver FIFO.
472 *
473 * \param       handle
474 *              The UART device handle.
475 *
476 * \param       size
477 *              [out] Pointer to an output parameter that contains the size of
478 *              the receiver FIFO.
479 *
480 * \retval      ALT_E_SUCCESS   The operation was successful.
481 * \retval      ALT_E_ERROR     The operation failed.
482 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
483 */
484ALT_STATUS_CODE alt_16550_fifo_size_get_rx(ALT_16550_HANDLE_t * handle,
485                                           uint32_t * size);
486
487/*!
488 * Queries the size of the transmitter FIFO.
489 *
490 * \param       handle
491 *              The UART device handle.
492 *
493 * \param       size
494 *              [out] Pointer to an output parameter that contains the size of
495 *              the transmitter FIFO.
496 *
497 * \retval      ALT_E_SUCCESS   The operation was successful.
498 * \retval      ALT_E_ERROR     The operation failed.
499 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
500 */
501ALT_STATUS_CODE alt_16550_fifo_size_get_tx(ALT_16550_HANDLE_t * handle,
502                                           uint32_t * size);
503
504/*!
505 * Queries the current level of the receiver FIFO.
506 *
507 * The FIFOs must first be enabled before calling this function by calling
508 * alt_16550_fifo_enable().
509 *
510 * For the Altera 16550 Compatible UART, it may not be possible to read the
511 * FIFO level and this function may always report 0. For more information on
512 * interacting with the FIFO in this situation, see documentation for
513 * alt_16550_fifo_read().
514 *
515 * \param       handle
516 *              The UART device handle.
517 *
518 * \param       level
519 *              [out] Pointer to an output parameter that contains the level
520 *              or number of characters in the receiver FIFO.
521 *
522 * \retval      ALT_E_SUCCESS   The operation was successful.
523 * \retval      ALT_E_ERROR     The operation failed.
524 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
525 */
526ALT_STATUS_CODE alt_16550_fifo_level_get_rx(ALT_16550_HANDLE_t * handle,
527                                            uint32_t * level);
528
529/*!
530 * Queries the current level of the transmitter FIFO.
531 *
532 * The FIFOs must first be enabled before calling this function by calling
533 * alt_16550_fifo_enable().
534 *
535 * For the Altera 16550 Compatible UART, it may not be possible to read the
536 * FIFO level and this function may always report 0. For more information on
537 * interacting with the FIFO in this situation, see documentation for
538 * alt_16550_fifo_write().
539 *
540 * \param       handle
541 *              The UART device handle.
542 *
543 * \param       level
544 *              [out] Pointer to an output parameter that contains the level
545 *              or number of characters in the transmitter FIFO.
546 *
547 * \retval      ALT_E_SUCCESS   The operation was successful.
548 * \retval      ALT_E_ERROR     The operation failed.
549 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
550 */
551ALT_STATUS_CODE alt_16550_fifo_level_get_tx(ALT_16550_HANDLE_t * handle,
552                                            uint32_t * level);
553
554/*!
555 * Sets the receiver FIFO level which will trigger the receiver FIFO to issue
556 * receiver FIFO full event. For the list of available receiver FIFO trigger
557 * levels, see the documentation for ALT_16550_FIFO_TRIGGER_RX_t.
558 *
559 * The FIFOs must first be enabled before calling this function by calling
560 * alt_16550_fifo_enable().
561 *
562 * \param       handle
563 *              The UART device handle.
564 *
565 * \param       trigger
566 *              The level of the receiver FIFO which is needed to trigger a
567 *              receiver FIFO full event.
568 *
569 * \retval      ALT_E_SUCCESS   The operation was successful.
570 * \retval      ALT_E_ERROR     The operation failed.
571 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
572 */
573ALT_STATUS_CODE alt_16550_fifo_trigger_set_rx(ALT_16550_HANDLE_t * handle,
574                                              ALT_16550_FIFO_TRIGGER_RX_t trigger);
575
576/*!
577 * Sets the transmitter FIFO level which will trigger the transmitter FIFO to
578 * transmitter FIFO empty event. For the list of available transmitter FIFO
579 * trigger levels, see the documentation for ALT_16550_FIFO_TRIGGER_TX_t.
580 *
581 * The FIFOs must first be enabled before calling this function by calling
582 * alt_16550_fifo_enable().
583 *
584 * \param       handle
585 *              The UART device handle.
586 *
587 * \param       trigger
588 *              The level of the transmitter FIFO which is needed to trigger a
589 *              transmitter FIFO empty event.
590 *
591 * \retval      ALT_E_SUCCESS   The operation was successful.
592 * \retval      ALT_E_ERROR     The operation failed.
593 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
594 */
595ALT_STATUS_CODE alt_16550_fifo_trigger_set_tx(ALT_16550_HANDLE_t * handle,
596                                              ALT_16550_FIFO_TRIGGER_TX_t trigger);
597
598/*!
599 * @}
600 */
601
602/*!
603 * \addtogroup UART_BAUD UART Baudrate Interface
604 *
605 * This group of APIs allows for the configuration of the UART's baudrate
606 * generation related functions.
607 *
608 * The UART baudrate is determined by dividing the ALT_CLK_L4_SP clock with
609 * the configured divisor.
610 *
611 * @{
612 */
613
614/*!
615 * This enumeration lists out the common baudrates used with modem and serial
616 * ports. Not every baudrate is available for the UART due to the limits of
617 * the serial clock frequency and divisor value.
618 */
619typedef enum ALT_16550_BAUDRATE_e
620{
621    ALT_16550_BAUDRATE_50     =     50, /*!< 50 bps baudrate. */
622    ALT_16550_BAUDRATE_75     =     75, /*!< 75 bps baudrate. */
623    ALT_16550_BAUDRATE_150    =    150, /*!< 150 bps baudrate. */
624    ALT_16550_BAUDRATE_300    =    300, /*!< 300 bps baudrate. */
625    ALT_16550_BAUDRATE_600    =    600, /*!< 600 bps baudrate. */
626    ALT_16550_BAUDRATE_900    =    900, /*!< 900 bps baudrate. */
627    ALT_16550_BAUDRATE_1200   =   1200, /*!< 1200 bps baudrate. */
628    ALT_16550_BAUDRATE_1800   =   1800, /*!< 1800 bps baudrate. */
629    ALT_16550_BAUDRATE_2400   =   2400, /*!< 2400 bps baudrate. */
630    ALT_16550_BAUDRATE_3600   =   3600, /*!< 3600 bps baudrate. */
631    ALT_16550_BAUDRATE_4800   =   4800, /*!< 4800 bps baudrate. */
632    ALT_16550_BAUDRATE_7200   =   7200, /*!< 7200 bps baudrate. */
633    ALT_16550_BAUDRATE_9600   =   9600, /*!< 9600 bps baudrate. */
634    ALT_16550_BAUDRATE_14400  =  14400, /*!< 14400 bps baudrate. */
635    ALT_16550_BAUDRATE_19200  =  19200, /*!< 19200 bps baudrate. */
636    ALT_16550_BAUDRATE_28800  =  28800, /*!< 28800 bps baudrate. */
637    ALT_16550_BAUDRATE_38400  =  38400, /*!< 38400 bps baudrate. */
638    ALT_16550_BAUDRATE_57600  =  57600, /*!< 57600 bps baudrate. */
639    ALT_16550_BAUDRATE_115200 = 115200  /*!< 115200 bps baudrate. */
640}
641ALT_16550_BAUDRATE_t;
642
643/*!
644 * Gets the baudrate for the UART.
645 *
646 * This is done by calculating the baudrate from the divisor and the serial
647 * clock. The reported baudrate may not correspond exactly to the request
648 * baudrate.
649 *
650 * \param       handle
651 *              The UART device handle.
652 *
653 * \param       baudrate
654 *              [out] Pointer to an output paramter that contains the current
655 *              baudrate of the UART.
656 *
657 * \retval      ALT_E_SUCCESS   The operation was successful.
658 * \retval      ALT_E_ERROR     The operation failed.
659 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
660 */
661ALT_STATUS_CODE alt_16550_baudrate_get(ALT_16550_HANDLE_t * handle,
662                                       uint32_t * baudrate);
663
664/*!
665 * Sets the baudrate for the UART. This change will take effect when the UART
666 * moves from disabled to enabled.
667 *
668 * This is done by calculating the correct divisor using the request baudrate
669 * and the known serial clock.
670 *
671 * \param       handle
672 *              The UART device handle.
673 *
674 * \param       baudrate
675 *              The requested baudrate for the UART.
676 *
677 * \retval      ALT_E_SUCCESS   The operation was successful.
678 * \retval      ALT_E_ERROR     The operation failed.
679 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
680 * \retval      ALT_E_ARG_RANGE The given baudrate is not possible due to
681 *                              limitations of the baudrate divisor and/or
682 *                              serial clock.
683 */
684ALT_STATUS_CODE alt_16550_baudrate_set(ALT_16550_HANDLE_t * handle,
685                                       uint32_t baudrate);
686
687/*!
688 * Gets the baudrate divisor for the UART.
689 *
690 * The baudrate is determined by the following formula:
691 *  * Baudrate = (serial clock frequency) / (16 * divisor)
692 *
693 * \param       handle
694 *              The UART device handle.
695 *
696 * \param       divisor
697 *              [out] Pointer to an output parameter that contains the current
698 *              divisor used for baudrate generation.
699 *
700 * \retval      ALT_E_SUCCESS   The operation was successful.
701 * \retval      ALT_E_ERROR     The operation failed.
702 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
703 */
704ALT_STATUS_CODE alt_16550_divisor_get(ALT_16550_HANDLE_t * handle,
705                                      uint32_t * divisor);
706
707/*!
708 * Sets the baudrate divisor for the UART. This change will take effect when
709 * the UART moves from disabled to enabled.
710 *
711 * The baudrate is determined by the following formula:
712 *  * Baudrate = (serial clock frequency) / (16 * divisor)
713 *
714 * \param       handle
715 *              The UART device handle.
716 *
717 * \param       divisor
718 *              The specified divisor value to use for baudrate generation.
719 *              Valid values are 1 - 65535.
720 *
721 * \retval      ALT_E_SUCCESS   The operation was successful.
722 * \retval      ALT_E_ERROR     The operation failed.
723 * \retval      ALT_E_BAD_ARG   The given UART identifier is invalid or the
724 *                              specified divisor is not supported by the
725 *                              UART.
726 */
727ALT_STATUS_CODE alt_16550_divisor_set(ALT_16550_HANDLE_t * handle,
728                                      uint32_t divisor);
729
730/*!
731 * @}
732 */
733
734/*!
735 * \addtogroup UART_INT UART Interrupt Interface
736 *
737 * This group of APIs provides access, configuration, and control of the
738 * UART interrupts.
739 *
740 * @{
741 */
742
743/*!
744 * This type definition enumerates the different interrupt conditions that can
745 * be generated by the UART controller.
746 *
747 * Interrupts are listed in highest to lowest priority order.
748 */
749typedef enum ALT_16550_INT_STATUS_e
750{
751    /*!
752     * This interrupt signals that a overrun, parity, or framing error
753     * occurred, or a break event occured. The interrupt is cleared by reading
754     * the line status by calling alt_16550_line_status_get() or by disabling
755     * line status interrupts by calling alt_16550_int_disable_line().
756     */
757    ALT_16550_INT_STATUS_LINE = 0x6,
758
759    /*!
760     * This interrupt signals that some data is available to be read from the
761     * UART. The definition of some depends on whether FIFOs are enabled or
762     * not.
763     *
764     * If FIFOs are disabled, this interrupt signals that the receiver
765     * contains data. In this case, the interrupt is cleared by reading the
766     * data from the UART by calling alt_16550_read().
767     *
768     * If FIFOs are enabled, this interrupt signals that the receiver FIFO
769     * level is above the receiver trigger level specified. In this case, the
770     * interrupt is cleared by reading a sufficiently large buffer from the
771     * receiver FIFO such that the FIFO is filled below the receiver trigger
772     * level specified by calling alt_16550_fifo_read() or by adjusting the
773     * receiver trigger level appropriately by calling
774     * alt_16550_fifo_trigger_set_rx().
775     *
776     * In either case, this interrupt can also be cleared by disabling
777     * receiver interrupts by calling alt_16550_int_disable_rx().
778     */
779    ALT_16550_INT_STATUS_RX_DATA = 0x4,
780
781    /*!
782     * This interrupt signals that data is available in the receiver FIFO and
783     * that there has been no activity with the receiver FIFO for the last 4
784     * character frames. In essence, the receiver FIFO has temporarily settled
785     * thus it may be a good time to empty the receiver FIFO. This interrupt
786     * is only available if FIFOs are enabled. The interrupt is cleared by
787     * reading from the receiver FIFO by calling alt_16550_fifo_read() or by
788     * disabling receiver interrupts by calling alt_16550_int_disable_rx().
789     */
790    ALT_16550_INT_STATUS_RX_TIMEOUT = 0xC,
791
792    /*!
793     * This interrupt signals that the transmitter is idling. The definition
794     * of idling depends on whether FIFOs are enabled or not.
795     *
796     * If FIFOs are disabled, this interrupt signals that the transmitter
797     * shift register is empty. In this case, the interrupt is cleared by
798     * writing data to the UART by calling alt_16550_write().
799     *
800     * If FIFO are enabled, this interrupt signals that the transmitter FIFO
801     * level is below the transmitter trigger level specified. In this case,
802     * the interrupt is cleared by writing a sufficiently large buffer to the
803     * transmitter FIFO such that the FIFO is filled above the transmitter
804     * trigger level specified by calling alt_16550_fifo_write() or by
805     * adjusting the transmitter trigger level appropriately by calling
806     * alt_16550_fifo_trigger_set_tx().
807     *
808     * In either case, this interrupt can also be cleared by disabling
809     * transmitter interrupts by calling alt_16550_int_disable_tx().
810     */
811    ALT_16550_INT_STATUS_TX_IDLE = 0x2,
812
813    /*!
814     * Modem status interrupt pending. The interrupt is cleared by reading the
815     * modem status by calling alt_16550_modem_status_get() or by disabling
816     * modem status interrupts by calling alt_16550_int_disable_modem().
817     */
818    ALT_16550_INT_STATUS_MODEM = 0x0,
819
820    /*!
821     * No interrupts pending.
822     */
823    ALT_16550_INT_STATUS_NONE = 0x1
824}
825ALT_16550_INT_STATUS_t;
826
827/*!
828 * Enables the receiver FIFO to generate interrupts. Enabling this interrupt
829 * allows for the following interrupt signal(s):
830 *  * ALT_16550_INT_STATUS_RX_DATA
831 *  * ALT_16550_INT_STATUS_RX_TIMEOUT
832 *
833 * This interrupt is disabled by default.
834 *
835 * The FIFOs must also be enabled for this interrupt to actually be generated.
836 *
837 * \param       handle
838 *              The UART device handle.
839 *
840 * \retval      ALT_E_SUCCESS   The operation was successful.
841 * \retval      ALT_E_ERROR     The operation failed.
842 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
843 */
844ALT_STATUS_CODE alt_16550_int_enable_rx(ALT_16550_HANDLE_t * handle);
845
846/*!
847 * Disables the receiver FIFO from generating interrupts.
848 *
849 * \param       handle
850 *              The UART device handle.
851 *
852 * \retval      ALT_E_SUCCESS   The operation was successful.
853 * \retval      ALT_E_ERROR     The operation failed.
854 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
855 */
856ALT_STATUS_CODE alt_16550_int_disable_rx(ALT_16550_HANDLE_t * handle);
857
858/*!
859 * Enables the transmitter FIFO to generate interrupts. Enabling this
860 * interrupt allows for the following interrupt signal(s):
861 *  * ALT_16550_INT_STATUS_TX_IDLE
862 *
863 * This interrupt is disabled by default.
864 *
865 * The FIFOs must also be enabled for this interrupt to actually be generated.
866 *
867 * \param       handle
868 *              The UART device handle.
869 *
870 * \retval      ALT_E_SUCCESS   The operation was successful.
871 * \retval      ALT_E_ERROR     The operation failed.
872 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
873 */
874ALT_STATUS_CODE alt_16550_int_enable_tx(ALT_16550_HANDLE_t * handle);
875
876/*!
877 * Disables the transmitter FIFO from generating interrupts.
878 *
879 * \param       handle
880 *              The UART device handle.
881 *
882 * \retval      ALT_E_SUCCESS   The operation was successful.
883 * \retval      ALT_E_ERROR     The operation failed.
884 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
885 */
886ALT_STATUS_CODE alt_16550_int_disable_tx(ALT_16550_HANDLE_t * handle);
887
888/*!
889 * Enables the receiver to generate line status interrupts. Enabling this
890 * interrupt allows for the following interrupt signal(s):
891 *  * ALT_16550_INT_STATUS_LINE
892 *
893 * This interrupt is disabled by default.
894 *
895 * \param       handle
896 *              The UART device handle.
897 *
898 * \retval      ALT_E_SUCCESS   The operation was successful.
899 * \retval      ALT_E_ERROR     The operation failed.
900 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
901 */
902ALT_STATUS_CODE alt_16550_int_enable_line(ALT_16550_HANDLE_t * handle);
903
904/*!
905 * Disables the receiver from generating line status interrupts.
906 *
907 * \param       handle
908 *              The UART device handle.
909 *
910 * \retval      ALT_E_SUCCESS   The operation was successful.
911 * \retval      ALT_E_ERROR     The operation failed.
912 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
913 */
914ALT_STATUS_CODE alt_16550_int_disable_line(ALT_16550_HANDLE_t * handle);
915
916/*!
917 * Enables the UART to generate modem status interrupts. Enabling this
918 * interrupt allows for the following interrupt signal(s):
919 *  * ALT_16550_INT_STATUS_MODEM
920 *
921 * This interrupt is disabled by default.
922 *
923 * \param       handle
924 *              The UART device handle.
925 *
926 * \retval      ALT_E_SUCCESS   The operation was successful.
927 * \retval      ALT_E_ERROR     The operation failed.
928 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
929 */
930ALT_STATUS_CODE alt_16550_int_enable_modem(ALT_16550_HANDLE_t * handle);
931
932/*!
933 * Disables the UART from generate modem status interrupts.
934 *
935 * \param       handle
936 *              The UART device handle.
937 *
938 * \retval      ALT_E_SUCCESS   The operation was successful.
939 * \retval      ALT_E_ERROR     The operation failed.
940 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
941 */
942ALT_STATUS_CODE alt_16550_int_disable_modem(ALT_16550_HANDLE_t * handle);
943
944/*!
945 * Disables all interrupts on the UART.
946 *
947 * \param       handle
948 *              The UART device handle.
949 *
950 * \retval      ALT_E_SUCCESS   The operation was successful.
951 * \retval      ALT_E_ERROR     The operation failed.
952 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
953 */
954ALT_STATUS_CODE alt_16550_int_disable_all(ALT_16550_HANDLE_t * handle);
955
956/*!
957 * Queries the interrupt status of the UART. This returns the highest priority
958 * interrupt pending. The appropriate interrupts must be enabled for them be
959 * generated in the UART.
960 *
961 * \param       handle
962 *              The UART device handle.
963 *
964 * \param       status
965 *              [out] Pointer to an output parameter that contains the current
966 *              interrupt status of the UART.
967 *
968 * \retval      ALT_E_SUCCESS   The operation was successful.
969 * \retval      ALT_E_ERROR     The operation failed.
970 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
971 */
972ALT_STATUS_CODE  alt_16550_int_status_get(ALT_16550_HANDLE_t * handle,
973                                          ALT_16550_INT_STATUS_t * status);
974
975/*!
976 * @}
977 */
978
979/*!
980 * \addtogroup UART_MODEM UART Modem Interface
981 *
982 * This group of APIs provides access, configuration, and control of the UART
983 * Modem interface.
984 *
985 * @{
986 */
987
988/*!
989 * This type definition enumerates the set of UART modem status conditions as
990 * register mask values.
991 */
992typedef enum ALT_16550_MODEM_STATUS_e
993{
994    /*!
995     * Data Carrier Detect. This status indicates that the carrier has been
996     * detected by the modem. It corresponds to an inverted dcd_n input. DCD
997     * is unasserted when dcd_n is logic 1 and asserted when dcd_n is logic 0.
998     */
999    ALT_16550_MODEM_STATUS_DCD = 1 << 7,
1000
1001    /*!
1002     * Ring Indicator. This status indicates that the telephone ringing signal
1003     * has been redeived by the modem. It corresponds to an inverted ri_n
1004     * input. RI is unasserted when ri_n is logic 1 and asserted when ri_n is
1005     * logic 0.
1006     */
1007    ALT_16550_MODEM_STATUS_RI = 1 << 6,
1008
1009    /*!
1010     * Data Set Ready. This status indicates that the modem is ready to
1011     * establish communications with the UART. It corresponds to an inverted
1012     * dsr_n input. DSR is unasserted when dsr_n is logic 1 and asserted when
1013     * dsr_n is logic 0.
1014     */
1015    ALT_16550_MODEM_STATUS_DSR = 1 << 5,
1016
1017    /*!
1018     * Clear To Send. This status indicates the current state of the modem
1019     * cts_n line. It corresponds to an inverted cts_n input. CTS is
1020     * unasserted when cts_n is logic 1 and asserted when cts_n is logic 0.
1021     */
1022    ALT_16550_MODEM_STATUS_CTS = 1 << 4,
1023
1024    /*!
1025     * Delta Data Carrier Detect. This status condition indicates that the
1026     * Data Carrier Detect has changed since the last time the modem status
1027     * was read. Reading the modem status clears this status. For more
1028     * information about the Data Carrier Detect status, see
1029     * ALT_16550_MODEM_STATUS_DCD.
1030     */
1031    ALT_16550_MODEM_STATUS_DDCD = 1 << 3,
1032
1033    /*!
1034     * Trailing Edge of Ring Indicator. This status indicates that the Ring
1035     * Indicator has changed from asserted to unasserted. Reading the modem
1036     * status will clear this status. For more information about the Ring
1037     * Indicator status, reference ALT_16550_MODEM_STATUS_RI.
1038     */
1039    ALT_16550_MODEM_STATUS_TERI = 1 << 2,
1040
1041    /*!
1042     * Delta Data Set Ready. This status condition indicates that the Data Set
1043     * Ready has changed since the last time the modem status was read.
1044     * Reading the modem status will clear this status. For more information
1045     * about the Data Set Ready status, see ALT_16550_MODEM_STATUS_DSR.
1046     */
1047    ALT_16550_MODEM_STATUS_DDSR = 1 << 1,
1048
1049    /*!
1050     * Delta Clear To Send. This status condition indicates that the Clear To
1051     * Send has changed since the last time the modem status was read. Reading
1052     * the modem status will clear this status. For more information about the
1053     * Clear To Send status, see ALT_16550_MODEM_STATUS_CTS.
1054     */
1055    ALT_16550_MODEM_STATUS_DCTS = 1 << 0
1056}
1057ALT_16550_MODEM_STATUS_t;
1058
1059/*!
1060 * Enables automatic flow control in the UART modem. When in this mode, the
1061 * rts_n is gated with the threshold trigger condition of the receiver FIFO.
1062 *
1063 * The Altera 16550 Compatible Soft IP UART may not have this option enabled.
1064 *
1065 * The FIFOs must be enabled for flow control to be used.
1066 *
1067 * The recommended bring up for flow control is as follows:
1068 *  * Enable automatic flow control by calling alt_16550_flowcontrol_enable().
1069 *    This will allow both the receiver FIFO and user RTS to control the rts_n
1070 *    output. Because the user RTS is not enabled, the rts_n will be inactive
1071 *    high.
1072 *  * Enable RTS by calling alt_16550_modem_enable_rts(). This will give the
1073 *    receiver FIFO to have full control of the rts_n output.
1074 *
1075 * \param       handle
1076 *              The UART device handle.
1077 *
1078 * \retval      ALT_E_SUCCESS   The operation was successful.
1079 * \retval      ALT_E_ERROR     The operation failed.
1080 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1081 */
1082ALT_STATUS_CODE alt_16550_flowcontrol_enable(ALT_16550_HANDLE_t * handle);
1083
1084/*!
1085 * Disables automatic flow control in the UART modem.
1086 *
1087 * The recommended bring down for flow control is as follows:
1088 *  * Disable RTS by calling alt_16550_modem_disable_rts(). This will disable
1089 *    generation of the rts_n ouput.
1090 *  * Disable automatic flow control by calling
1091 *    alt_16550_flowcontrol_disable().
1092 *
1093 * The receiver FIFO will still be active after these steps.
1094 *
1095 * \param       handle
1096 *              The UART device handle.
1097 *
1098 * \retval      ALT_E_SUCCESS   The operation was successful.
1099 * \retval      ALT_E_ERROR     The operation failed.
1100 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1101 */
1102ALT_STATUS_CODE alt_16550_flowcontrol_disable(ALT_16550_HANDLE_t * handle);
1103
1104/*!
1105 * Puts the UART in loopback mode. This is used for diagnostic and test
1106 * purposes.
1107 *
1108 * The SoCFPGA UARTs does not support automatic flow control when in loopback
1109 * mode.
1110 *
1111 * The Altera 16550 Compatible Soft IP UART implements this in 13.0sp1 and
1112 * later. Setting this has no effect with 13.0.
1113 *
1114 * When in this mode, the modem control inputs (dsr_n, cts_n, ri_n, dcd_n) are
1115 * disconnected and the modem control outputs (dtr_n, rts_n, out1_n, out2_n)
1116 * are held inactive high externally and internally looped back to the inputs.
1117 *
1118 * \param       handle
1119 *              The UART device handle.
1120 *
1121 * \retval      ALT_E_SUCCESS   The operation was successful.
1122 * \retval      ALT_E_ERROR     The operation failed.
1123 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1124 */
1125ALT_STATUS_CODE alt_16550_loopback_enable(ALT_16550_HANDLE_t * handle);
1126
1127/*!
1128 * Takes the UART out of loopback mode.
1129 *
1130 * \param       handle
1131 *              The UART device handle.
1132 *
1133 * \retval      ALT_E_SUCCESS   The operation was successful.
1134 * \retval      ALT_E_ERROR     The operation failed.
1135 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1136 */
1137ALT_STATUS_CODE alt_16550_loopback_disable(ALT_16550_HANDLE_t * handle);
1138
1139/*!
1140 * Asserts the OUT1 output. OUT1 is inverted then driven out to out1_n.
1141 *
1142 * There are special considerations when the UART is in loopback mode. See
1143 * alt_16550_loopback_enable() for more information.
1144 *
1145 * \param       handle
1146 *              The UART device handle.
1147 *
1148 * \retval      ALT_E_SUCCESS   The operation was successful.
1149 * \retval      ALT_E_ERROR     The operation failed.
1150 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1151 */
1152ALT_STATUS_CODE alt_16550_modem_enable_out1(ALT_16550_HANDLE_t * handle);
1153
1154/*!
1155 * Unasserts the OUT1 output.  OUT1 is inverted then driven out to out1_n.
1156 *
1157 * There are special considerations when the UART is in loopback mode. See
1158 * alt_16550_loopback_enable() for more information.
1159 *
1160 * \param       handle
1161 *              The UART device handle.
1162 *
1163 * \retval      ALT_E_SUCCESS   The operation was successful.
1164 * \retval      ALT_E_ERROR     The operation failed.
1165 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1166 */
1167ALT_STATUS_CODE alt_16550_modem_disable_out1(ALT_16550_HANDLE_t * handle);
1168
1169/*!
1170 * Asserts the OUT2 output. OUT2 is inverted then driven out to out2_n.
1171 *
1172 * There are special considerations when the UART is in loopback mode. See
1173 * alt_16550_loopback_enable() for more information.
1174 *
1175 * \param       handle
1176 *              The UART device handle.
1177 *
1178 * \retval      ALT_E_SUCCESS   The operation was successful.
1179 * \retval      ALT_E_ERROR     The operation failed.
1180 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1181 */
1182ALT_STATUS_CODE alt_16550_modem_enable_out2(ALT_16550_HANDLE_t * handle);
1183
1184/*!
1185 * Unasserts the OUT2 output. OUT2 is inverted then driven out to out2_n.
1186 *
1187 * There are special considerations when the UART is in loopback mode. See
1188 * alt_16550_loopback_enable() for more information.
1189 *
1190 * \param       handle
1191 *              The UART device handle.
1192 *
1193 * \retval      ALT_E_SUCCESS   The operation was successful.
1194 * \retval      ALT_E_ERROR     The operation failed.
1195 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1196 */
1197ALT_STATUS_CODE alt_16550_modem_disable_out2(ALT_16550_HANDLE_t * handle);
1198
1199/*!
1200 * Asserts the RTS (Request To Send) output. RTS is inverted then driven out
1201 * to rts_n. RTS is used to inform the modem that the UART is ready to receive
1202 * data.
1203 *
1204 * There are special considerations when the UART is in automatic flow control
1205 * mode. See alt_16550_flowcontrol_enable() for more information.
1206 *
1207 * There are special considerations when the UART is in loopback mode. See
1208 * alt_16550_loopback_enable() for more information.
1209 *
1210 * \param       handle
1211 *              The UART device handle.
1212 *
1213 * \retval      ALT_E_SUCCESS   The operation was successful.
1214 * \retval      ALT_E_ERROR     The operation failed.
1215 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1216 */
1217ALT_STATUS_CODE alt_16550_modem_enable_rts(ALT_16550_HANDLE_t * handle);
1218
1219/*!
1220 * Deaserts the RTS (Request To Send) output. RTS is inverted then driven out
1221 * to rts_n.
1222 *
1223 * There are special considerations when the UART is in automatic flow control
1224 * mode. See alt_16550_flowcontrol_enable() for more information.
1225 *
1226 * There are special considerations when the UART is in loopback mode. See
1227 * alt_16550_loopback_enable() for more information.
1228 *
1229 * \param       handle
1230 *              The UART device handle.
1231 *
1232 * \retval      ALT_E_SUCCESS   The operation was successful.
1233 * \retval      ALT_E_ERROR     The operation failed.
1234 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1235 */
1236ALT_STATUS_CODE alt_16550_modem_disable_rts(ALT_16550_HANDLE_t * handle);
1237
1238/*!
1239 * Asserts the DTR (Data Terminal Ready) output. DTR is inverted then driven
1240 * out to dtr_n. DTR is used to inform the modem that UART is ready to
1241 * establish communications.
1242 *
1243 * There are special considerations when the UART is in loopback mode. See
1244 * alt_16550_loopback_enable() for more information.
1245 *
1246 * \param       handle
1247 *              The UART device handle.
1248 *
1249 * \retval      ALT_E_SUCCESS   The operation was successful.
1250 * \retval      ALT_E_ERROR     The operation failed.
1251 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1252 */
1253ALT_STATUS_CODE alt_16550_modem_enable_dtr(ALT_16550_HANDLE_t * handle);
1254
1255/*!
1256 * Deasserts the DTR (Data Terminal Ready) output. DTR is inverted then driven
1257 * out to dtr_n.
1258 *
1259 * There are special considerations when the UART is in loopback mode. See
1260 * alt_16550_loopback_enable() for more information.
1261 *
1262 * \param       handle
1263 *              The UART device handle.
1264 *
1265 * \retval      ALT_E_SUCCESS   The operation was successful.
1266 * \retval      ALT_E_ERROR     The operation failed.
1267 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1268 */
1269ALT_STATUS_CODE alt_16550_modem_disable_dtr(ALT_16550_HANDLE_t * handle);
1270
1271/*!
1272 * Reads the modem status from the UART.
1273 *
1274 * \param       handle
1275 *              The UART device handle.
1276 *
1277 * \param       status
1278 *              [out] Pointer to an output parameter that contains the current
1279 *              modem status of the UART as a register mask.
1280 *
1281 * \retval      ALT_E_SUCCESS   The operation was successful.
1282 * \retval      ALT_E_ERROR     The operation failed.
1283 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1284 */
1285ALT_STATUS_CODE alt_16550_modem_status_get(ALT_16550_HANDLE_t * handle,
1286                                           uint32_t * status);
1287
1288/*!
1289 * @}
1290 */
1291
1292/*!
1293 * \addtogroup UART_LINE UART Line Interface
1294 *
1295 * This group of APIs provides access, configuration, and control of the UART
1296 * Line interface.
1297 *
1298 * @{
1299 */
1300
1301/*!
1302 * This type definition enumerates the supported databits per frame.
1303 */
1304typedef enum ALT_16550_DATABITS_e
1305{
1306    /*!
1307     * This option selects 5 databits per frame.
1308     */
1309    ALT_16550_DATABITS_5 = 0,
1310
1311    /*!
1312     * This option selects 6 databits per frame.
1313     */
1314    ALT_16550_DATABITS_6 = 1,
1315
1316    /*!
1317     * This option selects 7 databits per frame.
1318     */
1319    ALT_16550_DATABITS_7 = 2,
1320
1321    /*!
1322     * This option selects 8 databits per frame.
1323     */
1324    ALT_16550_DATABITS_8 = 3
1325}
1326ALT_16550_DATABITS_t;
1327
1328/*!
1329 * This type definition enumerates the supported stopbits per frame.
1330 */
1331typedef enum ALT_16550_STOPBITS_e
1332{
1333    /*!
1334     * This options specifies 1 stopbit per frame.
1335     */
1336    ALT_16550_STOPBITS_1 = 0,
1337
1338    /*!
1339     * This options specifies 2 stopbits per frame. If the frame is
1340     * configured with 5 databits, 1.5 stopbits is used instead.
1341     */
1342    ALT_16550_STOPBITS_2 = 1
1343}
1344ALT_16550_STOPBITS_t;
1345
1346/*!
1347 * This type definition enumerates the possible parity to use per frame.
1348 */
1349typedef enum ALT_16550_PARITY_e
1350{
1351    /*!
1352     * This option disables the parity error detection bit in the data frame.
1353     */
1354    ALT_16550_PARITY_DISABLE = 0,
1355
1356    /*!
1357     * This option enables the odd parity error detection bit in the data
1358     * frame.
1359     */
1360    ALT_16550_PARITY_ODD = 1,
1361
1362    /*!
1363     * This option enables the even parity error detection bit in the data
1364     * frame.
1365     */
1366    ALT_16550_PARITY_EVEN = 2
1367}
1368ALT_16550_PARITY_t;
1369
1370/*!
1371 * This type definition enumerates the set of UART line status conditions as
1372 * register mask values.
1373 */
1374typedef enum ALT_16550_LINE_STATUS_e
1375{
1376    /*!
1377     * Receiver FIFO Error. This status indicates that one or more parity
1378     * error, framing error, or break indication exists in the receiver FIFO.
1379     * It is only set when FIFO is enabled. This status cleared when line
1380     * status is read, the character with the issue is at the top of the FIFO,
1381     * and when no other issues exist in the FIFO.
1382     */
1383    ALT_16550_LINE_STATUS_RFE = 1 << 7,
1384
1385    /*!
1386     * Transmitter EMpTy (Empty). This status indicates that transmitter shift
1387     * register is empty. If FIFOs are enabled, the status is set when the
1388     * transmitter FIFO is also empty. This status is cleared when the
1389     * transmitter shift registers is loaded by writing to the UART
1390     * transmitter buffer or transmitter FIFO if FIFOs are enabled. This is
1391     * done by calling alt_16550_write() and alt_16550_fifo_write()
1392     * respectively.
1393     */
1394    ALT_16550_LINE_STATUS_TEMT = 1 << 6,
1395
1396    /*!
1397     * Transmitter Holding Register Empty. This status indicates that the
1398     * transmitter will run out of data soon. The definition of soon depends
1399     * on whether the FIFOs are enabled.
1400     *
1401     * If FIFOs are disabled, this status indicates that the transmitter will
1402     * run out of data to send after the current transmit shift register
1403     * completes. In this case, this status is cleared when the data is
1404     * written to the UART. This can be done by calling alt_16550_write().
1405     *
1406     * If FIFOs are enabled, this status indicates that the transmitter FIFO
1407     * level is below the transmitter trigger level specified. In this case,
1408     * this status is cleared by writing a sufficiently large buffer to the
1409     * transmitter FIFO such that the FIFO is filled above the transmitter
1410     * trigger level specified by calling alt_16550_fifo_write() or by
1411     * adjusting the transmitter trigger level appropriately by calling
1412     * alt_16550_fifo_trigger_set_tx().
1413     *
1414     * \internal
1415     * The implementation of the UART driver always ensures that IER[7] is
1416     * set. This means that the UART always has Programmable THRE (Transmitter
1417     * Holding Register Empty) Interrupt Mode Enable (PTIME) enabled.
1418     * \endinternal
1419     */
1420    ALT_16550_LINE_STATUS_THRE = 1 << 5,
1421
1422    /*!
1423     * Break Interrupt. This status indicates that a break interrupt sequence
1424     * is detected in the incoming serial data. This happens when the the data
1425     * is 0 for longer than a frame would normally be transmitted. The break
1426     * interrupt status is cleared by reading the line status by calling
1427     * alt_16550_line_status_get().
1428     *
1429     * If FIFOs are enabled, this status will be set when the character with
1430     * the break interrupt status is at the top of the receiver FIFO.
1431     */
1432    ALT_16550_LINE_STATUS_BI = 1 << 4,
1433
1434    /*!
1435     * Framing Error. This status indicates that a framing error occurred in
1436     * the receiver. This happens when the receiver detects a missing or
1437     * incorrect number of stopbit(s).
1438     *
1439     * If FIFOs are enabled, this status will be set when the character with
1440     * the framing error is at the top of the FIFO. When a framing error
1441     * occurs, the UART attempts to resynchronize with the transmitting UART.
1442     * This status is also set if break interrupt occurred.
1443     */
1444    ALT_16550_LINE_STATUS_FE = 1 << 3,
1445
1446    /*!
1447     * Parity Error. This status indicates that a parity error occurred in the
1448     * receiver.
1449     *
1450     * If FIFOs are enabled, this status will be set when the character with
1451     * the parity error is at the top of the receiver FIFO. This status is
1452     * also set if a break interrupt occurred.
1453     */
1454    ALT_16550_LINE_STATUS_PE = 1 << 2,
1455
1456    /*!
1457     * Overrun Error. This status indicates that an overrun occurred in the
1458     * receiver.
1459     *
1460     * If FIFOs are disabled, the arriving character will overwrite the
1461     * existing character in the receiver. Any previously existing
1462     * character(s) will be lost.
1463     *
1464     * If FIFOs are disabled, the arriving character will be discarded. The
1465     * buffer will continue to contain the preexisting characters.
1466     */
1467    ALT_16550_LINE_STATUS_OE = 1 << 1,
1468
1469    /*!
1470     * Data Ready. This status indicates that the receiver or receiver FIFO
1471     * contains at least one character.
1472     */
1473    ALT_16550_LINE_STATUS_DR = 1 << 0
1474}
1475ALT_16550_LINE_STATUS_t;
1476
1477/*!
1478 * Sets the configuration for a given character frame.
1479 *
1480 * \param       handle
1481 *              The UART device handle.
1482 *
1483 * \param       databits
1484 *              The number of databits for each character frame.
1485 *
1486 * \param       parity
1487 *              The parity to use for each character frame.
1488 *
1489 * \param       stopbits
1490 *              The number of stopbits for each character frame.
1491 *
1492 * \retval      ALT_E_SUCCESS   The operation was successful.
1493 * \retval      ALT_E_ERROR     The operation failed.
1494 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1495 */
1496ALT_STATUS_CODE alt_16550_line_config_set(ALT_16550_HANDLE_t * handle,
1497                                          ALT_16550_DATABITS_t databits,
1498                                          ALT_16550_PARITY_t parity,
1499                                          ALT_16550_STOPBITS_t stopbits);
1500
1501/*!
1502 * Starts transmitting a break condition by transmitting a logic 0 state
1503 * longer than a frame would normally be transmitted.
1504 *
1505 * \param       handle
1506 *              The UART device handle.
1507 *
1508 * \retval      ALT_E_SUCCESS   The operation was successful.
1509 * \retval      ALT_E_ERROR     The operation failed.
1510 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1511 */
1512ALT_STATUS_CODE alt_16550_line_break_enable(ALT_16550_HANDLE_t * handle);
1513
1514/*!
1515 * Stops transmitting a break condition.
1516 *
1517 * \param       handle
1518 *              The UART device handle.
1519 *
1520 * \retval      ALT_E_SUCCESS   The operation was successful.
1521 * \retval      ALT_E_ERROR     The operation failed.
1522 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1523 */
1524ALT_STATUS_CODE alt_16550_line_break_disable(ALT_16550_HANDLE_t * handle);
1525
1526/*!
1527 * Reads the line status from the UART.
1528 *
1529 * \param       handle
1530 *              The UART device handle.
1531 *
1532 * \param       status
1533 *              [out] Pointer to an output parameter that contains the current
1534 *              line status of the UART.
1535 *
1536 * \retval      ALT_E_SUCCESS   The operation was successful.
1537 * \retval      ALT_E_ERROR     The operation failed.
1538 * \retval      ALT_E_BAD_ARG   The given UART device handle is invalid.
1539 */
1540ALT_STATUS_CODE alt_16550_line_status_get(ALT_16550_HANDLE_t * handle,
1541                                          uint32_t * status);
1542
1543/*!
1544 * @}
1545 */
1546
1547/*!
1548 * @}
1549 */
1550
1551#ifdef __cplusplus
1552}
1553#endif
1554
1555#endif /* __ALT_16550_UART_H__ */
Note: See TracBrowser for help on using the repository browser.