csl_spi.h

ccs下对dm6446的测试程序

            status          Status of the function call
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_SpiHandle
 *   @n                         Valid SPI 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 SPI handle is returned
 *   @li            CSL_ESYS_FAIL       The SPI instance is invalid
 *
 *        2.    SPI object structure is populated
 *
 *   @b Modifies
 *   @n    1. The status variable
 *
 *         2. SPI object structure
 *
 *   @b Example
 *   @verbatim
            CSL_status              status;
            CSL_SpiObj              spiObj;
            CSL_SpiHandle           hSpi;

            hSpi = CSL_spiOpen (&spiObj, CSL_SPI, NULL, &status);
            ...
    @endverbatim
 * =============================================================================
 */
CSL_SpiHandle CSL_spiOpen (
    CSL_SpiObj              *spiObj,
    CSL_InstNum              spiNum,
    CSL_SpiParam            *pSpiParam,
    CSL_Status              *status
);

/** ============================================================================
 *   @n@b CSL_spiClose
 *
 *   @b Description
 *   @n This function marks that CSL for the SPI instance is closed.
 *      CSL for the SPI instance need to be reopened before using any
 *      SPI CSL API.
 *
 *   @b Arguments
 *   @verbatim
            hSpi         Handle to the SPI instance
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK            - SPI is closed
 *                                               successfully
 *
 *   @li                    CSL_ESYS_BADHANDLE - The handle passed is invalid
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  1. The SPI CSL APIs can not be called until the SPI
 *          CSL is reopened again using CSL_spiOpen()
 *
 *   @b Modifies
 *   @n  None
 *
 *   @b Example
 *   @verbatim
            CSL_spiClose (hSpi);
     @endverbatim
 * ===========================================================================
 */
CSL_Status CSL_spiClose (
    CSL_SpiHandle         hSpi
);

/** ============================================================================
 *   @n@b CSL_spiHwSetup
 *
 *   @b Description
 *   @n It configures the SPI instance registers as per the values passed
 *      in the hardware setup structure.
 *
 *   @b Arguments
 *   @verbatim
            hSpi            Handle to the SPI 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 Example
 *   @verbatim
        CSL_status          status;
        CSL_spiHwSetup      hwSetup;

        status = CSL_spiHwSetup (hSpi, &hwSetup);

     @endverbatim
 * ===========================================================================
 */
CSL_Status CSL_spiHwSetup (
    CSL_SpiHandle            hSpi,
    CSL_SpiHwSetup          *setup
);

/** ============================================================================
 *   @n@b CSL_spiGetHwSetup
 *
 *   @b Description
 *   @n It retrives the hardware setup parameters
 *
 *   @b Arguments
 *   @verbatim
            hSpi            Handle to the SPI instance

            hwSetup         Pointer to hardware setup structure

     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - Hardware setup retrieved
 *   @li                    CSL_ESYS_BADHANDLE  - Invalid handle
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  The hardware set up structure will be populated with values from
 *       the registers
 *
 *   @b Modifies
 *   @n None
 *
 *   @b Example
 *   @verbatim
        CSL_status          status;
        CSL_SpiHwSetup      hwSetup;

        status = CSL_spiGetHwsetup (hSpi, &hwSetup);

     @endverbatim
 * ===========================================================================
 */
CSL_Status CSL_spiGetHwSetup (
    CSL_SpiHandle               hSpi,
    CSL_SpiHwSetup             *setup
);

/** ============================================================================
 *   @n@b CSL_spiHwControl
 *
 *   @b Description
 *   @n This function performs various control operations on the SPI instance,
 *      based on the command passed.
 *
 *   @b Arguments
 *   @verbatim
            hSpi         Handle to the SPI instance

            cmd          Operation to be performed on the SPI

            arg          Argument specific to the command

     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK            - Command execution successful.
 *   @li                    CSL_ESYS_BADHANDLE - Invalid handle
 *   @li                    CSL_ESYS_INVCMD    - Invalid command
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  Registers of the SPI instance are configured according to the command
 *       and the command arguments. The command determines which registers are
 *       modified.
 *
 *   @b Modifies
 *   @n Registers determined by the command
 *
 *   @b Example
 *   @verbatim
        CSL_Status status;

        status  = CSL_spiHwControl (hSpi, CSL_SPI_CMD_CPT_DMA_ENABLE, NULL);

     @endverbatim
 * ===========================================================================
 */
CSL_Status CSL_spiHwControl (
    CSL_SpiHandle              hSpi,
    CSL_SpiHwControlCmd        cmd,
    void                      *arg
);

/** ============================================================================
 *   @n@b CSL_spiInit
 *
 *   @b Description
 *   @n This is the initialization function for the SPI 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 SPI 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  None
 *
 *   <b> Post Condition </b>
 *   @n  The CSL for SPI is initialized
 *
 *   @b Modifies
 *   @n  None
 *
 *   @b Example
 *   @verbatim
            CSL_spiInit();
     @endverbatim
 * =============================================================================
 */
CSL_Status CSL_spiInit (
    CSL_SpiContext       *pContext
);

/** ============================================================================
 *   @n@b CSL_spiHwSetupRaw
 *
 *   @b Description
 *   @n This function initializes the device registers with the register-values
 *      provided through the Config Data structure.
 *
 *   @b Arguments
 *   @verbatim
            hSpi            Handle to the SPI

            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
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  The registers of the specified SPI instance will be setup
 *       according to value passed.
 *
 *   @b Modifies
 *   @n Hardware registers of the specified SPI instance.
 *
 *   @b Example
 *   @verbatim
        CSL_SpiHandle       hSpi;
        CSL_SpiConfig       config = CSL_SPI_CONFIG_DEFAULTS;
        CSL_Status          status;

        status = CSL_spiHwSetupRaw (hSpi, &config);

     @endverbatim
 * ===========================================================================
 */
CSL_Status CSL_spiHwSetupRaw (
    CSL_SpiHandle               hSpi,
    CSL_SpiConfig              *config
);

/** ============================================================================
 *   @n@b CSL_spiGetHwStatus
 *
 *   @b Description
 *   @n This function is used to get the value of various parameters of the
 *      SPI instance. The value returned depends on the query passed.
 *
 *   @b Arguments
 *   @verbatim
            hSpi            Handle to the SPI 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 Example
 *   @verbatim

        CSL_status    status;
        Uint8         response;

        status = CSL_spiGetHwStatus(hSpi, CSL_SPI_QUERY_INT_VECTOR0, &response);
     @endverbatim
 * ===========================================================================
 */
CSL_Status CSL_spiGetHwStatus (
    CSL_SpiHandle                hSpi,
    CSL_SpiHwStatusQuery         query,
    void                        *response
);

/** ===========================================================================
 *   @n@b CSL_spiGetBaseAddress
 *
 *   @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_spiOpen()
 *       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
            spiNum          Specifies the instance of SPI to be opened.

            pSpiParam       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.
 *
 *   <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_SpiBaseAddress  baseAddress;

       ...
      status = CSL_spiGetBaseAddress(CSL_SPI_PER_CNT, NULL, &baseAddress);

    @endverbatim
 * ============================================================================
 */
CSL_Status CSL_spiGetBaseAddress (
    CSL_InstNum                     spiNum,
    CSL_SpiParam                   *pSpiParam,
    CSL_SpiBaseAddress             *pBaseAddress
);

#ifdef __cplusplus
}
#endif

#endif /* _CSL_SPI_H_ */