git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A9_Zynq_ZC702/RTOSDemo_bsp/ps7_cortexa9_0/libsrc/uartps_v3_1/src/xuartps.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2010 - 2015 Xilinx, Inc.  All rights reserved.
   4 *
   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:
  11 *
  12 * The above copyright notice and this permission notice shall be included in
  13 * all copies or substantial portions of the Software.
  14 *
  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.
  18 *
  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
  25 * SOFTWARE.
  26 *
  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.
  30 *
  31 ******************************************************************************/
  32 /****************************************************************************/
  33 /**
  34 *
  35 * @file xuartps.h
  36 * @addtogroup uartps_v3_1
  37 * @{
  38 * @details
  39 *
  40 * This driver supports the following features:
  41 *
  42 * - Dynamic data format (baud rate, data bits, stop bits, parity)
  43 * - Polled mode
  44 * - Interrupt driven mode
  45 * - Transmit and receive FIFOs (32 byte FIFO depth)
  46 * - Access to the external modem control lines
  47 *
  48 * <b>Initialization & Configuration</b>
  49 *
  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
  52 * build.
  53 *
  54 * To support multiple runtime loading and initialization strategies employed
  55 * by various operating systems, the driver instance can be initialized in the
  56 * following way:
  57 *
  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
  61 *         virtual address.
  62 *
  63 * <b>Baud Rate</b>
  64 *
  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.
  69 *
  70 * Accompanied with the baud rate divider register, the baud rate is determined
  71 * by:
  72 * <pre>
  73 *       baud_rate = input_clock / (bgen * (bdiv + 1)
  74 * </pre>
  75 * where bgen is the value of the baud rate generator, and bdiv is the value of
  76 * baud rate divider.
  77 *
  78 * <b>Interrupts</b>
  79 *
  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.
  82 *
  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.
  86 *
  87 * - A change in the modem signals
  88 * - Data in the receive FIFO for a configuable time without receiver activity
  89 * - A parity error
  90 * - A framing error
  91 * - An overrun error
  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
  97 *
  98 * The application can control which interrupts are enabled using the
  99 * XUartPs_SetInterruptMask() function.
 100 *
 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.
 107 *
 108 * <b>Data Transfer</b>
 109 *
 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.
 113 *
 114 * @note
 115 *
 116 * The default configuration for the UART after initialization is:
 117 *
 118 * - 9,600 bps or XPAR_DFT_BAUDRATE if defined
 119 * - 8 data bits
 120 * - 1 stop bit
 121 * - no parity
 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)
 124 *
 125 * <pre>
 126 * MODIFICATION HISTORY:
 127 *
 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
 137 *                       structure.
 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 *
 165 * </pre>
 166 *
 167 *****************************************************************************/
 168
 169 #ifndef XUARTPS_H               /* prevent circular inclusions */
 170 #define XUARTPS_H               /* by using protection macros */
 171
 172 #ifdef __cplusplus
 173 extern "C" {
 174 #endif
 175
 176 /***************************** Include Files ********************************/
 177
 178 #include "xil_types.h"
 179 #include "xil_assert.h"
 180 #include "xstatus.h"
 181 #include "xuartps_hw.h"
 182 #include "xplatform_info.h"
 183
 184 /************************** Constant Definitions ****************************/
 185
 186 /*
 187  * The following constants indicate the max and min baud rates and these
 188  * numbers are based only on the testing that has been done. The hardware
 189  * is capable of other baud rates.
 190  */
 191 #define XUARTPS_MAX_RATE         921600U
 192 #define XUARTPS_MIN_RATE         110U
 193
 194 #define XUARTPS_DFT_BAUDRATE  115200U   /* Default baud rate */
 195
 196 /** @name Configuration options
 197  * @{
 198  */
 199 /**
 200  * These constants specify the options that may be set or retrieved
 201  * with the driver, each is a unique bit mask such that multiple options
 202  * may be specified.  These constants indicate the available options
 203  * in active state.
 204  *
 205  */
 206
 207 #define XUARTPS_OPTION_SET_BREAK        0x0080U /**< Starts break transmission */
 208 #define XUARTPS_OPTION_STOP_BREAK       0x0040U /**< Stops break transmission */
 209 #define XUARTPS_OPTION_RESET_TMOUT      0x0020U /**< Reset the receive timeout */
 210 #define XUARTPS_OPTION_RESET_TX         0x0010U /**< Reset the transmitter */
 211 #define XUARTPS_OPTION_RESET_RX         0x0008U /**< Reset the receiver */
 212 #define XUARTPS_OPTION_ASSERT_RTS       0x0004U /**< Assert the RTS bit */
 213 #define XUARTPS_OPTION_ASSERT_DTR       0x0002U /**< Assert the DTR bit */
 214 #define XUARTPS_OPTION_SET_FCM          0x0001U /**< Turn on flow control mode */
 215 /*@}*/
 216
 217
 218 /** @name Channel Operational Mode
 219  *
 220  * The UART can operate in one of four modes: Normal, Local Loopback, Remote
 221  * Loopback, or automatic echo.
 222  *
 223  * @{
 224  */
 225
 226 #define XUARTPS_OPER_MODE_NORMAL                (u8)0x00U       /**< Normal Mode */
 227 #define XUARTPS_OPER_MODE_AUTO_ECHO             (u8)0x01U       /**< Auto Echo Mode */
 228 #define XUARTPS_OPER_MODE_LOCAL_LOOP    (u8)0x02U       /**< Local Loopback Mode */
 229 #define XUARTPS_OPER_MODE_REMOTE_LOOP   (u8)0x03U       /**< Remote Loopback Mode */
 230
 231 /* @} */
 232
 233 /** @name Data format values
 234  *
 235  * These constants specify the data format that the driver supports.
 236  * The data format includes the number of data bits, the number of stop
 237  * bits and parity.
 238  *
 239  * @{
 240  */
 241 #define XUARTPS_FORMAT_8_BITS           0U /**< 8 data bits */
 242 #define XUARTPS_FORMAT_7_BITS           2U /**< 7 data bits */
 243 #define XUARTPS_FORMAT_6_BITS           3U /**< 6 data bits */
 244
 245 #define XUARTPS_FORMAT_NO_PARITY        4U /**< No parity */
 246 #define XUARTPS_FORMAT_MARK_PARITY      3U /**< Mark parity */
 247 #define XUARTPS_FORMAT_SPACE_PARITY     2U /**< parity */
 248 #define XUARTPS_FORMAT_ODD_PARITY       1U /**< Odd parity */
 249 #define XUARTPS_FORMAT_EVEN_PARITY      0U /**< Even parity */
 250
 251 #define XUARTPS_FORMAT_2_STOP_BIT       2U /**< 2 stop bits */
 252 #define XUARTPS_FORMAT_1_5_STOP_BIT     1U /**< 1.5 stop bits */
 253 #define XUARTPS_FORMAT_1_STOP_BIT       0U /**< 1 stop bit */
 254 /*@}*/
 255
 256 /** @name Callback events
 257  *
 258  * These constants specify the handler events that an application can handle
 259  * using its specific handler function. Note that these constants are not bit
 260  * mask, so only one event can be passed to an application at a time.
 261  *
 262  * @{
 263  */
 264 #define XUARTPS_EVENT_RECV_DATA                 1U /**< Data receiving done */
 265 #define XUARTPS_EVENT_RECV_TOUT                 2U /**< A receive timeout occurred */
 266 #define XUARTPS_EVENT_SENT_DATA                 3U /**< Data transmission done */
 267 #define XUARTPS_EVENT_RECV_ERROR                4U /**< A receive error detected */
 268 #define XUARTPS_EVENT_MODEM                             5U /**< Modem status changed */
 269 #define XUARTPS_EVENT_PARE_FRAME_BRKE   6U /**< A receive parity, frame, break
 270                                                                                          *      error detected */
 271 #define XUARTPS_EVENT_RECV_ORERR                7U /**< A receive overrun error detected */
 272 /*@}*/
 273
 274
 275 /**************************** Type Definitions ******************************/
 276
 277 /**
 278  * This typedef contains configuration information for the device.
 279  */
 280 typedef struct {
 281         u16 DeviceId;    /**< Unique ID  of device */
 282         u32 BaseAddress; /**< Base address of device (IPIF) */
 283         u32 InputClockHz;/**< Input clock frequency */
 284         s32 ModemPinsConnected; /** Specifies whether modem pins are connected
 285                                  *  to MIO or FMIO */
 286 } XUartPs_Config;
 287
 288 /* Keep track of state information about a data buffer in the interrupt mode. */
 289 typedef struct {
 290         u8 *NextBytePtr;
 291         u32 RequestedBytes;
 292         u32 RemainingBytes;
 293 } XUartPsBuffer;
 294
 295 /**
 296  * Keep track of data format setting of a device.
 297  */
 298 typedef struct {
 299         u32 BaudRate;   /**< In bps, ie 1200 */
 300         u32 DataBits;   /**< Number of data bits */
 301         u32 Parity;             /**< Parity */
 302         u8 StopBits;    /**< Number of stop bits */
 303 } XUartPsFormat;
 304
 305 /******************************************************************************/
 306 /**
 307  * This data type defines a handler that an application defines to communicate
 308  * with interrupt system to retrieve state information about an application.
 309  *
 310  * @param       CallBackRef is a callback reference passed in by the upper layer
 311  *              when setting the handler, and is passed back to the upper layer
 312  *              when the handler is called. It is used to find the device driver
 313  *              instance.
 314  * @param       Event contains one of the event constants indicating events that
 315  *              have occurred.
 316  * @param       EventData contains the number of bytes sent or received at the
 317  *              time of the call for send and receive events and contains the
 318  *              modem status for modem events.
 319  *
 320  ******************************************************************************/
 321 typedef void (*XUartPs_Handler) (void *CallBackRef, u32 Event,
 322                                   u32 EventData);
 323
 324 /**
 325  * The XUartPs driver instance data structure. A pointer to an instance data
 326  * structure is passed around by functions to refer to a specific driver
 327  * instance.
 328  */
 329 typedef struct {
 330         XUartPs_Config Config;  /* Configuration data structure */
 331         u32 InputClockHz;       /* Input clock frequency */
 332         u32 IsReady;            /* Device is initialized and ready */
 333         u32 BaudRate;           /* Current baud rate */
 334
 335         XUartPsBuffer SendBuffer;
 336         XUartPsBuffer ReceiveBuffer;
 337
 338         XUartPs_Handler Handler;
 339         void *CallBackRef;      /* Callback reference for event handler */
 340         u32 Platform;
 341         u8 is_rxbs_error;
 342 } XUartPs;
 343
 344
 345 /***************** Macros (Inline Functions) Definitions ********************/
 346
 347 /****************************************************************************/
 348 /**
 349 * Get the UART Channel Status Register.
 350 *
 351 * @param        InstancePtr is a pointer to the XUartPs instance.
 352 *
 353 * @return       The value read from the register.
 354 *
 355 * @note         C-Style signature:
 356 *               u16 XUartPs_GetChannelStatus(XUartPs *InstancePtr)
 357 *
 358 ******************************************************************************/
 359 #define XUartPs_GetChannelStatus(InstancePtr)   \
 360         Xil_In32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_SR_OFFSET)
 361
 362 /****************************************************************************/
 363 /**
 364 * Get the UART Mode Control Register.
 365 *
 366 * @param        InstancePtr is a pointer to the XUartPs instance.
 367 *
 368 * @return       The value read from the register.
 369 *
 370 * @note         C-Style signature:
 371 *               u32 XUartPs_GetControl(XUartPs *InstancePtr)
 372 *
 373 ******************************************************************************/
 374 #define XUartPs_GetModeControl(InstancePtr)  \
 375         Xil_In32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_CR_OFFSET)
 376
 377 /****************************************************************************/
 378 /**
 379 * Set the UART Mode Control Register.
 380 *
 381 * @param        InstancePtr is a pointer to the XUartPs instance.
 382 * @param        RegisterValue is the value to be written to the register.
 383 *
 384 * @return       None.
 385 *
 386 * @note         C-Style signature:
 387 *       void XUartPs_SetModeControl(XUartPs *InstancePtr, u16 RegisterValue)
 388 *
 389 ******************************************************************************/
 390 #define XUartPs_SetModeControl(InstancePtr, RegisterValue) \
 391    Xil_Out32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_CR_OFFSET, \
 392                         (u32)(RegisterValue))
 393
 394 /****************************************************************************/
 395 /**
 396 * Enable the transmitter and receiver of the UART.
 397 *
 398 * @param        InstancePtr is a pointer to the XUartPs instance.
 399 *
 400 * @return       None.
 401 *
 402 * @note         C-Style signature:
 403 *               void XUartPs_EnableUart(XUartPs *InstancePtr)
 404 *
 405 ******************************************************************************/
 406 #define XUartPs_EnableUart(InstancePtr) \
 407    Xil_Out32(((InstancePtr)->Config.BaseAddress + (u32)XUARTPS_CR_OFFSET), \
 408           ((Xil_In32((InstancePtr)->Config.BaseAddress + (u32)XUARTPS_CR_OFFSET) & \
 409           (u32)(~XUARTPS_CR_EN_DIS_MASK)) | ((u32)XUARTPS_CR_RX_EN | (u32)XUARTPS_CR_TX_EN)))
 410
 411 /****************************************************************************/
 412 /**
 413 * Disable the transmitter and receiver of the UART.
 414 *
 415 * @param        InstancePtr is a pointer to the XUartPs instance.
 416 *
 417 * @return       None.
 418 *
 419 * @note         C-Style signature:
 420 *               void XUartPs_DisableUart(XUartPs *InstancePtr)
 421 *
 422 ******************************************************************************/
 423 #define XUartPs_DisableUart(InstancePtr) \
 424    Xil_Out32(((InstancePtr)->Config.BaseAddress + (u32)XUARTPS_CR_OFFSET), \
 425           (((Xil_In32((InstancePtr)->Config.BaseAddress + (u32)XUARTPS_CR_OFFSET)) & \
 426           (u32)(~XUARTPS_CR_EN_DIS_MASK)) | ((u32)XUARTPS_CR_RX_DIS | (u32)XUARTPS_CR_TX_DIS)))
 427
 428 /****************************************************************************/
 429 /**
 430 * Determine if the transmitter FIFO is empty.
 431 *
 432 * @param        InstancePtr is a pointer to the XUartPs instance.
 433 *
 434 * @return
 435 *               - TRUE if a byte can be sent
 436 *               - FALSE if the Transmitter Fifo is not empty
 437 *
 438 * @note         C-Style signature:
 439 *               u32 XUartPs_IsTransmitEmpty(XUartPs InstancePtr)
 440 *
 441 ******************************************************************************/
 442 #define XUartPs_IsTransmitEmpty(InstancePtr)                            \
 443         ((Xil_In32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_SR_OFFSET) & \
 444          (u32)XUARTPS_SR_TXEMPTY) == (u32)XUARTPS_SR_TXEMPTY)
 445
 446
 447 /************************** Function Prototypes *****************************/
 448
 449 /* Static lookup function implemented in xuartps_sinit.c */
 450 XUartPs_Config *XUartPs_LookupConfig(u16 DeviceId);
 451
 452 /* Interface functions implemented in xuartps.c */
 453 s32 XUartPs_CfgInitialize(XUartPs *InstancePtr,
 454                                   XUartPs_Config * Config, u32 EffectiveAddr);
 455
 456 u32 XUartPs_Send(XUartPs *InstancePtr,u8 *BufferPtr,
 457                            u32 NumBytes);
 458
 459 u32 XUartPs_Recv(XUartPs *InstancePtr,u8 *BufferPtr,
 460                            u32 NumBytes);
 461
 462 s32 XUartPs_SetBaudRate(XUartPs *InstancePtr, u32 BaudRate);
 463
 464 /* Options functions in xuartps_options.c */
 465 void XUartPs_SetOptions(XUartPs *InstancePtr, u16 Options);
 466
 467 u16 XUartPs_GetOptions(XUartPs *InstancePtr);
 468
 469 void XUartPs_SetFifoThreshold(XUartPs *InstancePtr, u8 TriggerLevel);
 470
 471 u8 XUartPs_GetFifoThreshold(XUartPs *InstancePtr);
 472
 473 u16 XUartPs_GetModemStatus(XUartPs *InstancePtr);
 474
 475 u32 XUartPs_IsSending(XUartPs *InstancePtr);
 476
 477 u8 XUartPs_GetOperMode(XUartPs *InstancePtr);
 478
 479 void XUartPs_SetOperMode(XUartPs *InstancePtr, u8 OperationMode);
 480
 481 u8 XUartPs_GetFlowDelay(XUartPs *InstancePtr);
 482
 483 void XUartPs_SetFlowDelay(XUartPs *InstancePtr, u8 FlowDelayValue);
 484
 485 u8 XUartPs_GetRecvTimeout(XUartPs *InstancePtr);
 486
 487 void XUartPs_SetRecvTimeout(XUartPs *InstancePtr, u8 RecvTimeout);
 488
 489 s32 XUartPs_SetDataFormat(XUartPs *InstancePtr, XUartPsFormat * FormatPtr);
 490
 491 void XUartPs_GetDataFormat(XUartPs *InstancePtr, XUartPsFormat * FormatPtr);
 492
 493 /* interrupt functions in xuartps_intr.c */
 494 u32 XUartPs_GetInterruptMask(XUartPs *InstancePtr);
 495
 496 void XUartPs_SetInterruptMask(XUartPs *InstancePtr, u32 Mask);
 497
 498 void XUartPs_InterruptHandler(XUartPs *InstancePtr);
 499
 500 void XUartPs_SetHandler(XUartPs *InstancePtr, XUartPs_Handler FuncPtr,
 501                          void *CallBackRef);
 502
 503 /* self-test functions in xuartps_selftest.c */
 504 s32 XUartPs_SelfTest(XUartPs *InstancePtr);
 505
 506 #ifdef __cplusplus
 507 }
 508 #endif
 509
 510 #endif /* end of protection macro */
 511 /** @} */