git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_R5_UltraScale_MPSoC/RTOSDemo_R5_bsp/psu_cortexr5_0/libsrc/uartps_v3_6/src/xuartps.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2010 - 2017 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_5
  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 * 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
 168 *                       for CR-965028.
 169 *       ms     03/17/17 Added readme.txt file in examples folder for doxygen
 170 *                       generation.
 171 * 3.6   ms     02/16/18 Updates the flow control mode offset value in modem
 172 *                       control register.
 173 *
 174 * </pre>
 175 *
 176 *****************************************************************************/
 177
 178 #ifndef XUARTPS_H               /* prevent circular inclusions */
 179 #define XUARTPS_H               /* by using protection macros */
 180
 181 #ifdef __cplusplus
 182 extern "C" {
 183 #endif
 184
 185 /***************************** Include Files ********************************/
 186
 187 #include "xil_types.h"
 188 #include "xil_assert.h"
 189 #include "xstatus.h"
 190 #include "xuartps_hw.h"
 191 #include "xplatform_info.h"
 192
 193 /************************** Constant Definitions ****************************/
 194
 195 /*
 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.
 199  */
 200 #define XUARTPS_MAX_RATE         921600U
 201 #define XUARTPS_MIN_RATE         110U
 202
 203 #define XUARTPS_DFT_BAUDRATE  115200U   /* Default baud rate */
 204
 205 /** @name Configuration options
 206  * @{
 207  */
 208 /**
 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
 212  * in active state.
 213  *
 214  */
 215
 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 */
 224 /*@}*/
 225
 226
 227 /** @name Channel Operational Mode
 228  *
 229  * The UART can operate in one of four modes: Normal, Local Loopback, Remote
 230  * Loopback, or automatic echo.
 231  *
 232  * @{
 233  */
 234
 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 */
 239
 240 /* @} */
 241
 242 /** @name Data format values
 243  *
 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
 246  * bits and parity.
 247  *
 248  * @{
 249  */
 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 */
 253
 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 */
 259
 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 */
 263 /*@}*/
 264
 265 /** @name Callback events
 266  *
 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.
 270  *
 271  * @{
 272  */
 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
 279                                                                                          *      error detected */
 280 #define XUARTPS_EVENT_RECV_ORERR                7U /**< A receive overrun error detected */
 281 /*@}*/
 282
 283
 284 /**************************** Type Definitions ******************************/
 285
 286 /**
 287  * This typedef contains configuration information for the device.
 288  */
 289 typedef struct {
 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
 294                                  *  to MIO or FMIO */
 295 } XUartPs_Config;
 296
 297 /* Keep track of state information about a data buffer in the interrupt mode. */
 298 typedef struct {
 299         u8 *NextBytePtr;
 300         u32 RequestedBytes;
 301         u32 RemainingBytes;
 302 } XUartPsBuffer;
 303
 304 /**
 305  * Keep track of data format setting of a device.
 306  */
 307 typedef struct {
 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 */
 312 } XUartPsFormat;
 313
 314 /******************************************************************************/
 315 /**
 316  * This data type defines a handler that an application defines to communicate
 317  * with interrupt system to retrieve state information about an application.
 318  *
 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
 322  *              instance.
 323  * @param       Event contains one of the event constants indicating events that
 324  *              have occurred.
 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.
 328  *
 329  ******************************************************************************/
 330 typedef void (*XUartPs_Handler) (void *CallBackRef, u32 Event,
 331                                   u32 EventData);
 332
 333 /**
 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
 336  * instance.
 337  */
 338 typedef struct {
 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 */
 343
 344         XUartPsBuffer SendBuffer;
 345         XUartPsBuffer ReceiveBuffer;
 346
 347         XUartPs_Handler Handler;
 348         void *CallBackRef;      /* Callback reference for event handler */
 349         u32 Platform;
 350         u8 is_rxbs_error;
 351 } XUartPs;
 352
 353
 354 /***************** Macros (Inline Functions) Definitions ********************/
 355
 356 /****************************************************************************/
 357 /**
 358 * Get the UART Channel Status Register.
 359 *
 360 * @param        InstancePtr is a pointer to the XUartPs instance.
 361 *
 362 * @return       The value read from the register.
 363 *
 364 * @note         C-Style signature:
 365 *               u16 XUartPs_GetChannelStatus(XUartPs *InstancePtr)
 366 *
 367 ******************************************************************************/
 368 #define XUartPs_GetChannelStatus(InstancePtr)   \
 369         Xil_In32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_SR_OFFSET)
 370
 371 /****************************************************************************/
 372 /**
 373 * Get the UART Mode Control Register.
 374 *
 375 * @param        InstancePtr is a pointer to the XUartPs instance.
 376 *
 377 * @return       The value read from the register.
 378 *
 379 * @note         C-Style signature:
 380 *               u32 XUartPs_GetControl(XUartPs *InstancePtr)
 381 *
 382 ******************************************************************************/
 383 #define XUartPs_GetModeControl(InstancePtr)  \
 384         Xil_In32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_CR_OFFSET)
 385
 386 /****************************************************************************/
 387 /**
 388 * Set the UART Mode Control Register.
 389 *
 390 * @param        InstancePtr is a pointer to the XUartPs instance.
 391 * @param        RegisterValue is the value to be written to the register.
 392 *
 393 * @return       None.
 394 *
 395 * @note         C-Style signature:
 396 *       void XUartPs_SetModeControl(XUartPs *InstancePtr, u16 RegisterValue)
 397 *
 398 ******************************************************************************/
 399 #define XUartPs_SetModeControl(InstancePtr, RegisterValue) \
 400    Xil_Out32(((InstancePtr)->Config.BaseAddress) + (u32)XUARTPS_CR_OFFSET, \
 401                         (u32)(RegisterValue))
 402
 403 /****************************************************************************/
 404 /**
 405 * Enable the transmitter and receiver of the UART.
 406 *
 407 * @param        InstancePtr is a pointer to the XUartPs instance.
 408 *
 409 * @return       None.
 410 *
 411 * @note         C-Style signature:
 412 *               void XUartPs_EnableUart(XUartPs *InstancePtr)
 413 *
 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)))
 419
 420 /****************************************************************************/
 421 /**
 422 * Disable the transmitter and receiver of the UART.
 423 *
 424 * @param        InstancePtr is a pointer to the XUartPs instance.
 425 *
 426 * @return       None.
 427 *
 428 * @note         C-Style signature:
 429 *               void XUartPs_DisableUart(XUartPs *InstancePtr)
 430 *
 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)))
 436
 437 /****************************************************************************/
 438 /**
 439 * Determine if the transmitter FIFO is empty.
 440 *
 441 * @param        InstancePtr is a pointer to the XUartPs instance.
 442 *
 443 * @return
 444 *               - TRUE if a byte can be sent
 445 *               - FALSE if the Transmitter Fifo is not empty
 446 *
 447 * @note         C-Style signature:
 448 *               u32 XUartPs_IsTransmitEmpty(XUartPs InstancePtr)
 449 *
 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)
 454
 455
 456 /************************** Function Prototypes *****************************/
 457
 458 /* Static lookup function implemented in xuartps_sinit.c */
 459 XUartPs_Config *XUartPs_LookupConfig(u16 DeviceId);
 460
 461 /* Interface functions implemented in xuartps.c */
 462 s32 XUartPs_CfgInitialize(XUartPs *InstancePtr,
 463                                   XUartPs_Config * Config, u32 EffectiveAddr);
 464
 465 u32 XUartPs_Send(XUartPs *InstancePtr,u8 *BufferPtr,
 466                            u32 NumBytes);
 467
 468 u32 XUartPs_Recv(XUartPs *InstancePtr,u8 *BufferPtr,
 469                            u32 NumBytes);
 470
 471 s32 XUartPs_SetBaudRate(XUartPs *InstancePtr, u32 BaudRate);
 472
 473 /* Options functions in xuartps_options.c */
 474 void XUartPs_SetOptions(XUartPs *InstancePtr, u16 Options);
 475
 476 u16 XUartPs_GetOptions(XUartPs *InstancePtr);
 477
 478 void XUartPs_SetFifoThreshold(XUartPs *InstancePtr, u8 TriggerLevel);
 479
 480 u8 XUartPs_GetFifoThreshold(XUartPs *InstancePtr);
 481
 482 u16 XUartPs_GetModemStatus(XUartPs *InstancePtr);
 483
 484 u32 XUartPs_IsSending(XUartPs *InstancePtr);
 485
 486 u8 XUartPs_GetOperMode(XUartPs *InstancePtr);
 487
 488 void XUartPs_SetOperMode(XUartPs *InstancePtr, u8 OperationMode);
 489
 490 u8 XUartPs_GetFlowDelay(XUartPs *InstancePtr);
 491
 492 void XUartPs_SetFlowDelay(XUartPs *InstancePtr, u8 FlowDelayValue);
 493
 494 u8 XUartPs_GetRecvTimeout(XUartPs *InstancePtr);
 495
 496 void XUartPs_SetRecvTimeout(XUartPs *InstancePtr, u8 RecvTimeout);
 497
 498 s32 XUartPs_SetDataFormat(XUartPs *InstancePtr, XUartPsFormat * FormatPtr);
 499
 500 void XUartPs_GetDataFormat(XUartPs *InstancePtr, XUartPsFormat * FormatPtr);
 501
 502 /* interrupt functions in xuartps_intr.c */
 503 u32 XUartPs_GetInterruptMask(XUartPs *InstancePtr);
 504
 505 void XUartPs_SetInterruptMask(XUartPs *InstancePtr, u32 Mask);
 506
 507 void XUartPs_InterruptHandler(XUartPs *InstancePtr);
 508
 509 void XUartPs_SetHandler(XUartPs *InstancePtr, XUartPs_Handler FuncPtr,
 510                          void *CallBackRef);
 511
 512 /* self-test functions in xuartps_selftest.c */
 513 s32 XUartPs_SelfTest(XUartPs *InstancePtr);
 514
 515 #ifdef __cplusplus
 516 }
 517 #endif
 518
 519 #endif /* end of protection macro */
 520 /** @} */