Memory

A primitive to describe and store data. More...

Functions
mkldnn_status_t MKLDNN_API	mkldnn_memory_desc_init (mkldnn_memory_desc_t *memory_desc, int ndims, const mkldnn_dims_t dims, mkldnn_data_type_t data_type, mkldnn_memory_format_t format)
	Initializes a memory_desc memory descriptor using ndims, dims, data_type, and data format. More...
mkldnn_status_t MKLDNN_API	mkldnn_memory_primitive_desc_create (mkldnn_primitive_desc_t *memory_primitive_desc, const mkldnn_memory_desc_t *memory_desc, mkldnn_engine_t engine)
	Creates a memory_primitive_desc memory primitive descriptor using memory_desc and engine. More...
mkldnn_status_t MKLDNN_API	mkldnn_view_primitive_desc_create (mkldnn_primitive_desc_t *view_primitive_desc, const_mkldnn_primitive_desc_t memory_primitive_desc, const mkldnn_dims_t dims, const mkldnn_dims_t offsets)
	Creates a view_primitive_desc for a given memory_primitive_desc, with dims sizes and offsets offsets. More...
int MKLDNN_API	mkldnn_memory_primitive_desc_equal (const_mkldnn_primitive_desc_t lhs, const_mkldnn_primitive_desc_t rhs)
	Compares two descriptors of memory primitives. More...
size_t MKLDNN_API	mkldnn_memory_primitive_desc_get_size (const_mkldnn_primitive_desc_t memory_primitive_desc)
	Returns the size (in bytes) that is required for given memory_primitive_desc. More...
mkldnn_status_t MKLDNN_API	mkldnn_memory_get_data_handle (const_mkldnn_primitive_t memory, void **handle)
	For a memory primitive, returns the data handle. More...
mkldnn_status_t MKLDNN_API	mkldnn_memory_set_data_handle (mkldnn_primitive_t memory, void *handle)
	For a memory primitive, sets the data handle. More...

Detailed Description

A primitive to describe and store data.

The library supports various data types and formats. Memory hierarchy consists of three levels of abstraction:

1. Memory descriptor – engine agnostic logical description of data (number of dimensions, dimensions themselves, and data type), and optionally the format/layout that describes the physical representation of data in memory. If the format is not known yet, one can pass mkldnn_any. This approach is used to allow compute-intensive primitives to specify the most appropriate format on their own with users required to reorder the data if the incoming format doesn't match the primitive's selection. Memory descriptor can be created with the mkldnn_memory_desc_init() function or by directly filling the mkldnn_memory_desc_t structure. The latter requires deep knowledge of how the physical data representation is mapped to the structure. The Understanding Memory Formats topic should shed some light on that.
2. Memory primitive descriptor – logical description of data that is fully defined; that is, it cannot contain mkldnn_any as a format. It also has the engine specified. A memory primitive descriptor is created by calling mkldnn_memory_primitive_desc_create() with two arguments: an mkldnn_memory_desc_t and an mkldnn_engine_t. It has the same type as other primitive descriptors and can be:
   • queried to return the underlying memory descriptor using mkldnn_primitive_desc_query() and mkldnn_primitive_desc_query_memory_d().
   • compared with another memory primitive descriptor using mkldnn_memory_primitive_desc_equal(). This is especially useful when checking whether a primitive requires reorder from the user's data format to the primitive's format.
   • queried to return the size of the data using mkldnn_memory_primitive_desc_get_size(). As described in Understanding Memory Formats, the size of data sometimes cannot be computed as the product of dimensions times the size of the data type. So users are encouraged to use this function for better code portability.
3. Memory primitive or simply memory – a pseudo-primitive that is defined by a memory primitive descriptor and a handle to the data itself. (In the case of CPU engine, the handle is simply a pointer to void.) The data handle can be queried using mkldnn_memory_get_data_handle() and set using mkldnn_memory_set_data_handle(). The latter function always sets the memory in the padding region to zero, which is the invariant maintained by all the primitives in Intel MKL-DNN. See Understanding Memory Formats for more details. A memory primitive can be created using mkldnn_primitive_create() with empty inputs and outputs. In this case, the memory primitive's data handle must be set manually using mkldnn_memory_set_data_handle().

