csl_intc.h

TI达芬奇dm644x各硬件模块测试代码

/*  ============================================================================
 *   Copyright (c) Texas Instruments Inc 2002, 2003, 2004, 2005                 
 *                                                                              
 *   Use of this software is controlled by the terms and conditions found in the
 *   license agreement under which this software has been supplied.             
 *   ===========================================================================
 */

/** @mainpage Interrupt Controller 
 *
 * @section Introduction 
 *
 * @subsection xxx Purpose and Scope
 * The purpose of this document is to detail the  CSL APIs for the
 * INTC Module.
 *
 * @subsection aaa Terms and Abbreviations
 *   -# CSL:  Chip Support Library
 *   -# API:  Application Programmer Interface
 *   -# INTC: Interrupt Controller
 *
 * @subsection References
 *    -# CSL 3.x Technical Requirements Specifications Version 0.5, dated
 *       May 14th, 2003
 *    -# Inerrupt Controller Specification 
 *
 * @subsection Assumptions
 *     The abbreviations INTC, Intc and intc have been used throughout this
 *     document to refer to Interrupt Controller
 */

/** @file csl_intc.h
 *
 *    @brief    Header file for functional layer CSL of INTC
 *
 *  Description
 *    - The different enumerations, structure definitions
 *      and function declarations
 *
 *  PATH  \\(CSLPATH)\\soc\\davinci\\c64plus\\src
 *
 */
  
/* =============================================================================
 *  Revision History
 *  ===============
 *  16-Mar-2005 brn modified for doxygen documentation
 *  14-Mar-2005 brn Moved the Event Ids to soc64plus.h
 * =============================================================================
 */
#ifndef _CSL_INTC_H_
#define _CSL_INTC_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <csl.h>
#include <cslr_intc.h>
#include <soc64plus.h>
/**
@defgroup CSL_INTC_API INTC
*/
/**
@defgroup CSL_INTC_DATASTRUCT  INTC Data Structures
@ingroup CSL_INTC_API
*/
/**
@defgroup CSL_INTC_SYMBOL  INTC Symbols Defined
@ingroup CSL_INTC_API
*/
/**
@defgroup CSL_INTC_ENUM  INTC Enumerated Data Types
@ingroup CSL_INTC_API
*/

/**
@defgroup CSL_INTC_FUNCTION  INTC Functions
@ingroup CSL_INTC_API
*/
/**
@defgroup CSL_INTC_FUNCTION_INTERNAL  INTC Internal Functions
@ingroup CSL_INTC_FUNCTION
*/

/** @addtogroup CSL_INTC_SYMBOL
* @{ */


#define CSL_INTC_EVENTID_CNT        128
/**< Number of Events in the System */

#define CSL_INTC_EVTHANDLER_NONE    ((CSL_IntcEventHandler) 0) 
/**<Indicates there is no associated event-handler */

#define CSL_INTC_BADHANDLE          (0) 
/**< Invalid handle */

#define CSL_INTC_MAPPED_NONE        (-1)
/**< None mapped */
/**
@}
*/
/** @addtogroup CSL_INTC_ENUM
* @{ */
/**
 * @brief   Interrupt Vector IDs
 */
typedef enum {
    CSL_INTC_VECTID_NMI      =   1,   
    /**< Should be used only along with CSL_intcHookIsr() */
    CSL_INTC_VECTID_4                   =   4,   /**< CPU Vector 4 */
    CSL_INTC_VECTID_5                   =   5,   /**< CPU Vector 5 */
    CSL_INTC_VECTID_6                   =   6,   /**< CPU Vector 6 */
    CSL_INTC_VECTID_7                   =   7,   /**< CPU Vector 7 */
    CSL_INTC_VECTID_8                   =   8,   /**< CPU Vector 8 */
    CSL_INTC_VECTID_9                   =   9,   /**< CPU Vector 9 */
    CSL_INTC_VECTID_10                  =   10,  /**< CPU Vector 10 */
    CSL_INTC_VECTID_11                  =   11,  /**< CPU Vector 11 */ 
    CSL_INTC_VECTID_12                  =   12,  /**< CPU Vector 12 */
    CSL_INTC_VECTID_13                  =   13,  /**< CPU Vector 13 */
    CSL_INTC_VECTID_14                  =   14,  /**< CPU Vector 14 */    
    CSL_INTC_VECTID_15                  =   15,  /**< CPU Vector 15 */
    CSL_INTC_VECTID_COMBINE  =   16,  
    /**< Should be used at the time of opening an Event handle
     *   to specify that the event needs to go to the combiner
     */
    CSL_INTC_VECTID_EXCEP    =   17   
    /**< Should be used at the time of opening an Event handle
     * to specify that the event needs to go to the exception
     * combiner.
                                                     */
} CSL_IntcVectId; 

