OpenCores
URL https://opencores.org/ocsvn/xenie/xenie/trunk

Subversion Repositories xenie

[/] [xenie/] [trunk/] [examples/] [Eth_example/] [mb_fw/] [drivers/] [iic_v3_4/] [doc/] [html/] [api/] [index.html] - Blame information for rev 4

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 4 DFC
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2
<html xmlns="http://www.w3.org/1999/xhtml">
3
<head>
4
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
5
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
6
<meta name="generator" content="Doxygen 1.8.11"/>
7
<title>iic_v3_4: Main Page</title>
8
<link href="tabs.css" rel="stylesheet" type="text/css"/>
9
<script type="text/javascript" src="jquery.js"></script>
10
<script type="text/javascript" src="dynsections.js"></script>
11
<link href="navtree.css" rel="stylesheet" type="text/css"/>
12
<script type="text/javascript" src="resize.js"></script>
13
<script type="text/javascript" src="navtreedata.js"></script>
14
<script type="text/javascript" src="navtree.js"></script>
15
<script type="text/javascript">
16
  $(document).ready(initResizable);
17
  $(window).load(resizeHeight);
18
</script>
19
<link href="doxygen.css" rel="stylesheet" type="text/css" />
20
<link href="HTML_custom.css" rel="stylesheet" type="text/css"/>
21
</head>
22
<body>
23
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
24
<div id="titlearea">
25
<table cellspacing="0" cellpadding="0">
26
 <tbody>
27
 <tr style="height: 56px;">
28
  <td id="projectlogo"><img alt="Logo" src="xlogo_bg.gif"/></td>
29
  <td id="projectalign" style="padding-left: 0.5em;">
30
   <div id="projectname">iic_v3_4
31
   </div>
32
   <div id="projectbrief">Xilinx SDK Drivers API Documentation</div>
33
  </td>
34
 </tr>
35
 </tbody>
36
</table>
37
</div>
38
<!-- end header part -->
39
<!-- Generated by Doxygen 1.8.11 -->
40
  <div id="navrow1" class="tabs">
41
    <ul class="tablist">
42
      <li class="current"><a href="index.html"><span>Overview</span></a></li>
43
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
44
      <li><a href="globals.html"><span>APIs</span></a></li>
45
      <li><a href="files.html"><span>File&#160;List</span></a></li>
46
    </ul>
47
  </div>
48
</div><!-- top -->
49
<div id="side-nav" class="ui-resizable side-nav-resizable">
50
  <div id="nav-tree">
51
    <div id="nav-tree-contents">
52
      <div id="nav-sync" class="sync"></div>
53
    </div>
54
  </div>
55
  <div id="splitbar" style="-moz-user-select:none;"
56
       class="ui-resizable-handle">
57
  </div>
58
</div>
59
<script type="text/javascript">
60
$(document).ready(function(){initNavTree('index.html','');});
61
</script>
62
<div id="doc-content">
63
<div class="header">
64
  <div class="headertitle">
