csl_dmax.h

Configuring External Interrupts on TMS320C672x Devices

} CSL_DmaxHwControlCmd;

/**************************************************************************\
* DMAX global function declarations
\**************************************************************************/

/*
 * =============================================================================
 *   @func CSL_dmaxInit
 *
 *   @desc
 *   @n This is the initialization function for the DMAX CSL. This function 
 *      needs to be called before any other DMAX CSL functions are called. 
 *      This function does not modify any registers or check status. It returns 
 *      status CSL_SOK. It has been kept for the future use.
 *
 *   @arg pContext
 *        Context information for DMAX
 *
 *   @ret CSL_Status
 *        CSL_SOK - Always returns
 *
 *   @eg
 *     CSL_dmaxInit (NULL);
 * =============================================================================
 */
extern CSL_Status  CSL_dmaxInit(
    CSL_DmaxContext * pContext
);


/*
 *============================================================================
 *   @func CSL_dmaxOpen
 *
 *   @desc
 *        This function populates the peripheral data object for the instance
 *        and returns a handle to the instance.
 *        The open call sets up the data structures for the particular instance
 *        of DMAX device. The device can be re-opened anytime after it has been
 *        normally closed if so required. DMAX Hardware setup will be performed
 *        at the end of the open call only if the HwSetup Pointer supplied was
 *        non- NULL. The handle returned by this call is input as an essential
 *        argument for rest of the APIs described for this module.
 *
 *   @arg pDmaxObj
 *        Pointer to the DMAX instance object
 *
 *   @arg dmaxNum
 *        Instance of the DMAX to be opened.
 *
 *   @arg pDmaxParam
 *        Pointer to module specific parameters
 *
 *   @arg pStatus
 *        pointer for returning status of the function call
 *
 *   @ret CSL_DmaxHandle
 *        Valid DMAX instance handle will be returned if status value is
 *        equal to CSL_SOK.
 *
 *   @eg
 *        CSL_status        status;
 *        CSL_DmaxObj       dmaxObj;
 *        CSL_DmaxHandle     hDmax;
 *
 *        hDmax = CSL_DmaxOpen (&dmaxObj,
 *                            CSL_DMAX_PER_CNT,
 *                            NULL,
 *                            &status
 *                            );
 *
 * ===========================================================================
 */
extern CSL_DmaxHandle CSL_dmaxOpen (
    CSL_DmaxObj              *pDmaxObj,
    CSL_InstNum              dmaxNum,
    CSL_DmaxParam            *pDmaxParam,
    CSL_Status               *pStatus
);


/*
 * =============================================================================
 *   @func CSL_dmaxClose
 *
 *   @b Description
 *   @n This function closes the specified instance of DMAX.
 *
 *   @arg  hDmax
           Handle to the DMAX instance
 *
 *   @ret CSL_Status
 *         CSL_SOK            - Close successful
 *         CSL_ESYS_BADHANDLE - Invalid handle
 *
 *   @eg
 *     CSL_dmaxClose (hDmax);
 * =============================================================================
 */
extern CSL_Status  CSL_dmaxClose(
    CSL_DmaxHandle  hDmax
);


/*
 * ===============================================================================
 * This function initializes the device registers with the appropriate values
 *  provided through the HwSetup Data structure. This function needs to be called
 *  only if the HwSetup Structure was not previously passed through the Open call.
 *  After the Setup is completed, the serial device is ready for data transfer.
 *  For information passed through the HwSetup Data structure refer
 *  @a CSL_DmaxHwSetup.
 *
 *  <b> Usage Constraints: </b>
 *  Both @a CSL_dmaxInit() and @a CSL_dmaxOpen() must be called
 *  successfully in that order before this function can be called. The user
 *  has to allocate space for & fill in the main setup structure appropriately
 *  before calling this function
 *
 * @b Example:
 * @verbatim
     CSL_DmaxHandle hDmax;
     CSL_DmaxHwSetup hwSetup = CSL_DMAX_HWSETUP_DEFAULTS;
     CSL_dmaxHwSetup(hDmax, &hwSetup);
  @endverbatim
 *
 * @return Returns the status of the setup operation
 *=================================================================================
 */