/**
 * @brief   Interrupt Event IDs
 */
typedef Int     CSL_IntcEventId; 


/**
 * @brief   Enumeration of the control commands
 *
 * These are the control commands that could be used with
 * CSL_intcHwControl(..). Some of the commands expect an
 * argument as documented along-side the description of
 * the command.
 */
typedef enum {
    CSL_INTC_CMD_EVTENABLE      = 0,
        /**<
         * @brief   Enables the event
         * @param   CSL_IntcEnableState
         */
    CSL_INTC_CMD_EVTDISABLE     = 1,
        /**<
         * @brief   Disables the event
         * @param   CSL_IntcEnableState
         */   
    CSL_INTC_CMD_EVTSET         =2,
        /**<
         * @brief   Sets the event manually
         * @param   None
         */
    CSL_INTC_CMD_EVTCLEAR       =3,
        /**<
         * @brief   Clears the event (if pending)
         * @param   None
         */    
    CSL_INTC_CMD_EVTDROPENABLE  =4,
        /**<
         * @brief   Enables the Drop Event detection feature for this event
         * @param   None
         */       
    CSL_INTC_CMD_EVTDROPDISABLE =5,
        /**<
         * @brief   Disables the Drop Event detection feature for this event
         * @param   None
         */             
    CSL_INTC_CMD_EVTINVOKEFUNCTION = 6
        /**<
         * @brief   To be used ONLY to invoke the associated Function handle 
         * with Event when the user is writing an exception handling routine. 
         * @param   None
         */                   
} CSL_IntcHwControlCmd;


/**
 * @brief   Enumeration of the queries
 *
 * These are the queries that could be used with CSL_intcGetHwStatus(..).
 * The queries return a value through the object pointed to by the pointer
 * that it takes as an argument. The argument supported by the query is
 * documented along-side the description of the query.
 */
typedef enum {
    CSL_INTC_QUERY_PENDSTATUS
        /**<
         * @brief   The Pend Status of the Event is queried 
         * @param   Bool
         */    
}CSL_IntcHwStatusQuery;


/**
 * @brief   Enumeration of the exception mask registers
 *
 * These are the symbols used along with the value to be programmed
 * into the Exception mask register.
 */
typedef enum {
    CSL_INTC_EXCEP_0TO31   = 0,
        /**<
         * @brief   Symbol for EXPMASK[0]
         * @param   BitMask for EXPMASK0
         */
    CSL_INTC_EXCEP_32TO63  = 1,
        /**<
         * @brief   Symbol for EXPMASK[1]
         * @param   BitMask for EXPMASK1
         */   
    CSL_INTC_EXCEP_64TO95  = 2,
        /**<
         * @brief   Symbol for EXPMASK[2]
         * @param   BitMask for EXPMASK2
         */
    CSL_INTC_EXCEP_96TO127 = 3
        /**<
         * @brief   Symbol for EXPMASK[3]
         * @param   BitMask for EXPMASK3
         */    
} CSL_IntcExcepEn;

/**
 * @brief   Enumeration of the exception
 *
 * These are the symbols used along with the Excpetion Clear
 * API
 */
