csl_dpll.h

dsp在音频处理中的运用

 *  DPLL device. The device can be re-opened anytime after it has been normally
 *  closed if so required. The handle returned by this call is input as an
 *  essential argument for rest of the APIs described for this module.
 *
 *  <b> Usage Constraints: </b>
 *  DPLL must be successfully initialized via @a CSL_dpllInit() before calling
 *  this function. Memory for the @a CSL_dpllObj must be allocated outside
 *  this call. This object must be retained while usage of this peripheral.
 *
 *  @b Example:
 *  @verbatim

	  CSL_DpllObj     dpllObj;
	  CSL_Status       status;
 		...
	  hDpll = CSL_dpllOpen(&dpllObj,
                          CSL_DPLL_1,
                          NULL,
                          &status);
   @endverbatim
 *
 * @return returns a handle @a CSL_DpllHandle to the requested instance of
 * DPLL if the call is successful, otherwise, a @a NULL is returned.
 *
 */
CSL_DpllHandle CSL_dpllOpen (
    /** Pointer to the object that holds reference to the
     *  instance of DPLL requested after the call
     */
    CSL_DpllObj*		    pDpllObj,
    /** Instance of DPLL to which a handle is requested
     */
    CSL_InstNum              dpllNum,
    /** Module specific parameters;
     * Currently there are none; the user should pass 'NULL'
     */
    CSL_DpllParam          *pDpllParam,
    /** This returns the status (success/errors) of the call.
     * Could be 'NULL' if the user does not want status information.
     */
    CSL_Status              *pStatus
	);



/** The Close call releases the resource and appropriate shared pins.
 *
 *	     <b> Usage Constraints: </b>
 *       Both @a CSL_dpllInit() and @a CSL_dpllOpen() must be called successfully
 *       in that order before CSL_dpllClose() can be called.
 *
 *  @b Example:
 *  @verbatim

      CSL_DpllHandle hDpll;
      ...
      CSL_dpllClose(hDpll);
    @endverbatim
 *
 * @return returns the status of the operation (see @a CSL_Status)
 *
 */
CSL_Status  CSL_dpllClose(
    /** Pointer to the object that holds reference to the
     *  instance of DPLL requested after the call
	 */
    CSL_DpllHandle                         hDpll
	);

/** 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. For information passed through the HwSetup Data structure refer
 *  @a CSL_DpllHwSetup.
 *
 *
 * @note   This function just configures the DPLL with values specified.
 *         This will not ensure that, the hardware has stabilized based on these
 *         changes. The query function needs to be called to check the status.
 *         For example, if the LOCK mode is specified, then after calling
 *         CSL_dpllHwSetup(), it's not guaranteed that, the specific frequency clock
 *         is generated. To ensure the frequency locking, use the CSL_dpllGetHwStatus()
 *         function call and check the LOCK status.
 *
 *	     <b> Usage Constraints:</b>
 *       Both @a CSL_dpllInit() and @a CSL_dpllOpen() must be called successfully
 *       in that order before CSL_dpllHwSetup() 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_DpllHandle hDpll;
     CSL_Status status;
     CSL_DpllHwSetup hwSetup = CSL_DPLL_HWSETUP_DEFAULTS;
     status = CSL_dpllHwSetup(hDpll, &hwSetup);
   @endverbatim
 *
 * @return Returns the status of the setup operation
 *
 */

CSL_Status  CSL_dpllHwSetup(
    /** Pointer to the object that holds reference to the
     *  instance of DPLL requested after the call
	 */
    CSL_DpllHandle                         hDpll,
    /** Pointer to setup structure which contains the
     *  information to program DPLL to a useful state
	 */
    CSL_DpllHwSetup                        *setup
	);

/** This function gets the current setup of the DPLL. The setup is returned
 *  through @a CSL_DpllHwSetup. The obtaining of status is the reverse
 *  operation of @a CSL_dpllHwSetup() function.
 *
 * <b> Usage Constraints: </b>
 * Both @a CSL_dpllInit() and @a CSL_dpllOpen() must be called successfully
 * in that order before @a CSL_dpllGetHwSetup() can be called.
 *
 * @b Example:
 * @verbatim

     CSL_DpllHandle hDpll;
     CSL_Status status;
     CSL_DpllHwSetup *mysetup;
      ...
     status = CSL_dpllGetHwSetup(hDpll, &mysetup);
   @endverbatim
 *
 * @return returns the status of operation.
 *
 */
