**Warning:** this is dirty working draft version and is subject to change in future.

The DMA engine device driver should include "gpdma_if.h", %%<%%sys/dev/gpdma/gpdma.h> header
files and support following kobject methods:

<code cpp>
int setup_channel(device_t dev, int channel, struct dmae_transfer *xfer)
</code>

Sets up provided transfer on selected channel number, but doesn't start transfer.
Transfer can be started by calling apporiated method or by external (hardware)
trigger. Returns 0 on success, nonzero on error.

<code cpp>
int clear_channel(device_t dev, int channel)
</code>

Clears previously set transfer on //channel// and effectively disables any
kind of operation on that channel. Returns 0 on success, nonzero on error.

<code cpp>
int start_channel(device_t dev, int channel)
</code>

Starts DMA transfer on //channel// or enables starting transfer from external
triggers (if DMAE_TRANSFER_EXTTRIG is set in xfer->dt_flags). Returns 0 on success,
nonzero on error.

<code cpp>
int stop_channel(device_t dev, int channel)
</code>

Stops previously started (but not completed) transfer. Returns 0 on success,
nonzero on error. This method is optional - default implementation returns
ENOTSUP.

<code cpp>
int poll_channel(device_t dev, int channel, int *status)
</code>

Returns channel status. Returns 0 if obtained correct status or
nonzero if any error occured or channel status is unavailable.
//*status// is filled with one of //enum gpdma_transfer_status//

<code cpp>
int validate_transfer(device_t dev, int channel, struct gpdma_transfer *xfer)
</code>

Returns 0 if supplied transfer can be done using //channel// on engine //dev//,
or nonzero if cannot. This method is optional - default implementation returns
0.

DMA engines registers themselves using //gpdma_register_driver// function in
their attach method. //gpdma_register_driver// is defined as follows:

<code cpp>
int gpdma_register_driver(device_t dev, struct dmae_capabilities *caps, bus_dma_tag_t tag);
</code>

  * dev - DMA engine device
  * caps - DMA capabilities structure defined as follows:

<code cpp>
struct gpdma_capabilities {
        uint32_t                        dc_ops; /* one or more from 'enum dmae_op' */
        uint32_t                        dc_buffers; /* one or more from 'enum dmae_buffer_type' */
        uint32_t                        dc_flags;
#define DMAECAP_REPEAT                  0x1
#define DMAECAP_LINK                    0x2
        int                             dc_nchannels;
};
</code>

  * tag - engine root DMA tag

and can be unregistered (at device detach) using:

<code cpp>
int gpdma_unregister_driver(device_t dev);
</code>

===== Required data structures: =====

<code cpp>
typedef struct gpdma_engine *gpdma_engine_t;
typedef int (*gpdma_callback_t)(int status, void *arg);

enum gpdma_op {
        DMAE_FILL       = 0x1,
        DMAE_COPY       = 0x2,
        DMAE_XOR        = 0x4,
};

enum gpdma_transfer_status {
        DMAE_TRANSFER_COMPLETED,
        DMAE_TRANSFER_COMPLETED_STRIDE,
        DMAE_TRANSFER_COMPLETED_LINK,
        DMAE_TRANSFER_CANCELLED,
        DMAE_TRANSFER_IN_PROGRESS,
        DMAE_TRANSFER_ERROR,
};

enum gpdma_buffer_type {
        DMAEBUF_BLOCK           = 0x1,
        DMAEBUF_FRAME           = 0x2,
        DMAEBUF_FIFO            = 0x4,
};

struct gpdma_buffer {
        struct gpdma_transfer * db_transfer;
        int                     db_type;
        int                     db_flags;
        bus_addr_t              db_addr;
        bus_size_t              db_length;
        bus_size_t              db_stride_width;
        bus_size_t              db_stride_spacing;
        bus_size_t              db_fifo_width;
        void *                  db_immediate;

        /* Private fields: */
        bus_dma_tag_t           db_dmatag;
        bus_dmamap_t            db_dmamap;
};

struct gpdma_transfer {
        int                     dt_type;
        int                     dt_op;
        int                     dt_flags;
#define GPDMA_TRANSFER_EXTTRIG           0x1 /* transfer is triggered by external source */
#define GPDMA_TRANSFER_REPEAT            0x2 /* repeat transfer until cancel */
#define GPDMA_TRANSFER_NOINTR            0x4 /* don't generate callbacks */
#define GPDMA_TRANSFER_STRIDE_CALLBACK   0x8 /* callback on every stride */
#define GPDMA_TRANSFER_LINK_CALLBACK     0x10 /* callback on every linked transfer */
        gpdma_callback_t        dt_callback;
        void *                  dt_callback_arg;
        struct gpdma_buffer     dt_buffers[8];
#define GPDMA_BUF_DST           0
#define GPDMA_BUF_SRC           1
        struct gpdma_transfer * dt_next;

        /* Private fields: */
        struct gpdma_engine *   dt_engine;
        struct resource *       dt_res;
};
</code>