csl_uart.h

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

} CSL_UartObj;

/** @brief this is a pointer to @a CSL_UartObj and is passed as the first
 * parameter to all UART CSL APIs
 */
typedef CSL_UartObj* CSL_UartHandle;

/** @brief Module specific context information. Present implementation of external
 *  memory interface timer CSL doesn't have any context information.
 */
typedef struct {
    /** Context information of UART CSL.
     *  The below declaration is just a place-holder for future implementation.
     */
    Uint16  contextInfo;

} CSL_UartContext;

/** @brief Module specific parameters. Present implementation of external memory
 *  interface CSL 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_UartParam;

/** @brief This structure contains the base-address information for the peripheral
 *  instance
 */
typedef struct {
    /** Base-address of the configuration registers of the peripheral
     */
    CSL_UartRegsOvly    regs;
} CSL_UartBaseAddress;

/**
@} */


/*****************************************************************************\
  CSL3.x mandatory function declarations
\*****************************************************************************/

/**
 *  @defgroup CSL_UART_INIT_API UART Init API
 *  @ingroup CSL_UART_FUNCTION
 *  @brief Initializes the UART
 @{
 */
/** ============================================================================
 *   @n@b CSL_uartInit
 *
 *   @b Description
 *   @n This is the initialization function for the UART 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 UART 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 UARTs is initialized
 *
 *   @b Modifies
 *   @n  None
 *
 *   @b Example
 *   @verbatim
            CSL_uartInit(NULL);
     @endverbatim
 * =============================================================================
 */
CSL_Status CSL_uartInit (
    CSL_UartContext     *pContext
);

/**
@} */

/** ============================================================================
 *   @n@b CSL_uartOpen
 *
 *   @b Description
 *   @n This function returns the handle to the Universal asynchronous receiver
        transmitter controllerinstance. This handle is passed to all other CSL
        APIs.
 *
 *   @b Arguments
 *   @verbatim
            uartObj          Pointer to Universal asynchronous receiver
                             transmitter object.

            uartNum          Instance of Universal asynchronous receiver
                             transmitter CSL to be opened. There is only one
                             instance of the Universal asynchronous receiver
                             transmitter available. So, the value for this
                             parameter will be CSL_UART always.

            pUartParam       Module specific parameters.

            status          Status of the function call
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_UartHandle
 *   @n                         Valid Universal asynchronous receiver
                                transmitter 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 uart handle is returned
 *   @li            CSL_ESYS_FAIL       The uart instance is invalid
 *
 *        2.    UART object structure is populated
 *
 *   @b Modifies
 *   @n    1. The status variable
 *
 *         2. Universal asynchronous receiver transmitter object structure
 *
 *   @b Example
 *   @verbatim
            CSL_status              status;
            CSL_UartObj              UartObj;
            CSL_UartHandle           hUart;

            ...

            hUart = CSL_uartOpen (&uartObj, CSL_UART, NULL, &status);

            ...
    @endverbatim
 * =============================================================================
 */
CSL_UartHandle CSL_uartOpen (
    CSL_UartObj             *hUartObj,
    CSL_InstNum             uartNum,
    CSL_UartParam           *pUartParam,
    CSL_Status              *status
);

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

            ...

            CSL_uartClose (hUart);

            ...
     @endverbatim
 * ===========================================================================
 */
 CSL_Status  CSL_uartClose (
   CSL_UartHandle           hUart
);

/** ============================================================================
 *   @n@b   CSL_uartHwSetup
 *
 *   @b Description
 *   @n 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 serial device is ready for
 *  data transfer. For information passed through the HwSetup Data structure
 *  refer @a CSL_UartHwSetup.
 *   @b Arguments
 *
 *   @verbatim
            hUart           Handle to the UARTS 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:
 *  Both @a CSL_uartInit() and @a CSL_uartOpen() 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_UartHandle hUart;
     CSL_UartHwSetup hwSetup = CSL_UART_HWSETUP_DEFAULTS;
     CSL_uartHwSetup(hUart, &hwSetup);
  @endverbatim
 *
 * ============================================================================
 */
CSL_Status CSL_uartHwSetup (
    CSL_UartHandle          hUart,
    CSL_UartHwSetup         *setup
);

/** ============================================================================
 *   @n@b CSL_uartGetHwSetup
 *
 *   @b Description
 *   @n Gets the output status of UART
 *
 *   @b Arguments
 *   @verbatim
        hUart            Handle to the UART instance
        setup            Pointer to the hard ware setup
 *   @endverbatim
 *
 *   <b> Return Value </b>  Uint32
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *    @n Returns the status of UART read register
 *
 *   @b Modifies
 *   @n  None
 *
 *   @b Example
 *   @verbatim
        CSL_UartHandle     hUart;
        Uint32             stat;
        CSL_UartHwSetup   *setup
        ...
        stat = CSL_uartGetHwSetup (hUart, setup);
        ...
     @endverbatim
 * ===========================================================================
 */
