csl_intc.h

Configuring External Interrupts on TMS320C672x Devices

    CSL_IntcHandle      hIntc,  
    CSL_IntcHwSetup     *hwSetup 
);



/** ============================================================================
 *   @n@b CSL_intcHwControl
 *
 *   @b Description
 *   @n This API is used to invoke any of the control-operations supported
 *      by the module. Note: Refer to the control-command documentation
 *      for details on the parameter (if any) that a specific command accepts.
 *
 *   @b Arguments
 *   @verbatim
            hIntc           Handle identifying the event
            command         The command to this API indicates the action to be
                            taken on INTC.
            commandArg      An optional argument.
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - HwControl successful.
 *   @li                    CSL_ESYS_BADHANDLE  - Invalid handle
 *   @li                    CSL_ESYS_INVCMD     - Invalid command
 *
 *   <b> Pre Condition </b>
 *   @n  INTC should be initialized and opened properly
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n The hardware registers of INTC.
 *
 *   @b Example:
 *   @verbatim
        CSL_intcHwControl (hIntc, CSL_INTC_CMD_EVTSET, NULL);
     @endverbatim
 * =============================================================================
 */
extern CSL_Status CSL_intcHwControl (
    CSL_IntcHandle          hIntc,       
    CSL_IntcHwControlCmd    command,     
    void                    *commandArg  
);


/** ============================================================================
 *   @n@b CSL_intcGetHwStatus
 *
 *   @b Description
 *   @n The CSL_intcGetHwStatus(..) API could be used to retrieve status
 *      or configuration information from the registers. The user must
 *      allocate an object that would hold the retrieved information
 *      and pass a pointer to it to the function. The type of the object
 *      is specific to the query-command.
 *
 *   @b Arguments
 *   @verbatim
            hIntc           Handle identifying the event
            query           The query to this API of INTC which indicates the
                            status to be returned.
            response        Placeholder to return the status.
     @endverbatim
 *
 *   <b> Return Value </b> CSL_Status
 *   @li                   CSL_SOK               - Status info return successful
 *   @li                   CSL_ESYS_BADHANDLE    - Invalid handle
 *   @li                   CSL_ESYS_INVQUERY     - Invalid query 
 *
 *   <b> Pre Condition </b>
 *   @n  INTC should be initialized and opened properly.
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n None
 *
 *   @b Example:
 *   @verbatim
     Bool    evtPending = FALSE;
     while (evtPending == FALSE)
      {
      CSL_intcGetHwStatus(hIntc,CSL_INTC_QUERY_ISEVENTPENDING,&evtPending);
      }
  
     @endverbatim
 *
 * =============================================================================
 */
extern CSL_Status CSL_intcGetHwStatus (
    CSL_IntcHandle          hIntc,      
    CSL_IntcHwStatusQuery   query,      
    void                    *response   
);

/** ============================================================================
 *   @n@b CSL_intcEventEnable
 *
 *   @b Description
 *   @n The API enables the specified event in the INTC. If the user wishes 
 *      to restore the enable-state of the event at a later point of time, 
 *      they may store the current state using the parameter, which could 
 *      be used with CSL_intcEventRestore (..).
 *      Note: The function directly works on the event and hence it is
 *      not necessary to "open" the event to invoke the API.
 * 
 *   @b Arguments
 *   @verbatim
         eventId     Event-ID of interest         
         prevState   (Optional) Pointer to object that would store current state
     @endverbatim
 *
 *   <b> Return Value </b> CSL_Status
 *   @li                   CSL_SOK on success
 *   @li                   CSL_INTC_EVENTID_INVALID 
 *
 *   @b Example:
 *   @verbatim
        CSL_intcEventEnable(CSL_INTC_EVENTID_SPI, NULL);
     @endverbatim
 *
 * ============================================================================
 */
extern CSL_Status CSL_intcEventEnable (
    CSL_IntcEventId             eventId,   
    CSL_IntcEventEnableState    *prevState   
);

/** ============================================================================
 *  @n@b CSL_intcEventDisable
 *
 *  @b Description
 *  @n The API disables the specified event in the INTC. If the user wishes to 
 *     restore the enable-state of the event at a later point of time, they may
 *     store the current state using the parameter, which could be used
 *     with CSL_intcEventRestore (..).
 *     Note: The function directly works on the event and hence it is
 *     not necessary to "open" the event to invoke the API.
 *
 *  @b Arguments
 *  @verbatim
        eventId     Event-ID of interest        
        prevState   (Optional) Pointer to object that would store current state
    @endverbatim
 *
 *  <b> Return Value </b> CSL_Status
 *  @li                   CSL_SOK on success
 *  @li                   CSL_INTC_EVENTID_INVALID 
 *
 * @b Example:
 * @verbatim
     CSL_IntcEventEnableState    oldState;
     CSL_intcEventDisable(CSL_INTC_EVENTID_SPI, &oldState);
   @endverbatim
 *
 * =============================================================================
 */