extern CSL_Status  CSL_dmaxHwSetup(
    CSL_DmaxHandle                         hDmax,
    CSL_DmaxHwSetup                        *setup
);

/*
 * ================================================================================
 * This function gets the current setup of the DMAX. The status is
 *  returned through @a CSL_DmaxHwSetup. The obtaining of status
 *  is the reverse operation of @a CSL_dmaxHwSetup() function.
 *
 *  <b> Usage Constraints: </b>
 *  Both @a CSL_dmaxInit() and @a CSL_dmaxOpen() must be called successfully
 *  in that order before @a CSL_dmaxGetHwSetup() can be called.
 *
 * @b Example:
 * @verbatim
      CSL_DmaxHandle hDmax;
      CSL_Status status;
      CSL_DmaxHwSetup *mysetup;
       ...
      status = CSL_dmaxGetHwSetup(hDmax, &mysetup);
   @endverbatim
 *
 * @return returns the status of the operation (see @a CSL_Status)
 *===================================================================================
 */
extern CSL_Status  CSL_dmaxGetHwSetup(
    CSL_DmaxHandle                         hDmax,
    CSL_DmaxHwSetup                        *setup
);


/*
 * ==================================================================================
 * Control operations for the DMAX.  For a particular control operation, the
 *  pointer to the corresponding data type needs to be passed as argument HwControl
 *  function Call. All the arguments (Structure elements included) passed to  the
 *  HwControl function are inputs. For the list of commands supported and argument
 *  type that can be @a void* casted & passed with a particular command refer to
 *  @a CSL_DmaxHwControlCmd.
 *
 *  <b> Usage Constraints: </b>
 *  Both @a CSL_dmaxInit() and @a CSL_dmaxOpen() must be called successfully
 *  in that order before @a CSL_dmaxHwControl() can be called. For the
 *  argument type that can be @a void* casted & passed with a particular command
 *  refer to @a CSL_DmaxHwControlCmd
 *
 * @b Example:
 * @verbatim
       CSL_DmaxHandle hDmax;
       CSL_Status status;
       ...
       status = CSL_dmaxHwControl(hDmax,
                                    CSL_DMAX_CMD_START,
                                   &command);
   @endverbatim
 *
 *  @return returns the status of the operation (see @a CSL_Status)
 *==================================================================================
 */
extern CSL_Status  CSL_dmaxHwControl(
    CSL_DmaxHandle                        hDmax,
    CSL_DmaxHwControlCmd                  cmd,
    void                                 *arg
);

/** =============================================================================
 *   @func CSL_dmaxHwSetupRaw
 *
 *   @desc
 *       This function configures the registers of DMAX as per the values given
 *       in the Config structure.
 *
 *   @arg hDmax
 *        Handle to the DMAX instance
 *
 *   @arg config
 *        Pointer to DMAX config structure
 *
 *   @ret CSL_Status
 *         CSL_SOK             - Configuration successful
 *         CSL_ESYS_BADHANDLE  - Invalid handle
 *
 *   @eg
 *
 *        CSL_Status            status;
 *        CSL_DmaxConfig        hwConfig;
 *
 *        status = CSL_dmaxHwsetupRaw (hDmax, &hwConfig);
 *
 * ===========================================================================
 */
extern CSL_Status  CSL_dmaxHwSetupRaw (
    CSL_DmaxHandle           hDmax,
    CSL_DmaxConfig *         config
);

