csl_uhpi.h

Configuring External Interrupts on TMS320C672x Devices

/** \brief This data type is used to return the handle to the CSL of the UHPI
 */
typedef struct CSL_UhpiObj    *CSL_UhpiHandle;

/*******************************************************************************
 * DSP UHPI controller function declarations
 ******************************************************************************/

/** ============================================================================
 *   @n@b CSL_uhpiInit
 *
 *   @b Description
 *   @n This is the initialization function for the uhpi CSL. The function
 *      must be called before calling any other API from this CSL.  
 *      This function does not modify any registers or check status. It returns 
 *      status CSL_SOK. It has been kept for the future use.

 *
 *   @b Arguments
 *   @verbatim
        pContext    Pointer to module-context. As uhpi doesn't have
                    any context based information user is expected to pass NULL.
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                        CSL_SOK - Always returns
 *
 *   <b> Pre Condition </b>
 *   @n  CSL_sysInit() must be called. 
 *
 *   <b> Post Condition </b>
 *   @n  The CSL for uhpi is initialized
 *
 *   @b Modifies
 *   @n  None
 *
 *   @b Example
 *   @verbatim
            CSL_uhpiInit(NULL);
     @endverbatim
 * =============================================================================
 */
extern CSL_Status  CSL_uhpiInit (
    CSL_UhpiContext * pContext
);

/** ============================================================================
 *   @n@b CSL_uhpiOpen
 *
 *   @b Description
 *   @n This function returns the handle to the DSP UHPI controller
 *      instance. This handle is passed to all other CSL APIs.
 *
 *   @b Arguments
 *   @verbatim
            pUhpiObj     Pointer to UHPI object.
 
            uhpiNum     Instance of DSP UHPI CSL to be opened. 
                        There is only one instance of the uhpi available.
                        So, the value for this parameter will be 
                        CSL_UHPI always.
 
            pUhpiParam  Module specific parameters.
 
            pStatus      Status of the function call
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_UhpiHandle
 *   @n                         Valid uhpi handle will be returned if
 *                              status value is equal to CSL_SOK.
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n   1.    The status is returned in the status variable. If status
 *              returned is
 *   @li            CSL_SOK             Valid uhpi handle is returned
 *   @li            CSL_ESYS_FAIL       The uhpi instance is invalid
 *   @li            CSL_ESYS_INVPARAMS  Invalid parameter
 *
 *        2.    UHPI object structure is populated
 *
 *   @b Modifies
 *   @n    1. The status variable
 *
 *         2. UHPI object structure
 *
 *   @b Example
 *   @verbatim
            CSL_status           status;
            CSL_UhpiObj          uhpiObj;
            CSL_UhpiHandle       hUhpi;

            ...
                
            hUhpi = CSL_uhpiOpen(&uhpiObj, CSL_UHPI, NULL, &status);
            
            ...
    @endverbatim
 * =============================================================================
 */
extern CSL_UhpiHandle CSL_uhpiOpen (
    CSL_UhpiObj         *pUhpiObj,
    CSL_InstNum         uhpiNum,
    CSL_UhpiParam       *pUhpiParam,
    CSL_Status          *pStatus
);

/** ============================================================================
 *   @n@b CSL_uhpiGetBaseAddress
 *
 *   @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_uhpiOpen()
 *       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
            uhpiNum         Specifies the instance of the uhpi to be opened.

            pUhpiParam      Module specific parameters.

            pBaseAddress    Pointer to base address 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.
 *   @li                    CSL_ESYS_INVPARAMS  Invalid parameter 
 *
 *   <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_UhpiBaseAddress  baseAddress;

        ...

        status = CSL_uhpiGetBaseAddress(CSL_UHPI_PER_CNT, NULL,
                                           &baseAddress);
        ...

    @endverbatim
 * ===========================================================================
 */
extern CSL_Status CSL_uhpiGetBaseAddress (
    CSL_InstNum              uhpiNum,
    CSL_UhpiParam *          pUhpiParam,
    CSL_UhpiBaseAddress *    pBaseAddress
);

/** =============================================================================
 *   @n@b CSL_uhpiClose
 *
 *   @b Description
 *   @n This function closes the specified instance of UHPI.
 *
 *   @b Arguments
 *   @verbatim
            hUhpi            Handle to the uhpi

     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - Close successful
 *   @li                    CSL_ESYS_BADHANDLE  - Invalid handle
 *
 *   @b Example
 *   @verbatim
            CSL_UhpiHandle   hUhpi;
            CSL_status          status;

            ...

            status = CSL_uhpiClose(hUhpi, &hwSetup);
     @endverbatim
 * ===========================================================================
 */
extern CSL_Status  CSL_uhpiClose (
    CSL_UhpiHandle    hUhpi
);

/** ============================================================================
 *   @n@b CSL_uhpiHwSetup
 *
 *   @b Description
 *   @n It configures the uhpi registers as uhpi the values passed
 *      in the hardware setup structure.
 *
 *   @b Arguments
 *   @verbatim
            hUhpi            Handle to the uhpi
 
            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
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  DSP UHPI controller registers are configured according 
 *       to the hardware setup parameters
 *
 *   @b Modifies
 *   @n ARM PLL controller registers
 *
 *   @b Example
 *   @verbatim
            CSL_UhpiHandle   hUhpi;
            CSL_UhpiObj      uhpiObj;
            CSL_UhpiHwSetup  hwSetup;
            CSL_status          status;

            ...
            
            hUhpi = CSL_uhpiOpen(&uhpiObj, CSL_UHPI, NULL, &status);            
                      
            status = CSL_uhpiHwSetup(hUhpi, &hwSetup);
     @endverbatim
 * ===========================================================================
 */
