dma.h File Reference

DMA mappings. More...

#include <stdint.h>
#include <ipxe/api.h>
#include <ipxe/io.h>
#include <ipxe/malloc.h>
#include <ipxe/umalloc.h>
#include <config/ioapi.h>

Go to the source code of this file.

Data Structures
struct	dma_mapping
	A DMA mapping. More...
struct	dma_device
	A DMA-capable device. More...
struct	dma_operations
	DMA operations. More...

Macros
#define	DMAAPI_PREFIX_op   __op_
#define	DMAAPI_PREFIX_flat   __flat_
#define	DMA_TX   0x01
	Device will read data from host memory. More...
#define	DMA_RX   0x02
	Device will write data to host memory. More...
#define	DMA_BI   ( DMA_TX | DMA_RX )
	Device will both read data from and write data to host memory. More...
#define	DMAAPI_INLINE(_subsys, _api_func)   SINGLE_API_INLINE ( DMAAPI_PREFIX_ ## _subsys, _api_func )
	Calculate static inline DMA I/O API function name. More...
#define	PROVIDE_DMAAPI(_subsys, _api_func, _func)   PROVIDE_SINGLE_API ( DMAAPI_PREFIX_ ## _subsys, _api_func, _func )
	Provide a DMA I/O API implementation. More...
