git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A53_64-bit_UltraScale_MPSoC/RTOSDemo_A53_bsp/psu_cortexa53_0/libsrc/uartps_v3_0/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 *
  37 * This driver supports the following features:
  38 *
  39 * - Dynamic data format (baud rate, data bits, stop bits, parity)
  40 * - Polled mode
  41 * - Interrupt driven mode
  42 * - Transmit and receive FIFOs (32 byte FIFO depth)
  43 * - Access to the external modem control lines
  44 *
  45 * <b>Initialization & Configuration</b>
  46 *
  47 * The XUartPs_Config structure is used by the driver to configure itself.
  48 * Fields inside this structure are properties of XUartPs based on its hardware
  49 * build.
  50 *
  51 * To support multiple runtime loading and initialization strategies employed
  52 * by various operating systems, the driver instance can be initialized in the
  53 * following way:
  54 *
  55 *   - XUartPs_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddr) - Uses a
  56 *        configuration structure provided by the caller. If running in a system
  57 *        with address translation, the parameter EffectiveAddr should be the
  58 *         virtual address.
  59 *
  60 * <b>Baud Rate</b>
  61 *
  62 * The UART has an internal baud rate generator, which furnishes the baud rate
  63 * clock for both the receiver and the transmitter. Ther input clock frequency
  64 * can be either the master clock or the master clock divided by 8, configured
  65 * through the mode register.
  66 *
  67 * Accompanied with the baud rate divider register, the baud rate is determined
  68 * by:
  69 * <pre>
  70 *       baud_rate = input_clock / (bgen * (bdiv + 1)
  71 * </pre>
  72 * where bgen is the value of the baud rate generator, and bdiv is the value of
  73 * baud rate divider.
  74 *
  75 * <b>Interrupts</b>
  76 *
  77 * The FIFOs are not flushed when the driver is initialized, but a function is
  78 * provided to allow the user to reset the FIFOs if desired.
  79 *
  80 * The driver defaults to no interrupts at initialization such that interrupts
  81 * must be enabled if desired. An interrupt is generated for one of the
  82 * following conditions.
  83 *
  84 * - A change in the modem signals
  85 * - Data in the receive FIFO for a configuable time without receiver activity
  86 * - A parity error
  87 * - A framing error
  88 * - An overrun error
  89 * - Transmit FIFO is full
  90 * - Transmit FIFO is empty
  91 * - Receive FIFO is full
  92 * - Receive FIFO is empty
  93 * - Data in the receive FIFO equal to the receive threshold
  94 *
  95 * The application can control which interrupts are enabled using the
  96 * XUartPs_SetInterruptMask() function.
  97 *
  98 * In order to use interrupts, it is necessary for the user to connect the
  99 * driver interrupt handler, XUartPs_InterruptHandler(), to the interrupt
 100 * system of the application. A separate handler should be provided by the
 101 * application to communicate with the interrupt system, and conduct
 102 * application specific interrupt handling. An application registers its own
 103 * handler through the XUartPs_SetHandler() function.
 104 *
 105 * <b>Data Transfer</b>
 106 *
 107 * The functions, XUartPs_Send() and XUartPs_Recv(), are provided in the
 108 * driver to allow data to be sent and received. They can be used in either
 109 * polled or interrupt mode.
 110 *
 111 * @note
 112 *
 113 * The default configuration for the UART after initialization is:
 114 *
 115 * - 9,600 bps or XPAR_DFT_BAUDRATE if defined
 116 * - 8 data bits
 117 * - 1 stop bit
 118 * - no parity
 119 * - FIFO's are enabled with a receive threshold of 8 bytes
 120 * - The RX timeout is enabled with a timeout of 1 (4 char times)
 121 *
 122 * <pre>
 123 * MODIFICATION HISTORY:
 124 *
 125 * Ver   Who    Date     Changes
 126 * ----- ------ -------- ----------------------------------------------
 127 * 1.00a drg/jz 01/12/10 First Release
 128 * 1.00a sdm    09/27/11 Fixed compiler warnings and also a bug
 129 *                       in XUartPs_SetFlowDelay where the value was not
 130 *                       being written to the register.
 131 * 1.01a sdm    12/20/11 Removed the InputClockHz parameter from the XUartPs
 132 *                       instance structure and the driver is updated to use
 133 *                       InputClockHz parameter from the XUartPs_Config config
 134 *                       structure.
 135 *                       Added a parameter to XUartPs_Config structure which
 136 *                       specifies whether the user has selected Modem pins
 137 *                       to be connected to MIO or FMIO.
 138 *                       Added the tcl file to generate the xparameters.h
 139 * 1.02a sg     05/16/12 Changed XUARTPS_RXWM_MASK to 0x3F for CR 652540 fix.
 140 * 1.03a sg     07/16/12 Updated XUARTPS_FORMAT_7_BITS and XUARTPS_FORMAT_6_BITS
 141 *                       with the correct values for CR 666724
 142 *                       Added defines for XUARTPS_IXR_TOVR,  XUARTPS_IXR_TNFUL
 143 *                       and XUARTPS_IXR_TTRIG.
 144 *                       Modified the name of these defines
 145 *                       XUARTPS_MEDEMSR_DCDX to XUARTPS_MODEMSR_DDCD
 146 *                       XUARTPS_MEDEMSR_RIX to XUARTPS_MODEMSR_TERI
 147 *                       XUARTPS_MEDEMSR_DSRX to XUARTPS_MODEMSR_DDSR
 148 *                       XUARTPS_MEDEMSR_CTSX to XUARTPS_MODEMSR_DCTS
 149 * 1.05a hk     08/22/13 Added API for uart reset and related
 150 *                       constant definitions.
 151 * 2.0   hk      03/07/14 Version number revised.
 152 * 2.1   hk     04/16/14 Change XUARTPS_MAX_RATE to 921600. CR# 780625.
 153 * 2.2   hk     06/23/14 SW reset of RX and TX should be done when changing
 154 *                       baud rate. CR# 804281.
 155 * 3.0   vm     12/09/14 Modified source code according to misrac guideline.
 156 *                       Support for Zynq Ultrascale Mp added.
 157 *
 158 * </pre>
 159 *
 160 *****************************************************************************/
 161
 162 #ifndef XUARTPS_H               /* prevent circular inclusions */
 163 #define XUARTPS_H               /* by using protection macros */
 164
 165 #ifdef __cplusplus
 166 extern "C" {
 167 #endif
 168
 169 /***************************** Include Files ********************************/
 170
 171 #include "xil_types.h"
 172 #include "xil_assert.h"
 173 #include "xstatus.h"
 174 #include "xuartps_hw.h"
 175
 176 /************************** Constant Definitions ****************************/
 177
 178 /*
 179  * The following constants indicate the max and min baud rates and these
 180  * numbers are based only on the testing that has been done. The hardware
 181  * is capable of other baud rates.
 182  */
 183 #define XUARTPS_MAX_RATE         921600U
 184 #define XUARTPS_MIN_RATE         110U
 185
 186 #define XUARTPS_DFT_BAUDRATE  115200U   /* Default baud rate */
 187
 188 /** @name Configuration options
 189  * @{
 190  */
 191 /**
 192  * These constants specify the options that may be set or retrieved
 193  * with the driver, each is a unique bit mask such that multiple options
 194  * may be specified.  These constants indicate the available options
 195  * in active state.
 196  *
 197  */
 198
 199 #define XUARTPS_OPTION_SET_BREAK        0x0080U /**< Starts break transmission */
 200 #define XUARTPS_OPTION_STOP_BREAK       0x0040U /**< Stops break transmission */
 201 #define XUARTPS_OPTION_RESET_TMOUT      0x0020U /**< Reset the receive timeout */
 202 #define XUARTPS_OPTION_RESET_TX         0x0010U /**< Reset the transmitter */
 203 #define XUARTPS_OPTION_RESET_RX         0x0008U /**< Reset the receiver */
 204 #define XUARTPS_OPTION_ASSERT_RTS       0x0004U /**< Assert the RTS bit */
 205 #define XUARTPS_OPTION_ASSERT_DTR       0x0002U /**< Assert the DTR bit */
 206 #define XUARTPS_OPTION_SET_FCM          0x0001U /**< Turn on flow control mode */
 207 /*@}*/
 208
 209
 210 /** @name Channel Operational Mode
 211  *
 212  * The UART can operate in one of four modes: Normal, Local Loopback, Remote
 213  * Loopback, or automatic echo.
 214  *
 215  * @{
 216  */
 217
 218 #define XUARTPS_OPER_MODE_NORMAL                (u8)0x00U       /**< Normal Mode */
 219 #define XUARTPS_OPER_MODE_AUTO_ECHO             (u8)0x01U       /**< Auto Echo Mode */
 220 #define XUARTPS_OPER_MODE_LOCAL_LOOP    (u8)0x02U       /**< Local Loopback Mode */
 221 #define XUARTPS_OPER_MODE_REMOTE_LOOP   (u8)0x03U       /**< Remote Loopback Mode */
 222
 223 /* @} */
 224
 225 /** @name Data format values
 226  *
 227  * These constants specify the data format that the driver supports.
 228  * The data format includes the number of data bits, the number of stop
 229  * bits and parity.
 230  *
 231  * @{
 232  */
 233 #define XUARTPS_FORMAT_8_BITS           0U /**< 8 data bits */
 234 #define XUARTPS_FORMAT_7_BITS           2U /**< 7 data bits */
 235 #define XUARTPS_FORMAT_6_BITS           3U /**< 6 data bits */
 236
 237 #define XUARTPS_FORMAT_NO_PARITY        4U /**< No parity */
 238 #define XUARTPS_FORMAT_MARK_PARITY      3U /**< Mark parity */
 239 #define XUARTPS_FORMAT_SPACE_PARITY     2U /**< parity */
 240 #define XUARTPS_FORMAT_ODD_PARITY       1U /**< Odd parity */
 241 #define XUARTPS_FORMAT_EVEN_PARITY      0U /**< Even parity */
 242
 243 #define XUARTPS_FORMAT_2_STOP_BIT       2U /**< 2 stop bits */
 244 #define XUARTPS_FORMAT_1_5_STOP_BIT     1U /**< 1.5 stop bits */
 245 #define XUARTPS_FORMAT_1_STOP_BIT       0U /**< 1 stop bit */
 246 /*@}*/
 247
 248 /** @name Callback events
 249  *
 250  * These constants specify the handler events that an application can handle
 251  * using its specific handler function. Note that these constants are not bit
 252  * mask, so only one event can be passed to an application at a time.
 253  *
 254  * @{
 255  */
 256 #define XUARTPS_EVENT_RECV_DATA         1U /**< Data receiving done */
 257 #define XUARTPS_EVENT_RECV_TOUT         2U /**< A receive timeout occurred */
 258 #define XUARTPS_EVENT_SENT_DATA         3U /**< Data transmission done */
 259 #define XUARTPS_EVENT_RECV_ERROR        4U /**< A receive error detected */
 260 #define XUARTPS_EVENT_MODEM                     5U /**< Modem status changed */
 261 /*@}*/
 262
 263
 264 /**************************** Type Definitions ******************************/
 265
 266 /**
 267  * This typedef contains configuration information for the device.
 268  */
 269 typedef struct {
 270         u16 DeviceId;    /**< Unique ID  of device */
 271         u32 BaseAddress; /**< Base address of device (IPIF) */
 272         u32 InputClockHz;/**< Input clock frequency */
 273         s32 ModemPinsConnected; /** Specifies whether modem pins are connected
 274                                  *  to MIO or FMIO */
 275 } XUartPs_Config;
 276
 277 /*
 278  * Keep track of state information about a data buffer in the interrupt mode.
 279  */
 280 typedef struct {
 281         u8 *NextBytePtr;
 282         u32 RequestedBytes;
 283         u32 RemainingBytes;
 284 } XUartPsBuffer;
 285
 286 /**
 287  * Keep track of data format setting of a device.
 288  */
 289 typedef struct {
 290         u32 BaudRate;   /**< In bps, ie 1200 */
 291         u32 DataBits;   /**< Number of data bits */
 292         u32 Parity;             /**< Parity */
 293         u8 StopBits;    /**< Number of stop bits */
 294 } XUartPsFormat;
 295
 296 /******************************************************************************/
 297 /**
 298  * This data type defines a handler that an application defines to communicate
 299  * with interrupt system to retrieve state information about an application.
 300  *
 301  * @param       CallBackRef is a callback reference passed in by the upper layer
 302  *              when setting the handler, and is passed back to the upper layer
 303  *              when the handler is called. It is used to find the device driver
 304  *              instance.
 305  * @param       Event contains one of the event constants indicating events that
 306  *              have occurred.
 307  * @param       EventData contains the number of bytes sent or received at the
 308  *              time of the call for send and receive events and contains the
 309  *              modem status for modem events.
 310  *
 311  ******************************************************************************/
 312 typedef void (*XUartPs_Handler) (void *CallBackRef, u32 Event,
 313                                   u32 EventData);
 314
 315 /**
 316  * The XUartPs driver instance data structure. A pointer to an instance data
 317  * structure is passed around by functions to refer to a specific driver
 318  * instance.
 319  */
 320 typedef struct {
 321         XUartPs_Config Config;  /* Configuration data structure */
 322         u32 InputClockHz;       /* Input clock frequency */
 323         u32 IsReady;            /* Device is initialized and ready */
 324         u32 BaudRate;           /* Current baud rate */
 325
 326         XUartPsBuffer SendBuffer;
 327         XUartPsBuffer ReceiveBuffer;
 328
 329         XUartPs_Handler Handler;
 330         void *CallBackRef;      /* Callback reference for event handler */
 331 } XUartPs;
 332
 333
 334 /***************** Macros (Inline Functions) Definitions ********************/
 335
 336 /****************************************************************************/
 337 /**
 338 * Get the UART Channel Status Register.
 339 *
 340 * @param        InstancePtr is a pointer to the XUartPs instance.
 341 *
 342 * @return       The value read from the register.
 343 *
 344 * @note         C-Style signature:
 345 *               u16 XUartPs_GetChannelStatus(XUartPs *InstancePtr)
 346 *
 347 ******************************************************************************/
 348 #define XUartPs_GetChannelStatus(InstancePtr)   \
 349         Xil_In32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_SR_OFFSET)
 350
 351 /****************************************************************************/
 352 /**
 353 * Get the UART Mode Control Register.
 354 *
 355 * @param        InstancePtr is a pointer to the XUartPs instance.
 356 *
 357 * @return       The value read from the register.
 358 *
 359 * @note         C-Style signature:
 360 *               u32 XUartPs_GetControl(XUartPs *InstancePtr)
 361 *
 362 ******************************************************************************/
 363 #define XUartPs_GetModeControl(InstancePtr)  \
 364         Xil_In32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_CR_OFFSET)
 365
 366 /****************************************************************************/
 367 /**
 368 * Set the UART Mode Control Register.
 369 *
 370 * @param        InstancePtr is a pointer to the XUartPs instance.
 371 * @param        RegisterValue is the value to be written to the register.
 372 *
 373 * @return       None.
 374 *
 375 * @note         C-Style signature:
 376 *       void XUartPs_SetModeControl(XUartPs *InstancePtr, u16 RegisterValue)
 377 *
 378 ******************************************************************************/
 379 #define XUartPs_SetModeControl(InstancePtr, RegisterValue) \
 380    Xil_Out32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_CR_OFFSET, \
 381                         (u32)(RegisterValue))
 382
 383 /****************************************************************************/
 384 /**
 385 * Enable the transmitter and receiver of the UART.
 386 *
 387 * @param        InstancePtr is a pointer to the XUartPs instance.
 388 *
 389 * @return       None.
 390 *
 391 * @note         C-Style signature:
 392 *               void XUartPs_EnableUart(XUartPs *InstancePtr)
 393 *
 394 ******************************************************************************/
 395 #define XUartPs_EnableUart(InstancePtr) \
 396    Xil_Out32(((InstancePtr)->Config.BaseAddress + (u32)XUARTPS_CR_OFFSET), \
 397           ((Xil_In32((InstancePtr)->Config.BaseAddress + (u32)XUARTPS_CR_OFFSET) & \
 398           (u32)(~XUARTPS_CR_EN_DIS_MASK)) | ((u32)XUARTPS_CR_RX_EN | (u32)XUARTPS_CR_TX_EN)))
 399
 400 /****************************************************************************/
 401 /**
 402 * Disable the transmitter and receiver of the UART.
 403 *
 404 * @param        InstancePtr is a pointer to the XUartPs instance.
 405 *
 406 * @return       None.
 407 *
 408 * @note         C-Style signature:
 409 *               void XUartPs_DisableUart(XUartPs *InstancePtr)
 410 *
 411 ******************************************************************************/
 412 #define XUartPs_DisableUart(InstancePtr) \
 413    Xil_Out32(((InstancePtr)->Config.BaseAddress + (u32)XUARTPS_CR_OFFSET), \
 414           (((Xil_In32((InstancePtr)->Config.BaseAddress + (u32)XUARTPS_CR_OFFSET)) & \
 415           (u32)(~XUARTPS_CR_EN_DIS_MASK)) | ((u32)XUARTPS_CR_RX_DIS | (u32)XUARTPS_CR_TX_DIS)))
 416
 417 /****************************************************************************/
 418 /**
 419 * Determine if the transmitter FIFO is empty.
 420 *
 421 * @param        InstancePtr is a pointer to the XUartPs instance.
 422 *
 423 * @return
 424 *               - TRUE if a byte can be sent
 425 *               - FALSE if the Transmitter Fifo is not empty
 426 *
 427 * @note         C-Style signature:
 428 *               u32 XUartPs_IsTransmitEmpty(XUartPs InstancePtr)
 429 *
 430 ******************************************************************************/
 431 #define XUartPs_IsTransmitEmpty(InstancePtr)                            \
 432         ((Xil_In32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_SR_OFFSET) & \
 433          (u32)XUARTPS_SR_TXEMPTY) == (u32)XUARTPS_SR_TXEMPTY)
 434
 435
 436 /************************** Function Prototypes *****************************/
 437
 438 /*
 439  * Static lookup function implemented in xuartps_sinit.c
 440  */
 441 XUartPs_Config *XUartPs_LookupConfig(u16 DeviceId);
 442
 443 /*
 444  * Interface functions implemented in xuartps.c
 445  */
 446 s32 XUartPs_CfgInitialize(XUartPs *InstancePtr,
 447                                   XUartPs_Config * Config, u32 EffectiveAddr);
 448
 449 u32 XUartPs_Send(XUartPs *InstancePtr,u8 *BufferPtr,
 450                            u32 NumBytes);
 451
 452 u32 XUartPs_Recv(XUartPs *InstancePtr,u8 *BufferPtr,
 453                            u32 NumBytes);
 454
 455 s32 XUartPs_SetBaudRate(XUartPs *InstancePtr, u32 BaudRate);
 456
 457 /*
 458  * Options functions in xuartps_options.c
 459  */
 460 void XUartPs_SetOptions(XUartPs *InstancePtr, u16 Options);
 461
 462 u16 XUartPs_GetOptions(XUartPs *InstancePtr);
 463
 464 void XUartPs_SetFifoThreshold(XUartPs *InstancePtr, u8 TriggerLevel);
 465
 466 u8 XUartPs_GetFifoThreshold(XUartPs *InstancePtr);
 467
 468 u16 XUartPs_GetModemStatus(XUartPs *InstancePtr);
 469
 470 u32 XUartPs_IsSending(XUartPs *InstancePtr);
 471
 472 u8 XUartPs_GetOperMode(XUartPs *InstancePtr);
 473
 474 void XUartPs_SetOperMode(XUartPs *InstancePtr, u8 OperationMode);
 475
 476 u8 XUartPs_GetFlowDelay(XUartPs *InstancePtr);
 477
 478 void XUartPs_SetFlowDelay(XUartPs *InstancePtr, u8 FlowDelayValue);
 479
 480 u8 XUartPs_GetRecvTimeout(XUartPs *InstancePtr);
 481
 482 void XUartPs_SetRecvTimeout(XUartPs *InstancePtr, u8 RecvTimeout);
 483
 484 s32 XUartPs_SetDataFormat(XUartPs *InstancePtr, XUartPsFormat * FormatPtr);
 485
 486 void XUartPs_GetDataFormat(XUartPs *InstancePtr, XUartPsFormat * FormatPtr);
 487
 488 /*
 489  * interrupt functions in xuartps_intr.c
 490  */
 491 u32 XUartPs_GetInterruptMask(XUartPs *InstancePtr);
 492
 493 void XUartPs_SetInterruptMask(XUartPs *InstancePtr, u32 Mask);
 494
 495 void XUartPs_InterruptHandler(XUartPs *InstancePtr);
 496
 497 void XUartPs_SetHandler(XUartPs *InstancePtr, XUartPs_Handler FuncPtr,
 498                          void *CallBackRef);
 499
 500 /*
 501  * self-test functions in xuartps_selftest.c
 502  */
 503 s32 XUartPs_SelfTest(XUartPs *InstancePtr);
 504
 505 #ifdef __cplusplus
 506 }
 507 #endif
 508
 509 #endif /* end of protection macro */