git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A9_Zynq_ZC702/RTOSDemo_bsp/ps7_cortexa9_0/libsrc/iicps_v2_1/src/xiicps.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 xiicps.h
  36 * @addtogroup iicps_v2_1
  37 * @{
  38 * @details
  39 *
  40 * This is an implementation of IIC driver in the PS block. The device can
  41 * be either a master or a slave on the IIC bus. This implementation supports
  42 * both interrupt mode transfer and polled mode transfer. Only 7-bit address
  43 * is used in the driver, although the hardware also supports 10-bit address.
  44 *
  45 * IIC is a 2-wire serial interface.  The master controls the clock, so it can
  46 * regulate when it wants to send or receive data. The slave is under control of
  47 * the master, it must respond quickly since it has no control of the clock and
  48 * must send/receive data as fast or as slow as the master does.
  49 *
  50 * The higher level software must implement a higher layer protocol to inform
  51 * the slave what to send to the master.
  52 *
  53 * <b>Initialization & Configuration</b>
  54 *
  55 * The XIicPs_Config structure is used by the driver to configure itself. This
  56 * configuration structure is typically created by the tool-chain based on HW
  57 * build properties.
  58 *
  59 * To support multiple runtime loading and initialization strategies employed by
  60 * various operating systems, the driver instance can be initialized in the
  61 * following way:
  62 *
  63 *    - XIicPs_LookupConfig(DeviceId) - Use the device identifier to find
  64 *      the static configuration structure defined in xiicps_g.c. This is
  65 *      setup by the tools. For some operating systems the config structure
  66 *      will be initialized by the software and this call is not needed.
  67 *
  68 *   - XIicPs_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddr) - Uses a
  69 *     configuration structure provided by the caller. If running in a
  70 *     system with address translation, the provided virtual memory base
  71 *     address replaces the physical address in the configuration
  72 *     structure.
  73 *
  74 * <b>Multiple Masters</b>
  75 *
  76 * More than one master can exist, bus arbitration is defined in the IIC
  77 * standard. Lost of arbitration causes arbitration loss interrupt on the device.
  78 *
  79 * <b>Multiple Slaves</b>
  80 *
  81 * Multiple slaves are supported by selecting them with unique addresses. It is
  82 * up to the system designer to be sure all devices on the IIC bus have
  83 * unique addresses.
  84 *
  85 * <b>Addressing</b>
  86 *
  87 * The IIC hardware can use 7 or 10 bit addresses.  The driver provides the
  88 * ability to control which address size is sent in messages as a master to a
  89 * slave device.
  90 *
  91 * <b>FIFO Size </b>
  92 * The hardware FIFO is 32 bytes deep. The user must know the limitations of
  93 * other IIC devices on the bus. Some are only able to receive a limited number
  94 * of bytes in a single transfer.
  95 *
  96 * <b>Data Rates</b>
  97 *
  98 * The data rate is set by values in the control register. The formula for
  99 * determining the correct register values is:
 100 * Fscl = Fpclk/(22 x (divisor_a+1) x (divisor_b+1))
 101 *
 102 * When the device is configured as a slave, the slck setting controls the
 103 * sample rate and so must be set to be at least as fast as the fastest scl
 104 * expected to be seen in the system.
 105 *
 106 * <b>Polled Mode Operation</b>
 107 *
 108 * This driver supports polled mode transfers.
 109 *
 110 * <b>Interrupts</b>
 111 *
 112 * The user must connect the interrupt handler of the driver,
 113 * XIicPs_InterruptHandler to an interrupt system such that it will be called
 114 * when an interrupt occurs. This function does not save and restore the
 115 * processor context such that the user must provide this processing.
 116 *
 117 * The driver handles the following interrupts:
 118 * - Transfer complete
 119 * - More Data
 120 * - Transfer not Acknowledged
 121 * - Transfer Time out
 122 * - Monitored slave ready - master mode only
 123 * - Receive Overflow
 124 * - Transmit FIFO overflow
 125 * - Receive FIFO underflow
 126 * - Arbitration lost
 127 *
 128 * <b>Bus Busy</b>
 129 *
 130 * Bus busy is checked before the setup of a master mode device, to avoid
 131 * unnecessary arbitration loss interrupt.
 132 *
 133 * <b>RTOS Independence</b>
 134 *
 135 * This driver is intended to be RTOS and processor independent.  It works with
 136 * physical addresses only.  Any needs for dynamic memory management, threads or
 137 * thread mutual exclusion, virtual memory, or cache control must be satisfied by
 138 * the layer above this driver.
 139 *
 140 * @note
 141 * . Less than FIFO size transfers work for both 100 KHz and 400 KHz.
 142 * . Larger than FIFO size interrupt-driven transfers are not reliable on
 143 *    busy systems where interrupt latency is high.
 144 * . Larger than FIFO size interrupt-driven transfers are not reliable for
 145 *    data rate of 400 KHz.
 146 * . Larger than FIFO size polled mode transfers work reliably.
 147 *
 148 * <pre> MODIFICATION HISTORY:
 149 *
 150 * Ver   Who     Date     Changes
 151 * ----- ------  -------- -----------------------------------------------
 152 * 1.00a drg/jz  01/30/08 First release
 153 * 1.00a sdm     09/21/11 Fixed an issue in the XIicPs_SetOptions and
 154 *                        XIicPs_ClearOptions where the InstancePtr->Options
 155 *                        was not updated correctly.
 156 *                        Updated the InstancePtr->Options in the
 157 *                        XIicPs_CfgInitialize by calling XIicPs_GetOptions.
 158 *                        Updated the XIicPs_SetupMaster to not check for
 159 *                        Bus Busy condition when the Hold Bit is set.
 160 *                        Removed some unused variables.
 161 * 1.01a sg      03/30/12 Fixed an issue in XIicPs_MasterSendPolled where a
 162 *                        check for transfer completion is added, which indicates
 163 *                        the completion of current transfer.
 164 * 1.02a sg      08/29/12 Updated the logic to arrive at the best divisors
 165 *                        to achieve I2C clock with minimum error for
 166 *                        CR #674195
 167 * 1.03a hk  05/04/13 Initialized BestDivA and BestDivB to 0.
 168 *                        This is fix for CR#704398 to remove warning.
 169 * 2.0   hk  03/07/14 Added check for error status in the while loop that
 170 *                    checks for completion.
 171 *                    (XIicPs_MasterSendPolled function). CR# 762244, 764875.
 172 *                    Limited frequency set when 100KHz or 400KHz is
 173 *                    selected. This is a hardware limitation. CR#779290.
 174 * 2.1   hk  04/24/14 Fix for CR# 789821 to handle >14 byte transfers.
 175 *                    Explicitly reset CR and clear FIFO in Abort function
 176 *                    and state the same in the comments. CR# 784254.
 177 *                    Fix for CR# 761060 - provision for repeated start.
 178 *
 179 * </pre>
 180 *
 181 ******************************************************************************/
 182
 183 #ifndef XIICPS_H       /* prevent circular inclusions */
 184 #define XIICPS_H       /* by using protection macros */
 185
 186 #ifdef __cplusplus
 187 extern "C" {
 188 #endif
 189
 190 /***************************** Include Files *********************************/
 191
 192 #include "xil_types.h"
 193 #include "xil_assert.h"
 194 #include "xstatus.h"
 195 #include "xiicps_hw.h"
 196
 197 /************************** Constant Definitions *****************************/
 198
 199 /** @name Configuration options
 200  *
 201  * The following options may be specified or retrieved for the device and
 202  * enable/disable additional features of the IIC.  Each of the options
 203  * are bit fields, so more than one may be specified.
 204  *
 205  * @{
 206  */
 207 #define XIICPS_7_BIT_ADDR_OPTION        0x01  /**< 7-bit address mode */
 208 #define XIICPS_10_BIT_ADDR_OPTION       0x02  /**< 10-bit address mode */
 209 #define XIICPS_SLAVE_MON_OPTION         0x04  /**< Slave monitor mode */
 210 #define XIICPS_REP_START_OPTION         0x08  /**< Repeated Start */
 211 /*@}*/
 212
 213 /** @name Callback events
 214  *
 215  * These constants specify the handler events that are passed to an application
 216  * event handler from the driver.  These constants are bit masks such that
 217  * more than one event can be passed to the handler.
 218  *
 219  * @{
 220  */
 221 #define XIICPS_EVENT_COMPLETE_SEND      0x0001  /**< Transmit Complete Event*/
 222 #define XIICPS_EVENT_COMPLETE_RECV      0x0002  /**< Receive Complete Event*/
 223 #define XIICPS_EVENT_TIME_OUT           0x0004  /**< Transfer timed out */
 224 #define XIICPS_EVENT_ERROR              0x0008  /**< Receive error */
 225 #define XIICPS_EVENT_ARB_LOST           0x0010  /**< Arbitration lost */
 226 #define XIICPS_EVENT_NACK               0x0020  /**< NACK Received */
 227 #define XIICPS_EVENT_SLAVE_RDY          0x0040  /**< Slave ready */
 228 #define XIICPS_EVENT_RX_OVR             0x0080  /**< RX overflow */
 229 #define XIICPS_EVENT_TX_OVR             0x0100  /**< TX overflow */
 230 #define XIICPS_EVENT_RX_UNF             0x0200  /**< RX underflow */
 231 /*@}*/
 232
 233 /** @name Role constants
 234  *
 235  * These constants are used to pass into the device setup routines to
 236  * set up the device according to transfer direction.
 237  */
 238 #define SENDING_ROLE            1  /**< Transfer direction is sending */
 239 #define RECVING_ROLE            0  /**< Transfer direction is receiving */
 240
 241 /* Maximum transfer size */
 242 #define XIICPS_MAX_TRANSFER_SIZE        (255 - 3)
 243
 244 /**************************** Type Definitions *******************************/
 245
 246 /**
 247 * The handler data type allows the user to define a callback function to
 248 * respond to interrupt events in the system. This function is executed
 249 * in interrupt context, so amount of processing should be minimized.
 250 *
 251 * @param        CallBackRef is the callback reference passed in by the upper
 252 *               layer when setting the callback functions, and passed back to
 253 *               the upper layer when the callback is invoked. Its type is
 254 *               not important to the driver, so it is a void pointer.
 255 * @param        StatusEvent indicates one or more status events that occurred.
 256 */
 257 typedef void (*XIicPs_IntrHandler) (void *CallBackRef, u32 StatusEvent);
 258
 259 /**
 260  * This typedef contains configuration information for the device.
 261  */
 262 typedef struct {
 263         u16 DeviceId;     /**< Unique ID  of device */
 264         u32 BaseAddress;  /**< Base address of the device */
 265         u32 InputClockHz; /**< Input clock frequency */
 266 } XIicPs_Config;
 267
 268 /**
 269  * The XIicPs driver instance data. The user is required to allocate a
 270  * variable of this type for each IIC device in the system. A pointer
 271  * to a variable of this type is then passed to the driver API functions.
 272  */
 273 typedef struct {
 274         XIicPs_Config Config;   /* Configuration structure */
 275         u32 IsReady;            /* Device is initialized and ready */
 276         u32 Options;            /* Options set in the device */
 277
 278         u8 *SendBufferPtr;      /* Pointer to send buffer */
 279         u8 *RecvBufferPtr;      /* Pointer to recv buffer */
 280         int SendByteCount;      /* Number of bytes still expected to send */
 281         int RecvByteCount;      /* Number of bytes still expected to receive */
 282         int CurrByteCount;      /* No. of bytes expected in current transfer */
 283
 284         int UpdateTxSize;       /* If tx size register has to be updated */
 285         int IsSend;             /* Whether master is sending or receiving */
 286         int IsRepeatedStart;    /* Indicates if user set repeated start */
 287
 288         XIicPs_IntrHandler StatusHandler;  /* Event handler function */
 289         void *CallBackRef;      /* Callback reference for event handler */
 290 } XIicPs;
 291
 292 /***************** Macros (Inline Functions) Definitions *********************/
 293 /****************************************************************************/
 294 /*
 295 *
 296 * Place one byte into the transmit FIFO.
 297 *
 298 * @param        InstancePtr is the instance of IIC
 299 *
 300 * @return       None.
 301 *
 302 * @note         C-Style signature:
 303 *               void XIicPs_SendByte(XIicPs *InstancePtr)
 304 *
 305 *****************************************************************************/
 306 #define XIicPs_SendByte(InstancePtr)                                    \
 307 {                                                                       \
 308          XIicPs_Out32((InstancePtr)->Config.BaseAddress                 \
 309                          + XIICPS_DATA_OFFSET,                          \
 310         *(InstancePtr)->SendBufferPtr ++);                              \
 311          (InstancePtr)->SendByteCount --;                               \
 312 }
 313
 314 /****************************************************************************/
 315 /*
 316 *
 317 * Receive one byte from FIFO.
 318 *
 319 * @param        InstancePtr is the instance of IIC
 320 *
 321 * @return       None.
 322 *
 323 * @note         C-Style signature:
 324 *               u8 XIicPs_RecvByte(XIicPs *InstancePtr)
 325 *
 326 *****************************************************************************/
 327 #define XIicPs_RecvByte(InstancePtr)                                    \
 328 {                                                                       \
 329         *(InstancePtr)->RecvBufferPtr ++ =                              \
 330          (u8)XIicPs_In32((InstancePtr)->Config.BaseAddress              \
 331                   + XIICPS_DATA_OFFSET);                                \
 332          (InstancePtr)->RecvByteCount --;                               \
 333 }
 334
 335 /************************** Function Prototypes ******************************/
 336
 337 /*
 338  * Function for configuration lookup, in xiicps_sinit.c
 339  */
 340 XIicPs_Config *XIicPs_LookupConfig(u16 DeviceId);
 341
 342 /*
 343  * Functions for general setup, in xiicps.c
 344  */
 345 int XIicPs_CfgInitialize(XIicPs *InstancePtr, XIicPs_Config * Config,
 346                                   u32 EffectiveAddr);
 347
 348 void XIicPs_Abort(XIicPs *InstancePtr);
 349 void XIicPs_Reset(XIicPs *InstancePtr);
 350
 351 int XIicPs_BusIsBusy(XIicPs *InstancePtr);
 352
 353 /*
 354  * Functions for interrupts, in xiicps_intr.c
 355  */
 356 void XIicPs_SetStatusHandler(XIicPs *InstancePtr, void *CallBackRef,
 357                                   XIicPs_IntrHandler FuncPtr);
 358
 359 /*
 360  * Functions for device as master, in xiicps_master.c
 361  */
 362 void XIicPs_MasterSend(XIicPs *InstancePtr, u8 *MsgPtr, int ByteCount,
 363                 u16 SlaveAddr);
 364 void XIicPs_MasterRecv(XIicPs *InstancePtr, u8 *MsgPtr, int ByteCount,
 365                 u16 SlaveAddr);
 366 int XIicPs_MasterSendPolled(XIicPs *InstancePtr, u8 *MsgPtr, int ByteCount,
 367                 u16 SlaveAddr);
 368 int XIicPs_MasterRecvPolled(XIicPs *InstancePtr, u8 *MsgPtr, int ByteCount,
 369                 u16 SlaveAddr);
 370 void XIicPs_EnableSlaveMonitor(XIicPs *InstancePtr, u16 SlaveAddr);
 371 void XIicPs_DisableSlaveMonitor(XIicPs *InstancePtr);
 372 void XIicPs_MasterInterruptHandler(XIicPs *InstancePtr);
 373
 374 /*
 375  * Functions for device as slave, in xiicps_slave.c
 376  */
 377 void XIicPs_SetupSlave(XIicPs *InstancePtr, u16 SlaveAddr);
 378 void XIicPs_SlaveSend(XIicPs *InstancePtr, u8 *MsgPtr, int ByteCount);
 379 void XIicPs_SlaveRecv(XIicPs *InstancePtr, u8 *MsgPtr, int ByteCount);
 380 int XIicPs_SlaveSendPolled(XIicPs *InstancePtr, u8 *MsgPtr, int ByteCount);
 381 int XIicPs_SlaveRecvPolled(XIicPs *InstancePtr, u8 *MsgPtr, int ByteCount);
 382 void XIicPs_SlaveInterruptHandler(XIicPs *InstancePtr);
 383
 384 /*
 385  * Functions for selftest, in xiicps_selftest.c
 386  */
 387 int XIicPs_SelfTest(XIicPs *InstancePtr);
 388
 389 /*
 390  * Functions for setting and getting data rate, in xiicps_options.c
 391  */
 392 int XIicPs_SetOptions(XIicPs *InstancePtr, u32 Options);
 393 int XIicPs_ClearOptions(XIicPs *InstancePtr, u32 Options);
 394 u32 XIicPs_GetOptions(XIicPs *InstancePtr);
 395
 396 int XIicPs_SetSClk(XIicPs *InstancePtr, u32 FsclHz);
 397 u32 XIicPs_GetSClk(XIicPs *InstancePtr);
 398
 399 #ifdef __cplusplus
 400 }
 401 #endif
 402
 403 #endif /* end of protection macro */
 404
 405 /** @} */