#define	PROVIDE_DMAAPI_INLINE(_subsys, _api_func)   PROVIDE_SINGLE_API_INLINE ( DMAAPI_PREFIX_ ## _subsys, _api_func )
	Provide a static inline DMA I/O API implementation. More...

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
static __always_inline int	DMAAPI_INLINE (flat, dma_map)(struct dma_device *dma
	Map buffer for DMA. More...
static __always_inline void	DMAAPI_INLINE (flat, dma_unmap)(struct dma_mapping *map)
	Unmap buffer. More...
static __always_inline void *	DMAAPI_INLINE (flat, dma_alloc)(struct dma_device *dma
	Allocate and map DMA-coherent buffer. More...
	if (DBG_LOG &&addr)
static __always_inline void	DMAAPI_INLINE (flat, dma_free)(struct dma_mapping *map
	Unmap and free DMA-coherent buffer. More...
	if (DBG_LOG)
static __always_inline userptr_t	DMAAPI_INLINE (flat, dma_umalloc)(struct dma_device *dma
	Allocate and map DMA-coherent buffer from external (user) memory. More...
static __always_inline void	DMAAPI_INLINE (flat, dma_ufree)(struct dma_mapping *map
	Unmap and free DMA-coherent buffer from external (user) memory. More...
static __always_inline void	DMAAPI_INLINE (flat, dma_set_mask)(struct dma_device *dma __unused
	Set addressable space mask. More...
void	dma_unmap (struct dma_mapping *map)
	Unmap buffer. More...
void *	dma_alloc (struct dma_device *dma, struct dma_mapping *map, size_t len, size_t align)
	Allocate and map DMA-coherent buffer. More...
void	dma_free (struct dma_mapping *map, void *addr, size_t len)
	Unmap and free DMA-coherent buffer. More...
userptr_t	dma_umalloc (struct dma_device *dma, struct dma_mapping *map, size_t len, size_t align)
	Allocate and map DMA-coherent buffer from external (user) memory. More...
void	dma_ufree (struct dma_mapping *map, userptr_t addr, size_t len)
	Unmap and free DMA-coherent buffer from external (user) memory. More...
void	dma_set_mask (struct dma_device *dma, physaddr_t mask)
	Set addressable space mask. More...
physaddr_t	dma_phys (struct dma_mapping *map, physaddr_t addr)
	Get DMA address from physical address. More...
static __always_inline physaddr_t	dma (struct dma_mapping *map, void *addr)
	Get DMA address from virtual address. More...
static __always_inline int	dma_mapped (struct dma_mapping *map)
	Check if DMA unmapping is required. More...
static __always_inline void	dma_init (struct dma_device *dma, struct dma_operations *op)
	Initialise DMA device. More...
static __always_inline void	dma_set_mask_64bit (struct dma_device *dma)
	Set 64-bit addressable space mask. More...

Variables
static __always_inline int struct dma_mapping *	map
static __always_inline int struct dma_mapping physaddr_t addr	__unused
static __always_inline void struct dma_mapping size_t	len
static __always_inline void struct dma_mapping size_t size_t	align
	addr = malloc_phys ( len, align )

Detailed Description

DMA mappings.

Definition in file dma.h.

Macro Definition Documentation

DMAAPI_PREFIX_op

#define DMAAPI_PREFIX_op   __op_

Definition at line 22 of file dma.h.

DMAAPI_PREFIX_flat

#define DMAAPI_PREFIX_flat   __flat_

Definition at line 28 of file dma.h.

DMA_TX

#define DMA_TX   0x01

Device will read data from host memory.

Definition at line 132 of file dma.h.

DMA_RX

#define DMA_RX   0x02

Device will write data to host memory.

Definition at line 135 of file dma.h.

DMA_BI

#define DMA_BI   ( DMA_TX | DMA_RX )

Device will both read data from and write data to host memory.

Definition at line 138 of file dma.h.

DMAAPI_INLINE

#define DMAAPI_INLINE	(		_subsys,
			_api_func
	)		SINGLE_API_INLINE ( DMAAPI_PREFIX_ ## _subsys, _api_func )

Calculate static inline DMA I/O API function name.

Parameters

_prefix	Subsystem prefix
_api_func	API function

Return values

_subsys_func

Subsystem API function

Definition at line 147 of file dma.h.

PROVIDE_DMAAPI

#define PROVIDE_DMAAPI	(		_subsys,
			_api_func,
			_func
	)		PROVIDE_SINGLE_API ( DMAAPI_PREFIX_ ## _subsys, _api_func, _func )

Provide a DMA I/O API implementation.

Parameters

_prefix	Subsystem prefix
_api_func	API function
_func	Implementing function

Definition at line 157 of file dma.h.

PROVIDE_DMAAPI_INLINE

#define PROVIDE_DMAAPI_INLINE	(		_subsys,
			_api_func
	)		PROVIDE_SINGLE_API_INLINE ( DMAAPI_PREFIX_ ## _subsys, _api_func )

Provide a static inline DMA I/O API implementation.

Parameters

_prefix	Subsystem prefix
_api_func	API function

Definition at line 166 of file dma.h.

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

DMAAPI_INLINE() [1/7]

static __always_inline int DMAAPI_INLINE ( flat  , dma_map    )

inlinestatic

Map buffer for DMA.

Parameters

dma	DMA device
map	DMA mapping to fill in
addr	Buffer address
len	Length of buffer
flags	Mapping flags

Return values

rc	Return status code

DMAAPI_INLINE() [2/7]

static __always_inline void DMAAPI_INLINE ( flat  , dma_unmap    )

inlinestatic

Unmap buffer.

Parameters

map	DMA mapping

Definition at line 200 of file dma.h.

                                                              {

        /* Decrement mapping count (for debugging) */
        if ( DBG_LOG ) {
                assert ( map->dma != NULL );
                map->dma->mapped--;
                map->dma = NULL;
        }
}

References assert(), DBG_LOG, dma_mapping::dma, map, dma_device::mapped, and NULL.

DMAAPI_INLINE() [3/7]

static __always_inline void* DMAAPI_INLINE ( flat  , dma_alloc    )

inlinestatic

Allocate and map DMA-coherent buffer.

Parameters

dma	DMA device
map	DMA mapping to fill in
len	Length of buffer
align	Physical alignment

Return values

addr	Buffer address, or NULL on error

if() [1/2]

if

(

DBG_LOG &&

addr

)

Definition at line 229 of file dma.h.

                               {
                map->dma = dma;
                dma->mapped++;
        }

References dma_mapping::dma, dma(), and map.

DMAAPI_INLINE() [4/7]

static __always_inline void DMAAPI_INLINE ( flat  , dma_free    )

inlinestatic

Unmap and free DMA-coherent buffer.

Parameters

map	DMA mapping
addr	Buffer address
len	Length of buffer

if() [2/2]

if

(

DBG_LOG

)

Definition at line 252 of file dma.h.

                       {
                assert ( map->dma != NULL );
                map->dma->mapped--;
                map->dma = NULL;
        }

References assert(), dma_mapping::dma, map, dma_device::mapped, and NULL.

DMAAPI_INLINE() [5/7]

static __always_inline userptr_t DMAAPI_INLINE ( flat  , dma_umalloc    )

inlinestatic

Allocate and map DMA-coherent buffer from external (user) memory.

Parameters

dma	DMA device
map	DMA mapping to fill in
len	Length of buffer
align	Physical alignment

Return values

addr	Buffer address, or NULL on error

DMAAPI_INLINE() [6/7]

static __always_inline void DMAAPI_INLINE ( flat  , dma_ufree    )

inlinestatic

Unmap and free DMA-coherent buffer from external (user) memory.

Parameters

map	DMA mapping
addr	Buffer address
len	Length of buffer

DMAAPI_INLINE() [7/7]

static __always_inline void DMAAPI_INLINE ( flat  , dma_set_mask    )

inlinestatic

Set addressable space mask.

Parameters

dma	DMA device
mask	Addressable space mask

dma_unmap()

void dma_unmap

(

struct dma_mapping *

map

)

Unmap buffer.

Parameters

map	DMA mapping

Referenced by intelxl_msix_disable(), intelxl_msix_enable(), and iob_unmap().

dma_alloc()

void* dma_alloc	(	struct dma_device *	dma,
		struct dma_mapping *	map,
		size_t	len,
		size_t	align
	)

Allocate and map DMA-coherent buffer.

Parameters

dma	DMA device
map	DMA mapping to fill in
len	Length of buffer
align	Physical alignment

Return values

addr	Buffer address, or NULL on error

Referenced by atl_ring_alloc(), gve_admin_alloc(), gve_alloc_queue(), intel_create_ring(), intelxl_alloc_admin(), intelxl_alloc_ring(), rdc_create_ring(), realtek_create_buffer(), realtek_create_ring(), vp_alloc_vq(), xhci_context(), xhci_dcbaa_alloc(), xhci_device_open(), xhci_event_alloc(), xhci_ring_alloc(), and xhci_scratchpad_alloc().

dma_free()

void dma_free	(	struct dma_mapping *	map,
		void *	addr,
		size_t	len
	)

Unmap and free DMA-coherent buffer.

Parameters

map	DMA mapping
addr	Buffer address
len	Length of buffer

Referenced by atl_ring_free(), gve_admin_alloc(), gve_admin_free(), gve_alloc_queue(), gve_free_queue(), intel_destroy_ring(), intelxl_alloc_ring(), intelxl_free_admin(), intelxl_free_ring(), rdc_destroy_ring(), realtek_destroy_buffer(), realtek_destroy_ring(), vp_free_vq(), xhci_context(), xhci_dcbaa_alloc(), xhci_dcbaa_free(), xhci_device_close(), xhci_device_open(), xhci_event_alloc(), xhci_event_free(), xhci_ring_alloc(), xhci_ring_free(), xhci_scratchpad_alloc(), and xhci_scratchpad_free().

dma_umalloc()

userptr_t dma_umalloc	(	struct dma_device *	dma,
		struct dma_mapping *	map,
		size_t	len,
		size_t	align
	)

Allocate and map DMA-coherent buffer from external (user) memory.

Parameters

dma	DMA device
map	DMA mapping to fill in
len	Length of buffer
align	Physical alignment

Return values

addr	Buffer address, or NULL on error

Referenced by gve_alloc_qpl(), gve_alloc_queue(), and xhci_scratchpad_alloc().

dma_ufree()

void dma_ufree	(	struct dma_mapping *	map,
		userptr_t	addr,
		size_t	len
	)

Unmap and free DMA-coherent buffer from external (user) memory.

Parameters

map	DMA mapping
addr	Buffer address
len	Length of buffer

Referenced by gve_alloc_queue(), gve_free_qpl(), gve_free_queue(), xhci_scratchpad_alloc(), and xhci_scratchpad_free().

dma_set_mask()

void dma_set_mask	(	struct dma_device *	dma,
		physaddr_t	mask
	)

Set addressable space mask.

Parameters

dma	DMA device
mask	Addressable space mask

Referenced by dma_set_mask_64bit().

dma_phys()

physaddr_t dma_phys	(	struct dma_mapping *	map,
		physaddr_t	addr
	)

Get DMA address from physical address.

Parameters

map	DMA mapping
addr	Physical address within the mapped region

Return values

addr	Device-side DMA address

Referenced by dma(), gve_create_rx_param(), gve_create_tx_param(), gve_register(), and xhci_scratchpad_alloc().

dma()

static __always_inline physaddr_t dma ( struct dma_mapping *  map, void *  addr  )

inlinestatic

Get DMA address from virtual address.

Parameters

map	DMA mapping
addr	Virtual address within the mapped region

Return values

addr	Device-side DMA address

Definition at line 436 of file dma.h.

                                                            {

        /* Get DMA address from corresponding physical address */
        return dma_phys ( map, virt_to_phys ( addr ) );
}

References addr, dma_phys(), map, and virt_to_phys().

Referenced by alloc_rx_iob(), atl_ring_alloc(), dma_init(), dma_op_alloc(), dma_op_free(), dma_op_map(), dma_op_set_mask(), dma_op_ufree(), dma_op_umalloc(), dma_op_unmap(), dma_set_mask_64bit(), efipci_dma_alloc(), efipci_dma_free(), efipci_dma_map(), efipci_dma_set_mask(), efipci_dma_ufree(), efipci_dma_umalloc(), efipci_dma_unmap(), gve_admin_alloc(), gve_admin_enable(), gve_alloc_queue(), gve_configure(), gve_create_rx_param(), gve_create_tx_param(), gve_describe(), gve_register(), ice_admin_add_txq(), if(), intel_create_ring(), intelxl_admin_command(), intelxl_admin_event_init(), intelxl_create_ring(), intelxl_enable_admin(), intelxl_msix_enable(), intelxlvf_admin_configure(), iob_dma(), iob_map(), iob_map_rx(), iob_map_tx(), myri10ge_net_poll(), rdc_create_ring(), realtek_create_buffer(), realtek_create_ring(), virtnet_enqueue_iob(), vp_find_vq(), vpm_find_vqs(), xhci_abort(), xhci_address_device_input(), xhci_command_alloc(), xhci_configure_endpoint_input(), xhci_context(), xhci_dcbaa_alloc(), xhci_device_open(), xhci_event_alloc(), xhci_event_poll(), xhci_ring_alloc(), xhci_scratchpad_alloc(), and xhci_set_tr_dequeue_pointer().

dma_mapped()

static __always_inline int dma_mapped ( struct dma_mapping *  map )

inlinestatic

Check if DMA unmapping is required.

Parameters

map	DMA mapping
unmap	Unmapping is required

Definition at line 449 of file dma.h.

                                                                         {

        /* Unmapping is required if a DMA device was recorded */
        return ( map->dma != NULL );
}

References dma_mapping::dma, map, and NULL.

Referenced by free_iob(), net_discard(), netdev_rx(), netdev_rx_err(), netdev_tx(), and netdev_tx_err().

dma_init()

static __always_inline void dma_init ( struct dma_device *  dma, struct dma_operations *  op  )

inlinestatic

Initialise DMA device.

Parameters

dma	DMA device
op	DMA operations

Definition at line 461 of file dma.h.

                                                                          {

        /* Set operations table */
        dma->op = op;
}

References dma(), and op.

Referenced by efipci_open().

dma_set_mask_64bit()

static __always_inline void dma_set_mask_64bit ( struct dma_device *  dma )

inlinestatic

Set 64-bit addressable space mask.

Parameters

dma	DMA device

Definition at line 474 of file dma.h.

                                              {

        /* Set mask to maximum physical address */
        dma_set_mask ( dma, ~( ( physaddr_t ) 0 ) );
}

References dma(), and dma_set_mask().

Referenced by gve_probe(), ice_probe(), intel_probe(), intelx_probe(), intelxl_probe(), intelxlvf_probe(), intelxvf_probe(), realtek_detect(), virtnet_probe_legacy(), virtnet_probe_modern(), and xhci_probe().

Variable Documentation

map

static __always_inline userptr_t struct dma_mapping * map

Definition at line 181 of file dma.h.

Referenced by arbel_cmd_map_fa(), arbel_cmd_map_icm(), arbel_cmd_map_icm_aux(), arbel_map_vpm(), dma(), dma_mapped(), dma_op_alloc(), dma_op_free(), dma_op_map(), dma_op_ufree(), dma_op_umalloc(), dma_op_unmap(), DMAAPI_INLINE(), efi_shim_get_memory_map(), efifb_colour_map(), efifb_select_mode(), efipci_dma_alloc(), efipci_dma_free(), efipci_dma_map(), efipci_dma_ufree(), efipci_dma_umalloc(), efipci_dma_unmap(), fbcon_colour(), fbcon_init(), hermon_cmd_map_fa(), hermon_cmd_map_icm(), hermon_cmd_map_icm_aux(), hermon_map_vpm(), if(), nii_map(), nii_pci_close(), nii_unmap(), nodnic_port_allocate_dbr_dma(), rsn_get_desc(), rsn_pick_desc(), sec80211_detect_ie(), sec80211_rsn_get_net80211_crypt(), skge_rx_setup(), skge_xmit_frame(), sky2_rx_add(), and xhci_context().

__unused

__always_inline void physaddr_t mask __unused

Initial value:

{

        
        if ( DBG_LOG ) {
                map->dma = dma;
                dma->mapped++;
        }

        return 0

Definition at line 181 of file dma.h.

len

__always_inline userptr_t struct dma_mapping size_t len

Initial value:

{

        
        free_phys ( addr, len )

Definition at line 221 of file dma.h.

align

__always_inline void struct dma_mapping size_t size_t align

Initial value:

{
        void *addr

Definition at line 222 of file dma.h.

Referenced by alloc_iob_fail_okx(), alloc_iob_okx(), alloc_iob_raw(), alloc_memblock(), dma_op_alloc(), dma_op_umalloc(), efipci_dma_umalloc(), ehci_align(), memtop_urealloc(), mlx_memory_alloc_dma(), mlx_memory_alloc_dma_priv(), virtio_pci_map_capability(), and xhci_align().

addr

__always_inline void userptr_t addr = malloc_phys ( len, align )

Definition at line 226 of file dma.h.

Referenced by dma().