1 /******************************************************************************
3 * Copyright (C) 2010 - 2014 Xilinx, Inc. All rights reserved.
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:
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
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.
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
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.
31 ******************************************************************************/
32 /*****************************************************************************/
36 * @addtogroup scugic_v2_1
40 * The generic interrupt controller driver component.
42 * The interrupt controller driver uses the idea of priority for the various
43 * handlers. Priority is an integer within the range of 1 and 31 inclusive with
44 * default of 1 being the highest priority interrupt source. The priorities
45 * of the various sources can be dynamically altered as needed through
46 * hardware configuration.
48 * The generic interrupt controller supports the following
51 * - specific individual interrupt enabling/disabling
52 * - specific individual interrupt acknowledging
53 * - attaching specific callback function to handle interrupt source
54 * - assigning desired priority to interrupt source if default is not
57 * Details about connecting the interrupt handler of the driver are contained
58 * in the source file specific to interrupt processing, xscugic_intr.c.
60 * This driver is intended to be RTOS and processor independent. It works with
61 * physical addresses only. Any needs for dynamic memory management, threads
62 * or thread mutual exclusion, virtual memory, or cache control must be
63 * satisfied by the layer above this driver.
65 * <b>Interrupt Vector Tables</b>
67 * The device ID of the interrupt controller device is used by the driver as a
68 * direct index into the configuration data table. The user should populate the
69 * vector table with handlers and callbacks at run-time using the
70 * XScuGic_Connect() and XScuGic_Disconnect() functions.
72 * Each vector table entry corresponds to a device that can generate an
73 * interrupt. Each entry contains an interrupt handler function and an
74 * argument to be passed to the handler when an interrupt occurs. The
75 * user must use XScuGic_Connect() when the interrupt handler takes an
76 * argument other than the base address.
78 * <b>Nested Interrupts Processing</b>
80 * Nested interrupts are not supported by this driver.
83 * The generic interrupt controller is not a part of the snoop control unit
84 * as indicated by the prefix "scu" in the name of the driver.
85 * It is an independent module in APU.
88 * MODIFICATION HISTORY:
90 * Ver Who Date Changes
91 * ----- ---- -------- ---------------------------------------------------------
92 * 1.00a drg 01/19/00 First release
93 * 1.01a sdm 11/09/11 The XScuGic and XScuGic_Config structures have changed.
94 * The HandlerTable (of type XScuGic_VectorTableEntry) is
95 * moved to XScuGic_Config structure from XScuGic structure.
97 * The "Config" entry in XScuGic structure is made as
98 * pointer for better efficiency.
100 * A new file named as xscugic_hw.c is now added. It is
101 * to implement low level driver routines without using
102 * any xscugic instance pointer. They are useful when the
103 * user wants to use xscugic through device id or
104 * base address. The driver routines provided are explained
106 * XScuGic_DeviceInitialize that takes device id as
107 * argument and initializes the device (without calling
108 * XScuGic_CfgInitialize).
109 * XScuGic_DeviceInterruptHandler that takes device id
110 * as argument and calls appropriate handlers from the
112 * XScuGic_RegisterHandler that registers a new handler
113 * by taking xscugic hardware base address as argument.
114 * LookupConfigByBaseAddress is used to return the
115 * corresponding config structure from XScuGic_ConfigTable
116 * based on the scugic base address passed.
117 * 1.02a sdm 12/20/11 Removed AckBeforeService from the XScuGic_Config
119 * 1.03a srt 02/27/13 Moved Offset calculation macros from *.c and *_hw.c to
122 * - XScuGic_SetPriTrigTypeByDistAddr()
123 * - XScuGic_GetPriTrigTypeByDistAddr()
125 * Added support to direct interrupts to the appropriate CPU. Earlier
126 * interrupts were directed to CPU1 (hard coded). Now depending
127 * upon the CPU selected by the user (xparameters.h), interrupts
128 * will be directed to the relevant CPU. This fixes CR 699688.
129 * 1.04a hk 05/04/13 Assigned EffectiveAddr to CpuBaseAddress in
130 * XScuGic_CfgInitialize. Fix for CR#704400 to remove warnings.
131 * Moved functions XScuGic_SetPriTrigTypeByDistAddr and
132 * XScuGic_GetPriTrigTypeByDistAddr to xscugic_hw.c.
133 * This is fix for CR#705621.
134 * 1.05a hk 06/26/13 Modified tcl to export external interrupts correctly to
135 * xparameters.h. Fix for CR's 690505, 708928 & 719359.
136 * 2.0 adk 12/10/13 Updated as per the New Tcl API's
137 * 2.1 adk 25/04/14 Fixed the CR:789373 changes are made in the driver tcl file.
141 ******************************************************************************/
143 #ifndef XSCUGIC_H /* prevent circular inclusions */
144 #define XSCUGIC_H /* by using protection macros */
151 /***************************** Include Files *********************************/
155 #include "xscugic_hw.h"
156 #include "xil_exception.h"
158 /************************** Constant Definitions *****************************/
161 /**************************** Type Definitions *******************************/
163 /* The following data type defines each entry in an interrupt vector table.
164 * The callback reference is the base address of the interrupting device
165 * for the low level driver and an instance pointer for the high level driver.
169 Xil_InterruptHandler Handler;
171 } XScuGic_VectorTableEntry;
174 * This typedef contains configuration information for the device.
178 u16 DeviceId; /**< Unique ID of device */
179 u32 CpuBaseAddress; /**< CPU Interface Register base address */
180 u32 DistBaseAddress; /**< Distributor Register base address */
181 XScuGic_VectorTableEntry HandlerTable[XSCUGIC_MAX_NUM_INTR_INPUTS];/**<
182 Vector table of interrupt handlers */
186 * The XScuGic driver instance data. The user is required to allocate a
187 * variable of this type for every intc device in the system. A pointer
188 * to a variable of this type is then passed to the driver API functions.
192 XScuGic_Config *Config; /**< Configuration table entry */
193 u32 IsReady; /**< Device is initialized and ready */
194 u32 UnhandledInterrupts; /**< Intc Statistics */
197 /***************** Macros (Inline Functions) Definitions *********************/
199 /****************************************************************************/
202 * Write the given CPU Interface register
204 * @param InstancePtr is a pointer to the instance to be worked on.
205 * @param RegOffset is the register offset to be written
206 * @param Data is the 32-bit value to write to the register
212 * void XScuGic_CPUWriteReg(XScuGic *InstancePtr, u32 RegOffset, u32 Data)
214 *****************************************************************************/
215 #define XScuGic_CPUWriteReg(InstancePtr, RegOffset, Data) \
216 (XScuGic_WriteReg(((InstancePtr)->Config->CpuBaseAddress), (RegOffset), \
219 /****************************************************************************/
222 * Read the given CPU Interface register
224 * @param InstancePtr is a pointer to the instance to be worked on.
225 * @param RegOffset is the register offset to be read
227 * @return The 32-bit value of the register
231 * u32 XScuGic_CPUReadReg(XScuGic *InstancePtr, u32 RegOffset)
233 *****************************************************************************/
234 #define XScuGic_CPUReadReg(InstancePtr, RegOffset) \
235 (XScuGic_ReadReg(((InstancePtr)->Config->CpuBaseAddress), (RegOffset)))
237 /****************************************************************************/
240 * Write the given Distributor Interface register
242 * @param InstancePtr is a pointer to the instance to be worked on.
243 * @param RegOffset is the register offset to be written
244 * @param Data is the 32-bit value to write to the register
250 * void XScuGic_DistWriteReg(XScuGic *InstancePtr, u32 RegOffset, u32 Data)
252 *****************************************************************************/
253 #define XScuGic_DistWriteReg(InstancePtr, RegOffset, Data) \
254 (XScuGic_WriteReg(((InstancePtr)->Config->DistBaseAddress), (RegOffset), \
257 /****************************************************************************/
260 * Read the given Distributor Interface register
262 * @param InstancePtr is a pointer to the instance to be worked on.
263 * @param RegOffset is the register offset to be read
265 * @return The 32-bit value of the register
269 * u32 XScuGic_DistReadReg(XScuGic *InstancePtr, u32 RegOffset)
271 *****************************************************************************/
272 #define XScuGic_DistReadReg(InstancePtr, RegOffset) \
273 (XScuGic_ReadReg(((InstancePtr)->Config->DistBaseAddress), (RegOffset)))
275 /************************** Function Prototypes ******************************/
278 * Required functions in xscugic.c
281 int XScuGic_Connect(XScuGic *InstancePtr, u32 Int_Id,
282 Xil_InterruptHandler Handler, void *CallBackRef);
283 void XScuGic_Disconnect(XScuGic *InstancePtr, u32 Int_Id);
285 void XScuGic_Enable(XScuGic *InstancePtr, u32 Int_Id);
286 void XScuGic_Disable(XScuGic *InstancePtr, u32 Int_Id);
288 int XScuGic_CfgInitialize(XScuGic *InstancePtr, XScuGic_Config *ConfigPtr,
291 int XScuGic_SoftwareIntr(XScuGic *InstancePtr, u32 Int_Id, u32 Cpu_Id);
293 void XScuGic_GetPriorityTriggerType(XScuGic *InstancePtr, u32 Int_Id,
294 u8 *Priority, u8 *Trigger);
295 void XScuGic_SetPriorityTriggerType(XScuGic *InstancePtr, u32 Int_Id,
296 u8 Priority, u8 Trigger);
299 * Initialization functions in xscugic_sinit.c
301 XScuGic_Config *XScuGic_LookupConfig(u16 DeviceId);
304 * Interrupt functions in xscugic_intr.c
306 void XScuGic_InterruptHandler(XScuGic *InstancePtr);
309 * Self-test functions in xscugic_selftest.c
311 int XScuGic_SelfTest(XScuGic *InstancePtr);
317 #endif /* end of protection macro */