csl_pllc.h

Configuring External Interrupts on TMS320C672x Devices

}

/** \brief This data type is used to return the handle to the CSL of the pllc
 */
typedef struct CSL_PllcObj    *CSL_PllcHandle;

/*******************************************************************************
 * PLL controller function declarations
 ******************************************************************************/

/** ============================================================================
 *   @n@b CSL_pllcInit
 *
 *   @b Description
 *   @n This is the initialization function for the pllc CSL. The function
 *      must be called before calling any other API from this CSL. This
 *      function is idem-potent. Currently, the function just return status
 *      CSL_SOK, without doing anything.
 *
 *   @b Arguments
 *   @verbatim
        pContext    Pointer to module-context. As pllc 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 pllc is initialized
 *
 *   @b Modifies
 *   @n  None
 *
 *   @b Example
 *   @verbatim
            CSL_pllcInit(NULL);
     @endverbatim
 * =============================================================================
 */
extern CSL_Status  CSL_pllcInit (
    CSL_PllcContext * pContext
);

/** ============================================================================
 *   @n@b CSL_pllcOpen
 *
 *   @b Description
 *   @n This function returns the handle to the PLL controller
 *      instance. This handle is passed to all other CSL APIs.
 *
 *   @b Arguments
 *   @verbatim
            pllcObj     Pointer to pllc object.
 
            pllcNum     Instance of pll CSL to be opened. 
                           There is only one instance of the pllc available.
                           So, the value for this parameter will be 
                           CSL_PLLC always.
 
            pPllcParam  Module specific parameters.
 
            status         Status of the function call
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_PllcHandle
 *   @n                         Valid pllc 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 pllc handle is returned
 *   @li            CSL_ESYS_FAIL       The pllc instance is invalid
 *   @li            CSL_ESYS_INVPARAMS  Invalid parameter
 *
 *        2.    PLLC object structure is populated
 *
 *   @b Modifies
 *   @n    1. The status variable
 *
 *         2. PLLC object structure
 *
 *   @b Example
 *   @verbatim
            CSL_status              status;
            CSL_PllcObj          pllcObj;
            CSL_PllcHandle       hPllc;

            ...
                
            hPllc = CSL_pllcOpen(&pllcObj, CSL_PLLC, NULL, &status);
            
            ...
    @endverbatim
 * =============================================================================
 */
extern CSL_PllcHandle CSL_pllcOpen (
    CSL_PllcObj         *pllcObj,
    CSL_InstNum         pllcNum,
    CSL_PllcParam       *pPllcParam,
    CSL_Status          *status
);

/** ============================================================================
 *   @n@b CSL_pllcGetBaseAddress
 *
 *   @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_pllcOpen()
 *       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
            pllcNum      Specifies the instance of the pllc to be opened.

            pPllcParam   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_PllcBaseAddress  baseAddress;

        ...

        status = CSL_pllcGetBaseAddress(CSL_PLLC_PLLC_CNT, NULL,
                                           &baseAddress);
        ...

    @endverbatim
 * ===========================================================================
 */
extern CSL_Status CSL_pllcGetBaseAddress (
    CSL_InstNum              pllcNum,
    CSL_PllcParam *          pPllcParam,
    CSL_PllcBaseAddress *    pBaseAddress
);

/** =============================================================================
 *   @n@b CSL_pllcClose
 *
 *   @b Description
 *   @n This function closes the specified instance of PLLC.
 *
 *   @b Arguments
 *   @verbatim
            hPllc            Handle to the pllc

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

            ...

            status = CSL_pllcClose(hPllc);
     @endverbatim
 * ===========================================================================
 */
extern CSL_Status  CSL_pllcClose (
    CSL_PllcHandle    hPllc
);

