1 /******************************************************************************
3 * Copyright (C) 2010 - 2014 Xilinx, Inc. All rights reserved.
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to deal
7 * in the Software without restriction, including without limitation the rights
8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 * copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
15 * Use of the Software is limited solely to applications:
16 * (a) running on a Xilinx device, or
17 * (b) that interact with a Xilinx device through a bus or interconnect.
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22 * XILINX BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
23 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
24 * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * Except as contained in this notice, the name of the Xilinx shall not be used
28 * in advertising or otherwise to promote the sale, use or other dealings in
29 * this Software without prior written authorization from Xilinx.
31 ******************************************************************************/
32 /****************************************************************************/
36 * @addtogroup uartps_v2_1
40 * This driver supports the following features:
42 * - Dynamic data format (baud rate, data bits, stop bits, parity)
44 * - Interrupt driven mode
45 * - Transmit and receive FIFOs (32 byte FIFO depth)
46 * - Access to the external modem control lines
48 * <b>Initialization & Configuration</b>
50 * The XUartPs_Config structure is used by the driver to configure itself.
51 * Fields inside this structure are properties of XUartPs based on its hardware
54 * To support multiple runtime loading and initialization strategies employed
55 * by various operating systems, the driver instance can be initialized in the
58 * - XUartPs_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddr) - Uses a
59 * configuration structure provided by the caller. If running in a system
60 * with address translation, the parameter EffectiveAddr should be the
65 * The UART has an internal baud rate generator, which furnishes the baud rate
66 * clock for both the receiver and the transmitter. Ther input clock frequency
67 * can be either the master clock or the master clock divided by 8, configured
68 * through the mode register.
70 * Accompanied with the baud rate divider register, the baud rate is determined
73 * baud_rate = input_clock / (bgen * (bdiv + 1)
75 * where bgen is the value of the baud rate generator, and bdiv is the value of
80 * The FIFOs are not flushed when the driver is initialized, but a function is
81 * provided to allow the user to reset the FIFOs if desired.
83 * The driver defaults to no interrupts at initialization such that interrupts
84 * must be enabled if desired. An interrupt is generated for one of the
85 * following conditions.
87 * - A change in the modem signals
88 * - Data in the receive FIFO for a configuable time without receiver activity
92 * - Transmit FIFO is full
93 * - Transmit FIFO is empty
94 * - Receive FIFO is full
95 * - Receive FIFO is empty
96 * - Data in the receive FIFO equal to the receive threshold
98 * The application can control which interrupts are enabled using the
99 * XUartPs_SetInterruptMask() function.
101 * In order to use interrupts, it is necessary for the user to connect the
102 * driver interrupt handler, XUartPs_InterruptHandler(), to the interrupt
103 * system of the application. A separate handler should be provided by the
104 * application to communicate with the interrupt system, and conduct
105 * application specific interrupt handling. An application registers its own
106 * handler through the XUartPs_SetHandler() function.
108 * <b>Data Transfer</b>
110 * The functions, XUartPs_Send() and XUartPs_Recv(), are provided in the
111 * driver to allow data to be sent and received. They can be used in either
112 * polled or interrupt mode.
116 * The default configuration for the UART after initialization is:
118 * - 9,600 bps or XPAR_DFT_BAUDRATE if defined
122 * - FIFO's are enabled with a receive threshold of 8 bytes
123 * - The RX timeout is enabled with a timeout of 1 (4 char times)
126 * MODIFICATION HISTORY:
128 * Ver Who Date Changes
129 * ----- ------ -------- ----------------------------------------------
130 * 1.00a drg/jz 01/12/10 First Release
131 * 1.00a sdm 09/27/11 Fixed compiler warnings and also a bug
132 * in XUartPs_SetFlowDelay where the value was not
133 * being written to the register.
134 * 1.01a sdm 12/20/11 Removed the InputClockHz parameter from the XUartPs
135 * instance structure and the driver is updated to use
136 * InputClockHz parameter from the XUartPs_Config config
138 * Added a parameter to XUartPs_Config structure which
139 * specifies whether the user has selected Modem pins
140 * to be connected to MIO or FMIO.
141 * Added the tcl file to generate the xparameters.h
142 * 1.02a sg 05/16/12 Changed XUARTPS_RXWM_MASK to 0x3F for CR 652540 fix.
143 * 1.03a sg 07/16/12 Updated XUARTPS_FORMAT_7_BITS and XUARTPS_FORMAT_6_BITS
144 * with the correct values for CR 666724
145 * Added defines for XUARTPS_IXR_TOVR, XUARTPS_IXR_TNFUL
146 * and XUARTPS_IXR_TTRIG.
147 * Modified the name of these defines
148 * XUARTPS_MEDEMSR_DCDX to XUARTPS_MODEMSR_DDCD
149 * XUARTPS_MEDEMSR_RIX to XUARTPS_MODEMSR_TERI
150 * XUARTPS_MEDEMSR_DSRX to XUARTPS_MODEMSR_DDSR
151 * XUARTPS_MEDEMSR_CTSX to XUARTPS_MODEMSR_DCTS
152 * 1.05a hk 08/22/13 Added API for uart reset and related
153 * constant definitions.
154 * 2.0 hk 03/07/14 Version number revised.
155 * 2.1 hk 04/16/14 Change XUARTPS_MAX_RATE to 921600. CR# 780625.
159 *****************************************************************************/
161 #ifndef XUARTPS_H /* prevent circular inclusions */
162 #define XUARTPS_H /* by using protection macros */
168 /***************************** Include Files ********************************/
170 #include "xil_types.h"
171 #include "xil_assert.h"
173 #include "xuartps_hw.h"
175 /************************** Constant Definitions ****************************/
178 * The following constants indicate the max and min baud rates and these
179 * numbers are based only on the testing that has been done. The hardware
180 * is capable of other baud rates.
182 #define XUARTPS_MAX_RATE 921600
183 #define XUARTPS_MIN_RATE 110
185 #define XUARTPS_DFT_BAUDRATE 115200 /* Default baud rate */
187 /** @name Configuration options
191 * These constants specify the options that may be set or retrieved
192 * with the driver, each is a unique bit mask such that multiple options
193 * may be specified. These constants indicate the available options
198 #define XUARTPS_OPTION_SET_BREAK 0x0080 /**< Starts break transmission */
199 #define XUARTPS_OPTION_STOP_BREAK 0x0040 /**< Stops break transmission */
200 #define XUARTPS_OPTION_RESET_TMOUT 0x0020 /**< Reset the receive timeout */
201 #define XUARTPS_OPTION_RESET_TX 0x0010 /**< Reset the transmitter */
202 #define XUARTPS_OPTION_RESET_RX 0x0008 /**< Reset the receiver */
203 #define XUARTPS_OPTION_ASSERT_RTS 0x0004 /**< Assert the RTS bit */
204 #define XUARTPS_OPTION_ASSERT_DTR 0x0002 /**< Assert the DTR bit */
205 #define XUARTPS_OPTION_SET_FCM 0x0001 /**< Turn on flow control mode */
209 /** @name Channel Operational Mode
211 * The UART can operate in one of four modes: Normal, Local Loopback, Remote
212 * Loopback, or automatic echo.
217 #define XUARTPS_OPER_MODE_NORMAL 0x00 /**< Normal Mode */
218 #define XUARTPS_OPER_MODE_AUTO_ECHO 0x01 /**< Auto Echo Mode */
219 #define XUARTPS_OPER_MODE_LOCAL_LOOP 0x02 /**< Local Loopback Mode */
220 #define XUARTPS_OPER_MODE_REMOTE_LOOP 0x03 /**< Remote Loopback Mode */
224 /** @name Data format values
226 * These constants specify the data format that the driver supports.
227 * The data format includes the number of data bits, the number of stop
232 #define XUARTPS_FORMAT_8_BITS 0 /**< 8 data bits */
233 #define XUARTPS_FORMAT_7_BITS 2 /**< 7 data bits */
234 #define XUARTPS_FORMAT_6_BITS 3 /**< 6 data bits */
236 #define XUARTPS_FORMAT_NO_PARITY 4 /**< No parity */
237 #define XUARTPS_FORMAT_MARK_PARITY 3 /**< Mark parity */
238 #define XUARTPS_FORMAT_SPACE_PARITY 2 /**< parity */
239 #define XUARTPS_FORMAT_ODD_PARITY 1 /**< Odd parity */
240 #define XUARTPS_FORMAT_EVEN_PARITY 0 /**< Even parity */
242 #define XUARTPS_FORMAT_2_STOP_BIT 2 /**< 2 stop bits */
243 #define XUARTPS_FORMAT_1_5_STOP_BIT 1 /**< 1.5 stop bits */
244 #define XUARTPS_FORMAT_1_STOP_BIT 0 /**< 1 stop bit */
247 /** @name Callback events
249 * These constants specify the handler events that an application can handle
250 * using its specific handler function. Note that these constants are not bit
251 * mask, so only one event can be passed to an application at a time.
255 #define XUARTPS_EVENT_RECV_DATA 1 /**< Data receiving done */
256 #define XUARTPS_EVENT_RECV_TOUT 2 /**< A receive timeout occurred */
257 #define XUARTPS_EVENT_SENT_DATA 3 /**< Data transmission done */
258 #define XUARTPS_EVENT_RECV_ERROR 4 /**< A receive error detected */
259 #define XUARTPS_EVENT_MODEM 5 /**< Modem status changed */
263 /**************************** Type Definitions ******************************/
266 * This typedef contains configuration information for the device.
269 u16 DeviceId; /**< Unique ID of device */
270 u32 BaseAddress; /**< Base address of device (IPIF) */
271 u32 InputClockHz;/**< Input clock frequency */
272 int ModemPinsConnected; /** Specifies whether modem pins are connected
277 * Keep track of state information about a data buffer in the interrupt mode.
281 unsigned int RequestedBytes;
282 unsigned int RemainingBytes;
286 * Keep track of data format setting of a device.
289 u32 BaudRate; /**< In bps, ie 1200 */
290 u32 DataBits; /**< Number of data bits */
291 u32 Parity; /**< Parity */
292 u8 StopBits; /**< Number of stop bits */
295 /******************************************************************************/
297 * This data type defines a handler that an application defines to communicate
298 * with interrupt system to retrieve state information about an application.
300 * @param CallBackRef is a callback reference passed in by the upper layer
301 * when setting the handler, and is passed back to the upper layer
302 * when the handler is called. It is used to find the device driver
304 * @param Event contains one of the event constants indicating events that
306 * @param EventData contains the number of bytes sent or received at the
307 * time of the call for send and receive events and contains the
308 * modem status for modem events.
310 ******************************************************************************/
311 typedef void (*XUartPs_Handler) (void *CallBackRef, u32 Event,
312 unsigned int EventData);
315 * The XUartPs driver instance data structure. A pointer to an instance data
316 * structure is passed around by functions to refer to a specific driver
320 XUartPs_Config Config; /* Configuration data structure */
321 u32 InputClockHz; /* Input clock frequency */
322 u32 IsReady; /* Device is initialized and ready */
323 u32 BaudRate; /* Current baud rate */
325 XUartPsBuffer SendBuffer;
326 XUartPsBuffer ReceiveBuffer;
328 XUartPs_Handler Handler;
329 void *CallBackRef; /* Callback reference for event handler */
333 /***************** Macros (Inline Functions) Definitions ********************/
335 /****************************************************************************/
337 * Get the UART Channel Status Register.
339 * @param InstancePtr is a pointer to the XUartPs instance.
341 * @return The value read from the register.
343 * @note C-Style signature:
344 * u16 XUartPs_GetChannelStatus(XUartPs *InstancePtr)
346 ******************************************************************************/
347 #define XUartPs_GetChannelStatus(InstancePtr) \
348 Xil_In32(((InstancePtr)->Config.BaseAddress) + XUARTPS_SR_OFFSET)
350 /****************************************************************************/
352 * Get the UART Mode Control Register.
354 * @param InstancePtr is a pointer to the XUartPs instance.
356 * @return The value read from the register.
358 * @note C-Style signature:
359 * u32 XUartPs_GetControl(XUartPs *InstancePtr)
361 ******************************************************************************/
362 #define XUartPs_GetModeControl(InstancePtr) \
363 Xil_In32(((InstancePtr)->Config.BaseAddress) + XUARTPS_CR_OFFSET)
365 /****************************************************************************/
367 * Set the UART Mode Control Register.
369 * @param InstancePtr is a pointer to the XUartPs instance.
370 * @param RegisterValue is the value to be written to the register.
374 * @note C-Style signature:
375 * void XUartPs_SetModeControl(XUartPs *InstancePtr, u16 RegisterValue)
377 ******************************************************************************/
378 #define XUartPs_SetModeControl(InstancePtr, RegisterValue) \
379 Xil_Out32(((InstancePtr)->Config.BaseAddress) + XUARTPS_CR_OFFSET, \
382 /****************************************************************************/
384 * Enable the transmitter and receiver of the UART.
386 * @param InstancePtr is a pointer to the XUartPs instance.
390 * @note C-Style signature:
391 * void XUartPs_EnableUart(XUartPs *InstancePtr)
393 ******************************************************************************/
394 #define XUartPs_EnableUart(InstancePtr) \
395 Xil_Out32(((InstancePtr)->Config.BaseAddress + XUARTPS_CR_OFFSET), \
396 ((Xil_In32((InstancePtr)->Config.BaseAddress + XUARTPS_CR_OFFSET) & \
397 ~XUARTPS_CR_EN_DIS_MASK) | (XUARTPS_CR_RX_EN | XUARTPS_CR_TX_EN)))
399 /****************************************************************************/
401 * Disable the transmitter and receiver of the UART.
403 * @param InstancePtr is a pointer to the XUartPs instance.
407 * @note C-Style signature:
408 * void XUartPs_DisableUart(XUartPs *InstancePtr)
410 ******************************************************************************/
411 #define XUartPs_DisableUart(InstancePtr) \
412 Xil_Out32(((InstancePtr)->Config.BaseAddress + XUARTPS_CR_OFFSET), \
413 (((Xil_In32((InstancePtr)->Config.BaseAddress + XUARTPS_CR_OFFSET)) & \
414 ~XUARTPS_CR_EN_DIS_MASK) | (XUARTPS_CR_RX_DIS | XUARTPS_CR_TX_DIS)))
416 /****************************************************************************/
418 * Determine if the transmitter FIFO is empty.
420 * @param InstancePtr is a pointer to the XUartPs instance.
423 * - TRUE if a byte can be sent
424 * - FALSE if the Transmitter Fifo is not empty
426 * @note C-Style signature:
427 * u32 XUartPs_IsTransmitEmpty(XUartPs InstancePtr)
429 ******************************************************************************/
430 #define XUartPs_IsTransmitEmpty(InstancePtr) \
431 ((Xil_In32(((InstancePtr)->Config.BaseAddress) + XUARTPS_SR_OFFSET) & \
432 XUARTPS_SR_TXEMPTY) == XUARTPS_SR_TXEMPTY)
435 /************************** Function Prototypes *****************************/
438 * Static lookup function implemented in xuartps_sinit.c
440 XUartPs_Config *XUartPs_LookupConfig(u16 DeviceId);
443 * Interface functions implemented in xuartps.c
445 int XUartPs_CfgInitialize(XUartPs *InstancePtr,
446 XUartPs_Config * Config, u32 EffectiveAddr);
448 unsigned int XUartPs_Send(XUartPs *InstancePtr, u8 *BufferPtr,
449 unsigned int NumBytes);
451 unsigned int XUartPs_Recv(XUartPs *InstancePtr, u8 *BufferPtr,
452 unsigned int NumBytes);
454 int XUartPs_SetBaudRate(XUartPs *InstancePtr, u32 BaudRate);
457 * Options functions in xuartps_options.c
459 void XUartPs_SetOptions(XUartPs *InstancePtr, u16 Options);
461 u16 XUartPs_GetOptions(XUartPs *InstancePtr);
463 void XUartPs_SetFifoThreshold(XUartPs *InstancePtr, u8 TriggerLevel);
465 u8 XUartPs_GetFifoThreshold(XUartPs *InstancePtr);
467 u16 XUartPs_GetModemStatus(XUartPs *InstancePtr);
469 u32 XUartPs_IsSending(XUartPs *InstancePtr);
471 u8 XUartPs_GetOperMode(XUartPs *InstancePtr);
473 void XUartPs_SetOperMode(XUartPs *InstancePtr, u8 OperationMode);
475 u8 XUartPs_GetFlowDelay(XUartPs *InstancePtr);
477 void XUartPs_SetFlowDelay(XUartPs *InstancePtr, u8 FlowDelayValue);
479 u8 XUartPs_GetRecvTimeout(XUartPs *InstancePtr);
481 void XUartPs_SetRecvTimeout(XUartPs *InstancePtr, u8 RecvTimeout);
483 int XUartPs_SetDataFormat(XUartPs *InstancePtr, XUartPsFormat * Format);
484 void XUartPs_GetDataFormat(XUartPs *InstancePtr, XUartPsFormat * Format);
487 * interrupt functions in xuartps_intr.c
489 u32 XUartPs_GetInterruptMask(XUartPs *InstancePtr);
491 void XUartPs_SetInterruptMask(XUartPs *InstancePtr, u32 Mask);
493 void XUartPs_InterruptHandler(XUartPs *InstancePtr);
495 void XUartPs_SetHandler(XUartPs *InstancePtr, XUartPs_Handler FuncPtr,
499 * self-test functions in xuartps_selftest.c
501 int XUartPs_SelfTest(XUartPs *InstancePtr);
507 #endif /* end of protection macro */