extern CSL_Status  CSL_uhpiHwSetup(
    CSL_UhpiHandle       hUhpi,
    CSL_UhpiHwSetup     *hwSetup
);

/** ============================================================================
 *   @n@b CSL_uhpiHwControl
 *
 *   @b Description
 *   @n Takes a command of UHPI with an optional argument & implements it.
 *
 *   @b Arguments
 *   @verbatim
            hUhpi        Handle to the UHPI instance

            cmd             The command to this API indicates the action to be
                            taken on UHPI.

            arg             An optional argument.

     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li            CSL_SOK               - Status info return successful.
 *   @li            CSL_ESYS_BADHANDLE    - Invalid handle
 *   @li            CSL_ESYS_INVCMD       - Invalid command
 *   @li            CSL_ESYS_NOTSUPPORTED - Action not supported.
                                            (system not in bypass mode. if the 
                                             mode is not bypass mode & the 
                                             developer tries to write into
                                             D0 or PLLM registers or tries to 
                                             set the uhpi in powerdown state
                                             then this error status is returned)
 *   @li            CSL_ESYS_INVPARAMS    - Invalid parameter
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n The hardware registers of UHPI.
 *
 *   @b Example
 *   @verbatim
        CSL_UhpiHandle         huhpi;
        CSL_UhpiHwControlCmd   cmd;
        void                      arg;

        status = CSL_uhpiHwControl (hUhpi, cmd, &arg);

     @endverbatim
 * =============================================================================
 */
extern CSL_Status  CSL_uhpiHwControl(
    CSL_UhpiHandle          hUhpi,
    CSL_UhpiHwControlCmd    cmd,
    void                    *cmdArg
);

/** ============================================================================
 *   @n@b CSL_uhpiGetHwStatus
 *
 *   @b Description
 *   @n Gets the status of the different operations of UHPI.
 *
 *   @b Arguments
 *   @verbatim
            hUhpi      Handle to the UHPI instance

            query         The query to this API of UHPI 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 command
 *   @li                    CSL_ESYS_INVPARAMS  - Invalid parameter
 *  
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n None
 *
 *   @b Example
 *   @verbatim
        CSL_UhpiHandle          hUhpi;
        CSL_uhpiHwStatusQuery   query;
        void                       reponse;

        status = CSL_uhpiGetHwStatus (hUhpi, query, &response);

     @endverbatim
 * =============================================================================
 */
extern CSL_Status  CSL_uhpiGetHwStatus (
    CSL_UhpiHandle           hUhpi,
    CSL_UhpiHwStatusQuery    query,
    void                     *response
);

/** ============================================================================
 *   @n@b CSL_uhpiHwSetupRaw
 *
 *   @b Description
 *   @n This function initializes the device registers with the register-values
 *      provided through the Config Data structure.
 *
 *   @b Arguments
 *   @verbatim
            hUhpi        Handle to the UHPI instance

            config          Pointer to config structure
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li            CSL_SOK               - Configuration successful
 *   @li            CSL_ESYS_BADHANDLE    - Invalid handle
 *   @li            CSL_ESYS_INVPARAMS    - Configuration is not
                                            properly initialized
 *   @li            CSL_ESYS_NOTSUPPORTED - Action not supported.
                                            (system not in bypass mode. if the 
                                             mode is not bypass mode & the 
                                             developer tries to write into
                                             D0 or PLLM registers or tries to 
                                             set the uhpi in powerdown state
                                             then this error status is returned)
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  The registers of the specified UHPI instance will be setup
 *       according to input configuration structure values.
 *
 *   @b Modifies
 *   @n Hardware registers of the specified UHPI instance.
 *
 *   @b Example
 *   @verbatim
        CSL_UhpiHandle       hUhpi;
        CSL_UhpiConfig       config = CSL_UHPI_CONFIG_DEFAULTS;
        CSL_Status              status;

        status = CSL_uhpiHwSetupRaw (hUhpi, &config);

     @endverbatim
 * =============================================================================
 */
extern CSL_Status  CSL_uhpiHwSetupRaw (
    CSL_UhpiHandle           hUhpi,
    CSL_UhpiConfig          *config
);

/** ============================================================================
 *   @n@b CSL_uhpiGetHwSetup
 *
 *   @b Description
 *   @n It retrives the hardware setup parameters of the uhpi
 *      specified by the given handle.
 *
 *   @b Arguments
 *   @verbatim
            hUhpi        Handle to the uhpi
 
            hwSetup         Pointer to the harware setup structure
 
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - Retrieving the hardware setup
 *                                                parameters is successful
 *   @li                    CSL_ESYS_BADHANDLE  - The handle is passed is
 *                                                invalid
 *   @li                    CSL_ESYS_INVPARAMS  - Invalid parameter
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  The hardware setup structure is populated with the hardware setup
 *       parameters
 *
 *   @b Modifies
 *   @n hwSetup variable
 *
 *   @b Example
 *   @verbatim
            CSL_UhpiHandle   hUhpi;
            CSL_UhpiHwSetup  hwSetup;

            ...
            
            status = CSL_uhpiGetHwSetup(hUhpi, &hwSetup);
            
            ...
            
     @endverbatim
 * ===========================================================================
 */
extern CSL_Status  CSL_uhpiGetHwSetup(
    CSL_UhpiHandle       hUhpi,
    CSL_UhpiHwSetup     *hwSetup
);

#ifdef __cplusplus
}
#endif

#endif  /* _CSL_UHPI_H_ */