/** ============================================================================
 *   @n@b CSL_pllcHwSetup
 *
 *   @b Description
 *   @n It configures the pllc registers as per the values passed
 *      in the hardware setup structure.
 *
 *   @b Arguments
 *   @verbatim
            hPllc            Handle to the pllc
 
            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  PLL controller registers are configured according 
 *       to the hardware setup parameters
 *
 *   @b Modifies
 *   @n PLL controller registers
 *
 *   @b Example
 *   @verbatim
            CSL_PllcHandle   hPllc;
            CSL_PllcObj      pllcObj;
            CSL_PllcHwSetup  hwSetup;
            CSL_status          status;

            ...
            
            hPllc = CSL_pllcOpen(&pllcObj, CSL_PLLC, NULL, &status);            
                      
            status = CSL_pllcHwSetup(hPllc, &hwSetup);
     @endverbatim
 * ===========================================================================
 */
extern CSL_Status  CSL_pllcHwSetup(
    CSL_PllcHandle       hPllc,
    CSL_PllcHwSetup     *hwSetup
);

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

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

            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_INVPARAMS    - Invalid parameter
 *   @li         CSL_ESYS_NOTSUPPORTED - Action Not Supported
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n The hardware registers of PLLC.
 *
 *   @b Example
 *   @verbatim
        CSL_PllcHandle         hPllc;
        CSL_PllcHwControlCmd   cmd=CSL_PLLC_CMD_SET_MODE;
        CSL_PllcMode           arg=CSL_PLLC_PLL_MODE;

        status = CSL_pllcHwControl (hPllc, cmd, &arg);

     @endverbatim
 * =============================================================================
 */
extern CSL_Status  CSL_pllcHwControl(
    CSL_PllcHandle          hPllc,
    CSL_PllcHwControlCmd    cmd,
    void                    *cmdArg
);

/** ============================================================================
 *   @n@b CSL_pllcGetHwStatus
 *
 *   @b Description
 *   @n Gets the status of the different operations of PLLC.
 *
 *   @b Arguments
 *   @verbatim
            hPllc      Handle to the PLLC instance

            query      The query to this API of PLLC 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
 *   @li                    CSL_ESYS_NOTSUPPORTED- Action Not Supported
 *  
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n None
 *
 *   @b Example
 *   @verbatim
        CSL_PllcHandle   hPllc;
        CSL_PllcState    response;

        status = CSL_pllcGetHwStatus (hPllc, CSL_PLLC_QUERY_OSC_STATE, &response);

     @endverbatim
 * =============================================================================
 */
extern CSL_Status  CSL_pllcGetHwStatus (
    CSL_PllcHandle           hPllc,
    CSL_PllcHwStatusQuery    query,
    void                       *response
);

/** ============================================================================
 *   @n@b CSL_pllcHwSetupRaw
 *
 *   @b Description
 *   @n This function initializes the device registers with the register-values
 *      provided through the Config Data structure.
 *
 *   @b Arguments
 *   @verbatim
            hPllc        Handle to the PLLC 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 pllc 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 PLLC instance will be setup
 *       according to input configuration structure values.
 *
 *   @b Modifies
 *   @n Hardware registers of the specified PLLC instance.
 *
 *   @b Example
 *   @verbatim
        CSL_PllcHandle       hPllc;
        CSL_PllcConfig       config = CSL_PLLC_CONFIG_DEFAULTS;
        CSL_Status              status;

        status = CSL_pllcHwSetupRaw (hPllc, &config);

     @endverbatim
 * =============================================================================
 */
extern CSL_Status  CSL_pllcHwSetupRaw (
    CSL_PllcHandle           hPllc,
    CSL_PllcConfig          *config
);

/** ============================================================================
 *   @n@b CSL_pllcGetHwSetup
 *
 *   @b Description
 *   @n It retrives the hardware setup parameters of the pllc
 *      specified by the given handle.
 *
 *   @b Arguments
 *   @verbatim
            hPllc        Handle to the pllc
 
            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_PllcHandle   hPllc;
            CSL_PllcHwSetup  hwSetup;

            ...
            
            status = CSL_pllcGetHwSetup(hPllc, &hwSetup);
            
            ...
            
     @endverbatim
 * ===========================================================================
 */
extern CSL_Status  CSL_pllcGetHwSetup(
    CSL_PllcHandle       hPllc,
    CSL_PllcHwSetup     *hwSetup
);

#ifdef __cplusplus
}
#endif

#endif  /* _CSL_PLLC_H_ */