extern CSL_Status CSL_intcEventDisable (
    CSL_IntcEventId             eventId,    
    CSL_IntcEventEnableState    *prevState   
);

/** ============================================================================
 *  @n@b CSL_intcEventRestore
 *
 *  @b Description
 *  @n The API restores the specified event to a previous enable-state
 *     as recorded by the event-enable state passed as an argument.
 *     Note: The function directly works on the event and hence it is
 *     not necessary to "open" the event to invoke the API.
 *
 *  @b Arguments
 *  @verbatim
        eventId     Event-ID of interest        
        prevState   Object that contains information about previous state
    @endverbatim
 *
 *  <b> Return Value </b> CSL_Status
 *  @li                   CSL_SOK on success
 *  @li                   CSL_INTC_EVENTID_INVALID 
 *
 * @b Example:
 * @verbatim
        CSL_intcEventRestore(CSL_INTC_EVENTID_SPI, oldState);
   @endverbatim
 *
 * =============================================================================
 */
extern CSL_Status CSL_intcEventRestore (
    CSL_IntcEventId  eventId,          
    CSL_IntcEventEnableState    prevState   
);

/** ============================================================================
 *  @n@b CSL_intcGlobalEnable
 *
 *  @b Description
 *  @n The API enables the global interrupt by manipulating the processor's
 *     global interrupt enable/disable flag. If the user wishes to restore
 *     the enable-state at a later point, they may store the current state
 *     using the parameter, which could be used with CSL_intcGlobalRestore (..).
 *
 *  @b Arguments
 *  @verbatim
        prevState   (Optional) Pointer to object that would store current
                    stateObject that contains information about previous state
    @endverbatim
 *
 *  <b> Return Value </b> CSL_Status
 *  @li                   CSL_SOK -on success
 *
 *  @b Example:
 *  @verbatim
    CSL_IntcGlobalEnableState   prevGie;
    CSL_Status status;
    
    status = CSL_intcGlobalEnable (&prevGie);
    @endverbatim
 *
 * =============================================================================
 */
extern CSL_Status CSL_intcGlobalEnable (
    CSL_IntcGlobalEnableState   *prevState   
);

/** ============================================================================
 *  @n@b CSL_intcGlobalDisable
 *
 *  @b Description
 *  @n The API disables the global interrupt by manipulating the processor's
 *     global interrupt enable/disable flag. If the user wishes to restore
 *     the enable-state at a later point, they may store the current state
 *     using the parameter, which could be used with CSL_intcGlobalRestore (..).
 *
 *  @b Arguments
 *  @verbatim
        prevState   (Optional) Pointer to object that would store current
                    state of Global Interrupt bit
    @endverbatim
 *
 *  <b> Return Value </b> CSL_Status
 *  @li                   CSL_SOK -on success
 *
 *  @b Example:
 *  @verbatim
     CSL_IntcGlobalEnableState   gieState;
  
     CSL_intcGlobalDisable(&gieState);
       // critical-section code //
     CSL_intcGlobalRestore(gieState);
    @endverbatim
 *
 * =============================================================================
 */
extern CSL_Status CSL_intcGlobalDisable (
    CSL_IntcGlobalEnableState   *prevState   
);




/** ============================================================================
 *  @n@b CSL_intcGlobalRestore
 *
 *  @b Description
 *  @n The API restores the global interrupt enable/disable state to a previous
 *    state as recorded by the global-event-enable state passed as an argument.
 *
 *  @b Arguments
 *  @verbatim
        prevState   Object containing information about previous state
    @endverbatim
 *
 *  <b> Return Value </b> CSL_Status
 *  @li                   CSL_SOK on success
 *
 *  @b Example:
 *  @verbatim
     CSL_IntcGlobalEnableState   gieState;
  
     CSL_intcGlobalDisable(&gieState);
     // critical-section code //
     CSL_intcGlobalRestore(gieState);
    @endverbatim
 *
 * =============================================================================
 */
extern CSL_Status CSL_intcGlobalRestore (
    CSL_IntcGlobalEnableState       prevState   
);


/** ============================================================================
 *  @n@b CSL_intcDispatcherInit
 *
 *  @b Description
 *  @n Sets up the CSL interrupt dispatcher. 
 *     The user should call CSL_intcDispatcherInit (..) if they
 *     wish to make use of the dispatcher built into the CSL INTC
 *     module.
 *
 *  Note: This API must be called before using
 *  CSL_intcPlugEventHandler (..).
 *
 *  @b Arguments
 *  @n pContext - context relevant to Dispatcher
 *
 *  <b> Return Value </b> CSL_Status
 *  @li                   CSL_SOK on success
 *  @li                   CSL_ESYS_ALREADY_INITIALIZED 
 *
 *  @b Pre Condition 
 *  @n Memory has to be allocated for the context variable
 *
 *  @b Post Condition 
 *  @n None 
 *
 *  @b Modifies 
 *  @n None
 *
 * @b Example:
 * @verbatim
      if ((CSL_intcInit( ) != CSL_SOK) || 
           (CSL_intcInit() != CSL_ESYS_ALREADY_INITIALIZED)
         )
         {
         // module initialization failed! //
         }
      if ((CSL_intcDispatcherInit ( ) != CSL_SOK) && 
           (CSL_intcDispatcherInit ( ) != CSL_ESYS_ALREADY_INITIALIZED)
         )
         {
         // CSL dispatcher setting up failed! //
         }
   @endverbatim
 *
 * =============================================================================
 */