CSL_Status CSL_uartGetHwSetup (
    CSL_UartHandle          hUart,
    CSL_UartHwSetup         *setup
);


/** ============================================================================
 *   @n@b   CSL_uartHwControl
 *
 *   @b Description
 *   @n Control operations for the UART.  For a particular control operation, the
 *  pointer to the corresponding data type needs to be passed as argument
 *  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_UartHwControlCmd.
 *
 *
 *   @b Arguments
 *   @verbatim
            hUart        Handle to the UART instance

            cmd          Operation to be performed on the UART

            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 UART 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> Usage Constraints:
 *  Both @a CSL_uartInit() and @a CSL_uartOpen() must be called successfully
 *  in that order before @a CSL_uartHwControl() can be called. For the
 *  argument type that can be @a void* casted & passed with a particular command
 *  refer to @a CSL_UartHwControlCmd
 *
 * @b Example:
 * @verbatim
       CSL_UartHandle hUart;
       CSL_Status status;
       ...
       status = CSL_uartHwControl(hUart,
                                  CSL_UART_CMD_START,
                                  &command);
   @endverbatim
 *
 *  @return returns the status of the operation (see @a CSL_Status)
 * ============================================================================
 */
CSL_Status CSL_uartHwControl (
    CSL_UartHandle          hUart,
    CSL_UartHwControlCmd    cmd,
    void                    *arg
);


/** ============================================================================
 *   @n@b CSL_uartGetHwStatus
 *
 *   @b Description
 *   @n Gets the status of the different operations of UART.
 *
 *   @b Arguments
 *   @verbatim
            hUart            Handle to the UART instance

            query           The query to this API of UART which indicates the
                            status to be returned.

            response        Placeholder to return the status.
     @endverbatim
 *
 *   <b> Return Value   CSL_Status
 *   @li                    CSL_SOK             - Status info return successful.
 *   @li                    CSL_ESYS_BADHANDLE  - Invalid handle
 *   @li                    CSL_ESYS_INVPARAMS  - Invalid parameter
 *
 *   <b> Pre Condition
 *   @n  None
 *
 *   <b> Post Condition
 *   @n  None
 *
 *   @b Modifies
 *   @n None
 *
 *   @b Example
 *   @verbatim
        CSL_UartHandle          hUart;
        CSL_UartHwStatusQuery   query;
        void                   reponse;

        status = CSL_uartGetHwStatus (hUart, query, &response);

     @endverbatim
 * =============================================================================
 */
CSL_Status CSL_uartGetHwStatus (
    CSL_UartHandle          hUart,
    CSL_UartHwStatusQuery   query,
    void                    *response
);


/** ============================================================================
 *   @n@b CSL_uartGetBaseAddress
 *
 *   @b Description
 *   @n The get base address call will give the UART current
 *      current instance base address
 *
 *   @b Arguments
 *   @verbatim
            uartNum         Specifies the instance of the external memory
                            interface for which the base address is requested

            pUartParam      Module specific parameters.

            pBaseAddress    Pointer to the base address structure to return the
                            base address details.
     @endverbatim
 *
 *   <b> Return Value   CSL_Status
 *   @li                    CSL_OK            Open call is successful
 *   @li                    CSL_ESYS_FAIL     The UART
 *                                            instance is not available.
 *
 *   <b> Pre Condition
 *   @n  None
 *
 *   <b> Post Condition
 *   @n  Base address structure is populated
 *
 *   @b Modifies
 *   @n    1. The status variable
 *
 *         2. Base address structure.
 *
 *   @b Example
 *   @verbatim
        CSL_Status          status;
        CSL_UartBaseAddress  baseAddress;

       ...

       status = CSL_uartGetBaseAddress(CSL_UART, NULL, &baseAddress);

    @endverbatim
 *  @return Retruns the status of the get base address operation
 * ============================================================================
 */
CSL_Status CSL_uartGetBaseAddress (
    CSL_InstNum             uartNum,
    CSL_UartParam           *pUartParam,
    CSL_UartBaseAddress     *pBaseAddress
);


/** ============================================================================
 *   @n@b CSL_uartHwSetupRaw
 *
 *   @b Description
 *   @n This function initializes the device registers with the register-values
 *      provided through the config data structure.
 *
 *   @b Arguments
 *   @verbatim
            hUart            Handle to the UART 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 UART instance will be setup
 *       according to the values passed through the config structure
 *
 *   @b Modifies
 *   @n Hardware registers of the specified UART instance
 *
 *   @b Example
 *   @verbatim
        CSL_UartHandle           hUart;
        CSL_UartConfig           config = CSL_UART_CONFIG_DEFAULTS;
        CSL_Status               status;

        ...

        status = CSL_uartHwSetupRaw (hUart, &config);

        ...

     @endverbatim
 * ===========================================================================
 */
CSL_Status  CSL_uartHwSetupRaw (
    CSL_UartHandle          hUart,
    CSL_UartConfig          *config
);


#ifdef __cplusplus
}
#endif

#endif