csl_pmx.h

TI达芬奇dm644x各硬件模块测试代码

 *
 *          ...
 *
 * =============================================================================
 */
CSL_PmxHandle CSL_pmxOpen (
    /** Pointer to the object that holds reference to the
     *  instance of PMX requested after the call
     */
    CSL_PmxObj              *hPmxObj,
    /** Instance of PMX to which a handle is requested
     */
    CSL_InstNum              PmxNum,
    /** Specifies if PMX should be opened with exclusive or
     *  shared access to the associate pins
     */
    CSL_PmxParam            *pPmxParam,
    /** This returns the status (success/errors) of the call
     */
	CSL_Status              *pStatus
);

/** ===========================================================================
 *   @n@b CSL_pmxClose
 *
 *   @b Description
 *   @n he Close call releases the resource and appropriate shared pins.
 *
 *   @b Arguments
 *   @verbatim
            hPmx         Handle to the PMX instance
     @endverbatim
 *
 *   <b> Return Value   CSL_Status
 *   @li                    CSL_SOK            - PMX is closed
 *                                               successfully
 *
 *   @li                    CSL_ESYS_BADHANDLE - The handle passed is invalid
 *
 *   <b> Pre Condition
 *   @n  None
 *
 *   <b> Post Condition
 *   @n  1. The PMX CSL APIs can not be called until the PMX
 *          CSL is reopened again using CSL_uartOpen()
 *
 *   @b Modifies
 *   @n  None
 *
 *  <b> Usage Constraints: </b>
 *  Both @a CSL_pmxInit() and @a CSL_pmxOpen() must be called successfully
 *  in that order before @a CSL_pmxClose() can be called.
 *
 *  @b Example:
 *  @verbatim

    CSL_pmxHandle hPmx;
    ...
    CSL_pmxClose(hPmx);
    @endverbatim
 *
 *  @return returns the status of the operation (see @a CSL_Status)
 * ============================================================================
 */
CSL_Status  CSL_pmxClose (
    /** Pointer to the object that holds reference to the
     *  instance of PMX requested after the call
     */
    CSL_PmxHandle         hPmx
);

/** ============================================================================
 *   @n@b CSL_pmxHwSetup
 *
 *   @b Description
 *  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 device is ready for  operation.
 *  For information passed through the HwSetup Data structure refer
 *  @a CSL_pmxHwSetup.
 *
 *   @verbatim
            hPmx           Handle to the PMXS instance

            setup           Pointer to hardware 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  The specified instance will be setup according to value passed
 *
 *   @b Modifies
 *   @n Hardware registers for the specified instance
 *
 *  <b> Usage Constraints: </b>
 *  Both @a CSL_pmxInit() and @a CSL_pmxOpen() 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_pmxHandle hPmx;
      CSL_pmxHwSetup hwSetup = CSL_PMX_HWSETUP_DEFAULTS;
      CSL_pmxHwSetup(hPmx, &hwSetup);
    @endverbatim
 *
 * ============================================================================
 */
CSL_Status CSL_pmxHwSetup (
	/** Pointer to the object that holds reference to the
     *  instance of PMX requested after the call
     */
    CSL_PmxHandle         hPmx,
    /** Pointer to setup structure which contains the
     *  information to program PMX to a useful state
     */
    CSL_PmxHwSetup        *setup
);

/** ============================================================================
 *   @n@b CSL_pmxGetHwSetup
 *
 *   @b Description
 *   @n It retrives the hardware setup parameters of the PMX
 *      specified by the given handle.
 *
 *   @b Arguments
 *   @verbatim
            hArmpllc        Handle to the PMX

            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_PmxHandle   hPmx;
            CSL_PmxHwSetup  hwSetup;

            ...

            status = CSL_pmxGetHwSetup(hPmx, &hwSetup);

            ...

     @endverbatim
 * ===========================================================================
 */
CSL_Status CSL_pmxGetHwSetup (
	/** Pointer to the object that holds reference to the
     *  instance of PMX requested after the call
     */
    CSL_PmxHandle         hPmx,
    /** Pointer to setup structure which contains the
     *  information to program PMX to a useful state
     */
    CSL_PmxHwSetup        *setup
);

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

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

            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
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n The hardware registers of PMX.
 *
 *   @b Example
 *   @verbatim
        CSL_PmxHandle         hPmx;
        CSL_PmxHwControlCmd   cmd;
        void                  arg;

        status = CSL_pmxHwControl (hPmx, cmd, &arg);

     @endverbatim
 * =============================================================================
 */
