scugic: Main Page

| scugic Xilinx SDK Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List
- Examples

scugic Documentation

The generic interrupt controller driver component.The interrupt controller driver uses the idea of priority for the various handlers. Priority is an integer within the range of 1 and 31 inclusive with default of 1 being the highest priority interrupt source. The priorities of the various sources can be dynamically altered as needed through hardware configuration.

The generic interrupt controller supports the following features:

- specific individual interrupt enabling/disabling
- specific individual interrupt acknowledging
- attaching specific callback function to handle interrupt source
- assigning desired priority to interrupt source if default is not acceptable.

Details about connecting the interrupt handler of the driver are contained in the source file specific to interrupt processing, xscugic_intr.c.

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.

Interrupt Vector Tables

The device ID of the interrupt controller device is used by the driver as a direct index into the configuration data table. The user should populate the vector table with handlers and callbacks at run-time using the XScuGic_Connect() and XScuGic_Disconnect() functions.

Each vector table entry corresponds to a device that can generate an interrupt. Each entry contains an interrupt handler function and an argument to be passed to the handler when an interrupt occurs. The user must use XScuGic_Connect() when the interrupt handler takes an argument other than the base address.

Nested Interrupts Processing

Nested interrupts are not supported by this driver.

NOTE: The generic interrupt controller is not a part of the snoop control unit as indicated by the prefix "scu" in the name of the driver. It is an independent module in APU.

    MODIFICATION HISTORY:

    Ver   Who  Date     Changes

    1.00a drg  01/19/00 First release
    1.01a sdm  11/09/11 The XScuGic and XScuGic_Config structures have changed.
                  The HandlerTable (of type XScuGic_VectorTableEntry) is
                  moved to XScuGic_Config structure from XScuGic structure.

                  The "Config" entry in XScuGic structure is made as
                  pointer for better efficiency.

                  A new file named as xscugic_hw.c is now added. It is
                  to implement low level driver routines without using
                  any xscugic instance pointer. They are useful when the
                  user wants to use xscugic through device id or
                  base address. The driver routines provided are explained
                  below.
                  XScuGic_DeviceInitialize that takes device id as
                  argument and initializes the device (without calling
                  XScuGic_CfgInitialize).
                  XScuGic_DeviceInterruptHandler that takes device id
                  as argument and calls appropriate handlers from the
                  HandlerTable.
                  XScuGic_RegisterHandler that registers a new handler
                  by taking xscugic hardware base address as argument.
                  LookupConfigByBaseAddress is used to return the
                  corresponding config structure from XScuGic_ConfigTable
                  based on the scugic base address passed.
    1.02a sdm  12/20/11 Removed AckBeforeService from the XScuGic_Config
                  structure.
    1.03a srt  02/27/13 Moved Offset calculation macros from *.c and *_hw.c to
                  *_hw.h
                  Added APIs

    XScuGic_SetPriTrigTypeByDistAddr()
    XScuGic_GetPriTrigTypeByDistAddr()
                  (CR 702687)
                    Added support to direct interrupts to the appropriate CPU. Earlier
                      interrupts were directed to CPU1 (hard coded). Now depending
                      upon the CPU selected by the user (xparameters.h), interrupts
                      will be directed to the relevant CPU. This fixes CR 699688.
    1.04a hk   05/04/13 Assigned EffectiveAddr to CpuBaseAddress in
                      XScuGic_CfgInitialize. Fix for CR#704400 to remove warnings.
                      Moved functions XScuGic_SetPriTrigTypeByDistAddr and
                XScuGic_GetPriTrigTypeByDistAddr to xscugic_hw.c.
                      This is fix for CR#705621.
    1.05a hk   06/26/13 Modified tcl to export external interrupts correctly to
                        xparameters.h. Fix for CR's 690505, 708928 & 719359.
    2.0   adk  12/10/13 Updated as per the New Tcl API's
    2.1   adk  25/04/14 Fixed the CR:789373 changes are made in the driver tcl file.
    3.00  kvn  02/13/15 Modified code for MISRA-C:2012 compliance.
    3.2   asa  02/29/16 Modified DistributorInit function for Zynq AMP case. The
                      distributor is left uninitialized for Zynq AMP. It is assumed
                that the distributor will be initialized by Linux master. However
                for CortexR5 case, the earlier code is left unchanged where the
                the interrupt processor target registers in the distributor is
                initialized with the corresponding CPU ID on which the application
                built over the scugic driver runs.
                These changes fix CR#937243.

    3.4   asa  04/07/16 Created a new static function DoDistributorInit to simplify
               the flow and avoid code duplication. Changes are made for
               USE_AMP use case for R5. In a scenario (in R5 split mode) when
               one R5 is operating with A53 in open amp config and other
               R5 running baremetal app, the existing code
               had the potential to stop the whole AMP solution to work (if
               for some reason the R5 running the baremetal app tasked to
               initialize the Distributor hangs or crashes before initializing).
               Changes are made so that the R5 under AMP first checks if
               the distributor is enabled or not and if not, it does the
               standard Distributor initialization.
               This fixes the CR#952962.
    3.6   ms   01/23/17 Modified xil_printf statement in main function for all
                        examples to ensure that "Successfully ran" and "Failed"
                        strings are available in all examples. This is a fix
                        for CR-965028.
          kvn  02/17/17 Add support for changing GIC CPU master at run time.
          kvn  02/28/17 Make the CpuId as static variable and Added new
                        XScugiC_GetCpuId to access CpuId.
          ms   03/17/17 Added readme.txt file in examples folder for doxygen
                        generation.
    3.7   ms   04/11/17 Modified tcl file to add suffix U for all macro
                        definitions of scugic in xparameters.h
    3.8   mus  07/05/17 Updated scugic.tcl to add support for interrupts connected
                        through util_reduced_vector IP(OR gate)
          mus  07/05/17 Updated xdefine_zynq_canonical_xpars proc to initialize
                        the HandlerTable in XScuGic_ConfigTable to 0, it removes
                        the compilation warning in xscugic_g.c. Fix for CR#978736.
          mus  07/25/17 Updated xdefine_gic_params proc to export correct canonical
                        definitions for pl to ps interrupts.Fix for CR#980534
    3.9   mus  02/21/18 Added new API's XScuGic_UnmapAllInterruptsFromCpu and
                        XScuGic_InterruptUnmapFromCpu, These API's can be used
                        by applications to unmap specific/all interrupts from
                        target CPU.
    3.10  aru  08/23/18 Resolved MISRA-C:2012 compliance mandatory violations
    4.0   mus  11/22/18 Fixed bugs in software interrupt generation through
                         XScuGic_SoftwareIntr API
    4.1   asa  03/30/19 Made changes not to direct each interrupt to all
                        available CPUs by default. This was breaking AMP
                        behavior. Instead every time an interrupt enable
                        request is received, the interrupt was mapped to
                        the respective CPU. There were several other changes
                        made to implement this. This set of changes was to
                        fix CR-1024716.
    4.1   mus  06/19/19 Added API's XScuGic_MarkCoreAsleep and
                        XScuGic_MarkCoreAwake to mark processor core as
                        asleep or awake. Fix for CR#1027220.