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

===== Allocating channels (in bus layers, etc) =====

<code cpp>
struct resource *gpdma_alloc_channel(const char *name, int chno)
</code>

Allocated a channel //chno// on engine named //name// (eg. edma0)

<code cpp>
int gpdma_release_channel(struct resource *rv)
</code>

Frees previously allocated channel.

===== Allocating transfers and starting DMA operations =====

<code cpp>
gpdma_transfer_t gpdma_alloc_transfer(struct resource *rv);
</code>

Allocates a new transfer structure, which will be used on engine and channel
represented by //rv//.
Transfer can be reused once completed.

<code cpp>
void gpdma_free_transfer(gpdma_transfer_t xfer);
</code>

Frees transfer //xfer//.

<code cpp>
void *gpdma_program_transfer(gpdma_transfer_t xfer);
</code>

Programs transfer //xfer// on channel described by //res//. This function
returns a cookie of type //void *// which will be used to reference this
DMA operation in future.

<code cpp>
int gpdma_start_transfer(void *cookie);
</code>

Starts previously programmed transfer. Returns 0 on success, nonzero on error.

<code cpp>
int gpdma_stop_transfer(void *cookie);
</code>

Stops previously started transfer. Returns 0 on success, nonzero on error.
In particular, it can return ENOTSUP if stopping transfers is not supported.

===== Setting up transfers, buffers, etc =====

<code cpp>
int gpdma_setup_buffer_raw(gpdma_transfer_t xfer, int buffer, bus_addr_t addr, bus_size_t length)
</code>

Sets //buffer// of //xfer// pointing to physical memory address //addr// with //length// size.

<code cpp>
int gpdma_setup_buffer_virt(gpdma_transfer_t xfer, int buffer, void *p, size_t length);
</code>

Sets //buffer// of //xfer// pointing to virtual memory address (in KVA) //p// with //length// size.

<code cpp>
int gpdma_setup_buffer_uio(gpdma_transfer_t xfer, int buffer, struct uio *uio);
</code>

TODO describe

<code cpp>
void gpdma_set_transfer_func(gpdma_transfer_t xfer, int func)
void gpdma_set_transfer_link(gpdma_transfer_t xfer, dmae_transfer_t next);
void gpdma_set_transfer_callback(gpdma_transfer_t xfer, dmae_callback_t cb, void *arg);
void gpdma_set_transfer_flags(gpdma_transfer_t xfer, int flags);

int gpdma_get_buffer_layout(gpdma_transfer_t xfer, int buffer);
void gpdma_set_buffer_layout(gpdma_transfer_t xfer, int buffer, int layout);
void gpdma_set_buffer_stride(gpdma_transfer_t xfer, int buffer, int width, int spacing);
void gpdma_set_buffer_fifo_width(gpdma_transfer_t xfer, int buffer, int width);
</code>

TODO describe