CSL_Status CSL_pmxHwControl (
	/** Pointer to the object that holds reference to the
     *  instance of PMX requested after the call
     */
    CSL_PmxHandle         hPmx,
    /** The command to this API indicates the action to be taken
     */
    CSL_PmxHwControlCmd   cmd,
    /** An optional argument @a void* casted
     */
    void                  *arg
);

/** ============================================================================
 *  @n@b CSL_pmxGetHwStatus
 *  @b Description
 *
 *  @n 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_PmxHwStatusQuery.
 *
 *   @b Arguments
 *   @verbatim
            hPmx           Handle to the PMX instance

            query           Query to be performed

            response        Pointer to buffer to return the data requested by
                            the query passed
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK            - Successful completion of the
 *                                               query
 *
 *   @li                    CSL_ESYS_BADHANDLE - Invalid handle
 *
 *   @li                    CSL_ESYS_INVQUERY  - Query command not supported
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *       Data requested by the query is returned through the variable "response"
 *
 *   @b Modifies
 *   @n  The input arguement "response" is modified
 *
 *  <b> Usage Constraints: </b>
 *  Both @a CSL_pmxInit() and @a CSL_pmxOpen() must be called successfully
 *  in that order before @a CSL_pmxGetHwStatus() can be called. For the
 *  argument type that can be @a void* casted & passed with a particular cmd
 *  refer to @a CSL_PmxHwStatusQuery
 *
 * @b Example:
 * @verbatim
      CSL_PmxHandle hPmx;
      CSL_Status 	status;
      Uint16  		*response;
       ...
      status = CSL_pmxGetHwStatus(hPmx, CSL_PMX_QUERY_PIN_MUX0_STAT, &response);
   @endverbatim
 *
 */
CSL_Status CSL_pmxGetHwStatus (
	/** Pointer to the object that holds reference to the
     *  instance of PMX requested after the call
     */
    CSL_PmxHandle         hPmx,
    /** The query to this API which indicates the status
     *  to be returned
     */
    CSL_PmxHwStatusQuery  query,
    /** Placeholder to return the status. @a void* casted */
   void                   *response
);

/** ============================================================================
 *   @n@b CSL_pmxGetBaseAddress
 *
 *   @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_pmxOpen()
 *       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
            pmxNum        Specifies the instance of the PMX to be opened.

            pPmxParam     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.
 *   @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_PmxBaseAddress  baseAddress;

       ...
      status = CSL_pmxGetBaseAddress(CSL_PMX_PER_CNT, NULL, &baseAddress);

    @endverbatim
 * ===========================================================================
 */
CSL_Status CSL_pmxGetBaseAddress (
    /** PMX specific instance number */
    CSL_InstNum           pmxNum,
    /** PMX Parameter */
    CSL_PmxParam          *pPmxParam,
    /** PMX Base addredd */
    CSL_PmxBaseAddress    *pBaseAddress
);

/** ============================================================================
 *   @n@b CSL_pmxHwSetupRaw
 *
 *   @b Description
 *   @n This function initializes the device registers with the register-values
 *      provided through the config data structure.
 *
 *   @b Arguments
 *   @verbatim
            hPmx            Handle to the PMX instance

            config          Pointer to the config structure containing the
                            device register values
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - Configuration successful
 *   @li                    CSL_ESYS_BADHANDLE  - Invalid handle
 *   @li                    CSL_ESYS_INVPARAMS  - Configuration structure
 *                                                pointer is not properly
 *                                                 initialized
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  The registers of the specified PMX instance will be setup
 *       according to the values passed through the config structure
 *
 *   @b Modifies
 *   @n Hardware registers of the specified PMX instance
 *
 *   @b Example
 *   @verbatim
        CSL_PmxHandle           hPmx;
        CSL_PmxConfig           config = CSL_PMX_CONFIG_DEFAULTS;
        CSL_Status              status;

        ...

        status = CSL_pmxHwSetupRaw (hPmx, &config);

        ...

     @endverbatim
 * ===========================================================================
 */
CSL_Status  CSL_pmxHwSetupRaw (
	/** Pointer to the object that holds reference to the
     *  instance of PMX requested after the call
     */
    CSL_PmxHandle        hPmx,
    /** Config structure to configure the PMX with raw values */
    CSL_PmxConfig        *config
);


#ifdef __cplusplus
}
#endif

#endif