65
<div class="title">iic_v3_4 Documentation</div>  </div>
66
</div><!--header-->
67
<div class="contents">
68
<div class="textblock"><p><a class="el" href="struct_x_iic.html" title="The XIic driver instance data. ">XIic</a> is the driver for an IIC master or slave device.In order to reduce the memory requirements of the driver the driver is partitioned such that there are optional parts of the driver. Slave, master, and multimaster features are optional such that all these files are not required at the same time. In order to use the slave and multimaster features of the driver, the user must call functions (XIic_SlaveInclude and XIic_MultiMasterInclude) to dynamically include the code. These functions may be called at any time.</p>
69
<p>Two sets of higher level API's are available in the <a class="el" href="struct_x_iic.html" title="The XIic driver instance data. ">XIic</a> driver that can be used for Transmission/Reception in Master mode :</p><ul>
70
<li><a class="el" href="group__iic__v3__1.html#ga977382e8a20bd5e690229f82af2e7603" title="This function sends data as a master on the IIC bus. ">XIic_MasterSend()</a>/ <a class="el" href="group__iic__v3__1.html#ga337bf0d322d4a7d9b4f8baa30e00ab45" title="This function receives data as a master from a slave device on the IIC bus. ">XIic_MasterRecv()</a> which is used in normal mode.</li>
71
<li><a class="el" href="group__iic__v3__1.html#gac4c6388d0db3b08ddcd47f0b2459ff3c" title="This function sends data as a Dynamic master on the IIC bus. ">XIic_DynMasterSend()</a>/ <a class="el" href="group__iic__v3__1.html#ga4d7985d95cd029ab0b0f2a5ccc614793" title="This function receives data as a master from a slave device on the IIC bus. ">XIic_DynMasterRecv()</a> which is used in Dynamic mode.</li>
72
</ul>
73
<p>Similarly two sets of lower level API's are available in <a class="el" href="struct_x_iic.html" title="The XIic driver instance data. ">XIic</a> driver that can be used for Transmission/Reception in Master mode:</p><ul>
74
<li><a class="el" href="group__iic__v3__1.html#ga907c577b53407fb0bfc98d0ca37ee221" title="Send data as a master on the IIC bus. ">XIic_Send()</a>/ <a class="el" href="group__iic__v3__1.html#ga7a848238d75ff57837afa5a58f11f326" title="Receive data as a master on the IIC bus. ">XIic_Recv()</a> which is used in normal mode</li>
75
<li><a class="el" href="group__iic__v3__1.html#gadeaf11cda2466ae1c6036a3de0f52874" title="Send data as a master on the IIC bus. ">XIic_DynSend()</a>/ <a class="el" href="group__iic__v3__1.html#ga9979fbd483e1c8c495c9eb2bfd7ad6e9" title="Receive data as a master on the IIC bus. ">XIic_DynRecv()</a> which is used in Dynamic mode.</li>
76
</ul>
77
<p>The user should use a single set of APIs as per his requirement and should not intermix them.</p>
78
<p>All the driver APIs can be used for read, write and combined mode of operations on the IIC bus.</p>
79
<p>In the normal mode IIC support both 7-bit and 10-bit addressing, and in the dynamic mode support only 7-bit addressing.</p>
80
<p><b>Initialization &amp; Configuration</b></p>
81
<p>The <a class="el" href="struct_x_iic___config.html" title="This typedef contains configuration information for the device. ">XIic_Config</a> structure is used by the driver to configure itself. This configuration structure is typically created by the tool-chain based on HW build properties.</p>
82
<p>To support multiple runtime loading and initialization strategies employed by various operating systems, the driver instance can be initialized in one of the following ways:</p>
83
<ul>
84
<li><a class="el" href="group__iic__v3__1.html#gad36c610ec3139cef71f3795f9ce81308" title="Initializes a specific XIic instance. ">XIic_Initialize()</a> - The driver looks up its own configuration structure created by the tool-chain based on an ID provided by the tool-chain.</li>
85
<li><a class="el" href="group__iic__v3__1.html#ga301f08e1fa6e74bf4c2885702bf0ff70" title="Initializes a specific XIic instance. ">XIic_CfgInitialize()</a> - The driver uses a configuration structure provided by the caller. If running in a system with address translation, the provided virtual memory base address replaces the physical address present in the configuration structure.</li>
86
</ul>
87
<p><b>General Purpose Output</b> The IIC hardware provides a General Purpose Output Register that allows the user to connect general purpose outputs to devices, such as a write protect, for an EEPROM. This register is parameterizable in the hardware such that there could be zero bits in this register and in this case it will cause a bus error if read or written.</p>
88
<p><b>Bus Throttling</b></p>
89
<p>The IIC hardware provides bus throttling which allows either the device, as either a master or a slave, to stop the clock on the IIC bus. This feature allows the software to perform the appropriate processing for each interrupt without an unreasonable response restriction. With this design, it is important for the user to understand the implications of bus throttling.</p>
90
<p><b>Repeated Start</b></p>
91
<p>An application can send multiple messages, as a master, to a slave device and re-acquire the IIC bus each time a message is sent. The repeated start option allows the application to send multiple messages without re-acquiring the IIC bus for each message. The transactions involving repeated start are also called combined transfers if there is Read and Write in the same transaction.</p>
92
<p>The repeated start feature works with all the API's in <a class="el" href="struct_x_iic.html" title="The XIic driver instance data. ">XIic</a> driver.</p>
93
<p>The Repeated Start feature also could cause the application to lock up, or monopolize the IIC bus, should repeated start option be enabled and sequences of messages never end(periodic data collection). Also when repeated start is not disable before the last master message is sent or received, will leave the bus captive to the master, but unused.</p>
94
<p><b>Addressing</b></p>
95
<p>The IIC hardware is parameterized such that it can be built for 7 or 10 bit addresses. The driver provides the ability to control which address size is sent in messages as a master to a slave device. The address size which the hardware responds to as a slave is parameterized as 7 or 10 bits but fixed by the hardware build.</p>
96
<p>Addresses are represented as hex values with no adjustment for the data direction bit as the software manages address bit placement. This is especially important as the bit placement is not handled the same depending on which options are used such as repeated start and 7 vs 10 bit addessing.</p>
97
<p><b>Data Rates</b></p>
98
<p>The IIC hardware is parameterized such that it can be built to support data rates from DC to 400KBit. The frequency of the interrupts which occur is proportional to the data rate.</p>
99
<p><b>Polled Mode Operation</b></p>
100
<p>This driver does not provide a polled mode of operation primarily because polled mode which is non-blocking is difficult with the amount of interaction with the hardware that is necessary.</p>
101
<p><b>Interrupts</b></p>
102
<p>The device has many interrupts which allow IIC data transactions as well as bus status processing to occur.</p>
103
<p>The interrupts are divided into two types, data and status. Data interrupts indicate data has been received or transmitted while the status interrupts indicate the status of the IIC bus. Some of the interrupts, such as Not Addressed As Slave and Bus Not Busy, are only used when these specific events must be recognized as opposed to being enabled at all times.</p>
104
<p>Many of the interrupts are not a single event in that they are continuously present such that they must be disabled after recognition or when undesired. Some of these interrupts, which are data related, may be acknowledged by the software by reading or writing data to the appropriate register, or must be disabled. The following interrupts can be continuous rather than single events.</p><ul>
105
<li>Data Transmit Register Empty/Transmit FIFO Empty</li>
106
<li>Data Receive Register Full/Receive FIFO</li>
107
<li>Transmit FIFO Half Empty</li>
108
<li>Bus Not Busy</li>
109
<li>Addressed As Slave</li>
110
<li>Not Addressed As Slave</li>
111
</ul>
112
<p>The following interrupts are not passed directly to the application thru the status callback. These are only used internally for the driver processing and may result in the receive and send handlers being called to indicate completion of an operation. The following interrupts are data related rather than status.</p><ul>
113
<li>Data Transmit Register Empty/Transmit FIFO Empty</li>
114
<li>Data Receive Register Full/Receive FIFO</li>
115
<li>Transmit FIFO Half Empty</li>
116
<li>Slave Transmit Complete</li>
117
</ul>
118
<p><b>Interrupt To Event Mapping</b></p>
119
<p>The following table provides a mapping of the interrupts to the events which are passed to the status handler and the intended role (master or slave) for the event. Some interrupts can cause multiple events which are combined together into a single status event such as XII_MASTER_WRITE_EVENT and XII_GENERAL_CALL_EVENT </p><pre>
120
Interrupt                         Event(s)                      Role</pre><pre>Arbitration Lost Interrupt        XII_ARB_LOST_EVENT            Master
121
Transmit Error                    XII_SLAVE_NO_ACK_EVENT        Master
122
IIC Bus Not Busy                  XII_BUS_NOT_BUSY_EVENT        Master
123
Addressed As Slave                XII_MASTER_READ_EVENT,        Slave
124
                                  XII_MASTER_WRITE_EVENT,       Slave
