dma.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016 Intel Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_DRIVERS_DMA_H_
#define ZEPHYR_INCLUDE_DRIVERS_DMA_H_
 
#include <zephyr/kernel.h>
#include <zephyr/device.h>
 
#ifdef __cplusplus
extern "C" {
#endif


enum dma_channel_direction {
        MEMORY_TO_MEMORY = 0x0,
        MEMORY_TO_PERIPHERAL,
        PERIPHERAL_TO_MEMORY,
        PERIPHERAL_TO_PERIPHERAL,
        HOST_TO_MEMORY,
        MEMORY_TO_HOST,

        DMA_CHANNEL_DIRECTION_COMMON_COUNT,

        DMA_CHANNEL_DIRECTION_PRIV_START = DMA_CHANNEL_DIRECTION_COMMON_COUNT,

        DMA_CHANNEL_DIRECTION_MAX = 0x7
};

enum dma_addr_adj {
        DMA_ADDR_ADJ_INCREMENT,
        DMA_ADDR_ADJ_DECREMENT,
        DMA_ADDR_ADJ_NO_CHANGE,
};

enum dma_channel_filter {
        DMA_CHANNEL_NORMAL, /* normal DMA channel */
        DMA_CHANNEL_PERIODIC, /* can be triggered by periodic sources */
};

enum dma_attribute_type {
        DMA_ATTR_BUFFER_ADDRESS_ALIGNMENT,
        DMA_ATTR_BUFFER_SIZE_ALIGNMENT,
        DMA_ATTR_COPY_ALIGNMENT,
        DMA_ATTR_MAX_BLOCK_COUNT,
};

struct dma_block_config {
#ifdef CONFIG_DMA_64BIT
        uint64_t source_address;
        uint64_t dest_address;
#else
        uint32_t source_address;
        uint32_t dest_address;
#endif
        uint32_t source_gather_interval;
        uint32_t dest_scatter_interval;
        uint16_t dest_scatter_count;
        uint16_t source_gather_count;
        uint32_t block_size;
        struct dma_block_config *next_block;
        uint16_t  source_gather_en :  1;
        uint16_t  dest_scatter_en :   1;
        uint16_t  source_addr_adj :   2;
        uint16_t  dest_addr_adj :     2;
        uint16_t  source_reload_en :  1;
        uint16_t  dest_reload_en :    1;
        uint16_t  fifo_mode_control : 4;
        uint16_t  flow_control_mode : 1;
 
        uint16_t  _reserved :          3;
};

#define DMA_STATUS_COMPLETE                     0
#define DMA_STATUS_BLOCK                        1
#define DMA_STATUS_HALF_COMPLETE        2

typedef void (*dma_callback_t)(const struct device *dev, void *user_data,
                               uint32_t channel, int status);

struct dma_config {
        uint32_t  dma_slot :             8;
        uint32_t  channel_direction :    3;
        uint32_t  half_complete_callback_en : 1;
        uint32_t  complete_callback_en : 1;
        uint32_t  error_callback_dis :    1;
        uint32_t  source_handshake :     1;
        uint32_t  dest_handshake :       1;
        uint32_t  channel_priority :     4;
        uint32_t  source_chaining_en :   1;
        uint32_t  dest_chaining_en :     1;
        uint32_t  linked_channel   :     7;
        uint32_t  cyclic :                               1;
 
        uint32_t  _reserved :             2;
        uint32_t  source_data_size :    16;
        uint32_t  dest_data_size :      16;
        uint32_t  source_burst_length : 16;
        uint32_t  dest_burst_length :   16;
        uint32_t block_count;
        struct dma_block_config *head_block;
        void *user_data;
        dma_callback_t dma_callback;
};

struct dma_status {
        bool busy;
        enum dma_channel_direction dir;
        uint32_t pending_length;
        uint32_t free;
        uint32_t write_position;
        uint32_t read_position;
        uint64_t total_copied;
};

struct dma_context {
        int32_t magic;
        int dma_channels;
        atomic_t *atomic;
};

#define DMA_MAGIC 0x47494749

typedef int (*dma_api_config)(const struct device *dev, uint32_t channel,
                              struct dma_config *config);
 
#ifdef CONFIG_DMA_64BIT
typedef int (*dma_api_reload)(const struct device *dev, uint32_t channel,
                              uint64_t src, uint64_t dst, size_t size);
#else
typedef int (*dma_api_reload)(const struct device *dev, uint32_t channel,
                              uint32_t src, uint32_t dst, size_t size);
#endif
 
typedef int (*dma_api_start)(const struct device *dev, uint32_t channel);
 
typedef int (*dma_api_stop)(const struct device *dev, uint32_t channel);
 
typedef int (*dma_api_suspend)(const struct device *dev, uint32_t channel);
 
typedef int (*dma_api_resume)(const struct device *dev, uint32_t channel);
 
typedef int (*dma_api_get_status)(const struct device *dev, uint32_t channel,
                                  struct dma_status *status);
 
typedef int (*dma_api_get_attribute)(const struct device *dev, uint32_t type, uint32_t *value);

typedef bool (*dma_api_chan_filter)(const struct device *dev,
                                int channel, void *filter_param);

typedef void (*dma_api_chan_release)(const struct device *dev,
                                     uint32_t channel);
 
__subsystem struct dma_driver_api {
        dma_api_config config;
        dma_api_reload reload;
        dma_api_start start;
        dma_api_stop stop;
        dma_api_suspend suspend;
        dma_api_resume resume;
        dma_api_get_status get_status;
        dma_api_get_attribute get_attribute;
        dma_api_chan_filter chan_filter;
        dma_api_chan_release chan_release;
};

static inline int dma_config(const struct device *dev, uint32_t channel,
                             struct dma_config *config)
{
        return DEVICE_API_GET(dma, dev)->config(dev, channel, config);
}

#ifdef CONFIG_DMA_64BIT
static inline int dma_reload(const struct device *dev, uint32_t channel,
                             uint64_t src, uint64_t dst, size_t size)
#else
static inline int dma_reload(const struct device *dev, uint32_t channel,
                uint32_t src, uint32_t dst, size_t size)
#endif
{
        const struct dma_driver_api *api = DEVICE_API_GET(dma, dev);
 
        if (api->reload) {
                return api->reload(dev, channel, src, dst, size);
        }
 
        return -ENOSYS;
}

static inline int dma_start(const struct device *dev, uint32_t channel)
{
        return DEVICE_API_GET(dma, dev)->start(dev, channel);
}

static inline int dma_stop(const struct device *dev, uint32_t channel)
{
        return DEVICE_API_GET(dma, dev)->stop(dev, channel);
}

static inline int dma_suspend(const struct device *dev, uint32_t channel)
{
        const struct dma_driver_api *api = DEVICE_API_GET(dma, dev);
 
        if (api->suspend == NULL) {
                return -ENOSYS;
        }
        return api->suspend(dev, channel);
}

static inline int dma_resume(const struct device *dev, uint32_t channel)
{
        const struct dma_driver_api *api = DEVICE_API_GET(dma, dev);
 
        if (api->resume == NULL) {
                return -ENOSYS;
        }
        return api->resume(dev, channel);
}

static inline int dma_request_channel(const struct device *dev, void *filter_param)
{
        int i = 0;
        int channel = -EINVAL;
        const struct dma_driver_api *api = DEVICE_API_GET(dma, dev);
        /* dma_context shall be the first one in dev data */
        struct dma_context *dma_ctx = (struct dma_context *)dev->data;
 
        if (dma_ctx->magic != DMA_MAGIC) {
                return channel;
        }
 
        for (i = 0; i < dma_ctx->dma_channels; i++) {
                if (!atomic_test_and_set_bit(dma_ctx->atomic, i)) {
                        if (api->chan_filter &&
                            !api->chan_filter(dev, i, filter_param)) {
                                atomic_clear_bit(dma_ctx->atomic, i);
                                continue;
                        }
                        channel = i;
                        break;
                }
        }
 
        return channel;
}

static inline void dma_release_channel(const struct device *dev, uint32_t channel)
{
        const struct dma_driver_api *api = DEVICE_API_GET(dma, dev);
        struct dma_context *dma_ctx = (struct dma_context *)dev->data;
 
        if (dma_ctx->magic != DMA_MAGIC) {
                return;
        }
 
        if ((int)channel < dma_ctx->dma_channels) {
                if (api->chan_release) {
                        api->chan_release(dev, channel);
                }
 
                atomic_clear_bit(dma_ctx->atomic, channel);
        }
 
}

static inline int dma_chan_filter(const struct device *dev, int channel, void *filter_param)
{
        const struct dma_driver_api *api = DEVICE_API_GET(dma, dev);
 
        if (api->chan_filter) {
                return api->chan_filter(dev, channel, filter_param);
        }
 
        return -ENOSYS;
}

static inline int dma_get_status(const struct device *dev, uint32_t channel,
                                 struct dma_status *stat)
{
        const struct dma_driver_api *api = DEVICE_API_GET(dma, dev);
 
        if (api->get_status) {
                return api->get_status(dev, channel, stat);
        }
 
        return -ENOSYS;
}

static inline int dma_get_attribute(const struct device *dev, uint32_t type, uint32_t *value)
{
        const struct dma_driver_api *api = DEVICE_API_GET(dma, dev);
 
        if (api->get_attribute) {
                return api->get_attribute(dev, type, value);
        }
 
        return -ENOSYS;
}

static inline uint32_t dma_width_index(uint32_t size)
{
        /* Check boundaries (max supported width is 32 Bytes) */
        if (size < 1 || size > 32) {
                return 0; /* Zero is the default (8 Bytes) */
        }
 
        /* Ensure size is a power of 2 */
        if (!is_power_of_two(size)) {
                return 0; /* Zero is the default (8 Bytes) */
        }
 
        /* Convert to bit pattern for writing to a register */
        return find_msb_set(size);
}

static inline uint32_t dma_burst_index(uint32_t burst)
{
        /* Check boundaries (max supported burst length is 256) */
        if (burst < 1 || burst > 256) {
                return 0; /* Zero is the default (1 burst length) */
        }
 
        /* Ensure burst is a power of 2 */
        if (!(burst & (burst - 1))) {
                return 0; /* Zero is the default (1 burst length) */
        }
 
        /* Convert to bit pattern for writing to a register */
        return find_msb_set(burst);
}

#define DMA_BUF_ADDR_ALIGNMENT(node) DT_PROP(node, dma_buf_addr_alignment)

#define DMA_BUF_SIZE_ALIGNMENT(node) DT_PROP(node, dma_buf_size_alignment)

#define DMA_COPY_ALIGNMENT(node) DT_PROP(node, dma_copy_alignment)

 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_DMA_H_ */