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.
 *   ===========================================================================
 */

/** @file csl_intc.h
 *
 *  @brief CSL functional-layer header file for the INTC
 *
 *  Description
 *  - Comprises the function declarations for the various APIs and the
 *    associated enumerations, type and symbol definitions for the INTC
 *    module.
 *
 *  Path: \\(CSLPATH)\\soc\\davinci\\arm9\\src
 */

/* =============================================================================
 *  Revision History
 *  ===============
 *  27-Jan-2005 kpn Moved the interrupt counts & event Id's to soc.h
 *  18-Dec-2004 kpn Updated according to CSL upgradation guidelines.
 * =============================================================================
 */

#ifndef _CSL_INTC_H_
#define _CSL_INTC_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <cslr.h>
#include <csl_error.h>
#include <csl_types.h>
#include <_csl_intc0.h>
#include <_csl_intc1.h>

/**
 * @brief   Indicates there is no associated event-handler
 */
#define CSL_INTC_EVTHANDLER_NONE        ((CSL_IntcEventHandlerRecord *) 0)

/**
 * @brief   Invalid handle
 */
#define CSL_INTC_BADHANDLE        (0)

/**
 * @brief   Interrupt Vector IDs
 */
typedef enum {
    CSL_INTC_VECTID_DEFAULT   =   0,  /**< default vector */
    CSL_INTC_VECTID_INVALID   =  -1,  /**< invalid vector */

/* for use only with HookIsr -- by design! */
    CSL_INTC_VECTID_RESET     =   1,  /**< the RESET exception vector */
    CSL_INTC_VECTID_UNDEF     =   2,  /**< the UNDEF exception vector */
    CSL_INTC_VECTID_SWI       =   3,  /**< the SWI exception vector */
    CSL_INTC_VECTID_PREABT    =   4,  /**< the PREABT exception vector */
    CSL_INTC_VECTID_DATABT    =   5,  /**< the DATABT exception vector */
    CSL_INTC_VECTID_IRQ       =   7,  /**< the IRQ exception vector */
    CSL_INTC_VECTID_FIQ       =   8   /**< the FIQ exception vector */

} CSL_IntcVectId;

/**
 * @brief   Interrupt Event IDs
 */
typedef Int     CSL_IntcEventId; /* event-id enumeration in soc.h */

/**
 * @brief   Interrupt Priority
 */
typedef enum {

    CSL_INTC_PRIORITY_DEFAULT   = 0,  /**< Default priority */
    _CSL_INTC_PRIORITY__INTC1START     = 0,
    CSL_INTC_PRIORITY_0         = 0 ,  /**< Priority 0 (FIQ, Highest) */
    CSL_INTC_PRIORITY_1         = 1 ,  /**< Priority 1 (FIQ, Lowest) */
    CSL_INTC_PRIORITY_2         = 2 ,  /**< Priority 2 (IRQ, Highest) */
    CSL_INTC_PRIORITY_3         = 3 ,  /**< Priority 3 (IRQ) */
    CSL_INTC_PRIORITY_4         = 4 ,  /**< Priority 4 (IRQ) */
    CSL_INTC_PRIORITY_5         = 5 ,  /**< Priority 5 (IRQ) */
    CSL_INTC_PRIORITY_6         = 6 ,  /**< Priority 6 (IRQ) */
    CSL_INTC_PRIORITY_7         = 7 ,  /**< Priority 7 (IRQ, Lowest) */
    _CSL_INTC_PRIORITY__INTC1END       = 7,

    CSL_INTC_PRIORITY_INVALID    =   -1        /**< Invalid Priority */

} CSL_IntcPriority;

/**
 * @brief   Interrupt Type (Routing)
 */
typedef enum {
    CSL_INTC_TYPE_IRQ   = 0,    /**< IRQ -- normal interrupt request */
    CSL_INTC_TYPE_FIQ   = 1     /**< FIQ -- fast interrupt request */
} CSL_IntcType;

/**
 * @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 = 1,
        /**<
         * @brief   Enables the event
         * @param   None
         */
    CSL_INTC_CMD_EVTDISABLE = 2,
        /**<
         * @brief   Disables the event
         * @param   None
         */
    CSL_INTC_CMD_SETPRIORITY = 3,
        /**<
         * @brief   Modifies the interrupt priority
         * @param   CSL_IntcPriority
         */
    CSL_INTC_CMD_SETPACE = 4
        /**<
         * @brief   Not Supported
         * @param   Not Applicable
         */
} 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_PRIORITY = 1,
        /**<
         * @brief   Retrieves the interrupt priority
         * @param   (CSL_IntcPriority *)
         */

    CSL_INTC_QUERY_TYPE = 2,
        /**<
         * @brief   Returns the type (route)
         * @param   (CSL_IntcType *)
         */

    CSL_INTC_QUERY_ISEVENTPENDING = 3
        /**<
         * @brief   Checks if event is pending
         * @param   (Bool *)
         */

} CSL_IntcHwStatusQuery;

/**
 * @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_IntcEventHandlerRecord {
    CSL_IntcEventHandler    handler;    /**< pointer to the event handler */
    void *                  arg;        /**< the argument to be passed to the
                                         *   handler when it is invoked
                                         */
    CSL_IntcEventId         evtId;      /**< event Id */
    Uint32                  dummy;      /**< dummy to fill 16 byte size entry */
    /* Note: This structure should be of size 16 bytes */
} CSL_IntcEventHandlerRecord;