125
                                  XII_GENERAL_CALL_EVENT        Slave
126
</pre><p> <b>Not Addressed As Slave Interrupt</b></p>
127
<p>The Not Addressed As Slave interrupt is not passed directly to the application thru the status callback. It is used to determine the end of a message being received by a slave when there was no stop condition (repeated start). It will cause the receive handler to be called to indicate completion of the operation.</p>
128
<p><b>RTOS Independence</b></p>
129
<p>This driver is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads or thread mutual exclusion, virtual memory, or cache control must be satisfied by the layer above this driver.</p>
130
<pre>
131
MODIFICATION HISTORY:</pre><pre>Ver   Who  Date     Changes
132
----- ---- -------- -----------------------------------------------
133
1.01a rfp  10/19/01 release
134
1.01c ecm  12/05/02 new rev
135
1.01d jhl  10/08/03 Added general purpose output feature
136
1.01d sv   05/09/05 Changed the data being written to the Address/Control
137
                    Register and removed the code for testing the
138
                    Receive Data Register in XIic_SelfTest function of
139
                    <a class="el" href="xiic__selftest_8c.html">xiic_selftest.c</a> source file
140
1.02a jvb  12/14/05 I separated dependency on the static config table and
141
                    xparameters.h from the driver initialization by moving
