csl_ulpd.h

来自「dsp在音频处理中的运用」· C头文件 代码 · 共 827 行 · 第 1/2 页

/** @brief This object contains the reference to the instance of ULPD opened
 *  using the @a CSL_ulpdOpen().
 *
 *  The pointer to this, is passed to all ULPD CSL APIs.
 */
typedef struct CSL_UlpdObj {
	/** This is a pointer to the registers of the instance of ULPD
     *  referred to by this object
     */
	CSL_UlpdRegsOvly regs;
	/** This is the instance of ULPD being referred to by this object  */
	CSL_InstNum  	perNum;
} CSL_UlpdObj;

typedef struct CSL_UlpdObj *CSL_UlpdHandle;

/** @brief This will have the base-address information for the peripheral
 *  instance
 */
typedef struct {
	/** Base-address of the Configuration registers of the peripheral
	 */
	CSL_UlpdRegsOvly	regs;
} CSL_UlpdBaseAddress;


/** @brief Module specific parameters. Present implementation doesn't have
 *  any module specific parameters.
 */
typedef struct{
	/** Bit mask to be used for module specific parameters.
         *  The below declaration is just a place-holder for future
 	 *  implementation.
	 */
	CSL_BitMask16   flags;
} CSL_UlpdParam;

/** @brief Module specific context information. Present implementation doesn't have
 *  any Context information.
 */

typedef struct {
	/** Context information of ULPD.
         *  The below declaration is just a place-holder for future
 	 *  implementation.
 	 */
    Uint16	contextInfo;
} CSL_UlpdContext;

/** @brief This has all the fields required to configure Analog cells.
 *
 * This structure is used to setup the Sleep clock cycles for Analog
 * cells.
 */
typedef struct ULPD_SetupCell {
	/** Sleep clock cycles of Analog cell1  */
	Uint16  analog_cell1;
	/** Sleep clock cycles of Analog cell2  */
	Uint16  analog_cell2;
	/** Sleep clock cycles of Analog cell3  */
	Uint16  analog_cell3;
	/** Sleep clock cycles of Analog cell4  */
	Uint16  analog_cell4;
	/** Sleep clock cycles of Analog cell5  */
	Uint16  analog_cell5;
	/** Sleep clock cycles of Analog cell6  */
	Uint16  analog_cell6;
}ULPD_CellSetup;

/** @brief This has all the fields required to configure ULPD at Power Up
 * (After a Hardware Reset).
 *
 * This structure is used to setup or obtain the existing setup of
 * ULPD using @a CSL_ulpdHwSetup() & @a CSL_ulpdGetHwSetup() functions
 * respectively.
 */
typedef struct CSL_UlpdHwSetup {
		/** Clock cycle delay after receiving FIQ. */
	    Uint16                  fiqCycleDelay;
		/** PLL clock divider */
	    Uint16                  pllClkDiv;
		/** PLL control */
	    Uint16                  pllCtrl;
		/** Clock control mask */
	    Uint16                  clkCtrlMask;
		/** Sleep clock cycles of Analog cells */
	    ULPD_CellSetup          *cellsetup;
}CSL_UlpdHwSetup;

/**************************************************************************\
* ULPD global function declarations
\**************************************************************************/

/** @brief Peripheral specific initialization function.
 *
 * This is the peripheral specific intialization function. This function is
 * idempotent in that calling it many times is same as calling it once.
 * This function initializes the CSL data structures, and doesn't touches
 * the hardware.
 *
 * <b> Usage Constraints: </b>
 * This function should be called before using any of the CSL APIs in the ULPD
 * module.
 *
 *  Note: As ULPD doesn't have any context based information, currently, the function
 *  just returns CSL_SOK. User is expected to pass NULL in the function call.
 *
 * @b Example:
 * @verbatim

   ...
   if (CSL_SOK != CSL_ulpdInit(NULL)) {
       return;
   }
   @endverbatim
 *
 * @return returns the status of the operation
 *
 */

CSL_Status CSL_ulpdInit(
	/** ULPD specific context information
	 */
	CSL_UlpdContext * pContext
	);

/** @brief Opens the instance of ULPD requested.
 *
 *  The open call sets up the data structures for the particular instance of
 *  ULPD 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>
 *  ULPD must be successfully initialized via @a CSL_ulpdInit() before calling
 *  this function. Memory for the @a CSL_ulpdObj must be allocated outside
 *  this call. This object must be retained while usage of this peripheral.
 *
 *  @b Example:
 *  @verbatim

	  CSL_UlpdObj     ulpdObj;
	  CSL_Status       status;
 		...
	  hUlpd = CSL_ulpdOpen(&ulpdObj,
                          CSL_ULPD,
                          NULL,
                          &status);
   @endverbatim
 *
 * @return returns a handle @a CSL_UlpdHandle to the requested instance of
 * ULPD if the call is successful, otherwise, a @a NULL is returned.
 *
 */
