device/class/dma.h header reference
[Devices support library module]

The source code of this header can be browsed online.

Description [link] 

This class of device provides a generic API for accessing DMA controllers from other device drivers.

Transfer between memory and device registers are both supported. A DMA operation request may perform multiple transfers of the same type. A request embeds an array of transfer descriptors. Each transfer entry specifies the addresses, size, stride and access width that must be used to perform the copy. It is possible to loop over the array of descriptors during a single request.

These modes of operation are supported:

  • In continuous mode, a callback is invoked after each transfer of the request, letting the initiator decide if the transfer must go on.

  • In single shot mode, a callback is invoked when the whole operation is over. A loop count is provided when the requested is submitted, allowing the hardware to perform the whole operation without software intervention.

A per request channel mask is used to specifies the channels that can be used to perform an operation.

See also DRIVER_CLASS_DMA.

Members [link] 

Types [link] 

Functions [link] 

Macros [link] 

Members detail [link] 

#define DEVDMA_REQUEST(n) [link] 

This macro is declared in device/class/dma.h source file, line 306.

See also devdma_request_t.

#define DEV_DMA_CALLBACK(n) [link] 

This macro is declared in device/class/dma.h source file, line 199.

See also dev_dma_callback_t.

#define DEV_DMA_CANCEL(n) [link] 

This macro is declared in device/class/dma.h source file, line 344.

See also dev_dma_cancel_t.

#define DEV_DMA_GET_INC(inc) [link] 

This macro is declared in device/class/dma.h source file, line 135.

#define DEV_DMA_GET_STATUS(n) [link] 

This macro is declared in device/class/dma.h source file, line 368.

See also dev_dma_status_t.

#define DEV_DMA_RQ_TYPE(n) [link] 

This macro is declared in device/class/dma.h source file, line 299.

This macro declare a struct dev_dma_rq_s object type with an embedded array of struct dev_dma_desc_s at the end.

#define DEV_STATIC_RES_DEV_DMA(path_) [link] 

This macro is declared in device/class/dma.h source file, line 410.

Preprocessor condition: defined( CONFIG_DEVICE_DMA )

#define DEV_STATIC_RES_DEV_DMA(path_) [link] 

This macro is declared in device/class/dma.h source file, line 420.

Preprocessor condition: not defined( CONFIG_DEVICE_DMA )

#define DEV_STATIC_RES_DMA(channel_mask_, link_) [link] 

This macro is declared in device/class/dma.h source file, line 401.

This macro specifies a DMA resource entry in a static device resources table declaration.

Alternate declarations with same identifier: [1], [2].

Preprocessor condition: defined( CONFIG_DEVICE_DMA )

See also DEV_RES_DMA and DEV_DECLARE_STATIC.

#define DEV_STATIC_RES_DMA(channel_mask_, link_) [link] 

This macro is declared in device/class/dma.h source file, line 415.

Documentation from alternate declaration:

This macro specifies a DMA resource entry in a static device resources table declaration.

Alternate declarations with same identifier: [1], [2].

Preprocessor condition: not defined( CONFIG_DEVICE_DMA )

See also DEV_RES_DMA and DEV_DECLARE_STATIC.

#define DRIVER_DMA_METHODS(prefix) [link] 

This macro is declared in device/class/dma.h source file, line 388.

See also struct driver_dma_s.

#define GCT_CONTAINER_ALGO_dev_dma_queue [link] 

This macro is declared in device/class/dma.h source file, line 230.

#define __DEVICE_DMA_H__ [link] 

This macro is declared in device/class/dma.h source file, line 56.

typedef bool_t (dev_dma_callback_t)(struct dev_dma_rq_s *rq, uint_fast16_t desc_id, error_t err) [link] 

This typedef is declared in device/class/dma.h source file, line 229.

This typedef is called when a DMA transfer has completed.

Depending on the type of operation requested, this will be called multiple times during a single operation:

  • When a continuous DMA operation has been requested, this function is called for each completed descriptor. The desc_id indicates the completed descriptor. The DMA operation terminates when this callback returns 0. The driver loops over the array of descriptors until this happens.

  • For other type of operations, this callback is called once when the operation terminates as the last descriptor is reached and the loop counter is decremented to 0.

In any case, the err parameter is not 0, the operation is terminated ans the callback will not be called anymore.

It is not permitted to call the devdma_request_t function in order to start a new operation from this callback. This callback may be invoked from the interrupt handler of the DMA controller. Deferred execution must be implemented as needed.

This declaration involves expansion of the DEV_DMA_CALLBACK macro.

struct dev_dma_desc_s [link] 

This struct is declared in device/class/dma.h source file, line 142.

This struct specifies parameter of a single DMA transfer. This is used as an array element in the struct dev_dma_rq_s structure.