142
                    _Initialize and _LookupConfig to _sinit.c. I also added
143
                    the new _CfgInitialize routine.
144
1.02a mta  03/09/06 Added a new function XIic_IsIicBusy() which returns
145
                whether IIC Bus is Busy or Free.
146
1.02a mta  03/09/06 Implemented Repeated Start in the Low Level Driver.
147
1.03a mta  07/17/06 Added files to support Dynamic IIC controller in High
148
              level driver. Added <a class="el" href="xiic__dyn__master_8c.html">xiic_dyn_master.c</a>. Added support
149
                      for IIC Dynamic controller in Low level driver in <a class="el" href="xiic__l_8c.html">xiic_l.c</a>
150
1.13a wgr  03/22/07 Converted to new coding style.
151
1.13b ecm  11/29/07 added BB polling loops to the DynSend and DynRecv
152
              routines to handle the race condition with BNB in IISR.
153
1.14a sdm  08/22/08 Removed support for static interrupt handlers from the MDD
154
              file
155
1.14a ecm  11/13/08 changed BB polling loops in DynRecv to handle race
156
              condition, CR491889. DynSend was correct from v1.13.b
157
1.15a ktn  02/17/09 Fixed <a class="el" href="group__iic__v3__1.html#ga3e8f77e5df8d92a4b27627e03b5e1807" title="This function gets the addresses for the IIC device driver. ">XIic_GetAddress()</a> to return correct device address.
158
1.16a ktn  07/17/09 Updated the <a class="el" href="group__iic__v3__1.html#ga0a4d9b646c26bcf932561699d69d52b1" title="Runs a limited self-test on the driver/device. ">XIic_SelfTest()</a> to test only Interrupt
159
              Registers.
160
2.00a ktn  10/22/09 Converted all register accesses to 32 bit access.,
161
              Removed the macro XIIC_RESET, XIic_Reset API should be
162
              used in its place.
163
              Removed the XIIC_CLEAR_STATS macro, XIic_ClearStats API
164
              should be used in its place.
165
              Removed the macro XIic_mEnterCriticalRegion,
166
              XIic_IntrGlobalDisable should be used in its place.
167
              Removed the macro XIic_mExitCriticalRegion,
168
              XIic_IntrGlobalEnable should be used in its place.
169
              Some of the macros have been renamed to remove _m from
170
              the name see the <a class="el" href="xiic__i_8h.html">xiic_i.h</a> and <a class="el" href="xiic__l_8h.html">xiic_l.h</a> file for further
171
              information (Example XIic_mClearIntr is now
172
              XIic_ClearIntr).
173
              Some of the macros have been renamed to be consistent,
174
              see the <a class="el" href="xiic__l_8h.html">xiic_l.h</a> file for further information
175
              (Example XIIC_WRITE_IIER is renamed as XIic_WriteIier).
176
              The driver has been updated to use the HAL APIs/macros