CSL_Status  CSL_dpllGetHwSetup(
    /** Pointer to the object that holds reference to the
     *  instance of DPLL requested after the call
     */
    CSL_DpllHandle                         hDpll,
    /** Pointer to setup structure which contains the
     *  information to program DPLL to a useful state
     */
    CSL_DpllHwSetup                        *setup
	);

/** This function initializes the device registers with the register-values
 *  provided through the Config Data structure.  For information passed through
 *  the Config Data structure refer to @a CSL_DpllConfig.
 *
 *  <b> Usage Constraints: </b>
 *  The user has to allocate space for & fill in the main setup structure
 *  appropriately before calling this function.
 *
 * @b Example:
 * @verbatim
     CSL_DpllHandle hDpll;
     CSL_DpllConfig config;
     config.CTL = 0x1000;
     CSL_dpllHwSetupRaw(hDpll, &config);
  @endverbatim
 *
 * @return Returns the status of the setup operation
 *
 */

 CSL_Status  CSL_dpllHwSetupRaw(
    CSL_DpllHandle     hDpll,
    CSL_DpllConfig *   setup
);

/** Control operations for the DPLL. For a particular control operation, the
 *  pointer to the corresponding data type needs to be passed as argument in
 *  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_DpllHwControlCmd
 *
 *	<b> Usage Constraints:</b>
 *  Both @a CSL_dpllInit() and @a CSL_dpllOpen() must be called successfully
 *  in that order before CSL_dpllHwControl() can be called. For the
 *  argument type that can be @a void* casted & passed with a particular command
 *  refer to @a CSL_DpllHwControlCmd
 *
 *  @b Example:
 *  @verbatim


      CSL_DpllHandle hDpll;
      CSL_Status status;
      ...
      status = CSL_dpllHwControl(hDpll,
                                   CSL_DPLL_CMD_SET_MODE,
                                   &command);
    @endverbatim
 *
 * @return Returns the status of the operation
 *
 */
CSL_Status  CSL_dpllHwControl(
    /** Pointer to the object that holds reference to the
     *  instance of DPLL requested after the call
	 */
    CSL_DpllHandle                         hDpll,
    /** The command to this API, which indicates the action to be taken
	 */
    CSL_DpllHwControlCmd                     cmd,
    /** An optional argument @a void* casted
	 */
    void                                     *arg
	);

/** This function is used to read the current device configuration and the
 *  value present in associated registers. 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_DpllHwStatusQuery.
 *
 *  <b> Usage Constraints: </b>
 *  Both @a CSL_dpllInit() and @a CSL_dpllOpen() must be called successfully
 *  in that order before @a CSL_dpllGetHwStatus() can be called. For the
 *  argument type that can be void* casted & passed with a particular command,
 *  refer to @a CSL_DpllHwStatusQuery
 *
 *  @b Example:
 *  @verbatim
     Code below checks whether LOCK status is ON.
     CSL_DpllHandle hDpll;
     CSL_Status status;
     Uint16 *lock_sts;
     ...
     status = CSL_dpllGetHwStatus(hDpll,
                                  CSL_DPLL_QUERY_LOCK_STATUS,
                                  &lock_sts);
	 if(*lock_sts & CSL_DPLL_LOCK_ON)
	 	{    Lock status on.       }
   @endverbatim
 *
 *  @return Returns the status of the operation
 */
CSL_Status  CSL_dpllGetHwStatus(
    /** Pointer to the object that holds reference to the
     *  instance of DPLL requested after the call
	 */
    CSL_DpllHandle                         hDpll,
    /** The query to this API, which indicates the status
     *  to be returned
	 */
    CSL_DpllHwStatusQuery                  query,
    /** Placeholder to return the status; @a void* casted
	 */
    void                                    *response
	);

/** @brief 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_dpllOpen()
 *  function call.
 *
 *  Note: 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. Please refer the documentation for
 *        more details.
 *
 * @b Example:
 * @verbatim

      CSL_Status status;
      CSL_DpllBaseAddress   baseAddress;

       ...
      status = CSL_dpllGetBaseAddress(CSL_DPLL_1, NULL, &baseAddress);
   @endverbatim
 *
 * @return Returns the status of the operation (see @a CSL_Status)
 *
 */

CSL_Status CSL_dpllGetBaseAddress(
        /** Instance number
         */
        CSL_InstNum  		dpllNum,
        /** Module specific parameters
         */
        CSL_DpllParam *		pDpllParam,
        /** Base address details
         */
        CSL_DpllBaseAddress *	pBaseAddress
);

#ifdef __cplusplus
}
#endif


#endif