/*
 * ===========================================================================
 * This function is used to read the current device configuration, status
 *  flags and the value present associated registers. Following table details
 *  the various status queries supported and the associated data structure to
 *  record the response. User should allocate memory for the said data type and
 *  pass its pointer as an unadorned void* argument to the status query call.
 *  For details about the various status queries supported and the associated
 *  data structure to record the response, refer to @a CSL_DmaxHwStatusQuery
 *
 *  <b> Usage Constraints: </b>
 *  Both @a CSL_dmaxInit() and @a CSL_dmaxOpen() must be called successfully
 *  in that order before @a CSL_dmaxGetHwStatus() can be called. For the
 *  argument type that can be @a void* casted & passed with a particular cmd
 *  refer to @a CSL_DmaxHwStatusQuery
 *
 * @b Example:
 * @verbatim
      CSL_DmaxHandle hDmax;
      CSL_Status status;
      Uint16  *response;
       ...
      status = CSL_dmaxGetHwStatus(hDmax,
                           CSL_DMAX_QUERY_BUS_BUSY,
                                  &response);
   @endverbatim
 *
 * @return Returns the status of the operation (see @a CSL_Status)
 *===========================================================================
 */
extern CSL_Status  CSL_dmaxGetHwStatus(
    CSL_DmaxHandle                         hDmax,
    CSL_DmaxHwStatusQuery                  query,
    void                                  *response
);


/** ============================================================================
 *   @n@b CSL_dmaxGetBaseAddress
 *
 *   @b Description
 *   @n  Function to get the base address of the peripheral instance.
 *       This function is used for getting the base address of the peripheral
 *       instance. This function will be called inside the CSL_dmaxOpen()
 *       function call. This function is open for re-implementing if the user
 *       wants to modify the base address of the peripheral object to point to
 *       a different location and there by allow CSL initiated write/reads into
 *       peripheral MMR's go to an alternate location.
 *
 *   @b Arguments
 *   @verbatim
            dmaxNum          Specifies the instance of DMAX to be opened.

            pDmaxParam       Module specific parameters.

            pBaseAddress    Pointer to baseaddress structure containing base
                            address details.

     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_OK            Open call is successful
 *   @li                    CSL_ESYS_FAIL     The instance number is invalid.
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  Base Address structure is populated
 *
 *   @b Modifies
 *   @n    1. The status variable
 *
 *         2. Base address structure is modified.
 *
 *   @b Example
 *   @verbatim
        CSL_Status              status;
        CSL_DmaxBaseAddress  baseAddress;

       ...
      status = CSL_dmaxGetBaseAddress(CSL_DMAX_PER_CNT, NULL, &baseAddress);

    @endverbatim
 * ===========================================================================
 */
extern CSL_Status   CSL_dmaxGetBaseAddress (
    CSL_InstNum,
    CSL_DmaxParam*,
    CSL_DmaxBaseAddress*
);

/** =======================================================================
 *   @n@b CSL_dmaxSetupFifoDesc
 *
 *   @b Description
 *   @n This function formats a FIFO Descriptor object.
 *   @a CSL_dmaxSetupFifoDesc.
 *
 *   @b Arguments
 *   @verbatim
 *    
 *          fifoObj     Pointer to data area in RAM where descriptor is to be stored.
 *          setup       Pointer to a dMax FIFO descriptor Object.
 *           
 *   @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK - Successful completion of hardware     
 *                                    setup
 *   @li                    CSL_ESYS_ INVPARAMS - Hardware structure is not properly 
 *                                    initialized
 *   @li                    CSL_ESYS_ BADHANDLE - Invalid CSL handle
 *
 *
 *   <b> Pre Condition </b>
 *   @n  Both CSL_dmaxInit() and a CSL_dmaxOpen() must be called
 *
 *   <b> Post Condition </b>
 *   @n  DMAX registers are configured 
 *
 *   @b  Modifies
 *   @n  DMAX registers
 *
 *   @b Example
 *   @verbatim  
      CSL_DmaxFifoDescriptor        fifoObj;
      CSL_DmaxFifoDescriptorSetup   setup;
            
    setup.fifoBaseAddr      = 0x20000100;
    .
    .
    setup.wPtr              = 0x10000000;