board: xilinx: Remove unused ancient i2c driver
[karo-tx-uboot.git] / board / xilinx / common / xipif_v1_23_b.c
1 /* $Id: xipif_v1_23_b.c,v 1.1 2002/03/18 23:24:52 linnj Exp $ */
2 /******************************************************************************
3 *
4 *       XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS"
5 *       AS A COURTESY TO YOU, SOLELY FOR USE IN DEVELOPING PROGRAMS AND
6 *       SOLUTIONS FOR XILINX DEVICES.  BY PROVIDING THIS DESIGN, CODE,
7 *       OR INFORMATION AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE,
8 *       APPLICATION OR STANDARD, XILINX IS MAKING NO REPRESENTATION
9 *       THAT THIS IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT,
10 *       AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE
11 *       FOR YOUR IMPLEMENTATION.  XILINX EXPRESSLY DISCLAIMS ANY
12 *       WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE
13 *       IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR
14 *       REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF
15 *       INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
16 *       FOR A PARTICULAR PURPOSE.
17 *
18 *       (c) Copyright 2002 Xilinx Inc.
19 *       All rights reserved.
20 *
21 ******************************************************************************/
22 /******************************************************************************
23 *
24 * FILENAME:
25 *
26 * xipif.c
27 *
28 * DESCRIPTION:
29 *
30 * This file contains the implementation of the XIpIf component. The
31 * XIpIf component encapsulates the IPIF, which is the standard interface
32 * that IP must adhere to when connecting to a bus.  The purpose of this
33 * component is to encapsulate the IPIF processing such that maintainability
34 * is increased.  This component does not provide a lot of abstraction from
35 * from the details of the IPIF as it is considered a building block for
36 * device drivers.  A device driver designer must be familiar with the
37 * details of the IPIF hardware to use this component.
38 *
39 * The IPIF hardware provides a building block for all hardware devices such
40 * that each device does not need to reimplement these building blocks. The
41 * IPIF contains other building blocks, such as FIFOs and DMA channels, which
42 * are also common to many devices.  These blocks are implemented as separate
43 * hardware blocks and instantiated within the IPIF.  The primary hardware of
44 * the IPIF which is implemented by this software component is the interrupt
45 * architecture.  Since there are many blocks of a device which may generate
46 * interrupts, all the interrupt processing is contained in the common part
47 * of the device, the IPIF.  This interrupt processing is for the device level
48 * only and does not include any processing for the interrupt controller.
49 *
50 * A device is a mechanism such as an Ethernet MAC.  The device is made
51 * up of several parts which include an IPIF and the IP.  The IPIF contains most
52 * of the device infrastructure which is common to all devices, such as
53 * interrupt processing, DMA channels, and FIFOs.  The infrastructure may also
54 * be referred to as IPIF internal blocks since they are part of the IPIF and
55 * are separate blocks that can be selected based upon the needs of the device.
56 * The IP of the device is the logic that is unique to the device and interfaces
57 * to the IPIF of the device.
58 *
59 * In general, there are two levels of registers within the IPIF.  The first
60 * level, referred to as the device level, contains registers which are for the
61 * entire device.  The second level, referred to as the IP level, contains
62 * registers which are specific to the IP of the device.  The two levels of
63 * registers are designed to be hierarchical such that the device level is
64 * is a more general register set above the more specific registers of the IP.
65 * The IP level of registers provides functionality which is typically common
66 * across all devices and allows IP designers to focus on the unique aspects
67 * of the IP.
68 *
69 * The interrupt registers of the IPIF are parameterizable such that the only
70 * the number of bits necessary for the device are implemented. The functions
71 * of this component do not attempt to validate that the passed in arguments are
72 * valid based upon the number of implemented bits.  This is necessary to
73 * maintain the level of performance required for the common components.  Bits
74 * of the registers are assigned starting at the least significant bit of the
75 * registers.
76 *
77 * Critical Sections
78 *
79 * It is the responsibility of the device driver designer to use critical
80 * sections as necessary when calling functions of the IPIF.  This component
81 * does not use critical sections and it does access registers using
82 * read-modify-write operations.  Calls to IPIF functions from a main thread
83 * and from an interrupt context could produce unpredictable behavior such that
84 * the caller must provide the appropriate critical sections.
85 *
86 * Mutual Exclusion
87 *
88 * The functions of the IPIF are not thread safe such that the caller of all
89 * functions is responsible for ensuring mutual exclusion for an IPIF.  Mutual
90 * exclusion across multiple IPIF components is not necessary.
91 *
92 * NOTES:
93 *
94 * None.
95 *
96 * MODIFICATION HISTORY:
97 *
98 * Ver   Who  Date     Changes
99 * ----- ---- -------- -----------------------------------------------
100 * 1.23b jhl  02/27/01 Repartioned to reduce size
101 *
102 ******************************************************************************/
103
104 /***************************** Include Files *********************************/
105
106 #include "xipif_v1_23_b.h"
107 #include "xio.h"
108
109 /************************** Constant Definitions *****************************/
110
111 /* the following constant is used to generate bit masks for register testing
112  * in the self test functions, it defines the starting bit mask that is to be
113  * shifted from the LSB to MSB in creating a register test mask
114  */
115 #define XIIF_V123B_FIRST_BIT_MASK     1UL
116
117 /**************************** Type Definitions *******************************/
118
119 /***************** Macros (Inline Functions) Definitions *********************/
120
121 /************************** Variable Definitions *****************************/
122
123 /************************** Function Prototypes ******************************/
124
125 static XStatus IpIntrSelfTest(u32 RegBaseAddress, u32 IpRegistersWidth);
126
127 /******************************************************************************
128 *
129 * FUNCTION:
130 *
131 * XIpIf_SelfTest
132 *
133 * DESCRIPTION:
134 *
135 * This function performs a self test on the specified IPIF component.  Many
136 * of the registers in the IPIF are tested to ensure proper operation.  This
137 * function is destructive because the IPIF is reset at the start of the test
138 * and at the end of the test to ensure predictable results.  The IPIF reset
139 * also resets the entire device that uses the IPIF.  This function exits with
140 * all interrupts for the device disabled.
141 *
142 * ARGUMENTS:
143 *
144 * InstancePtr points to the XIpIf to operate on.
145 *
146 * DeviceRegistersWidth contains the number of bits in the device interrupt
147 * registers. The hardware is parameterizable such that only the number of bits
148 * necessary to support a device are implemented.  This value must be between 0
149 * and 32 with 0 indicating there are no device interrupt registers used.
150 *
151 * IpRegistersWidth contains the number of bits in the IP interrupt registers
152 * of the device.  The hardware is parameterizable such that only the number of
153 * bits necessary to support a device are implemented.  This value must be
154 * between 0 and 32 with 0 indicating there are no IP interrupt registers used.
155 *
156 * RETURN VALUE:
157 *
158 * A value of XST_SUCCESS indicates the test was successful with no errors.
159 * Any one of the following error values may also be returned.
160 *
161 *   XST_IPIF_RESET_REGISTER_ERROR       The value of a register at reset was
162 *                                       not valid
163 *   XST_IPIF_IP_STATUS_ERROR            A write to the IP interrupt status
164 *                                       register did not read back correctly
165 *   XST_IPIF_IP_ACK_ERROR               One or more bits in the IP interrupt
166 *                                       status register did not reset when acked
167 *   XST_IPIF_IP_ENABLE_ERROR            The IP interrupt enable register
168 *                                       did not read back correctly based upon
169 *                                       what was written to it
170 *
171 * NOTES:
172 *
173 * None.
174 *
175 ******************************************************************************/
176
177 /* the following constant defines the maximum number of bits which may be
178  * used in the registers at the device and IP levels, this is based upon the
179  * number of bits available in the registers
180  */
181 #define XIIF_V123B_MAX_REG_BIT_COUNT 32
182
183 XStatus
184 XIpIfV123b_SelfTest(u32 RegBaseAddress, u8 IpRegistersWidth)
185 {
186         XStatus Status;
187
188         /* assert to verify arguments are valid */
189
190         XASSERT_NONVOID(IpRegistersWidth <= XIIF_V123B_MAX_REG_BIT_COUNT);
191
192         /* reset the IPIF such that it's in a known state before the test
193          * and interrupts are globally disabled
194          */
195         XIIF_V123B_RESET(RegBaseAddress);
196
197         /* perform the self test on the IP interrupt registers, if
198          * it is not successful exit with the status
199          */
200         Status = IpIntrSelfTest(RegBaseAddress, IpRegistersWidth);
201         if (Status != XST_SUCCESS) {
202                 return Status;
203         }
204
205         /* reset the IPIF such that it's in a known state before exiting test */
206
207         XIIF_V123B_RESET(RegBaseAddress);
208
209         /* reaching this point means there were no errors, return success */
210
211         return XST_SUCCESS;
212 }
213
214 /******************************************************************************
215 *
216 * FUNCTION:
217 *
218 * IpIntrSelfTest
219 *
220 * DESCRIPTION:
221 *
222 * Perform a self test on the IP interrupt registers of the IPIF. This
223 * function modifies registers of the IPIF such that they are not guaranteed
224 * to be in the same state when it returns.  Any bits in the IP interrupt
225 * status register which are set are assumed to be set by default after a reset
226 * and are not tested in the test.
227 *
228 * ARGUMENTS:
229 *
230 * InstancePtr points to the XIpIf to operate on.
231 *
232 * IpRegistersWidth contains the number of bits in the IP interrupt registers
233 * of the device.  The hardware is parameterizable such that only the number of
234 * bits necessary to support a device are implemented.  This value must be
235 * between 0 and 32 with 0 indicating there are no IP interrupt registers used.
236 *
237 * RETURN VALUE:
238 *
239 * A status indicating XST_SUCCESS if the test was successful.  Otherwise, one
240 * of the following values is returned.
241 *
242 *   XST_IPIF_RESET_REGISTER_ERROR       The value of a register at reset was
243 *                                       not valid
244 *   XST_IPIF_IP_STATUS_ERROR            A write to the IP interrupt status
245 *                                       register did not read back correctly
246 *   XST_IPIF_IP_ACK_ERROR               One or more bits in the IP status
247 *                                       register did not reset when acked
248 *   XST_IPIF_IP_ENABLE_ERROR            The IP interrupt enable register
249 *                                       did not read back correctly based upon
250 *                                       what was written to it
251 * NOTES:
252 *
253 * None.
254 *
255 ******************************************************************************/
256 static XStatus
257 IpIntrSelfTest(u32 RegBaseAddress, u32 IpRegistersWidth)
258 {
259         /* ensure that the IP interrupt interrupt enable register is  zero
260          * as it should be at reset, the interrupt status is dependent upon the
261          * IP such that it's reset value is not known
262          */
263         if (XIIF_V123B_READ_IIER(RegBaseAddress) != 0) {
264                 return XST_IPIF_RESET_REGISTER_ERROR;
265         }
266
267         /* if there are any used IP interrupts, then test all of the interrupt
268          * bits in all testable registers
269          */
270         if (IpRegistersWidth > 0) {
271                 u32 BitCount;
272                 u32 IpInterruptMask = XIIF_V123B_FIRST_BIT_MASK;
273                 u32 Mask = XIIF_V123B_FIRST_BIT_MASK;   /* bits assigned MSB to LSB */
274                 u32 InterruptStatus;
275
276                 /* generate the register masks to be used for IP register tests, the
277                  * number of bits supported by the hardware is parameterizable such
278                  * that only that number of bits are implemented in the registers, the
279                  * bits are allocated starting at the MSB of the registers
280                  */
281                 for (BitCount = 1; BitCount < IpRegistersWidth; BitCount++) {
282                         Mask = Mask << 1;
283                         IpInterruptMask |= Mask;
284                 }
285
286                 /* get the current IP interrupt status register contents, any bits
287                  * already set must default to 1 at reset in the device and these
288                  * bits can't be tested in the following test, remove these bits from
289                  * the mask that was generated for the test
290                  */
291                 InterruptStatus = XIIF_V123B_READ_IISR(RegBaseAddress);
292                 IpInterruptMask &= ~InterruptStatus;
293
294                 /* set the bits in the device status register and verify them by reading
295                  * the register again, all bits of the register are latched
296                  */
297                 XIIF_V123B_WRITE_IISR(RegBaseAddress, IpInterruptMask);
298                 InterruptStatus = XIIF_V123B_READ_IISR(RegBaseAddress);
299                 if ((InterruptStatus & IpInterruptMask) != IpInterruptMask)
300                 {
301                         return XST_IPIF_IP_STATUS_ERROR;
302                 }
303
304                 /* test to ensure that the bits set in the IP interrupt status register
305                  * can be cleared by acknowledging them in the IP interrupt status
306                  * register then read it again and verify it was cleared
307                  */
308                 XIIF_V123B_WRITE_IISR(RegBaseAddress, IpInterruptMask);
309                 InterruptStatus = XIIF_V123B_READ_IISR(RegBaseAddress);
310                 if ((InterruptStatus & IpInterruptMask) != 0) {
311                         return XST_IPIF_IP_ACK_ERROR;
312                 }
313
314                 /* set the IP interrupt enable set register and then read the IP
315                  * interrupt enable register and verify the interrupts were enabled
316                  */
317                 XIIF_V123B_WRITE_IIER(RegBaseAddress, IpInterruptMask);
318                 if (XIIF_V123B_READ_IIER(RegBaseAddress) != IpInterruptMask) {
319                         return XST_IPIF_IP_ENABLE_ERROR;
320                 }
321
322                 /* clear the IP interrupt enable register and then read the
323                  * IP interrupt enable register and verify the interrupts were disabled
324                  */
325                 XIIF_V123B_WRITE_IIER(RegBaseAddress, 0);
326                 if (XIIF_V123B_READ_IIER(RegBaseAddress) != 0) {
327                         return XST_IPIF_IP_ENABLE_ERROR;
328                 }
329         }
330         return XST_SUCCESS;
331 }