FieldDescription
union <anonymous> {
struct <anonymous> {
uintptr_t addr;This specifies the address of the source memory buffer. This field may be modified by the driver.
uint16_t size;This specifies the number of units minus one to transfer from memory.
uint16_t width:2;This specifies the log2 of the memory load access width in bytes. This defines the unit size.
enum dev_dma_inc_e inc:2;This specifies the memory source address increment in units
uint16_t stride:12;This specifies the number of units to add to the source address pointer when looping.
} mem;
struct <anonymous> {
uintptr_t addr;This specifies the address of the device to load from register.
uint16_t size;This specifies the number of units minus one to transfer from memory.
uint16_t width:2;This specifies the log2 of the register load access width in bytes. This defines the unit size.
uint16_t _unused:2;
uint16_t burst:12;This specifies the number of units that is transfered at once from the device. Value 0 means that all units can be transfered at once
} reg;
} src;
union <anonymous> {
struct <anonymous> {
uintptr_t addr;This specifies the address of the destination memory buffer. This field may be modified by the driver.
enum dev_dma_inc_e inc:2;This specifies the memory destination address increment in word unit
uint16_t _unused:2;
uint16_t stride:12;This specifies the number of units to add to the destination address pointer when looping.
} mem;
struct <anonymous> {
uintptr_t addr;This specifies the address of the device register to write to.
uint16_t _unused:4;
uint16_t burst:12;This specifies the number of units that is transfered at once to the device. Value 0 means that all units can be transfered at once
} reg;
} dst;

enum dev_dma_inc_e [link] 

This enum is declared in device/class/dma.h source file, line 129.

IdentifierDescription
DEV_DMA_INC_0_UNIT
DEV_DMA_INC_1_UNITS
DEV_DMA_INC_2_UNITS
DEV_DMA_INC_4_UNITS

typedef void * dev_dma_queue_entry_t [link] 

This typedef is declared in device/class/dma.h source file, line 294.

typedef struct dev_dma_rq_s * dev_dma_queue_item_t [link] 

This typedef is declared in device/class/dma.h source file, line 294.

typedef void * dev_dma_queue_root_t [link] 

This typedef is declared in device/class/dma.h source file, line 294.

struct dev_dma_rq_s [link] 

This struct is declared in device/class/dma.h source file, line 238.

This struct is the DMA operation object. The array of DMA transfer descriptors declared in this structure has null size. The DEV_DMA_RQ_TYPE macro must be used instead to declare a DMA operation embedding some transfer descriptors.

FieldDescription
enum dev_dma_rq_type_e type:5;Type of DMA operation requested
uint8_t drv_pv:5;Reserved for use by the driver of the DMA controller
uint8_t desc_count_m1:6;Number of descriptors embedded at the end of the object minus one
uint16_t loop_count_m1;Number of iterations over the list of descriptors when not in continuous mode minus one.
uint32_t chan_mask;Mask of channels the operation is allowed to execute on. This is used for channel allocation. It should be specified in resources of the device relying on the DMA.
struct <anonymous> {This identifies a link between the device and the DMA controller. The exact meaning is hardware dependent.
uint16_t src;
uint16_t dst;
} dev_link;
dev_dma_callback_t * f_done;Completion callback.
union <anonymous> {
struct <anonymous> {
uint32_t size;Accumulated number of unit transferred by DMA. For continous operation, it contains number of transferred units since last dma callback
uint32_t desc_idx;Index of last descriptor processed by DMA.
} cancel;
};
void * cache_ptr;This may be used by the driver in order to reuse some internal data structure associated to a repeated request. It must be set to NULL before submitting a new request. It should be left untouched when the same request is submitted again. Only the mem.addr, mem.size and mem.stride fields of the request descriptor are allowed to change between submissions when not reset to NULL.
struct dev_dma_desc_s desc[0];Array of transfer descriptors. The driver is allowed to modify the src.mem.addr and dst.mem.addr fields during execution of the request.

See also dev_dma_queue_item_t.

enum dev_dma_rq_type_e [link] 

This enum is declared in device/class/dma.h source file, line 83.

This enum specifies the type of dma operation.

See also struct dev_dma_rq_s.

IdentifierDescription
DEV_DMA_MEM_MEMThis enum_value type of request performs some memory to memory transfers. All fields of the descriptors in src.mem and dst.mem must be initialized. The request terminates and the callback is invoked when the last descriptor is reached and the loop counter reaches 0.
DEV_DMA_MEM_REGThis enum_value type of request performs some memory to device register transfers. Fields of the descriptors in src.mem and dst.reg must be initialized. The request terminates and the callback is invoked when the last descriptor is reached and the loop counter reaches 0.
DEV_DMA_MEM_REG_CONTThis enum_value type of request performs an indefinite number of memory to device register transfers. All fields of the descriptors in src.mem and dst.reg must be initialized. The callback is invoked after each transfer. The request terminates when the callback returns 0.
DEV_DMA_REG_MEMThis enum_value type of request performs some device register to memory transfers. Fields of the descriptors in src.reg and dst.mem must be initialized. The request terminates and the callback is invoked when the last descriptor is reached and the loop counter reaches 0.
DEV_DMA_REG_MEM_CONTThis enum_value type of request performs an indefinite number of device register to memory transfers. All fields of the descriptors in src.reg and dst.mem must be initialized. The callback is invoked after each transfer. The request terminates when the callback returns 0.
DEV_DMA_REG_REGThis enum_value type of request performs some device register to device register transfers. Fields of the descriptors in src.reg and dst.reg must be initialized. The request terminates and the callback is invoked when the last descriptor is reached and the loop counter reaches 0.
DEV_DMA_REG_REG_CONTThis enum_value type of request performs an indefinite number of device register to device register transfers. All fields of the descriptors in src.reg and dst.mem must be initialized. The callback is invoked after each transfer. The request terminates when the callback returns 0.