CSL_UlpdHandle CSL_ulpdOpen (
    /** Pointer to the object that holds reference to the
     *  instance of ULPD requested after the call
     */
    CSL_UlpdObj*		    pUlpdObj,
    /** Instance of ULPD to which a handle is requested
     */
    CSL_InstNum              ulpdNum,
    /** Module specific parameters;
     * Currently there are none; the user should pass 'NULL'
     */
    CSL_UlpdParam          *pUlpdParam,
    /** 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(if any).
 *
 *  <b> Usage Constraints: </b>
 *  Both @a CSL_ulpdInit() and @a CSL_ulpdOpen() must be called successfully
 *  in that order before @a CSL_ulpdClose() can be called.
 *
 *  @b Example:
 *  @verbatim

     CSL_UlpdHandle hUlpd;
     ...
     CSL_ulpdClose(hUlpd);
   @endverbatim
 *
 *  @return Returns the status of the operation (see @a CSL_Status)
 *
 */
CSL_Status  CSL_ulpdClose(
    /** Pointer to the object that holds reference to the
     * instance of ULPD requested after the call
	 */
    CSL_UlpdHandle                         hUlpd
	);


/** This function initializes the device registers with the appropriate values
 *  provided through HwSetup Data structure. This function needs to be called
 *  only if the HwSetup Structure was not previously passed through the Open call.
 *  For the parameters passed through the HwSetup Data structure, refer
 *  @a CSL_UlpdHwSetup.
 *
 *
 *  <b> Usage Constraints: </b>
 *  Both @a CSL_ulpdInit() and @a CSL_ulpdOpen() 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_UlpdHandle hUlpd;
      CSL_UlpdHwSetup hwSetup = CSL_ULPD_HWSETUP_DEFAULTS;
      CSL_ulpdHwSetup(hUlpd, &hwSetup);
    @endverbatim
 *
 *  @return Returns the status of the setup operation
 *
 */
CSL_Status  CSL_ulpdHwSetup(
    /** Pointer to the object that holds reference to the
     *  instance of ULPD requested after the call
	 */
    CSL_UlpdHandle                         hUlpd,
    /** Pointer to setup structure which contains the
     *  information to program ULPD to a useful state
	 */
    CSL_UlpdHwSetup                        *setup
	);

/** This function gets the current setup of the ULPD. The status is returned
 *  through @a CSL_UlpdHwSetup. The obtaining of status is the reverse operation
 *  of @a CSL_ulpdHwSetup() function.
 *
 *  <b> Usage Constraints: </b>
 *  Both @a CSL_ulpdInit() and @a CSL_ulpdOpen() must be called successfully
 *  in that order before @a CSL_ulpdGetHwSetup() can be called.
 *
 *  @b Example:
 *  @verbatim
 *
 *    CSL_UlpdHandle hUlpd;
 *    CSL_Status status;
 *    CSL_UlpdHwSetup *mysetup;
 *     ...
 *    status = CSL_ulpdGetHwSetup(hUlpd, &mysetup);
 *  @endverbatim
 *
 * @return returns the status of the operation.
 */
 CSL_Status  CSL_ulpdGetHwSetup(
     /** Pointer to the object that holds reference to the
      *  instance of ULPD requested after the call
 	 */
     CSL_UlpdHandle                         hUlpd,
     /** Pointer to setup structure which contains the
 	 *  information to program ULPD to a useful state
 	 */
     CSL_UlpdHwSetup                        *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_UlpdConfig.
 *
 *  <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_UlpdHandle hUlpd;
     CSL_UlpdConfig config;
     ...
     config.SETUP_ANALOG_CELL3_REG = 0x0100;
     config.SETUP_ANALOG_CELL2_REG = 0x0100;
     ...
     config.SOFT_REQ_REG = 01E01;

     CSL_ulpdHwSetupRaw(hUlpd, &config);
  @endverbatim
 *
 * @return Returns the status of the setup operation
 *
 */

 CSL_Status  CSL_ulpdHwSetupRaw(
    CSL_UlpdHandle     hUlpd,
    CSL_UlpdConfig *   setup
);

/** Control operations for the ULPD.  For a particular control operation, the
 *  pointer to the corresponding data type needs to be passed as argument
 *  HwControl function Call. For the list of commands supported and argument
 *  type that can be @a void* casted & passed with a particular command refer
 *  to @a CSL_UlpdHwControlCmd.
 *
 *       <b> Usage Constraints: </b>
 *       Both @a CSL_ulpdInit() and @a CSL_ulpdOpen() must be called successfully
 *       in that order before @a CSL_ulpdHwControl() can be called.
 *
 * @b Example:
 * @verbatim

      CSL_UlpdHandle hUlpd;
      CSL_Status status;
      ...
      status = CSL_ulpdHwControl(hUlpd,
                                   CSL_ULPD_CMD_LOW_PWR_REQ,
                                   &command);
   @endverbatim
 *
 * @return Returns the status of the operation
 *
 */
CSL_Status  CSL_ulpdHwControl(
    /** Pointer to the object that holds reference to the
     *  instance of ULPD requested after the call */
    CSL_UlpdHandle                         hUlpd,
    /** The command to this API which indicates the action to be taken */
    CSL_UlpdHwControlCmd                     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_UlpdHwStatusQuery.
 *
 *		<b> Usage Constraints: </b>
 *      This function can be called only after getting the peripheral
 *      handle via CSL_ulpdOpen() function call.
 *
 * @b Example:
 * @verbatim


    CSL_UlpdHandle hUlpd;
    CSL_Status status;
    CSL_UlpdIntStat response;
    ...
    status = CSL_ulpdGetHwStatus(hUlpd,
                                  CSL_ULPD_QUERY_INT_STATUS,
                                  &response);
   @endverbatim
 *
 *  @return Returns the status of the operation
 *
 */
CSL_Status  CSL_ulpdGetHwStatus(
    /** Pointer to the object that holds reference to the
     *  instance of ULPD requested after the call
	 */
    CSL_UlpdHandle                         hUlpd,
    /** The query to this API which indicates the status
     *  to be returned
	 */
    CSL_UlpdHwStatusQuery                  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_ulpdOpen()
 *  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_UlpdBaseAddress   baseAddress;

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

CSL_Status CSL_ulpdGetBaseAddress(
        /** Instance number
         */
        CSL_InstNum  		ulpdNum,
        /** Module specific parameters
         */
        CSL_UlpdParam *		pUlpdParam,
        /** Base address details
         */
        CSL_UlpdBaseAddress *	pBaseAddress
);

#ifdef __cplusplus
}
#endif

#endif