A memory descriptor. More...

#include <dnnl.hpp>

Collaboration diagram for dnnl::memory::desc:

[legend]

Public Member Functions
	desc ()
	Constructs a zero (empty) memory descriptor. More...

	desc (const memory::dims &dims, data_type data_type, format_tag format_tag, bool allow_empty=false)
	Constructs a memory descriptor. More...

	desc (const memory::dims &dims, data_type data_type, const memory::dims &strides, bool allow_empty=false)
	Constructs a memory descriptor by strides. More...

	desc (const dnnl_memory_desc_t &data)
	Constructs a memory descriptor from a C API data structure. More...

desc	submemory_desc (const memory::dims &dims, const memory::dims &offsets, bool allow_empty=false) const
	Constructs a memory descriptor for a region inside an area described by this memory descriptor. More...

desc	reshape (const memory::dims &dims, bool allow_empty=false) const
	Constructs a memory descriptor by reshaping an existing one. More...

desc	permute_axes (const std::vector< int > &permutation, bool allow_empty=false) const
	Constructs a memory descriptor by permuting axes in an existing one. More...

memory::dims	dims () const
	Returns dimensions of the memory descriptor. More...

memory::data_type	data_type () const
	Returns the data type of the memory descriptor. More...

size_t	get_size () const
	Returns size of the memory descriptor in bytes. More...

bool	is_zero () const
	Checks whether the memory descriptor is zero (empty). More...

bool	operator== (const desc &other) const
	An equality operator. More...

bool	operator!= (const desc &other) const
	An inequality operator. More...

Public Attributes
dnnl_memory_desc_t	data
	The underlying C API data structure.

Detailed Description

A memory descriptor.

Examples:: cnn_inference_f32.cpp, cnn_inference_int8.cpp, cnn_training_f32.cpp, cpu_cnn_training_bf16.cpp, cpu_matmul_quantization.cpp, cpu_rnn_inference_f32.cpp, cpu_rnn_inference_int8.cpp, cpu_sgemm_and_matmul.cpp, getting_started.cpp, gpu_opencl_interop.cpp, inference_int8_matmul.cpp, memory_format_propagation.cpp, performance_profiling.cpp, and rnn_training_f32.cpp.

Constructor & Destructor Documentation

◆ desc() [1/4]

dnnl::memory::desc::desc ( )

inline

Constructs a zero (empty) memory descriptor.

Such a memory descriptor can be used to indicate absence of an argument.

◆ desc() [2/4]

dnnl::memory::desc::desc	(	const memory::dims &	dims,
		data_type	data_type,
		format_tag	format_tag,
		bool	allow_empty = `false`
	)

inline

Constructs a memory descriptor.

Note: The logical order of dimensions corresponds to the abc... format tag, and the interpretation of the dimensions depends on the primitive that consumes the memory.

Parameters

dims	Tensor dimensions.
data_type	Data precision/type.
format_tag	Memory format tag.
allow_empty	A flag signifying whether construction is allowed to fail without throwing an exception. In this case a zero memory descriptor will be constructed. This flag is optional and defaults to false.

◆ desc() [3/4]

dnnl::memory::desc::desc	(	const memory::dims &	dims,
		data_type	data_type,
		const memory::dims &	strides,
		bool	allow_empty = `false`
	)

inline

Constructs a memory descriptor by strides.

Note: The logical order of dimensions corresponds to the abc... format tag, and the interpretation of the dimensions depends on the primitive that consumes the memory.

Parameters

dims	Tensor dimensions.
data_type	Data precision/type.
strides	Strides for each dimension.
allow_empty	A flag signifying whether construction is allowed to fail without throwing an exception. In this case a zero memory descriptor will be constructed. This flag is optional and defaults to false.

◆ desc() [4/4]

dnnl::memory::desc::desc ( const dnnl_memory_desc_t & data )

inline

Constructs a memory descriptor from a C API data structure.

Parameters

data	A C API dnnl_memory_desc_t structure.

Member Function Documentation

◆ submemory_desc()

desc dnnl::memory::desc::submemory_desc	(	const memory::dims &	dims,
		const memory::dims &	offsets,
		bool	allow_empty = `false`
	)		const

inline

Constructs a memory descriptor for a region inside an area described by this memory descriptor.

Parameters

dims	Sizes of the region.
offsets	Offsets to the region from the encompassing memory object in each dimension.
allow_empty	A flag signifying whether construction is allowed to fail without throwing an exception. In this case a zero memory descriptor will be returned. This flag is optional and defaults to false.

Returns: A memory descriptor for the region.

Examples:: cpu_rnn_inference_f32.cpp, cpu_rnn_inference_int8.cpp, and rnn_training_f32.cpp.

◆ reshape()

desc dnnl::memory::desc::reshape	(	const memory::dims &	dims,
		bool	allow_empty = `false`
	)		const