Along with ordinary memory with all dimensions being positive, Intel MKL-DNN supports zero-volume memory with one or more dimensions set to zero. This is to support the NumPy* convention. If a zero-volume memory is passed to a primitive, the primitive does not perform any computations on this memory. For example:

• Convolution with (0 batch, 3 input channels, 13 height, 13 width) source and (16 output channels, 3 inputs, channel, 3 height, 3 width) weights would produce (0 batch, 16 ouput channels, 11 height, 11 width) destination (assuming strides are 1 and paddings are zero) and perform zero multiply-add operations.
• Concatenation of three memories of shapes (3, 4, 13, 13), (3, 0, 13, 13), and (3, 1, 13, 13) along the second axis would produce the output of the shape (3, 5, 13, 13), effectively ignoring the second input (however, if the user created a concatenation primitive descriptor with three inputs they should also provide all three memories to the concatenation primitive, including the one with zero second dimension).
• However, Intel MKL-DNN would return an error when attempting to create a convolution with zero-volume memory passed for weights because such a convolution is not well-defined:

  dst(1, 16, 11, 11) <-- src(1, 0, 13, 13) (*) wei(16, 0, 3, 3)

  Should the values in the destination be zeroes or just not accessed at all? Moreover, backward pass w.r.t. weights in such cases is also not well-defined.

Data handle of zero-volume memory is never accessed and hence can be unset (NULL in case of CPU engine).

See also

Understanding Memory Formats

Function Documentation

mkldnn_memory_desc_init()

mkldnn_status_t MKLDNN_API mkldnn_memory_desc_init	(	mkldnn_memory_desc_t *	memory_desc,
		int	ndims,
		const mkldnn_dims_t	dims,
		mkldnn_data_type_t	data_type,
		mkldnn_memory_format_t	format
	)

Initializes a memory_desc memory descriptor using ndims, dims, data_type, and data format.

format can be mkldnn_any, which means that specific data layouts are not permitted.

mkldnn_memory_primitive_desc_create()

mkldnn_status_t MKLDNN_API mkldnn_memory_primitive_desc_create	(	mkldnn_primitive_desc_t *	memory_primitive_desc,
		const mkldnn_memory_desc_t *	memory_desc,
		mkldnn_engine_t	engine
	)

Creates a memory_primitive_desc memory primitive descriptor using memory_desc and engine.

memory_desc cannot be uncertain; that is, it cannot be initialized with mkldnn_any.

mkldnn_view_primitive_desc_create()

mkldnn_status_t MKLDNN_API mkldnn_view_primitive_desc_create	(	mkldnn_primitive_desc_t *	view_primitive_desc,
		const_mkldnn_primitive_desc_t	memory_primitive_desc,
		const mkldnn_dims_t	dims,
		const mkldnn_dims_t	offsets
	)

Creates a view_primitive_desc for a given memory_primitive_desc, with dims sizes and offsets offsets.

May fail if the format used does not allow obtaining the desired view. In this case, consider using the extract primitive.

mkldnn_memory_primitive_desc_equal()

int MKLDNN_API mkldnn_memory_primitive_desc_equal	(	const_mkldnn_primitive_desc_t	lhs,
		const_mkldnn_primitive_desc_t	rhs
	)

Compares two descriptors of memory primitives.

Returns

1 if the descriptors are the same.

0 if the descriptors are different.

Use this function to identify whether a reorder is required for the memory primitives. lhs and rhs must be either memory or view primitive descriptors.

mkldnn_memory_primitive_desc_get_size()

size_t MKLDNN_API mkldnn_memory_primitive_desc_get_size

(

const_mkldnn_primitive_desc_t

memory_primitive_desc

)

Returns the size (in bytes) that is required for given memory_primitive_desc.

mkldnn_memory_get_data_handle()

mkldnn_status_t MKLDNN_API mkldnn_memory_get_data_handle	(	const_mkldnn_primitive_t	memory,
		void **	handle
	)

For a memory primitive, returns the data handle.

For the CPU engine, the data handle is a pointer to the actual data.

mkldnn_memory_set_data_handle()

mkldnn_status_t MKLDNN_API mkldnn_memory_set_data_handle	(	mkldnn_primitive_t	memory,
		void *	handle
	)

For a memory primitive, sets the data handle.