csl_ata.h

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

    Uint16  contextInfo;
} CSL_AtaContext;

/** @brief Module specific parameters. Present implementation of ATA 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_AtaParam;

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

/** @brief ATA object structure
 */
typedef struct CSL_AtaObj {
    /** Pointer to the register overlay structure of the ATA */
    CSL_AtaRegsOvly  regs;
    /** Instance of ATA being referred by this object  */
    CSL_InstNum      ataNum;
} CSL_AtaObj;

/** @brief This data type is used to return the handle to the CSL of ATA
 */
typedef struct CSL_AtaObj *CSL_AtaHandle;

/*******************************************************************************
 * ATA function declarations
 ******************************************************************************/

/** ============================================================================
 *   @n@b CSL_ataInit
 *
 *   @b Description
 *   @n This is the initialization function for the ATA. 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 affect
 *      the H/W.
 *
 *   @b Arguments
     @verbatim
            pContext   Context information for the instance. Should be NULL
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK - Always returns
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n  None
 *
 *   @b Example
 *   @verbatim
 *    ...
 *    if (CSL_sysInit() == CSL_SOK) {
 *       CSL_ataInit();
 *    }
 *   @endverbatim
 *  ============================================================================
 */
CSL_Status CSL_ataInit (
    CSL_AtaContext       *pContext
);

/** ============================================================================
 *   @n@b CSL_ataOpen
 *
 *   @b Description
 *   @n This function populates the peripheral data object for the ATA instance
 *      and returns a handle to the instance.
 *      The open call sets up the data structures for the particular instance
 *      of ATA 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 Arguments
 *   @verbatim
              pAtaObj      Pointer to the ATA instance object
              ataNum       Instance of the ATA to be opened
              pAtaParam    Pointer to module specific parameters
              pStatus      pointer for returning status of the function call
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_AtaHandle
 *   @n                     Valid ATA instance 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 ata handle is returned
 *   @li            CSL_ESYS_FAIL       The ata instance is invalid
 *   @li            CSL_ESYS_INVPARAMS  Invalid parameter
 *
 *        2.    ATA object structure is populated
 *
 *   @b Modifies
 *   @n    1. The status variable
 *
 *         2. ATA object structure
 *
 *   @b Example
 *   @verbatim
            CSL_status         status;
            CSL_AtaObj         ataObj;
            CSL_AtaHandle      hAta;

            ...

            hAta = CSL_ataOpen (&ataObj, CSL_ATA_PER_CNT, NULL, &status);
    @endverbatim
 *  ============================================================================
 */
CSL_AtaHandle CSL_ataOpen (
    CSL_AtaObj              *ataObj,
    CSL_InstNum              ataNum,
    CSL_AtaParam            *pAtaParam,
    CSL_Status              *status
);

/** ============================================================================
 *   @n@b CSL_ataGetBaseAddress
 *
 *   @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_ataOpen()
 *       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
            ataNum          Specifies the instance of the ata to be opened.

            pAtaParam       Module specific parameters.

            pBaseAddress    Pointer to base address 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_AtaBaseAddress      baseAddress;

        ...

        status = CSL_ataGetBaseAddress(CSL_ATA_PER_CNT, NULL,
                                           &baseAddress);
        ...

    @endverbatim
 *  ============================================================================
 */
CSL_Status CSL_ataGetBaseAddress (
    CSL_InstNum                     ataNum,
    CSL_AtaParam                   *pAtaParam,
    CSL_AtaBaseAddress             *pBaseAddress
);

/** ============================================================================
 *   @n@b CSL_ataClose
 *
 *   @b Description
 *   @n This function closes the specified instance of ATA.
 *
 *   @b Arguments
 *   @verbatim
            hAta            Handle to the ATA instance
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - Close successful
 *   @li                    CSL_ESYS_BADHANDLE  - Invalid handle
 *
 *   @b Example
 *   @verbatim
            CSL_AtaHandle       hAta;
            CSL_status          status;

            ...

            status = CSL_ataClose(hAta);
     @endverbatim
 *  ============================================================================
 */
CSL_Status  CSL_ataClose (
    CSL_AtaHandle          hAta
);

/** ============================================================================
 *   @n@b CSL_ataHwSetup
 *
 *   @b Description
 *   @n It configures the ata registers as per the values passed
 *      in the hardware setup structure.
 *
 *   @b Arguments
 *   @verbatim
            hAta            Handle to the ATA instance
            hwSetup         Pointer to harware 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 Modifies
 *   @n The hardware registers of ATA.
 *
 *   @b Example
 *   @verbatim
        CSL_AtaHandle    hAta;
        CSL_AtaObj       ataObj;
        CSL_AtaHwSetup   hwSetup;
        CSL_status       status;

        ...

        hAta = CSL_ataOpen (&ataObj, CSL_ATA_PRIMARY, NULL, &status);

        status = CSL_ataHwSetup(hAta, &hwSetup);
 *   @endverbatim
 *  ============================================================================
 */
CSL_Status  CSL_ataHwSetup (
    CSL_AtaHandle             hAta,
    CSL_AtaHwSetup           *hwSetup
);

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

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

            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_FAIL       - Invalid instance number
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n The hardware registers of ATA.
 *
 *   @b Example
 *   @verbatim
        CSL_AtaHandle         hAta;
        CSL_AtaHwControlCmd   cmd;
        void                  arg;

        status = CSL_ataHwControl (hAta, cmd, &arg);

     @endverbatim
 *  ============================================================================
 */
CSL_Status  CSL_ataHwControl (
    CSL_AtaHandle               hAta,
    CSL_AtaHwControlCmd         cmd,
    void                       *cmdArg
);

/** ============================================================================
 *   @n@b CSL_ataGetHwStatus
 *
 *   @b Description
 *   @n Gets the status of the different operations of ATA.
 *
 *   @b Arguments
 *   @verbatim
            hAta            Handle to the ATA instance

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

            response        Placeholder to return the status.

     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - Status info return successful.
 *   @li                    CSL_ESYS_BADHANDLE  - Invalid handle
 *   @li                    CSL_ESYS_INVPARAMS  - Invalid parameter
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n None
 *
 *   @b Example
 *   @verbatim
        CSL_AtaHandle          hAta;
        CSL_AtaHwStatusQuery   query;
        void                   reponse;

        status = CSL_ataGetHwStatus (hAta, query, &response);

     @endverbatim
 *  ============================================================================
 */
CSL_Status  CSL_ataGetHwStatus (
    CSL_AtaHandle                 hAta,
    CSL_AtaHwStatusQuery          query,
    void                         *response