inline

Constructs a memory descriptor by reshaping an existing one.

The new memory descriptor inherits the data type. This operation is valid only for memory descriptors that have format_kind set to dnnl::memory::format_kind::blocked or dnnl::memory::format_kind::any.

The operation ensures that the transformation of the physical memory format corresponds to the transformation of the logical dimensions. If such transformation is impossible, the function either throws an exception (default) or returns a zero memory descriptor depending on the allow_empty flag.

The reshape operation can be described as a combination of the following basic operations:

Add a dimension of size 1. This is always possible.
Remove a dimension of size 1. This is possible only if the dimension has no padding (i.e. padded_dims[dim] == dims[dim] && dims[dim] == 1).
Split a dimension into multiple ones. This is possible only if the size of the dimension is exactly equal to the product of the split ones and the dimension does not have padding (i.e. padded_dims[dim] = dims[dim]).
Joining multiple consecutive dimensions into a single one. As in the cases above, this requires that the dimensions do not have padding and that the memory format is such that in physical memory these dimensions are dense and have the same order as their logical counterparts. This also assumes that these dimensions are not blocked.
- Here, dense means: stride for dim[i] == (stride for dim[i + 1]) * dim[i + 1];
- And same order means: i < j <=> stride for dim[i] < stride for dim[j].

Warning: Some combinations of physical memory layout and/or offsets or dimensions may result in a failure to make a reshape.

Parameters

dims	New dimensions. The product of dimensions must remain constant.
allow_empty	A flag signifying whether construction is allowed to fail without throwing an exception. In this case a zero memory descriptor will be returned. This flag is optional and defaults to false.

Returns: A new memory descriptor with new dimensions.

◆ permute_axes()

desc dnnl::memory::desc::permute_axes	(	const std::vector< int > &	permutation,
		bool	allow_empty = `false`
	)		const

inline

Constructs a memory descriptor by permuting axes in an existing one.

The physical memory layout representation is adjusted accordingly to maintain the consistency between the logical and physical parts of the memory descriptor.

The new memory descriptor inherits the data type. This operation is valid only for memory descriptors that have format_kind set to dnnl::memory::format_kind::blocked or dnnl::memory::format_kind::any.

The logical axes will be permuted in the following manner:

for (i: 0 .. ndims())

new_desc.dims()[permutation[i]] = dims()[i];

Example:

std::vector<int> permutation = {1, 0}; // swap the first and
                                       // the second axes
dnnl::memory::desc in_md(
        {2, 3}, data_type, memory::format_tag::ab);
dnnl::memory::desc expect_out_md(
        {3, 2}, data_type, memory::format_tag::ba);
assert(in_md.permute_axes(permutation) == expect_out_md);

Parameters

permutation	Axes permutation.
allow_empty	A flag signifying whether construction is allowed to fail without throwing an exception. In this case a zero memory descriptor will be returned. This flag is optional and defaults to false.

Returns: A new memory descriptor with new dimensions.

◆ dims()

memory::dims dnnl::memory::desc::dims ( ) const

inline

Returns dimensions of the memory descriptor.

Potentially expensive due to the data copy involved.

Returns: A copy of the dimensions vector.

Examples:: inference_int8_matmul.cpp.

◆ data_type()

memory::data_type dnnl::memory::desc::data_type ( ) const

inline

Returns the data type of the memory descriptor.

Returns: The data type.

◆ get_size()

size_t dnnl::memory::desc::get_size ( ) const

inline

Returns size of the memory descriptor in bytes.

Returns: The number of bytes required to allocate a memory buffer for the memory object described by this memory descriptor including the padding area.

Examples:: cpu_rnn_inference_f32.cpp, cpu_rnn_inference_int8.cpp, and performance_profiling.cpp.

◆ is_zero()

bool dnnl::memory::desc::is_zero ( ) const

inline

Checks whether the memory descriptor is zero (empty).

Returns: true if the memory descriptor describes an empty memory and false otherwise.

◆ operator==()

bool dnnl::memory::desc::operator== ( const desc & other ) const

inline

An equality operator.

Parameters

other Another memory descriptor.

Returns: Whether this and the other memory descriptors have the same format tag, dimensions, strides, blocking, etc.

◆ operator!=()

bool dnnl::memory::desc::operator!= ( const desc & other ) const

inline

An inequality operator.

Parameters

other Another memory descriptor.

Returns: Whether this and the other memory descriptors describe different memory.

The documentation for this struct was generated from the following file:

include/dnnl.hpp

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ desc() [1/4]

◆ desc() [2/4]

◆ desc() [3/4]

◆ desc() [4/4]

Member Function Documentation

◆ submemory_desc()

◆ reshape()

◆ permute_axes()

◆ dims()

◆ data_type()

◆ get_size()

◆ is_zero()

◆ operator==()

◆ operator!=()