typedef enum {
    CSL_INTC_EXCEPTION_NMI = 31,
        /**<
         * @brief   Symbol for NMI
         * @param   None
         */  
    CSL_INTC_EXCEPTION_EXT = 30,
        /**<
         * @brief   Symbol for External Exception
         * @param   None
         */ 
    CSL_INTC_EXCEPTION_INT = 1,
        /**<
         * @brief   Symbol for Internal Exception
         * @param   None
         */ 
    CSL_INTC_EXCEPTION_SW = 0
        /**<
         * @brief   Symbol for Software Exception
         * @param   None
         */ 
}CSL_IntcExcep;
/**
@}
*/
/** @addtogroup CSL_INTC_DATASTRUCT
@{ */


/**
 * @brief   Event Handler pointer
 *
 * Event handlers ought to conform to this type
 */
typedef void (* CSL_IntcEventHandler)(void *);


/**
 * @brief   Event Handler Record
 *
 * Used to set-up the event-handler using CSL_intcPlugEventHandler(..)
 */
typedef struct  {
    CSL_IntcEventHandler    handler;    /**< pointer to the event handler */
    void *                  arg;        /**< the argument to be passed to the
                                          handler when it is invoked */
} CSL_IntcEventHandlerRecord;

/**
 * @brief   INTC Module Context. 
 */
typedef struct {
	/** Pointer to the event handle record */
    CSL_IntcEventHandlerRecord* eventhandlerRecord;
    
    /** Event allocation mask */
    CSL_BitMask32   eventAllocMask[(CSL_INTC_EVENTID_CNT + 31) / 32];
    
    /** Number of event entries */
    Uint16          numEvtEntries;
    
    /** Reserved */
    Int8            offsetResv[128];
} CSL_IntcContext;


/**
 * @brief   Event enable state
 */
typedef Uint32 CSL_IntcEventEnableState;


/**
 * @brief   Global Interrupt enable state
 */
typedef Uint32 CSL_IntcGlobalEnableState;
/**
 * @brief   The interrupt handle object
 *
 * This object is used refenced by the handle to identify the event.
 */
typedef struct CSL_IntcObj {
    CSL_IntcEventId eventId;    /**< The event-id */
    CSL_IntcVectId   vectId;    /**< The vector-id */
} CSL_IntcObj;

/**
 * @brief   The drop status structure
 *
 * This object is used along with the CSL_intcQueryDropStatus()
 * API.
 */
typedef struct {
    Bool drop;                  /**< whether dropped/not */
    CSL_IntcEventId eventId;    /**< The event-id */
    CSL_IntcVectId  vectId;     /**< The vect-id */
}CSL_IntcDropStatus;

/**
 * @brief   INTC module parameters for open
 *
 * This is equivalent to the Vector Id for the event number.
 */
typedef CSL_IntcVectId CSL_IntcParam;

/**
@}
*/

/**
 * @brief   The interrupt handle
 *
 * This is returned by the CSL_intcOpen(..) API. The handle is used
 * to identify the event of interest in all INTC calls.
 */

typedef struct CSL_IntcObj*   CSL_IntcHandle;

/** @addtogroup CSL_INTC_FUNCTION
@{ */
/*
 * ======================================================
 *   @func   CSL_intcInit
 * ======================================================
 */
/** @brief 
 *     Must be called before the use of the 
 *  top level APIs.
 */
 /* ======================================================
 *   @arg  intcEventHandlerRecord
 *     Pointer to the user allocated Intc context.
 *   The user must allocate memory for an object of this kind 
 *   and pass the pointer to that object as the argument.
 *   This object should be placed in persistent memory 
 *   (global preferred).
 *
 *   @b Description
 *   @n This is the initialization function for the INTC. This function is
 *      idempotent in that calling it many times is same as calling it once.
 *      This function initializes the CSL data structures, and doesn't affect
 *      the H/W.
 *
 *   @b Arguments
 *   @n None
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK - Always returns
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n  None
 *
 *   @b Example
 *   @verbatim
        CSL_IntcContext context; 
        CSL_Status intStat;
        CSL_IntcParam vectId;
        CSL_IntcEventHandlerRecord recordTable[10];
        
        context.numEvtEntries = 10;
        context.eventhandlerRecord = &recordTable;
        
        // Init Module
        ...