/**
 * @brief   The setup-structure
 *
 * Used to configure the interrupt controller for an event using
 * CSL_intcHwSetup()
 */
typedef struct CSL_IntcHwSetup {
    CSL_IntcPriority    priority;   /**< The interrupt priority */
} CSL_IntcHwSetup;

/**
 * @brief   Default values for the setup-parameters
 */
#define CSL_INTC_HWSETUP_DEFAULTS {                 \
    (CSL_IntcPriority) CSL_INTC_PRIORITY_DEFAULT    \
}

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

/**
 * @brief   Global Interrupt enable state
 */
typedef Uint8 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_IntcPriority  priority;   /**< The priority level */
    void *            reserved;   /**< Reserved for the future */
} CSL_IntcObj;

/**
 * @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;

/*******************************************************************************
 * Interrupt Controller function declarations
 ******************************************************************************/

/** ============================================================================
 *  @n@b CSL_intcInit
 *
 *  @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
          ...
          if (CSL_sysInit() == CSL_SOK) {
             CSL_intcInit();
       }
    @endverbatim
 * =============================================================================
 */
CSL_Status CSL_intcInit (
    void
);

/** ============================================================================
 *  @n@b CSL_intcOpen
 *
 *  @b Description
 *  @n The API would reserve an interrupt-event for use. It returns
 *     a valid handle to the event only if the event is not currently
 *     allocated. The user could release the event after use by calling
 *     CSL_intcClose(). The CSL-object ('intcObj') that the user
 *     passes would be used to store information pertaining handle.
 *
 *  @b Arguments
 *  @verbatim
             pIntcObj     pointer to the CSL-object allocated by the user

             eventId      the event-id of the interrupt

             vectId       the vector-id of the interrupt

             setup        (optional) pointer to an optional setup-structure

             pStatus      (optional) pointer for returning status of the
                          function call
    @endverbatim
 *
 *  <b> Return Value </b>  CSL_IntcHandle
 *  @n                     Valid INTC handle identifying the event
 *
 *  <b> Pre Condition </b>
 *  @n  None
 *
 *  <b> Post Condition </b>
 *  @n   1.    INTC object structure is populated
 *  @n   2.    The status is returned in the status variable. If status
 *             returned is
 *  @li            CSL_SOK             Valid intc handle is returned
 *  @li            CSL_ESYS_FAIL       The open command failed
 *
 *  @b Modifies
 *  @n    1. The status variable
 *  @n    2. INTC object structure
 *
 *  @b Example:
 *  @verbatim
         CSL_IntcObj     intcObj;
         CSL_IntcHandle  hIntc;
         CSL_Status      openStatus;

         hIntc = CSL_intcOpen(&intcObj, CSL_INTC_EVENTID_TIMER3,
                     CSL_INTC_VECTID_DEFAULT, NULL, &openStatus);
         if (openStatus != CSL_SOK) {
             // open failed //
         }
    @endverbatim
 * =============================================================================
 */
CSL_IntcHandle CSL_intcOpen (
    CSL_IntcObj               *pIntcObj,
    CSL_IntcEventId            eventId,
    CSL_IntcVectId             vectId,
    CSL_IntcHwSetup           *setup,
    CSL_Status                *pStatus
);

/** ============================================================================
 *  @n@b CSL_intcClose
 *
 *  @b Description
 *  @n Releases an allocated event. CSL_intcClose() must be called to
 *     release an event that has been previously allocated with a call
 *     to CSL_intcOpen().
 *
 *  @b Arguments
 *  @verbatim
           hIntc            Handle identifying the event
    @endverbatim
 *
 *  <b> Return Value </b>  CSL_Status
 *  @li                    CSL_SOK             - Close successful
 *  @li                    CSL_ESYS_FAIL       - Close failed
 *
 *  @b Example
 *  @verbatim
             CSL_IntcHandle       hIntc;
             CSL_status           status;
             ...

             status = CSL_intcClose(hIntc);
             if (status != CSL_SOK) {
             // close failed! //
         }
    @endverbatim
 * =============================================================================
 */
CSL_Status CSL_intcClose (
    CSL_IntcHandle         hIntc
);

/** ============================================================================
 *  @n@b CSL_intcHwSetup
 *
 *  @b Description
 *  @n  Sets up the interrupt controller for a particular event.
 *      CSL_intcHwSetup() API is used to configure the interrupt controller
 *      for the event identified by the handle. The user must instantiate
 *      and initialize a setup-structure with appropriate configuration
 *      parameters before passing it to the function.
 *
 *  @b Arguments
 *  @verbatim
         hIntc        Handle to the INTC instance

         hwSetup      Pointer to harware setup structure
    @endverbatim
 *
 *  <b> Return Value </b>  CSL_Status
 *  @li        CSL_SOK                - Hardware setup successful
 *  @li        CSL_ESYS_BADHANDLE     - Invalid handle
 *  @li        CSL_ESYS_INVPARAMS     - Hardware structure is not properly
                                        initialized
 *  @li        CSL_ESYS_NOTSUPPORTED  - Action not supported
 *
 *  @b Example:
 *  @verbatim
         CSL_Status status = CSL_SOK;
         CSL_IntcHwSetup setup = CSL_INTC_HWSETUP_DEFAULTS;

         setup.priority = CSL_INTC_PRIORITY_DEFAULT;
         setup.type = CSL_INTC_TYPE_IRQ;