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

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2010 - 2014 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_v2_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 *
 157 * </pre>
 158 *
 159 *****************************************************************************/
 160
 161 #ifndef XUARTPS_H               /* prevent circular inclusions */
 162 #define XUARTPS_H               /* by using protection macros */
 163
 164 #ifdef __cplusplus
 165 extern "C" {
 166 #endif
 167
 168 /***************************** Include Files ********************************/
 169
 170 #include "xil_types.h"
 171 #include "xil_assert.h"
 172 #include "xstatus.h"
 173 #include "xuartps_hw.h"
 174
 175 /************************** Constant Definitions ****************************/
 176
 177 /*
 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.
 181  */
 182 #define XUARTPS_MAX_RATE         921600
 183 #define XUARTPS_MIN_RATE         110
 184
 185 #define XUARTPS_DFT_BAUDRATE  115200   /* Default baud rate */
 186
 187 /** @name Configuration options
 188  * @{
 189  */
 190 /**
 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
 194  * in active state.
 195  *
 196  */
 197
 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 */
 206 /*@}*/
 207
 208
 209 /** @name Channel Operational Mode
 210  *
 211  * The UART can operate in one of four modes: Normal, Local Loopback, Remote
 212  * Loopback, or automatic echo.
 213  *
 214  * @{
 215  */
 216
 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 */
 221
 222 /* @} */
 223
 224 /** @name Data format values
 225  *
 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
 228  * bits and parity.
 229  *
 230  * @{
 231  */
 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 */
 235
 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 */
 241
 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 */
 245 /*@}*/
 246
 247 /** @name Callback events
 248  *
 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.
 252  *
 253  * @{
 254  */
 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 */
 260 /*@}*/
 261
 262
 263 /**************************** Type Definitions ******************************/
 264
 265 /**
 266  * This typedef contains configuration information for the device.
 267  */
 268 typedef struct {
 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
 273                                  *  to MIO or FMIO */
 274 } XUartPs_Config;
 275
 276 /*
 277  * Keep track of state information about a data buffer in the interrupt mode.
 278  */
 279 typedef struct {
 280         u8 *NextBytePtr;
 281         unsigned int RequestedBytes;
 282         unsigned int RemainingBytes;
 283 } XUartPsBuffer;
 284
 285 /**
 286  * Keep track of data format setting of a device.
 287  */
 288 typedef struct {
 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 */
 293 } XUartPsFormat;
 294
 295 /******************************************************************************/
 296 /**
 297  * This data type defines a handler that an application defines to communicate
 298  * with interrupt system to retrieve state information about an application.
 299  *
 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
 303  *              instance.
 304  * @param       Event contains one of the event constants indicating events that
 305  *              have occurred.
 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.
 309  *
 310  ******************************************************************************/
 311 typedef void (*XUartPs_Handler) (void *CallBackRef, u32 Event,
 312                                   unsigned int EventData);
 313
 314 /**
 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
 317  * instance.
 318  */
 319 typedef struct {
 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 */
 324
 325         XUartPsBuffer SendBuffer;
 326         XUartPsBuffer ReceiveBuffer;
 327
 328         XUartPs_Handler Handler;
 329         void *CallBackRef;      /* Callback reference for event handler */
 330 } XUartPs;
 331
 332
 333 /***************** Macros (Inline Functions) Definitions ********************/
 334
 335 /****************************************************************************/
 336 /**
 337 * Get the UART Channel Status Register.
 338 *
 339 * @param        InstancePtr is a pointer to the XUartPs instance.
 340 *
 341 * @return       The value read from the register.
 342 *
 343 * @note         C-Style signature:
 344 *               u16 XUartPs_GetChannelStatus(XUartPs *InstancePtr)
 345 *
 346 ******************************************************************************/
 347 #define XUartPs_GetChannelStatus(InstancePtr)   \
 348         Xil_In32(((InstancePtr)->Config.BaseAddress) + XUARTPS_SR_OFFSET)
 349
 350 /****************************************************************************/
 351 /**
 352 * Get the UART Mode Control Register.
 353 *
 354 * @param        InstancePtr is a pointer to the XUartPs instance.
 355 *
 356 * @return       The value read from the register.
 357 *
 358 * @note         C-Style signature:
 359 *               u32 XUartPs_GetControl(XUartPs *InstancePtr)
 360 *
 361 ******************************************************************************/
 362 #define XUartPs_GetModeControl(InstancePtr)  \
 363         Xil_In32(((InstancePtr)->Config.BaseAddress) + XUARTPS_CR_OFFSET)
 364
 365 /****************************************************************************/
 366 /**
 367 * Set the UART Mode Control Register.
 368 *
 369 * @param        InstancePtr is a pointer to the XUartPs instance.
 370 * @param        RegisterValue is the value to be written to the register.
 371 *
 372 * @return       None.
 373 *
 374 * @note         C-Style signature:
 375 *       void XUartPs_SetModeControl(XUartPs *InstancePtr, u16 RegisterValue)
 376 *
 377 ******************************************************************************/
 378 #define XUartPs_SetModeControl(InstancePtr, RegisterValue) \
 379    Xil_Out32(((InstancePtr)->Config.BaseAddress) + XUARTPS_CR_OFFSET, \
 380                         (RegisterValue))
 381
 382 /****************************************************************************/
 383 /**
 384 * Enable the transmitter and receiver of the UART.
 385 *
 386 * @param        InstancePtr is a pointer to the XUartPs instance.
 387 *
 388 * @return       None.
 389 *
 390 * @note         C-Style signature:
 391 *               void XUartPs_EnableUart(XUartPs *InstancePtr)
 392 *
 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)))
 398
 399 /****************************************************************************/
 400 /**
 401 * Disable the transmitter and receiver of the UART.
 402 *
 403 * @param        InstancePtr is a pointer to the XUartPs instance.
 404 *
 405 * @return       None.
 406 *
 407 * @note         C-Style signature:
 408 *               void XUartPs_DisableUart(XUartPs *InstancePtr)
 409 *
 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)))
 415
 416 /****************************************************************************/
 417 /**
 418 * Determine if the transmitter FIFO is empty.
 419 *
 420 * @param        InstancePtr is a pointer to the XUartPs instance.
 421 *
 422 * @return
 423 *               - TRUE if a byte can be sent
 424 *               - FALSE if the Transmitter Fifo is not empty
 425 *
 426 * @note         C-Style signature:
 427 *               u32 XUartPs_IsTransmitEmpty(XUartPs InstancePtr)
 428 *
 429 ******************************************************************************/
 430 #define XUartPs_IsTransmitEmpty(InstancePtr)                            \
 431         ((Xil_In32(((InstancePtr)->Config.BaseAddress) + XUARTPS_SR_OFFSET) & \
 432          XUARTPS_SR_TXEMPTY) == XUARTPS_SR_TXEMPTY)
 433
 434
 435 /************************** Function Prototypes *****************************/
 436
 437 /*
 438  * Static lookup function implemented in xuartps_sinit.c
 439  */
 440 XUartPs_Config *XUartPs_LookupConfig(u16 DeviceId);
 441
 442 /*
 443  * Interface functions implemented in xuartps.c
 444  */
 445 int XUartPs_CfgInitialize(XUartPs *InstancePtr,
 446                                    XUartPs_Config * Config, u32 EffectiveAddr);
 447
 448 unsigned int XUartPs_Send(XUartPs *InstancePtr, u8 *BufferPtr,
 449                            unsigned int NumBytes);
 450
 451 unsigned int XUartPs_Recv(XUartPs *InstancePtr, u8 *BufferPtr,
 452                            unsigned int NumBytes);
 453
 454 int XUartPs_SetBaudRate(XUartPs *InstancePtr, u32 BaudRate);
 455
 456 /*
 457  * Options functions in xuartps_options.c
 458  */
 459 void XUartPs_SetOptions(XUartPs *InstancePtr, u16 Options);
 460
 461 u16 XUartPs_GetOptions(XUartPs *InstancePtr);
 462
 463 void XUartPs_SetFifoThreshold(XUartPs *InstancePtr, u8 TriggerLevel);
 464
 465 u8 XUartPs_GetFifoThreshold(XUartPs *InstancePtr);
 466
 467 u16 XUartPs_GetModemStatus(XUartPs *InstancePtr);
 468
 469 u32 XUartPs_IsSending(XUartPs *InstancePtr);
 470
 471 u8 XUartPs_GetOperMode(XUartPs *InstancePtr);
 472
 473 void XUartPs_SetOperMode(XUartPs *InstancePtr, u8 OperationMode);
 474
 475 u8 XUartPs_GetFlowDelay(XUartPs *InstancePtr);
 476
 477 void XUartPs_SetFlowDelay(XUartPs *InstancePtr, u8 FlowDelayValue);
 478
 479 u8 XUartPs_GetRecvTimeout(XUartPs *InstancePtr);
 480
 481 void XUartPs_SetRecvTimeout(XUartPs *InstancePtr, u8 RecvTimeout);
 482
 483 int XUartPs_SetDataFormat(XUartPs *InstancePtr, XUartPsFormat * Format);
 484 void XUartPs_GetDataFormat(XUartPs *InstancePtr, XUartPsFormat * Format);
 485
 486 /*
 487  * interrupt functions in xuartps_intr.c
 488  */
 489 u32 XUartPs_GetInterruptMask(XUartPs *InstancePtr);
 490
 491 void XUartPs_SetInterruptMask(XUartPs *InstancePtr, u32 Mask);
 492
 493 void XUartPs_InterruptHandler(XUartPs *InstancePtr);
 494
 495 void XUartPs_SetHandler(XUartPs *InstancePtr, XUartPs_Handler FuncPtr,
 496                          void *CallBackRef);
 497
 498 /*
 499  * self-test functions in xuartps_selftest.c
 500  */
 501 int XUartPs_SelfTest(XUartPs *InstancePtr);
 502
 503 #ifdef __cplusplus
 504 }
 505 #endif
 506
 507 #endif /* end of protection macro */
 508 /** @} */