177
              (Example XASSERT_NONVOID is now Xil_AssertNonvoid)
178
2.01a ktn  04/09/10 Updated TxErrorhandler in <a class="el" href="xiic__intr_8c.html">xiic_intr.c</a> to be called for
179
              Master Transmitter case based on Addressed As Slave (AAS)
180
              bit rather than MSMS bit(CR 540199).
181
2.02a sdm  10/08/10 Updated to disable the device at the end of the transfer,
182
              using Addressed As Slave (AAS) bit when addressed as
183
              slave in XIic_Send for CR565373.
184
2.03a rkv  01/25/11 Updated in NAAS interrupt handler to support data
185
              recieved less than FIFO size prior to NAAS interrupt.
186
              Fixed for CR590212.
187
2.04a sdm  07/22/11 Added IsSlaveSetAckOff flag to the instance structure.
188
              This flag is set when the Slave has set the Ack Off in the
189
              RecvSlaveData function (<a class="el" href="xiic__slave_8c.html">xiic_slave.c</a>) and
190
              is cleared in the NotAddrAsSlaveHandler (<a class="el" href="xiic__slave_8c.html">xiic_slave.c</a>)
191
              when the master has released the bus. This flag is
192
              to be used by slave applications for recovering when it
193
              has gone out of sync with the master for CR 615004.
194
              Removed a compiler warning in XIic_Send (<a class="el" href="xiic__l_8c.html">xiic_l.c</a>)
195
2.05a bss  02/05/12 Assigned RecvBufferPtr in XIic_MasterSend API and
196
              SendBufferPtr in XIic_MasterRecv to NULL in <a class="el" href="xiic__master_8c.html">xiic_master.c</a>
197
2.06a bss  02/14/13 Modified TxErrorHandler in <a class="el" href="xiic__intr_8c.html">xiic_intr.c</a> to fix CR #686483
198
              Modified <a class="el" href="xiic__eeprom__example_8c.html" title="This file consists of a Interrupt mode design example which uses the Xilinx IIC device and XIic drive...">xiic_eeprom_example.c</a> to fix CR# 683509.
199
              Modified bitwise OR to logical OR in
200
              XIic_InterruptHandler API in <a class="el" href="xiic__intr_8c.html">xiic_intr.c</a>.
201
2.07a adk  18/04/13 Updated the code to avoid unused variable warnings
202
                    when compiling with the -Wextra -Wall flags.
203
                    Changes done in files <a class="el" href="xiic_8c.html">xiic.c</a> and <a class="el" href="xiic__i_8h.html">xiic_i.h</a>. CR:705001
204
2.08a adk  29/07/13 In Low level driver In repeated start condition the
205
              Direction of Tx bit must be disabled in recv condition
206
              It Fixes the CR:685759 Changes are done in the file
207
              <a class="el" href="xiic__l_8c.html">xiic_l.c</a> in the function XIic_Recv.
208
3.0   adk  19/12/13 Updated as per the New Tcl API's
209
3.1   adk  01/08/15 When configured as a slave return the actual number of
210
                    bytes have been received/sent by the Master
211
                    to the user callback (CR: 828504). Changes are made in the
212
              file <a class="el" href="xiic__slave_8c.html">xiic_slave.c</a>.
213
3.2   sk   11/10/15 Used UINTPTR instead of u32 for Baseaddress CR# 867425.
214
                    Changed the prototype of XIic_CfgInitialize API.
215
3.2     sd   18/02/16 In Low level driver in repeated start condition
216
                    NACK for last byte is added. Changes are done in
217
                    XIic_Recv for CR# 862303
218
3.3   sk   06/17/16 Added bus busy checks for slave send/recv and master
219
                    send/recv.
220
3.3   als  06/27/16 XIic_IsIicBusy now a wrapper for XIic_CheckIsBusBusy.
221
</pre> </div></div><!-- contents -->
222
</div><!-- doc-content -->
223
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
224
  <ul>
225
    <li class="footer">Copyright &copy; 2015 Xilinx Inc. All rights reserved.</li>
226
  </ul>
227
</div>
228
</body>
229
</html>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.