struct dev_dma_status_s [link] 

This struct is declared in device/class/dma.h source file, line 363.

typedef error_t (devdma_cancel_t)(struct device_dma_s *accessor, struct dev_dma_rq_s *rq) [link] 

This typedef is declared in device/class/dma.h source file, line 360.

This typedef cancel a dma request.

The function returns 0 if the request has been cancelled or -EBUSY if the request has already ended or will terminate very soon. It may also return -ENOTSUP. The DMA callback is not executed when this function returns 0.

In case of success the cancel structure field of the request contains information about cancelled request

This declaration involves expansion of the DEV_DMA_CANCEL macro.

typedef error_t (devdma_get_status_t)(struct device_dma_s *accessor, struct dev_dma_rq_s *rq, struct dev_dma_status_s *status) [link] 

This typedef is declared in device/class/dma.h source file, line 380.

This typedef get status of a dma request.

In case of success the cancel structure field of the request contains information about cancelled request

This declaration involves expansion of the DEV_DMA_GET_STATUS macro.

typedef error_t (devdma_request_t)(const struct device_dma_s *accessor, ...) [link] 

This typedef is declared in device/class/dma.h source file, line 342.

Dma device class request() function type.

This typedef enqueues one or more struct dev_dma_rq_s objects. The argument list of pointers to request must be NULL terminated.

When multiple requests are passed on the same calls, they are guaranteed to be started in order. This means that a request sending data to a device might be postponed until an other request is ready to sink data from the device.

The dev_dma_rq_s::cache_ptr field of the request must be set to NULL unless the same request has been pushed previously.

Execution of the request consists in performing multiple transfers specified in the embedded descriptors. The type of request specifies the exact behavior. The src.mem.addr and dst.mem.addr fields of request descriptors are left undefined when the request terminates. Other fields of the descriptors are not modified.

A request will not start until one of the channel specified in chan_mask becomes idle. It returns -ENOENT if the channel mask does not have at least one bit set for an implemented channel.

The function returns -ENOTSUP when the requested type of operation is not supported.

If a descriptor related issue is detected (unsupported alignment, non mapped address...), the error is reported to the callback function instead.

This declaration involves expansion of the DEVDMA_REQUEST macro.

struct device_dma_s [link] 

This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 20 in device/class/dma.h source file, line 386.

This struct is the device accessor object type for the dma device class. This accessor must be initialized by calling the device_get_accessor function.

See also DRIVER_CLASS_DMA, struct device_accessor_s and Device accessor.

FieldDescription
union <anonymous> {
struct device_accessor_s base;
struct <anonymous> {
struct device_s * dev;
struct driver_dma_s * api;
uint_fast8_t number;
};
};

struct device_accessor_s * device_dma_s_base(struct device_dma_s *x) [link] 

This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 41 in device/class/dma.h source file, line 386.

This function casts a dma device accessor to a generic device accessor

struct device_dma_s * device_dma_s_cast(struct device_accessor_s *x) [link] 

This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 34 in device/class/dma.h source file, line 386.

This function casts a generic device accessor to a dma device accessor

error_t device_res_get_dma(const struct device_s *dev, uint_fast16_t id, uint32_t *channel_mask, uint32_t *link) [link] 

This function is declared in device/class/dma.h source file, line 441.

This is available when CONFIG_DEVICE_DMA is defined.

struct driver_dma_s [link] 

This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 5 in device/class/dma.h source file, line 386.

This struct is the driver API descriptor for the dma device class.

See also DRIVER_CLASS_DMA and struct driver_class_s.

#define _DEV_DMA_CONTINUOUS [link] 

This macro is declared in device/class/dma.h source file, line 77.

loop an indefinite number of times over descriptors

This macro is for internal use only.

#define _DEV_DMA_DST_MEM [link] 

This macro is declared in device/class/dma.h source file, line 75.

destination is a memory buffer

This macro is for internal use only.

#define _DEV_DMA_DST_REG [link] 

This macro is declared in device/class/dma.h source file, line 73.

destination is a device register

This macro is for internal use only.

#define _DEV_DMA_SRC_MEM [link] 

This macro is declared in device/class/dma.h source file, line 71.

source is a memory buffer

This macro is for internal use only.

#define _DEV_DMA_SRC_REG [link] 

This macro is declared in device/class/dma.h source file, line 69.

source is a device register

This macro is for internal use only.

Valid XHTML 1.0 StrictGenerated by diaxen on Thu Aug 4 15:44:05 2022 using MkDoc