dma.h

Go to the documentation of this file.

/*
 * This file is part of the Ultibo project, https://ultibo.org/
 *
 * The MIT License (MIT)
 *
 * Copyright (c) 2026 Garry Wood <garry@softoz.com.au>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
#ifndef _ULTIBO_DMA_H
#define _ULTIBO_DMA_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "ultibo/globaltypes.h"
#include "ultibo/globalconst.h"
#include "ultibo/system.h"
#include "ultibo/devices.h"

#define DMA_NAME_PREFIX "DMA" 

#define DMA_TYPE_NONE   0

#define DMA_STATE_DISABLED  0
#define DMA_STATE_ENABLED   1

#define DMA_FLAG_NONE   0x00000000
#define DMA_FLAG_SHARED 0x00000001 
#define DMA_FLAG_NOCACHE    0x00000002 
#define DMA_FLAG_COHERENT   0x00000004 
#define DMA_FLAG_STRIDE 0x00000008 
#define DMA_FLAG_DREQ   0x00000010 
#define DMA_FLAG_NOINCREMENT    0x00000020 
#define DMA_FLAG_NOREAD 0x00000040 
#define DMA_FLAG_NOWRITE    0x00000080 
#define DMA_FLAG_WIDE   0x00000100 
#define DMA_FLAG_BULK   0x00000200 
#define DMA_FLAG_LITE   0x00000400 
#define DMA_FLAG_40BIT  0x00000800 


#define DMA_REQUEST_FLAG_NONE   0x00000000
#define DMA_REQUEST_FLAG_RELEASE    0x00000001 
#define DMA_REQUEST_FLAG_CYCLIC 0x00000002 
#define DMA_REQUEST_FLAG_COMPATIBLE 0x00000004 


typedef struct _DMA_PROPERTIES DMA_PROPERTIES;
struct _DMA_PROPERTIES
{
    uint32_t flags; 
    uint32_t alignment; 
    uint32_t multiplier; 
    uint32_t channels; 
    uint32_t maxsize; 
    uint32_t maxcount; 
    uint32_t maxlength; 
    int32_t minstride; 
    uint32_t maxstride; 
};

typedef struct _DMA_HOST DMA_HOST;
typedef struct _DMA_REQUEST DMA_REQUEST; 

typedef uint32_t STDCALL (*dma_enumerate_cb)(DMA_HOST *dma, void *data);
typedef uint32_t STDCALL (*dma_notification_cb)(DEVICE *device, void *data, uint32_t notification);

typedef uint32_t STDCALL (*dma_host_start_proc)(DMA_HOST *dma);
typedef uint32_t STDCALL (*dma_host_stop_proc)(DMA_HOST *dma);
typedef uint32_t STDCALL (*dma_host_reset_proc)(DMA_HOST *dma);
typedef uint32_t STDCALL (*dma_host_submit_proc)(DMA_HOST *dma, DMA_REQUEST *request);
typedef uint32_t STDCALL (*dma_host_cancel_proc)(DMA_HOST *dma, DMA_REQUEST *request);
typedef uint32_t STDCALL (*dma_host_properties_proc)(DMA_HOST *dma, DMA_PROPERTIES *properties);
 
struct _DMA_HOST
{
    // Device Properties
    DEVICE device; 
    // DMA Properties
    uint32_t dmaid; 
    uint32_t dmastate; 
    dma_host_start_proc hoststart; 
    dma_host_stop_proc hoststop; 
    dma_host_reset_proc hostreset; 
    dma_host_submit_proc hostsubmit; 
    dma_host_cancel_proc hostcancel; 
    dma_host_properties_proc hostproperties; 
    // Driver Properties
    MUTEX_HANDLE lock; 
    uint32_t alignment; 
    uint32_t multiplier; 
    DMA_PROPERTIES properties; 
    uint32_t lasterror; 
    uint32_t pendingcount; 
    THREAD_ID waiterthread; 
    // Statistics Properties
    uint32_t requestcount; 
    uint32_t requesterrors; 
    // Internal Properties
    DMA_HOST *prev; 
    DMA_HOST *next; 
};


typedef void STDCALL (*dma_request_completed_cb)(DMA_REQUEST *request);
 
struct _DMA_REQUEST
{
    // Request Properties
    DMA_HOST *host;
    DMA_DATA *data; 
    uint32_t flags; 
    uint32_t direction; 
    uint32_t peripheral; 
    dma_request_completed_cb callback; 
    void *driverdata; 
    // Result Properties
    uint32_t status; 
    // Driver Properties
    void *controlblocks;
};

 
uint32_t STDCALL dma_host_start(DMA_HOST *dma);
uint32_t STDCALL dma_host_stop(DMA_HOST *dma);
uint32_t STDCALL dma_host_reset(DMA_HOST *dma);
uint32_t STDCALL dma_host_properties(DMA_HOST *dma, DMA_PROPERTIES *properties);

DMA_HOST * STDCALL dma_host_create(void);

DMA_HOST * STDCALL dma_host_create_ex(uint32_t size);

uint32_t STDCALL dma_host_destroy(DMA_HOST *dma);

uint32_t STDCALL dma_host_register(DMA_HOST *dma);

uint32_t STDCALL dma_host_deregister(DMA_HOST *dma);
 
DMA_HOST * STDCALL dma_host_find(uint32_t dmaid);
uint32_t STDCALL dma_host_enumerate(dma_enumerate_cb callback, void *data);
 
uint32_t STDCALL dma_host_notification(DMA_HOST *dma, dma_notification_cb callback, void *data, uint32_t notification, uint32_t flags);


uint32_t STDCALL dma_data_count(DMA_DATA *data);

uint32_t STDCALL dma_data_flags(DMA_DATA *data);

uint32_t STDCALL dma_data_maximum(DMA_DATA *data);


void * STDCALL dma_buffer_allocate(DMA_HOST *dma, uint32_t size);

void * STDCALL dma_buffer_allocate_ex(DMA_HOST *dma, uint32_t *size);

uint32_t STDCALL dma_buffer_validate(DMA_HOST *dma, void *buffer, uint32_t size);

uint32_t STDCALL dma_buffer_release(void *buffer);


DMA_REQUEST * STDCALL dma_request_allocate(DMA_HOST *dma, DMA_DATA *data, dma_request_completed_cb callback, void *driverdata, uint32_t direction, uint32_t peripheral, uint32_t flags);

uint32_t STDCALL dma_request_release(DMA_REQUEST *request);

uint32_t STDCALL dma_request_submit(DMA_REQUEST *request);

uint32_t STDCALL dma_request_cancel(DMA_REQUEST *request);

void STDCALL dma_request_complete(DMA_REQUEST *request);


uint32_t STDCALL dma_transfer_request(DMA_HOST *dma, DMA_DATA *data, uint32_t direction, uint32_t peripheral, uint32_t flags, uint32_t timeout);

uint32_t STDCALL dma_transfer_request_ex(DMA_HOST *dma, DMA_DATA *data, dma_request_completed_cb callback, void *driverdata, uint32_t direction, uint32_t peripheral, uint32_t flags);

void STDCALL dma_transfer_request_complete(DMA_REQUEST *request);


uint32_t STDCALL dma_get_count(void);

DMA_HOST * STDCALL dma_host_get_default(void);

uint32_t STDCALL dma_host_set_default(DMA_HOST *dma);

DMA_HOST * STDCALL dma_host_check(DMA_HOST *dma);

uint32_t STDCALL dma_type_to_string(uint32_t dmatype, char *string, uint32_t len);

uint32_t STDCALL dma_state_to_string(uint32_t dmastate, char *string, uint32_t len);
 
#ifdef __cplusplus
}
#endif
 
#endif // _ULTIBO_DMA_H