patrick/zephyr
1
0
Fork 0
Code Issues Pull requests Actions 7 Packages Projects Releases Wiki Activity

dma: Move struct member doc comments to fields

Browse source 
To better cover the struct fields of the DMA API in doxygen the fields
are now individually documented rather than documenting them ad-hoc in
the struct header doc comment.

A best attempt at marking fields that are HW specific has been done as
well. That means almost all of them.

Signed-off-by: Tom Burdick <thomas.burdick@intel.com>
This commit is contained in:
Tom Burdick 2023-11-09 09:59:38 -06:00 committed by Carles Cufí
parent 344d24bcb7
commit 986422f4f2
1 changed files with 132 additions and 92 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

224
include/zephyr/drivers/dma.h
View file

@ -28,12 +28,21 @@ extern "C" {
* @{
*/
/**
* @brief DMA channel direction
*/
enum dma_channel_direction {
/** Memory to memory */
MEMORY_TO_MEMORY = 0x0,
/** Memory to peripheral */
MEMORY_TO_PERIPHERAL,
/** Peripheral to memory */
PERIPHERAL_TO_MEMORY,
/** Peripheral to peripheral */
PERIPHERAL_TO_PERIPHERAL,
/** Host to memory */
HOST_TO_MEMORY,
/** Memory to host */
MEMORY_TO_HOST,
/**
@ -53,20 +62,31 @@ enum dma_channel_direction {
DMA_CHANNEL_DIRECTION_MAX = 0x7
};
/** Valid values for @a source_addr_adj and @a dest_addr_adj */
/**
* @brief DMA address adjustment
*
* Valid values for @a source_addr_adj and @a dest_addr_adj
*/
enum dma_addr_adj {
/** Increment the address */
DMA_ADDR_ADJ_INCREMENT,
/** Decrement the address */
DMA_ADDR_ADJ_DECREMENT,
/** No change the address */
DMA_ADDR_ADJ_NO_CHANGE,
};
/* channel attributes */
/**
* @brief DMA channel attributes
*/
enum dma_channel_filter {
DMA_CHANNEL_NORMAL, /* normal DMA channel */
DMA_CHANNEL_PERIODIC, /* can be triggered by periodic sources */
};
/* DMA attributes */
/**
* @brief DMA attributes
*/
enum dma_attribute_type {
DMA_ATTR_BUFFER_ADDRESS_ALIGNMENT,
DMA_ATTR_BUFFER_SIZE_ALIGNMENT,
@ -78,65 +98,73 @@ enum dma_attribute_type {
* @struct dma_block_config
* @brief DMA block configuration structure.
*
* @param source_address is block starting address at source
* @param source_gather_interval is the address adjustment at gather boundary
* @param dest_address is block starting address at destination
* @param dest_scatter_interval is the address adjustment at scatter boundary
* @param dest_scatter_count is the continuous transfer count between scatter
* boundaries
* @param source_gather_count is the continuous transfer count between gather
* boundaries
*
* @param block_size is the number of bytes to be transferred for this block.
*
* @param config is a bit field with the following parts:
*
* source_gather_en [ 0 ] - 0-disable, 1-enable.
* dest_scatter_en [ 1 ] - 0-disable, 1-enable.
* source_addr_adj [ 2 : 3 ] - 00-increment, 01-decrement,
* 10-no change.
* dest_addr_adj [ 4 : 5 ] - 00-increment, 01-decrement,
* 10-no change.
* source_reload_en [ 6 ] - reload source address at the end of
* block transfer
* 0-disable, 1-enable.
* dest_reload_en [ 7 ] - reload destination address at the end
* of block transfer
* 0-disable, 1-enable.
* fifo_mode_control [ 8 : 11 ] - How full of the fifo before transfer
* start. HW specific.
* flow_control_mode [ 12 ] - 0-source request served upon data
* availability.
* 1-source request postponed until
* destination request happens.
* reserved [ 13 : 15 ]
* Aside from source address, destination address, and block size many of these options are hardware
* and driver dependent.
*/
struct dma_block_config {
#ifdef CONFIG_DMA_64BIT
/** block starting address at source */
uint64_t source_address;
/** block starting address at destination */
uint64_t dest_address;
#else
/** block starting address at source */
uint32_t source_address;
/** block starting address at destination */
uint32_t dest_address;
#endif
/** Address adjustment at gather boundary */
uint32_t source_gather_interval;
/** Address adjustment at scatter boundary */
uint32_t dest_scatter_interval;
/** Continuous transfer count between scatter boundaries */
uint16_t dest_scatter_count;
/** Continuous transfer count between gather boundaries */
uint16_t source_gather_count;
/** Number of bytes to be transferred for this block */
uint32_t block_size;
/** Pointer to next block in a transfer list */
struct dma_block_config *next_block;
/** Enable source gathering when set to 1 */
uint16_t source_gather_en : 1;
/** Enable destination scattering when set to 1 */
uint16_t dest_scatter_en : 1;
/**
* Source address adjustment option
*
* - 0b00 increment
* - 0b01 decrement
* - 0b10 no change
*/
uint16_t source_addr_adj : 2;
/**
* Destination address adjustment
*
* - 0b00 increment
* - 0b01 decrement
* - 0b10 no change
*/
uint16_t dest_addr_adj : 2;
/** Reload source address at the end of block transfer */
uint16_t source_reload_en : 1;
/** Reload destination address at the end of block transfer */
uint16_t dest_reload_en : 1;
/** FIFO fill before starting transfer, HW specific meaning */
uint16_t fifo_mode_control : 4;
/**
* Transfer flow control mode
*
* - 0b0 source request service upon data availability
* - 0b1 source request postponed until destination request happens
*/
uint16_t flow_control_mode : 1;
uint16_t reserved : 3;
uint16_t _reserved : 3;
};
/** The DMA callback event has occurred at the completion of a transfer list */
#define DMA_STATUS_COMPLETE 0
/** The DMA callback has occurred at the completion of a single transfer block in a transfer list */
#define DMA_STATUS_BLOCK 1
/**
@ -151,10 +179,11 @@ struct dma_block_config {
* @param dev Pointer to the DMA device calling the callback.
* @param user_data A pointer to some user data or NULL
* @param channel The channel number
* @param status - 0-DMA_STATUS_COMPLETE buffer fully consumed
* - 1-DMA_STATUS_BLOCK buffer consumption reached a configured block
* @param status Status of the transfer
* - DMA_STATUS_COMPLETE buffer fully consumed
* - DMA_STATUS_BLOCK buffer consumption reached a configured block
* or water mark
* - a negative errno otherwise
* - A negative errno otherwise
*/
typedef void (*dma_callback_t)(const struct device *dev, void *user_data,
uint32_t channel, int status);
@ -162,86 +191,99 @@ typedef void (*dma_callback_t)(const struct device *dev, void *user_data,
/**
* @struct dma_config
* @brief DMA configuration structure.
*
* @param dma_slot [ 0 : 7 ] - which peripheral and direction
* (HW specific)
* @param channel_direction [ 8 : 10 ] - 000-memory to memory,
* 001-memory to peripheral,
* 010-peripheral to memory,
* 011-peripheral to peripheral,
* 100-host to memory
* 101-memory to host
* ...
* @param complete_callback_en [ 11 ] - 0-callback invoked at completion only
* 1-callback invoked at completion of
* each block
* @param error_callback_en [ 12 ] - 0-error callback enabled
* 1-error callback disabled
* @param source_handshake [ 13 ] - 0-HW, 1-SW
* @param dest_handshake [ 14 ] - 0-HW, 1-SW
* @param channel_priority [ 15 : 18 ] - DMA channel priority
* @param source_chaining_en [ 19 ] - enable/disable source block chaining
* 0-disable, 1-enable
* @param dest_chaining_en [ 20 ] - enable/disable destination block
* chaining.
* 0-disable, 1-enable
* @param linked_channel [ 21 : 27 ] - after channel count exhaust will
* initiate a channel service request
* at this channel
* @param cyclic [ 28 ] - enable/disable cyclic buffer
* 0-disable, 1-enable
* @param reserved [ 29 : 31 ]
* @param source_data_size [ 0 : 15 ] - width of source data (in bytes)
* @param dest_data_size [ 16 : 31 ] - width of dest data (in bytes)
* @param source_burst_length [ 0 : 15 ] - number of source data units
* @param dest_burst_length [ 16 : 31 ] - number of destination data units
* @param block_count is the number of blocks used for block chaining, this
* depends on availability of the DMA controller.
* @param user_data private data from DMA client.
* @param dma_callback see dma_callback_t for details
*/
struct dma_config {
/** Which peripheral and direction, HW specific */
uint32_t dma_slot : 8;
/**
* Direction the transfers are occurring
*
* - 0b000 memory to memory,
* - 0b001 memory to peripheral,
* - 0b010 peripheral to memory,
* - 0b011 peripheral to peripheral,
* - 0b100 host to memory
* - 0b101 memory to host
* - others hardware specific
*/
uint32_t channel_direction : 3;
/**
* Completion callback enable
*
* - 0b0 callback invoked at transfer list completion only
* - 0b1 callback invoked at completion of each block
*/
uint32_t complete_callback_en : 1;
/**
* Error callback enable
*
* - 0b0 error callback enabled
* - 0b1 error callback disabled
*/
uint32_t error_callback_en : 1;
/**
* Source handshake, HW specific
*
* - 0b0 HW
* - 0b1 SW
*/
uint32_t source_handshake : 1;
/**
* Destination handshake, HW specific
*
* - 0b0 HW
* - 0b1 SW
*/
uint32_t dest_handshake : 1;
/**
* Channel priority for arbitration, HW specific
*/
uint32_t channel_priority : 4;
/** Source chaining enable, HW specific */
uint32_t source_chaining_en : 1;
/** Destination chaining enable, HW specific */
uint32_t dest_chaining_en : 1;
/** Linked channel, HW specific */
uint32_t linked_channel : 7;
/** Cyclic transfer list, HW specific */
uint32_t cyclic : 1;
uint32_t reserved : 3;
uint32_t _reserved : 3;
/** Width of source data (in bytes) */
uint32_t source_data_size : 16;
/** Width of destination data (in bytes) */
uint32_t dest_data_size : 16;
/** Source burst length in bytes */
uint32_t source_burst_length : 16;
/** Destination burst length in bytes */
uint32_t dest_burst_length : 16;
/** Number of blocks in transfer list */
uint32_t block_count;
/** Pointer to the first block in the transfer list */
struct dma_block_config *head_block;
/** Optional attached user data for callbacks */
void *user_data;
/** Optional callback for completion and error events */
dma_callback_t dma_callback;
};
/**
* DMA runtime status structure
*
* busy - is current DMA transfer busy or idle
* dir - DMA transfer direction
* pending_length - data length pending to be transferred in bytes
* or platform dependent.
* free - free buffer space
* write_position - write position in a circular dma buffer
* read_position - read position in a circular dma buffer
*
*/
struct dma_status {
/** Is the current DMA transfer busy or idle */
bool busy;
/** Direction fo the transfer */
enum dma_channel_direction dir;
/** Pending length to be transferred in bytes, HW specific */
uint32_t pending_length;
/** Available buffers space, HW specific */
uint32_t free;
/** Write position in circular DMA buffer, HW specific */
uint32_t write_position;
/** Read position in circular DMA buffer, HW specific */
uint32_t read_position;
/** Total copied, HW specific */
uint64_t total_copied;
};
@ -249,19 +291,17 @@ struct dma_status {
* DMA context structure
* Note: the dma_context shall be the first member
* of DMA client driver Data, got by dev->data
*
* magic - magic code to identify the context
* dma_channels - dma channels
* atomic - driver atomic_t pointer
*
*/
struct dma_context {
/** magic code to identify the context */
int32_t magic;
/** number of dma channels */
int dma_channels;
/** atomic holding bit flags for each channel to mark as used/unused */
atomic_t *atomic;
};
/* magic code to identify context content */
/** Magic code to identify context content */
#define DMA_MAGIC 0x47494749
/**