1 /******************************************************************************
3 * Copyright (C) 2010 - 2017 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_v3_5
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.
156 * 2.2 hk 06/23/14 SW reset of RX and TX should be done when changing
157 * baud rate. CR# 804281.
158 * 3.0 vm 12/09/14 Modified source code according to misrac guideline.
159 * Support for Zynq Ultrascale Mp added.
160 * 3.1 kvn 04/10/15 Modified code for latest RTL changes. Also added
161 * platform variable in driver instance structure.
162 * 3.1 adk 14/03/16 Include interrupt examples in the peripheral test when
163 * uart is connected to a valid interrupt controller CR#946803.
164 * 3.2 rk 07/20/16 Modified the logic for transmission break bit set
165 * 3.4 ms 01/23/17 Added xil_printf statement in main function for all
166 * examples to ensure that "Successfully ran" and "Failed"
167 * strings are available in all examples. This is a fix
169 * ms 03/17/17 Added readme.txt file in examples folder for doxygen
171 * 3.6 ms 02/16/18 Updates the flow control mode offset value in modem
176 *****************************************************************************/
178 #ifndef XUARTPS_H /* prevent circular inclusions */
179 #define XUARTPS_H /* by using protection macros */
185 /***************************** Include Files ********************************/
187 #include "xil_types.h"
188 #include "xil_assert.h"
190 #include "xuartps_hw.h"
191 #include "xplatform_info.h"
193 /************************** Constant Definitions ****************************/
196 * The following constants indicate the max and min baud rates and these
197 * numbers are based only on the testing that has been done. The hardware
198 * is capable of other baud rates.
200 #define XUARTPS_MAX_RATE 921600U
201 #define XUARTPS_MIN_RATE 110U
203 #define XUARTPS_DFT_BAUDRATE 115200U /* Default baud rate */
205 /** @name Configuration options
209 * These constants specify the options that may be set or retrieved
210 * with the driver, each is a unique bit mask such that multiple options
211 * may be specified. These constants indicate the available options
216 #define XUARTPS_OPTION_SET_BREAK 0x0080U /**< Starts break transmission */
217 #define XUARTPS_OPTION_STOP_BREAK 0x0040U /**< Stops break transmission */
218 #define XUARTPS_OPTION_RESET_TMOUT 0x0020U /**< Reset the receive timeout */
219 #define XUARTPS_OPTION_RESET_TX 0x0010U /**< Reset the transmitter */
220 #define XUARTPS_OPTION_RESET_RX 0x0008U /**< Reset the receiver */
221 #define XUARTPS_OPTION_ASSERT_RTS 0x0004U /**< Assert the RTS bit */
222 #define XUARTPS_OPTION_ASSERT_DTR 0x0002U /**< Assert the DTR bit */
223 #define XUARTPS_OPTION_SET_FCM 0x0001U /**< Turn on flow control mode */
227 /** @name Channel Operational Mode
229 * The UART can operate in one of four modes: Normal, Local Loopback, Remote
230 * Loopback, or automatic echo.
235 #define XUARTPS_OPER_MODE_NORMAL (u8)0x00U /**< Normal Mode */
236 #define XUARTPS_OPER_MODE_AUTO_ECHO (u8)0x01U /**< Auto Echo Mode */
237 #define XUARTPS_OPER_MODE_LOCAL_LOOP (u8)0x02U /**< Local Loopback Mode */
238 #define XUARTPS_OPER_MODE_REMOTE_LOOP (u8)0x03U /**< Remote Loopback Mode */
242 /** @name Data format values
244 * These constants specify the data format that the driver supports.
245 * The data format includes the number of data bits, the number of stop
250 #define XUARTPS_FORMAT_8_BITS 0U /**< 8 data bits */
251 #define XUARTPS_FORMAT_7_BITS 2U /**< 7 data bits */
252 #define XUARTPS_FORMAT_6_BITS 3U /**< 6 data bits */
254 #define XUARTPS_FORMAT_NO_PARITY 4U /**< No parity */
255 #define XUARTPS_FORMAT_MARK_PARITY 3U /**< Mark parity */
256 #define XUARTPS_FORMAT_SPACE_PARITY 2U /**< parity */
257 #define XUARTPS_FORMAT_ODD_PARITY 1U /**< Odd parity */
258 #define XUARTPS_FORMAT_EVEN_PARITY 0U /**< Even parity */
260 #define XUARTPS_FORMAT_2_STOP_BIT 2U /**< 2 stop bits */
261 #define XUARTPS_FORMAT_1_5_STOP_BIT 1U /**< 1.5 stop bits */
262 #define XUARTPS_FORMAT_1_STOP_BIT 0U /**< 1 stop bit */
265 /** @name Callback events
267 * These constants specify the handler events that an application can handle
268 * using its specific handler function. Note that these constants are not bit
269 * mask, so only one event can be passed to an application at a time.
273 #define XUARTPS_EVENT_RECV_DATA 1U /**< Data receiving done */
274 #define XUARTPS_EVENT_RECV_TOUT 2U /**< A receive timeout occurred */
275 #define XUARTPS_EVENT_SENT_DATA 3U /**< Data transmission done */
276 #define XUARTPS_EVENT_RECV_ERROR 4U /**< A receive error detected */
277 #define XUARTPS_EVENT_MODEM 5U /**< Modem status changed */
278 #define XUARTPS_EVENT_PARE_FRAME_BRKE 6U /**< A receive parity, frame, break
280 #define XUARTPS_EVENT_RECV_ORERR 7U /**< A receive overrun error detected */
284 /**************************** Type Definitions ******************************/
287 * This typedef contains configuration information for the device.
290 u16 DeviceId; /**< Unique ID of device */
291 u32 BaseAddress; /**< Base address of device (IPIF) */
292 u32 InputClockHz;/**< Input clock frequency */
293 s32 ModemPinsConnected; /** Specifies whether modem pins are connected
297 /* Keep track of state information about a data buffer in the interrupt mode. */
305 * Keep track of data format setting of a device.
308 u32 BaudRate; /**< In bps, ie 1200 */
309 u32 DataBits; /**< Number of data bits */
310 u32 Parity; /**< Parity */
311 u8 StopBits; /**< Number of stop bits */
314 /******************************************************************************/
316 * This data type defines a handler that an application defines to communicate
317 * with interrupt system to retrieve state information about an application.
319 * @param CallBackRef is a callback reference passed in by the upper layer
320 * when setting the handler, and is passed back to the upper layer
321 * when the handler is called. It is used to find the device driver
323 * @param Event contains one of the event constants indicating events that
325 * @param EventData contains the number of bytes sent or received at the
326 * time of the call for send and receive events and contains the
327 * modem status for modem events.
329 ******************************************************************************/
330 typedef void (*XUartPs_Handler) (void *CallBackRef, u32 Event,
334 * The XUartPs driver instance data structure. A pointer to an instance data
335 * structure is passed around by functions to refer to a specific driver
339 XUartPs_Config Config; /* Configuration data structure */
340 u32 InputClockHz; /* Input clock frequency */
341 u32 IsReady; /* Device is initialized and ready */
342 u32 BaudRate; /* Current baud rate */
344 XUartPsBuffer SendBuffer;
345 XUartPsBuffer ReceiveBuffer;
347 XUartPs_Handler Handler;
348 void *CallBackRef; /* Callback reference for event handler */
354 /***************** Macros (Inline Functions) Definitions ********************/
356 /****************************************************************************/
358 * Get the UART Channel Status Register.
360 * @param InstancePtr is a pointer to the XUartPs instance.
362 * @return The value read from the register.
364 * @note C-Style signature:
365 * u16 XUartPs_GetChannelStatus(XUartPs *InstancePtr)
367 ******************************************************************************/
368 #define XUartPs_GetChannelStatus(InstancePtr) \
369 Xil_In32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_SR_OFFSET)
371 /****************************************************************************/
373 * Get the UART Mode Control Register.
375 * @param InstancePtr is a pointer to the XUartPs instance.
377 * @return The value read from the register.
379 * @note C-Style signature:
380 * u32 XUartPs_GetControl(XUartPs *InstancePtr)
382 ******************************************************************************/
383 #define XUartPs_GetModeControl(InstancePtr) \
384 Xil_In32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_CR_OFFSET)
386 /****************************************************************************/
388 * Set the UART Mode Control Register.
390 * @param InstancePtr is a pointer to the XUartPs instance.
391 * @param RegisterValue is the value to be written to the register.
395 * @note C-Style signature:
396 * void XUartPs_SetModeControl(XUartPs *InstancePtr, u16 RegisterValue)
398 ******************************************************************************/
399 #define XUartPs_SetModeControl(InstancePtr, RegisterValue) \
400 Xil_Out32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_CR_OFFSET, \
401 (u32)(RegisterValue))
403 /****************************************************************************/
405 * Enable the transmitter and receiver of the UART.
407 * @param InstancePtr is a pointer to the XUartPs instance.
411 * @note C-Style signature:
412 * void XUartPs_EnableUart(XUartPs *InstancePtr)
414 ******************************************************************************/
415 #define XUartPs_EnableUart(InstancePtr) \
416 Xil_Out32(((InstancePtr)->Config.BaseAddress + (u32)XUARTPS_CR_OFFSET), \
417 ((Xil_In32((InstancePtr)->Config.BaseAddress + (u32)XUARTPS_CR_OFFSET) & \
418 (u32)(~XUARTPS_CR_EN_DIS_MASK)) | ((u32)XUARTPS_CR_RX_EN | (u32)XUARTPS_CR_TX_EN)))
420 /****************************************************************************/
422 * Disable the transmitter and receiver of the UART.
424 * @param InstancePtr is a pointer to the XUartPs instance.
428 * @note C-Style signature:
429 * void XUartPs_DisableUart(XUartPs *InstancePtr)
431 ******************************************************************************/
432 #define XUartPs_DisableUart(InstancePtr) \
433 Xil_Out32(((InstancePtr)->Config.BaseAddress + (u32)XUARTPS_CR_OFFSET), \
434 (((Xil_In32((InstancePtr)->Config.BaseAddress + (u32)XUARTPS_CR_OFFSET)) & \
435 (u32)(~XUARTPS_CR_EN_DIS_MASK)) | ((u32)XUARTPS_CR_RX_DIS | (u32)XUARTPS_CR_TX_DIS)))
437 /****************************************************************************/
439 * Determine if the transmitter FIFO is empty.
441 * @param InstancePtr is a pointer to the XUartPs instance.
444 * - TRUE if a byte can be sent
445 * - FALSE if the Transmitter Fifo is not empty
447 * @note C-Style signature:
448 * u32 XUartPs_IsTransmitEmpty(XUartPs InstancePtr)
450 ******************************************************************************/
451 #define XUartPs_IsTransmitEmpty(InstancePtr) \
452 ((Xil_In32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_SR_OFFSET) & \
453 (u32)XUARTPS_SR_TXEMPTY) == (u32)XUARTPS_SR_TXEMPTY)
456 /************************** Function Prototypes *****************************/
458 /* Static lookup function implemented in xuartps_sinit.c */
459 XUartPs_Config *XUartPs_LookupConfig(u16 DeviceId);
461 /* Interface functions implemented in xuartps.c */
462 s32 XUartPs_CfgInitialize(XUartPs *InstancePtr,
463 XUartPs_Config * Config, u32 EffectiveAddr);
465 u32 XUartPs_Send(XUartPs *InstancePtr,u8 *BufferPtr,
468 u32 XUartPs_Recv(XUartPs *InstancePtr,u8 *BufferPtr,
471 s32 XUartPs_SetBaudRate(XUartPs *InstancePtr, u32 BaudRate);
473 /* Options functions in xuartps_options.c */
474 void XUartPs_SetOptions(XUartPs *InstancePtr, u16 Options);
476 u16 XUartPs_GetOptions(XUartPs *InstancePtr);
478 void XUartPs_SetFifoThreshold(XUartPs *InstancePtr, u8 TriggerLevel);
480 u8 XUartPs_GetFifoThreshold(XUartPs *InstancePtr);
482 u16 XUartPs_GetModemStatus(XUartPs *InstancePtr);
484 u32 XUartPs_IsSending(XUartPs *InstancePtr);
486 u8 XUartPs_GetOperMode(XUartPs *InstancePtr);
488 void XUartPs_SetOperMode(XUartPs *InstancePtr, u8 OperationMode);
490 u8 XUartPs_GetFlowDelay(XUartPs *InstancePtr);
492 void XUartPs_SetFlowDelay(XUartPs *InstancePtr, u8 FlowDelayValue);
494 u8 XUartPs_GetRecvTimeout(XUartPs *InstancePtr);
496 void XUartPs_SetRecvTimeout(XUartPs *InstancePtr, u8 RecvTimeout);
498 s32 XUartPs_SetDataFormat(XUartPs *InstancePtr, XUartPsFormat * FormatPtr);
500 void XUartPs_GetDataFormat(XUartPs *InstancePtr, XUartPsFormat * FormatPtr);
502 /* interrupt functions in xuartps_intr.c */
503 u32 XUartPs_GetInterruptMask(XUartPs *InstancePtr);
505 void XUartPs_SetInterruptMask(XUartPs *InstancePtr, u32 Mask);
507 void XUartPs_InterruptHandler(XUartPs *InstancePtr);
509 void XUartPs_SetHandler(XUartPs *InstancePtr, XUartPs_Handler FuncPtr,
512 /* self-test functions in xuartps_selftest.c */
513 s32 XUartPs_SelfTest(XUartPs *InstancePtr);
519 #endif /* end of protection macro */