/*
* @file hv_drv_UsbMusbDma.h
* @brief Header file of musb dma.
*
* @author HiView SoC Software Team
* @version 1.0.0
* @date 2022-06-15
*/

#ifndef __HV_DRV_USB_MUSB_DMA_H
#define __HV_DRV_USB_MUSB_DMA_H

#define is_dma_capable()            (1)

struct musb_hw_ep;

#include "hv_drv_UsbCoreCommonUsb.h"

/*
 * DMA channel status ... updated by the dma controller driver whenever that
 * status changes, and protected by the overall controller spinlock.
 */
enum dma_channel_status {
    /* unallocated */
    MUSB_DMA_STATUS_UNKNOWN,
    /* allocated ... but not busy, no errors */
    MUSB_DMA_STATUS_FREE,
    /* busy ... transactions are active */
    MUSB_DMA_STATUS_BUSY,
    /* transaction(s) aborted due to ... dma or memory bus error */
    MUSB_DMA_STATUS_BUS_ABORT,
    /* transaction(s) aborted due to ... core error or USB fault */
    MUSB_DMA_STATUS_CORE_ABORT
};

/**
 * struct dma_channel - A DMA channel.
 * @private_data: channel-private data
 * @max_len: the maximum number of bytes the channel can move in one
 *  transaction (typically representing many USB maximum-sized packets)
 * @actual_len: how many bytes have been transferred
 * @status: current channel status (updated e.g. on interrupt)
 * @desired_mode: true if mode 1 is desired; false if mode 0 is desired
 *
 * channels are associated with an endpoint for the duration of at least
 * one usb transfer.
 */
struct dma_channel {
    void            *private_data;
    /* FIXME not void* private_data, but a dma_controller * */
    size_t          max_len;
    size_t          actual_len;
    enum dma_channel_status status;
    boolean            desired_mode;
};

INLINE enum dma_channel_status
dma_channel_status(struct dma_channel *c) {
    return (is_dma_capable() && c) ? c->status : MUSB_DMA_STATUS_UNKNOWN;
}

/**
 * struct dma_controller - A DMA Controller.
 * @start: call this to start a DMA controller;
 *  return 0 on success, else negative errno
 * @stop: call this to stop a DMA controller
 *  return 0 on success, else negative errno
 * @channel_alloc: call this to allocate a DMA channel
 * @channel_release: call this to release a DMA channel
 * @channel_abort: call this to abort a pending DMA transaction,
 *  returning it to FREE (but allocated) state
 *
 * Controllers manage dma channels.
 */
struct dma_controller {
    int         (*start)(struct dma_controller *);
    int         (*stop)(struct dma_controller *);
    struct dma_channel  *(*channel_alloc)(struct dma_controller *dma, struct musb_hw_ep *ep, u8 is_tx);
    void        (*channel_release)(struct dma_channel *dma);
    int         (*channel_program)(struct dma_channel *channel,
                                   u16 maxpacket, u8 mode,
                                   dma_addr_t dma_addr, u32 length);
    int         (*channel_abort)(struct dma_channel *dma);
};

/* called after channel_program(), may indicate a fault */
extern void musb_dma_completion(struct musb *musb, u8 epnum, u8 transmit);
extern struct dma_controller *dma_controller_create(struct musb *musb);
extern void dma_controller_destroy(struct dma_controller *);
extern void dma_controller_irq(struct musb *musb, u8 int_hsdma);
#endif