drivers/i2c/xilinx_iic/xiic.h

   1 /* $Id: xiic.h,v 1.1.1.1 2005/04/11 02:50:21 jack Exp $ */
   2 /******************************************************************************
   3 *
   4 *     Author: Xilinx, Inc.
   5 *
   6 *
   7 *     This program is free software; you can redistribute it and/or modify it
   8 *     under the terms of the GNU General Public License as published by the
   9 *     Free Software Foundation; either version 2 of the License, or (at your
  10 *     option) any later version.
  11 *
  12 *
  13 *     XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS" AS A
  14 *     COURTESY TO YOU. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION AS
  15 *     ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION OR STANDARD,
  16 *     XILINX IS MAKING NO REPRESENTATION THAT THIS IMPLEMENTATION IS FREE
  17 *     FROM ANY CLAIMS OF INFRINGEMENT, AND YOU ARE RESPONSIBLE FOR
  18 *     OBTAINING ANY RIGHTS YOU MAY REQUIRE FOR YOUR IMPLEMENTATION.
  19 *     XILINX EXPRESSLY DISCLAIMS ANY WARRANTY WHATSOEVER WITH RESPECT TO
  20 *     THE ADEQUACY OF THE IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY
  21 *     WARRANTIES OR REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM
  22 *     CLAIMS OF INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND
  23 *     FITNESS FOR A PARTICULAR PURPOSE.
  24 *
  25 *
  26 *     Xilinx products are not intended for use in life support appliances,
  27 *     devices, or systems. Use in such applications is expressly prohibited.
  28 *
  29 *
  30 *     (c) Copyright 2002 Xilinx Inc.
  31 *     All rights reserved.
  32 *
  33 *
  34 *     You should have received a copy of the GNU General Public License along
  35 *     with this program; if not, write to the Free Software Foundation, Inc.,
  36 *     675 Mass Ave, Cambridge, MA 02139, USA.
  37 *
  38 ******************************************************************************/
  39 /*****************************************************************************/
  40 /**
  41 *
  42 * @file xiic.h
  43 *
  44 * XIic is the driver for an IIC master or slave device.
  45
  46 * In order to reduce the memory requirements of the driver it is partitioned
  47 * such that there are optional parts of the driver.  Slave, master, and
  48 * multimaster features are optional such that these files are not required.
  49 * In order to use the slave and multimaster features of the driver, the user
  50 * must call functions (XIic_SlaveInclude and XIic_MultiMasterInclude)
  51 * to dynamically include the code .  These functions may be called at any time.
  52 *
  53 * <b>Bus Throttling</b>
  54 *
  55 * The IIC hardware provides bus throttling which allows either the device, as
  56 * either a master or a slave, to stop the clock on the IIC bus. This feature
  57 * allows the software to perform the appropriate processing for each interrupt
  58 * without an unreasonable response restriction.  With this design, it is
  59 * important for the user to understand the implications of bus throttling.
  60 *
  61 * <b>Repeated Start</b>
  62 *
  63 * An application can send multiple messages, as a master, to a slave device
  64 * and re-acquire the IIC bus each time a message is sent. The repeated start
  65 * option allows the application to send multiple messages without re-acquiring
  66 * the IIC bus for each message. This feature also could cause the application
  67 * to lock up, or monopolize the IIC bus, should repeated start option be
  68 * enabled and sequences of messages never end (periodic data collection).
  69 * Also when repeated start is not disable before the last master message is
  70 * sent or received, will leave the bus captive to the master, but unused.
  71 *
  72 * <b>Addressing</b>
  73 *
  74 * The IIC hardware is parameterized such that it can be built for 7 or 10
  75 * bit addresses. The driver provides the ability to control which address
  76 * size is sent in messages as a master to a slave device.  The address size
  77 * which the hardware responds to as a slave is parameterized as 7 or 10 bits
  78 * but fixed by the hardware build.
  79 *
  80 * Addresses are represented as hex values with no adjustment for the data
  81 * direction bit as the software manages address bit placement. This is
  82 * especially important as the bit placement is not handled the same depending
  83 * on which options are used such as repeated start and 7 vs 10 bit addessing.
  84 *
  85 * <b>Data Rates</b>
  86 *
  87 * The IIC hardware is parameterized such that it can be built to support
  88 * data rates from DC to 400KBit. The frequency of the interrupts which
  89 * occur is proportional to the data rate.
  90 *
  91 * <b>Polled Mode Operation</b>
  92 *
  93 * This driver does not provide a polled mode of operation primarily because
  94 * polled mode which is non-blocking is difficult with the amount of
  95 * interaction with the hardware that is necessary.
  96 *
  97 * <b>Interrupts</b>
  98 *
  99 * The device has many interrupts which allow IIC data transactions as well
 100 * as bus status processing to occur.
 101 *
 102 * The interrupts are divided into two types, data and status. Data interrupts
 103 * indicate data has been received or transmitted while the status interrupts
 104 * indicate the status of the IIC bus. Some of the interrupts, such as Not
 105 * Addressed As Slave and Bus Not Busy, are only used when these specific
 106 * events must be recognized as opposed to being enabled at all times.
 107 *
 108 * Many of the interrupts are not a single event in that they are continuously
 109 * present such that they must be disabled after recognition or when undesired.
 110 * Some of these interrupts, which are data related, may be acknowledged by the
 111 * software by reading or writing data to the appropriate register, or must
 112 * be disabled. The following interrupts can be continuous rather than single
 113 * events.
 114 *   - Data Transmit Register Empty/Transmit FIFO Empty
 115 *   - Data Receive Register Full/Receive FIFO
 116 *   - Transmit FIFO Half Empty
 117 *   - Bus Not Busy
 118 *   - Addressed As Slave
 119 *   - Not Addressed As Slave
 120 *
 121 * The following interrupts are not passed directly to the application thru the
 122 * status callback.  These are only used internally for the driver processing
 123 * and may result in the receive and send handlers being called to indicate
 124 * completion of an operation.  The following interrupts are data related
 125 * rather than status.
 126 *   - Data Transmit Register Empty/Transmit FIFO Empty
 127 *   - Data Receive Register Full/Receive FIFO
 128 *   - Transmit FIFO Half Empty
 129 *   - Slave Transmit Complete
 130 *
 131 * <b>Interrupt To Event Mapping</b>
 132 *
 133 * The following table provides a mapping of the interrupts to the events which
 134 * are passed to the status handler and the intended role (master or slave) for
 135 * the event.  Some interrupts can cause multiple events which are combined
 136 * together into a single status event such as XII_MASTER_WRITE_EVENT and
 137 * XII_GENERAL_CALL_EVENT
 138 * <pre>
 139 * Interrupt                         Event(s)                     Role
 140 *
 141 * Arbitration Lost Interrupt        XII_ARB_LOST_EVENT            Master
 142 * Transmit Error                    XII_SLAVE_NO_ACK_EVENT        Master
 143 * IIC Bus Not Busy                  XII_BUS_NOT_BUSY_EVENT        Master
 144 * Addressed As Slave                XII_MASTER_READ_EVENT,        Slave
 145 *                                   XII_MASTER_WRITE_EVENT,       Slave
 146 *                                   XII_GENERAL_CALL_EVENT        Slave
 147 * </pre>
 148 * <b>Not Addressed As Slave Interrupt</b>
 149 *
 150 * The Not Addressed As Slave interrupt is not passed directly to the
 151 * application thru the status callback.  It is used to determine the end of
 152 * a message being received by a slave when there was no stop condition
 153 * (repeated start).  It will cause the receive handler to be called to
 154 * indicate completion of the operation.
 155 *
 156 * <b>RTOS Independence</b>
 157 *
 158 * This driver is intended to be RTOS and processor independent.  It works
 159 * with physical addresses only.  Any needs for dynamic memory management,
 160 * threads or thread mutual exclusion, virtual memory, or cache control must
 161 * be satisfied by the layer above this driver.
 162 *
 163 * <pre>
 164 * MODIFICATION HISTORY:
 165 *
 166 * Ver   Who  Date     Changes
 167 * ----- ---- -------- -----------------------------------------------
 168 * 1.01a rfp  10/19/01 release
 169 * </pre>
 170 *
 171 ******************************************************************************/
 172
 173 #ifndef XIIC_H                  /* prevent circular inclusions */
 174 #define XIIC_H                  /* by using protection macros */
 175
 176 /***************************** Include Files *********************************/
 177
 178 #include "xbasic_types.h"
 179 #include "xstatus.h"
 180 #include "xipif_v1_23_b.h"
 181 #include "xiic_l.h"
 182
 183 /************************** Constant Definitions *****************************/
 184
 185 /** @name Configuration options
 186  *
 187  * The following options may be specified or retrieved for the device and
 188  * enable/disable additional features of the IIC bus.  Each of the options
 189  * are bit fields such that more than one may be specified.
 190  * @{
 191  */
 192 /**
 193  * <pre>
 194  * XII_GENERAL_CALL_OPTION      The general call option allows an IIC slave to
 195  *                              recognized the general call address. The status
 196  *                              handler is called as usual indicating the device
 197  *                              has been addressed as a slave with a general
 198  *                              call. It is the application's responsibility to
 199  *                              perform any special processing for the general
 200  *                              call.
 201  *
 202  * XII_REPEATED_START_OPTION    The repeated start option allows multiple
 203  *                              messages to be sent/received on the IIC bus
 204  *                              without rearbitrating for the bus.  The messages
 205  *                              are sent as a series of messages such that the
 206  *                              option must be enabled before the 1st message of
 207  *                              the series, to prevent an stop condition from
 208  *                              being generated on the bus, and disabled before
 209  *                              the last message of the series, to allow the
 210  *                              stop condition to be generated.
 211  *
 212  * XII_SEND_10_BIT_OPTION       The send 10 bit option allows 10 bit addresses
 213  *                              to be sent on the bus when the device is a
 214  *                              master. The device can be configured to respond
 215  *                              as to 7 bit addresses even though it may be
 216  *                              communicating with other devices that support 10
 217  *                              bit addresses.  When this option is not enabled,
 218  *                              only 7 bit addresses are sent on the bus.
 219  *
 220  * </pre>
 221  */
 222 #define XII_GENERAL_CALL_OPTION    0x00000001
 223 #define XII_REPEATED_START_OPTION  0x00000002
 224 #define XII_SEND_10_BIT_OPTION     0x00000004
 225
 226 /*@}*/
 227
 228 /** @name Status events
 229  *
 230  * The following status events occur during IIC bus processing and are passed
 231  * to the status callback. Each event is only valid during the appropriate
 232  * processing of the IIC bus. Each of these events are bit fields such that
 233  * more than one may be specified.
 234  * @{
 235  */
 236 /**
 237  * <pre>
 238  *   XII_BUS_NOT_BUSY_EVENT      bus transitioned to not busy
 239  *   XII_ARB_LOST_EVENT          arbitration was lost
 240  *   XII_SLAVE_NO_ACK_EVENT      slave did not acknowledge data (had error)
 241  *   XII_MASTER_READ_EVENT       master reading from slave
 242  *   XII_MASTER_WRITE_EVENT      master writing to slave
 243  *   XII_GENERAL_CALL_EVENT      general call to all slaves
 244  * </pre>
 245  */
 246 #define XII_BUS_NOT_BUSY_EVENT   0x00000001
 247 #define XII_ARB_LOST_EVENT       0x00000002
 248 #define XII_SLAVE_NO_ACK_EVENT   0x00000004
 249 #define XII_MASTER_READ_EVENT    0x00000008
 250 #define XII_MASTER_WRITE_EVENT   0x00000010
 251 #define XII_GENERAL_CALL_EVENT   0x00000020
 252 /*@}*/
 253
 254 /* The following address types are used when setting and getting the addresses
 255  * of the driver. These are mutually exclusive such that only one or the other
 256  * may be specified.
 257  */
 258 /** bus address of slave device */
 259 #define XII_ADDR_TO_SEND_TYPE       1
 260 /** this device's bus address when slave */
 261 #define XII_ADDR_TO_RESPOND_TYPE    2
 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;/**< Device base address */
 271         u32 Has10BitAddr;
 272                        /**< does device have 10 bit address decoding */
 273 } XIic_Config;
 274
 275 /**
 276  * This callback function data type is defined to handle the asynchronous
 277  * processing of sent and received data of the IIC driver.  The application
 278  * using this driver is expected to define a handler of this type to support
 279  * interrupt driven mode. The handlers are called in an interrupt context such
 280  * that minimal processing should be performed. The handler data type is
 281  * utilized for both send and receive handlers.
 282  *
 283  * @param CallBackRef is a callback reference passed in by the upper layer when
 284  *        setting the callback functions, and passed back to the upper layer
 285  *        when the callback is invoked. Its type is unimportant to the driver
 286  *        component, so it is a void pointer.
 287  *
 288  * @param ByteCount indicates the number of bytes remaining to be sent or
 289  *        received.  A value of zero indicates that the requested number of
 290  *        bytes were sent or received.
 291  */
 292 typedef void (*XIic_Handler) (void *CallBackRef, int ByteCount);
 293
 294 /**
 295  * This callback function data type is defined to handle the asynchronous
 296  * processing of status events of the IIC driver.  The application using
 297  * this driver is expected to define a handler of this type to support
 298  * interrupt driven mode. The handler is called in an interrupt context such
 299  * that minimal processing should be performed.
 300  *
 301  * @param CallBackRef is a callback reference passed in by the upper layer when
 302  *        setting the callback functions, and passed back to the upper layer
 303  *        when the callback is invoked. Its type is unimportant to the driver
 304  *        component, so it is a void pointer.
 305  *
 306  * @param StatusEvent indicates one or more status events that occurred.  See
 307  *        the definition of the status events above.
 308  */
 309 typedef void (*XIic_StatusHandler) (void *CallBackRef, XStatus StatusEvent);
 310
 311 /**
 312  * XIic statistics
 313  */
 314 typedef struct {
 315         u8 ArbitrationLost;/**< Number of times arbitration was lost */
 316         u8 RepeatedStarts; /**< Number of repeated starts */
 317         u8 BusBusy;        /**< Number of times bus busy status returned */
 318         u8 RecvBytes;      /**< Number of bytes received */
 319         u8 RecvInterrupts; /**< Number of receive interrupts */
 320         u8 SendBytes;      /**< Number of transmit bytes received */
 321         u8 SendInterrupts; /**< Number of transmit interrupts */
 322         u8 TxErrors;       /**< Number of transmit errors (no ack) */
 323         u8 IicInterrupts;  /**< Number of IIC (device) interrupts */
 324 } XIicStats;
 325
 326 /**
 327  * The XIic driver instance data. The user is required to allocate a
 328  * variable of this type for every IIC device in the system. A pointer
 329  * to a variable of this type is then passed to the driver API functions.
 330  */
 331 typedef struct {
 332         XIicStats Stats;        /* Statistics                              */
 333         u32 BaseAddress;        /* Device base address                     */
 334         u32 Has10BitAddr;       /* TRUE when 10 bit addressing in design  */
 335         u32 IsReady;            /* Device is initialized and ready         */
 336         u32 IsStarted;          /* Device has been started                 */
 337         int AddrOfSlave;        /* Slave addr writing to                   */
 338
 339         u32 Options;            /* current operating options               */
 340         u8 *SendBufferPtr;      /* Buffer to send (state)                  */
 341         u8 *RecvBufferPtr;      /* Buffer to receive (state)               */
 342         u8 TxAddrMode;          /* State of Tx Address transmission        */
 343         int SendByteCount;      /* Number of data bytes in buffer (state)  */
 344         int RecvByteCount;      /* Number of empty bytes in buffer (state) */
 345
 346         XIic_StatusHandler StatusHandler;
 347         void *StatusCallBackRef;        /* Callback reference for status handler */
 348         XIic_Handler RecvHandler;
 349         void *RecvCallBackRef;  /* Callback reference for recv handler */
 350         XIic_Handler SendHandler;
 351         void *SendCallBackRef;  /* Callback reference for send handler */
 352
 353 } XIic;
 354
 355 /***************** Macros (Inline Functions) Definitions *********************/
 356
 357 /************************** Function Prototypes ******************************/
 358
 359 /*
 360  * Required functions in xiic.c
 361  */
 362 XStatus XIic_Initialize(XIic * InstancePtr, u16 DeviceId);
 363
 364 XStatus XIic_Start(XIic * InstancePtr);
 365 XStatus XIic_Stop(XIic * InstancePtr);
 366
 367 void XIic_Reset(XIic * InstancePtr);
 368
 369 XStatus XIic_SetAddress(XIic * InstancePtr, int AddressType, int Address);
 370 u16 XIic_GetAddress(XIic * InstancePtr, int AddressType);
 371
 372 XIic_Config *XIic_LookupConfig(u16 DeviceId);
 373
 374 /*
 375  * Interrupt (currently required) functions in xiic_intr.c
 376  */
 377 void XIic_InterruptHandler(void *InstancePtr);
 378 void XIic_SetRecvHandler(XIic * InstancePtr, void *CallBackRef,
 379                          XIic_Handler FuncPtr);
 380 void XIic_SetSendHandler(XIic * InstancePtr, void *CallBackRef,
 381                          XIic_Handler FuncPtr);
 382 void XIic_SetStatusHandler(XIic * InstancePtr, void *CallBackRef,
 383                            XIic_StatusHandler FuncPtr);
 384 /*
 385  * Master send and receive functions in xiic_master.c
 386  */
 387 XStatus XIic_MasterRecv(XIic * InstancePtr, u8 * RxMsgPtr, int ByteCount);
 388 XStatus XIic_MasterSend(XIic * InstancePtr, u8 * TxMsgPtr, int ByteCount);
 389
 390 /*
 391  * Slave send and receive functions in xiic_slave.c
 392  */
 393 void XIic_SlaveInclude(void);
 394 XStatus XIic_SlaveRecv(XIic * InstancePtr, u8 * RxMsgPtr, int ByteCount);
 395 XStatus XIic_SlaveSend(XIic * InstancePtr, u8 * TxMsgPtr, int ByteCount);
 396
 397 /*
 398  * Statistics functions in xiic_stats.c
 399  */
 400 void XIic_GetStats(XIic * InstancePtr, XIicStats * StatsPtr);
 401 void XIic_ClearStats(XIic * InstancePtr);
 402
 403 /*
 404  * Self test functions in xiic_selftest.c
 405  */
 406 XStatus XIic_SelfTest(XIic * InstancePtr);
 407
 408 /*
 409  * Options functions in xiic_options.c
 410  */
 411 void XIic_SetOptions(XIic * InstancePtr, u32 Options);
 412 u32 XIic_GetOptions(XIic * InstancePtr);
 413
 414 /*
 415  * Multi-master functions in xiic_multi_master.c
 416  */
 417 void XIic_MultiMasterInclude(void);
 418
 419 #endif                          /* end of protection macro */