/**
 * @file hv_drv_OsdDMA.h
 * @brief Osd driver layer Inner DMA interface.
 * @verbatim
 * ==============================================================================
 *                        ##### How to use this driver #####
 * ==============================================================================
 * (+) Use Hv_Drv_OsdDMA_Init(...) to init DMA entries.
 * (+) Use Hv_Drv_OsdDMA_TransferPrepare(...) to prepare a new DMA transfer.
 * (+) Use Hv_Drv_OsdDMA_Pend(...) to pend DMA transfer request.
 * (+) Use Hv_Drv_OsdDMA_Transfer(...) to start DMA transfer.
 * @endverbatim
 *
 * @author HiView SoC Software Team
 * @version 0.0.1
 * @date 2022-08-22
 */

#ifndef _HV_DRV_OSDDMA_H
#define _HV_DRV_OSDDMA_H

#include "hv_comm_DataType.h"
#include "hv_drv_OsdTypes.h"

/* 等待DMA搬运完成的最大超时时间 */
#define OSD_DMA_WAITDONE_MS 30

typedef Status (*pfOsdDMACallback)(OsdDMAEntry *);

/**
 * @brief print Inner DMA status
 * @param[in] None
 * @return VOID without return
 */
VOID Hv_Drv_OsdDMA_DebugPrintState(VOID);

/**
 * @brief Get DMA transfer finish flag
 * @param[in] None
 * @return HV_TURE if DMA transfer finished, otherwise HV_FALSE
 */
BOOL Hv_Drv_OsdDMA_GetTransferDone(VOID);

/**
 * @brief Prepare to start a new DMA transfer
 * @param[in] None
 * @return HV_FAILURE if last DMA not finished, otherwise HV_SUCCESS
 */
Status Hv_Drv_OsdDMA_TransferPrepare(VOID);

/**
 * @brief pend DMA request to current transfer
 * @param[in] uiSrc source address in DDR, aligned to 16 Bytes
 * @param[in] uiDst destination address in OSD RAM, aligned to 16 Bytes
 * @param[in] uiLength data length in bytes, aligned to 16
 * @return VOID without return
 */
VOID Hv_Drv_OsdDMA_Pend(UINT32 uiSrc, UINT32 uiDst, UINT32 uiLength);

/**
 * @brief clear used DMA channel count
 * @param[in] None
 * @return VOID without return
 */
VOID Hv_Drv_OsdDMA_ClearDMAChannel(VOID);

/**
 * @brief set DMA start register, actually start at next VSYNC
 * @param[in] None
 * @return VOID without return
 */
VOID Hv_Drv_OsdDMA_Transfer(VOID);

/**
 * @brief set DMA transfer finish flag, called within ISR
 * @param[in] None
 * @return VOID without return
 */
VOID Hv_Drv_OsdDMA_TransferFinish(VOID);

/**
 * @brief Execute callback function for all DMA entries
 * @param[in] pfCallback callback function to execute for each DMA entry
 * @param[in] ucCount DMA entries count to execute pfCallback
 * @return HV_SUCCESS for success, HV_FAILURE for failure
 */
Status Hv_Drv_OsdDMA_Walk(pfOsdDMACallback pfCallback, UCHAR8 ucCount);

/**
 * @brief Init global DMA management data
 * @param[in] None
 * @return VOID without return
 */
VOID Hv_Drv_OsdDMA_Init(VOID);

#endif