git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/MicroBlaze_Kintex7_EthernetLite/BSP/microblaze_0/libsrc/uartlite_v3_2/src/xuartlite.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2002 - 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 xuartlite.h
  36 * @addtogroup uartlite_v3_1
  37 * @{
  38 * @details
  39 *
  40 * This component contains the implementation of the XUartLite component which is
  41 * the driver for the Xilinx UART Lite device. This UART is a minimal hardware
  42 * implementation with minimal features.  Most of the features, including baud
  43 * rate, parity, and number of data bits are only configurable when the hardware
  44 * device is built, rather than at run time by software.
  45 *
  46 * The device has 16 byte transmit and receive FIFOs and supports interrupts.
  47 * The device does not have any way to disable the receiver such that the
  48 * receive FIFO may contain unwanted data.  The FIFOs are not flushed when the
  49 * driver is initialized, but a function is provided to allow the user to
  50 * reset the FIFOs if desired.
  51 *
  52 * The driver defaults to no interrupts at initialization such that interrupts
  53 * must be enabled if desired. An interrupt is generated when the transmit FIFO
  54 * transitions from having data to being empty or when any data is contained in
  55 * the receive FIFO.
  56 *
  57 * In order to use interrupts, it's necessary for the user to connect the driver
  58 * interrupt handler, XUartLite_InterruptHandler, to the interrupt system of the
  59 * application.  This function does not save and restore the processor context
  60 * such that the user must provide it.  Send and receive handlers may be set for
  61 * the driver such that the handlers are called when transmit and receive
  62 * interrupts occur.  The handlers are called from interrupt context and are
  63 * designed to allow application specific processing to be performed.
  64 *
  65 * The functions, XUartLite_Send and XUartLite_Recv, are provided in the driver
  66 * to allow data to be sent and received. They are designed to be used in
  67 * polled or interrupt modes.
  68 *
  69 * The driver provides a status for each received byte indicating any parity
  70 * frame or overrun error. The driver provides statistics which allow visibility
  71 * into these errors.
  72 *
  73 * <b>Initialization & Configuration</b>
  74 *
  75 * The XUartLite_Config structure is used by the driver to configure itself. This
  76 * configuration structure is typically created by the tool-chain based on HW
  77 * build properties.
  78 *
  79 * To support multiple runtime loading and initialization strategies employed
  80 * by various operating systems, the driver instance can be initialized in one
  81 * of the following ways:
  82 *
  83 *   - XUartLite_Initialize(InstancePtr, DeviceId) - The driver looks up its own
  84 *     configuration structure created by the tool-chain based on an ID provided
  85 *     by the tool-chain.
  86 *
  87 *   - XUartLite_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddr) - Uses a
  88 *     configuration structure provided by the caller. If running in a system
  89 *     with address translation, the provided virtual memory base address
  90 *     replaces the physical address present in the configuration structure.
  91 *
  92 * <b>RTOS Independence</b>
  93 *
  94 * This driver is intended to be RTOS and processor independent.  It works
  95 * with physical addresses only.  Any needs for dynamic memory management,
  96 * threads or thread mutual exclusion, virtual memory, or cache control must
  97 * be satisfied by the layer above this driver.
  98 *
  99 * @note
 100 *
 101 * The driver is partitioned such that a minimal implementation may be used.
 102 * More features require additional files to be linked in.
 103 *
 104 * <pre>
 105 * MODIFICATION HISTORY:
 106 *
 107 * Ver   Who  Date     Changes
 108 * ----- ---- -------- -----------------------------------------------
 109 * 1.00a ecm  08/31/01 First release
 110 * 1.00b jhl  02/21/02 Repartitioned the driver for smaller files
 111 * 1.01a jvb  12/14/05 I separated dependency on the static config table and
 112 *                     xparameters.h from the driver initialization by moving
 113 *                     _Initialize and _LookupConfig to _sinit.c. I also added
 114 *                     the new _CfgInitialize routine.
 115 * 1.02a rpm  02/14/07 Added check for outstanding transmission before
 116 *                     calling the send callback (avoids extraneous
 117 *                     callback invocations) in interrupt service routine.
 118 * 1.12a mta  03/31/07 Updated to new coding conventions
 119 * 1.13a sv   01/21/08 Updated driver to support access through DCR bus
 120 * 1.14a sdm  08/22/08 Removed support for static interrupt handlers from the MDD
 121 *                     file
 122 * 1.14a sdm  09/26/08 Updated code to avoid race condition in
 123 *                     XUartLite_SendBuffer
 124 * 2.00a ktn  10/20/09 Updated to use HAL Processor APIs. The macros have been
 125 *                     renamed to remove _m from the name. XUartLite_mClearStats
 126 *                     macro is removed and XUartLite_ClearStats function should
 127 *                     be used in its place.
 128 * 2.01a adk  18/04/13 Updated the code to avoid unused variable
 129 *                     warnings when compiling with the -Wextra -Wall flags
 130 *                     In the file xuartlite.c. CR:704999.
 131 *                     Added notes for CR 710483 that the XUL_FIFO_SIZE is not
 132 *                     used in the driver. This is the size of the FIFO for
 133 *                     Transmit/Receive FIFOs which cannot be changed.
 134 * 3.0 adk 17/12/13  Fixed CR:741186,761863 Changes are made in the file
 135 *                     xuartlite_selftest.c
 136 * 3.0 adk 19/12/13  Update the driver as per new TCL API's
 137 * 3.1 nsk 21/07/15  Updated XUartLite_ReceiveBuffer function in xuartlite.c
 138 *                   to update the receive data into user buffer in critical
 139 *                   region.CR#865787.
 140 * 3.2   sk   11/10/15 Used UINTPTR instead of u32 for Baseaddress CR# 867425.
 141 *                     Changed the prototype of XUartLite_CfgInitialize API.
 142 *
 143 * </pre>
 144 *
 145 *****************************************************************************/
 146
 147 #ifndef XUARTLITE_H /* prevent circular inclusions */
 148 #define XUARTLITE_H /* by using protection macros */
 149
 150 #ifdef __cplusplus
 151 extern "C" {
 152 #endif
 153
 154 /***************************** Include Files ********************************/
 155
 156 #include "xil_types.h"
 157 #include "xil_assert.h"
 158 #include "xstatus.h"
 159
 160 /************************** Constant Definitions ****************************/
 161
 162 /**************************** Type Definitions ******************************/
 163
 164 /**
 165  * Callback function.  The first argument is a callback reference passed in by
 166  * the upper layer when setting the callback functions, and passed back to the
 167  * upper layer when the callback is invoked.
 168  * The second argument is the ByteCount which is the number of bytes that
 169  * actually moved from/to the buffer provided in the _Send/_Receive call.
 170  */
 171 typedef void (*XUartLite_Handler)(void *CallBackRef, unsigned int ByteCount);
 172
 173 /**
 174  * Statistics for the XUartLite driver
 175  */
 176 typedef struct {
 177         u32 TransmitInterrupts;         /**< Number of transmit interrupts */
 178         u32 ReceiveInterrupts;          /**< Number of receive interrupts */
 179         u32 CharactersTransmitted;      /**< Number of characters transmitted */
 180         u32 CharactersReceived;         /**< Number of characters received */
 181         u32 ReceiveOverrunErrors;       /**< Number of receive overruns */
 182         u32 ReceiveParityErrors;        /**< Number of receive parity errors */
 183         u32 ReceiveFramingErrors;       /**< Number of receive framing errors */
 184 } XUartLite_Stats;
 185
 186 /**
 187  * The following data type is used to manage the buffers that are handled
 188  * when sending and receiving data in the interrupt mode. It is intended
 189  * for internal use only.
 190  */
 191 typedef struct {
 192         u8 *NextBytePtr;
 193         unsigned int RequestedBytes;
 194         unsigned int RemainingBytes;
 195 } XUartLite_Buffer;
 196
 197 /**
 198  * This typedef contains configuration information for the device.
 199  */
 200 typedef struct {
 201         u16 DeviceId;           /**< Unique ID  of device */
 202         UINTPTR RegBaseAddr;    /**< Register base address */
 203         u32 BaudRate;           /**< Fixed baud rate */
 204         u8  UseParity;          /**< Parity generator enabled when TRUE */
 205         u8  ParityOdd;          /**< Parity generated is odd when TRUE, even
 206                                         when FALSE */
 207         u8  DataBits;           /**< Fixed data bits */
 208 } XUartLite_Config;
 209
 210 /**
 211  * The XUartLite driver instance data. The user is required to allocate a
 212  * variable of this type for every UART Lite device in the system. A pointer
 213  * to a variable of this type is then passed to the driver API functions.
 214  */
 215 typedef struct {
 216         XUartLite_Stats Stats;          /* Component Statistics */
 217         UINTPTR RegBaseAddress;         /* Base address of registers */
 218         u32 IsReady;                    /* Device is initialized and ready */
 219
 220         XUartLite_Buffer SendBuffer;
 221         XUartLite_Buffer ReceiveBuffer;
 222
 223         XUartLite_Handler RecvHandler;
 224         void *RecvCallBackRef;          /* Callback ref for recv handler */
 225         XUartLite_Handler SendHandler;
 226         void *SendCallBackRef;          /* Callback ref for send handler */
 227 } XUartLite;
 228
 229
 230 /***************** Macros (Inline Functions) Definitions ********************/
 231
 232
 233 /************************** Function Prototypes *****************************/
 234
 235 /*
 236  * Initialization functions in xuartlite_sinit.c
 237  */
 238 int XUartLite_Initialize(XUartLite *InstancePtr, u16 DeviceId);
 239 XUartLite_Config *XUartLite_LookupConfig(u16 DeviceId);
 240
 241 /*
 242  * Required functions, in file xuart.c
 243  */
 244 int XUartLite_CfgInitialize(XUartLite *InstancePtr,
 245                                 XUartLite_Config *Config,
 246                                 UINTPTR EffectiveAddr);
 247
 248 void XUartLite_ResetFifos(XUartLite *InstancePtr);
 249
 250 unsigned int XUartLite_Send(XUartLite *InstancePtr, u8 *DataBufferPtr,
 251                                 unsigned int NumBytes);
 252 unsigned int XUartLite_Recv(XUartLite *InstancePtr, u8 *DataBufferPtr,
 253                                 unsigned int NumBytes);
 254
 255 int XUartLite_IsSending(XUartLite *InstancePtr);
 256
 257 /*
 258  * Functions for statistics, in file xuartlite_stats.c
 259  */
 260 void XUartLite_GetStats(XUartLite *InstancePtr, XUartLite_Stats *StatsPtr);
 261 void XUartLite_ClearStats(XUartLite *InstancePtr);
 262
 263 /*
 264  * Functions for self-test, in file xuartlite_selftest.c
 265  */
 266 int XUartLite_SelfTest(XUartLite *InstancePtr);
 267
 268 /*
 269  * Functions for interrupts, in file xuartlite_intr.c
 270  */
 271 void XUartLite_EnableInterrupt(XUartLite *InstancePtr);
 272 void XUartLite_DisableInterrupt(XUartLite *InstancePtr);
 273
 274 void XUartLite_SetRecvHandler(XUartLite *InstancePtr, XUartLite_Handler FuncPtr,
 275                                 void *CallBackRef);
 276 void XUartLite_SetSendHandler(XUartLite *InstancePtr, XUartLite_Handler FuncPtr,
 277                                 void *CallBackRef);
 278
 279 void XUartLite_InterruptHandler(XUartLite *InstancePtr);
 280
 281 #ifdef __cplusplus
 282 }
 283 #endif
 284
 285 #endif                  /* end of protection macro */
 286
 287 /** @} */