extern CSL_Status CSL_intcDispatcherInit (
    CSL_IntcDispatcherContext   *pContext
);


/** ============================================================================
 *  @n@b CSL_intcPlugEventHandler
 *
 *  @b Description
 *  @n CSL_intcPlugEventHandler (..) ties an event-handler to an event; so
 *     that the occurence of the event, would result in the event-handler
 *     being invoked.
 *
 *  @b Arguments
 *  @verbatim
        hIntc                Handle identifying the interrupt-event        
        eventHandlerRecord   Provides the details of the event-handler
    @endverbatim
 *
 *  <b> Return Value </b>
 *  @n  Returns the address of the previous handler
 *
 *  @b Pre Condition 
 *  @n 1. INTC has to be initialized and  opened for the event
 *  @n 2. DispatcherInit has to called
 *  @n 3. EventHandlerRecord has to be filled 
 
 *  @b Post Condition 
 *  @n Handler plugged

 *  @b Modifies 
 *  @n None
 *
 *  <b> Return Value </b>
 *  @n  Returns the address of the previous handler or
 *      CSL_INTC_EVENTHANDLER_PLUG_ERROR if the isr was not properly plugged  
 *
 *  @b Example:
 *  @verbatim
        CSL_IntcEventHandlerRecord  evtHandlerRecord;
  
        evtHandlerRecord.handler = myIsr;
        evtHandlerRecord.arg     = (void *)hI2c;
        CSL_intcPlugEventHandler(hIntc, &evtHandlerRecord);
    @endverbatim
 *
 * =============================================================================
 */
extern CSL_IntcEventHandler CSL_intcPlugEventHandler (
    CSL_IntcHandle                  hIntc,              
    CSL_IntcEventHandlerRecord  *eventHandlerRecord               
);

/** ============================================================================
 *  @n@b CSL_intcHookIsr
 *
 *  @b Description
 *  @n The CSL_intcHookIsr (..) hooks up the Interrupt Service Routine(ISR) to 
 *     the specified event. Note: Unlike CSL_intcPlugEventHandler (..)  , this is 
 *     done without opening the module (INTC) for the event. Hence the 
 *     CSL dispatcher is also not made use.
 *
 *  @b Arguments
 *  @verbatim
        eventId       Event Identifier        
        isrAddr      Pointer to the handler
    @endverbatim
 *    
 *  @b Pre Condition 
 *  @n INTC has to be initialized properly
 *
 *  @b Post Condition 
 *  @n Handler plugged
 *
 *  @b Modifies 
 *  @n None
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK         - Isr plugged properly
 *   @li                    CSL_ESYS_FAIL   - Isr plug failed.(The DMAX 
 *	    									  uid used in INTC ie 
 *											  CSL_DMAX_LOPRIORITY_EVENT0_UID 
 *											  might be in use by some other
 *											  application)

 *
 * @b Example:
 * @verbatim
        CSL_intcHookIsr(CSL_INTC_EVENTID_RTI_INT_REQ0 , (void *)rtiIsr);
   @endverbatim 
 * =============================================================================
 */
extern CSL_Status  CSL_intcHookIsr (
    CSL_IntcEventId       evtId,   
    Uint32                isrAddr 
);

/** ============================================================================
 *  @n@b CSL_intcSetVectorPtr
 *
 *  @b Description
 *  @n The API changes the base address of the Interrupt Vector table to the 
 *     value passed.
 *
 *  @b Arguments
 *  @verbatim
        vecPtr   New base address of the Interrupt Vector Table. Care should be 
                 taken that first ten lower bits are all zeroes
    @endverbatim
 *
 *  <b> Return Value </b> 
 *  @li                   Previously loaded ISTP value
 *
 *  @b Example:
 *  @verbatim
    #define VEC_ADDR        0x100c0000
    Uint32 prevValue;
    
    
    prevValue = CSL_intcSetVectorPtr (VEC_ADDR);
    
    @endverbatim
 *
 * =============================================================================
 */   
extern Uint32 CSL_intcSetVectorPtr(
    Uint32 vecPtr
);
         
#ifdef __cplusplus
 }
#endif

#endif /**_CSL_INTC_H_ */