Common¶
Overview¶
Common operations to create, destroy and inspect primitives. More…
// typedefs typedef struct dnnl_primitive_desc* dnnl_primitive_desc_t; typedef const struct dnnl_primitive_desc* const_dnnl_primitive_desc_t; typedef struct dnnl_primitive* dnnl_primitive_t; typedef const struct dnnl_primitive* const_dnnl_primitive_t; // enums enum dnnl_alg_kind_t; enum dnnl_normalization_flags_t; enum dnnl_primitive_kind_t; enum dnnl_prop_kind_t; enum dnnl_query_t; enum dnnl::normalization_flags; enum dnnl::query; // structs struct dnnl_exec_arg_t; struct dnnl_primitive; struct dnnl_primitive_desc; struct dnnl::primitive; struct dnnl::primitive_desc; struct dnnl::primitive_desc_base; // global functions dnnl_primitive_kind_t dnnl::convert_to_c(primitive::kind akind); dnnl_normalization_flags_t dnnl::convert_to_c(normalization_flags flags); dnnl_query_t dnnl::convert_to_c(query aquery); dnnl_status_t DNNL_API dnnl_primitive_desc_next_impl(dnnl_primitive_desc_t primitive_desc); dnnl_status_t DNNL_API dnnl_primitive_desc_clone( dnnl_primitive_desc_t* primitive_desc, const_dnnl_primitive_desc_t existing_primitive_desc ); dnnl_status_t DNNL_API dnnl_primitive_desc_get_attr( const_dnnl_primitive_desc_t primitive_desc, const_dnnl_primitive_attr_t* attr ); dnnl_status_t DNNL_API dnnl_primitive_desc_destroy(dnnl_primitive_desc_t primitive_desc); dnnl_status_t DNNL_API dnnl_primitive_desc_query( const_dnnl_primitive_desc_t primitive_desc, dnnl_query_t what, int index, void* result ); const_dnnl_memory_desc_t DNNL_API dnnl_primitive_desc_query_md( const_dnnl_primitive_desc_t primitive_desc, dnnl_query_t what, int index ); int DNNL_API dnnl_primitive_desc_query_s32( const_dnnl_primitive_desc_t primitive_desc, dnnl_query_t what, int index ); dnnl_status_t DNNL_API dnnl_primitive_create( dnnl_primitive_t* primitive, const_dnnl_primitive_desc_t primitive_desc ); dnnl_status_t DNNL_API dnnl_primitive_create_from_cache_blob( dnnl_primitive_t* primitive, const_dnnl_primitive_desc_t primitive_desc, size_t size, const uint8_t* cache_blob ); dnnl_status_t DNNL_API dnnl_primitive_execute( const_dnnl_primitive_t primitive, dnnl_stream_t stream, int nargs, const dnnl_exec_arg_t* args ); dnnl_status_t DNNL_API dnnl_primitive_get_primitive_desc( const_dnnl_primitive_t primitive, const_dnnl_primitive_desc_t* primitive_desc ); dnnl_status_t DNNL_API dnnl_primitive_get_cache_blob( const_dnnl_primitive_t primitive, size_t* size, uint8_t* cache_blob ); dnnl_status_t DNNL_API dnnl_primitive_destroy(dnnl_primitive_t primitive); // macros #define DNNL_ARG_ATTR_DROPOUT_MASK #define DNNL_ARG_ATTR_DROPOUT_PROBABILITY #define DNNL_ARG_ATTR_DROPOUT_SEED #define DNNL_ARG_ATTR_MULTIPLE_POST_OP(idx) #define DNNL_ARG_ATTR_MULTIPLE_POST_OP_BASE #define DNNL_ARG_ATTR_OUTPUT_SCALES #define DNNL_ARG_ATTR_POST_OP_DW #define DNNL_ARG_ATTR_ROUNDING_SEED #define DNNL_ARG_ATTR_SCALES #define DNNL_ARG_ATTR_ZERO_POINTS #define DNNL_ARG_AUGRU_ATTENTION #define DNNL_ARG_BIAS #define DNNL_ARG_DIFF_AUGRU_ATTENTION #define DNNL_ARG_DIFF_BIAS #define DNNL_ARG_DIFF_DST #define DNNL_ARG_DIFF_DST_0 #define DNNL_ARG_DIFF_DST_1 #define DNNL_ARG_DIFF_DST_2 #define DNNL_ARG_DIFF_DST_ITER #define DNNL_ARG_DIFF_DST_ITER_C #define DNNL_ARG_DIFF_DST_LAYER #define DNNL_ARG_DIFF_SCALE #define DNNL_ARG_DIFF_SHIFT #define DNNL_ARG_DIFF_SRC #define DNNL_ARG_DIFF_SRC_0 #define DNNL_ARG_DIFF_SRC_1 #define DNNL_ARG_DIFF_SRC_2 #define DNNL_ARG_DIFF_SRC_3 #define DNNL_ARG_DIFF_SRC_ITER #define DNNL_ARG_DIFF_SRC_ITER_C #define DNNL_ARG_DIFF_SRC_LAYER #define DNNL_ARG_DIFF_WEIGHTS #define DNNL_ARG_DIFF_WEIGHTS_0 #define DNNL_ARG_DIFF_WEIGHTS_1 #define DNNL_ARG_DIFF_WEIGHTS_2 #define DNNL_ARG_DIFF_WEIGHTS_3 #define DNNL_ARG_DIFF_WEIGHTS_ITER #define DNNL_ARG_DIFF_WEIGHTS_LAYER #define DNNL_ARG_DIFF_WEIGHTS_PEEPHOLE #define DNNL_ARG_DIFF_WEIGHTS_PROJECTION #define DNNL_ARG_DST #define DNNL_ARG_DST_0 #define DNNL_ARG_DST_1 #define DNNL_ARG_DST_2 #define DNNL_ARG_DST_ITER #define DNNL_ARG_DST_ITER_C #define DNNL_ARG_DST_LAYER #define DNNL_ARG_FROM #define DNNL_ARG_MEAN #define DNNL_ARG_MULTIPLE_DST #define DNNL_ARG_MULTIPLE_SRC #define DNNL_ARG_SCALE #define DNNL_ARG_SCRATCHPAD #define DNNL_ARG_SHIFT #define DNNL_ARG_SRC #define DNNL_ARG_SRC_0 #define DNNL_ARG_SRC_1 #define DNNL_ARG_SRC_2 #define DNNL_ARG_SRC_3 #define DNNL_ARG_SRC_ITER #define DNNL_ARG_SRC_ITER_C #define DNNL_ARG_SRC_LAYER #define DNNL_ARG_TO #define DNNL_ARG_UNDEF #define DNNL_ARG_VARIANCE #define DNNL_ARG_WEIGHTS #define DNNL_ARG_WEIGHTS_0 #define DNNL_ARG_WEIGHTS_1 #define DNNL_ARG_WEIGHTS_2 #define DNNL_ARG_WEIGHTS_3 #define DNNL_ARG_WEIGHTS_ITER #define DNNL_ARG_WEIGHTS_LAYER #define DNNL_ARG_WEIGHTS_PEEPHOLE #define DNNL_ARG_WEIGHTS_PROJECTION #define DNNL_ARG_WORKSPACE
Detailed Documentation¶
Common operations to create, destroy and inspect primitives.
Typedefs¶
typedef struct dnnl_primitive_desc* dnnl_primitive_desc_t
A primitive descriptor handle.
typedef const struct dnnl_primitive_desc* const_dnnl_primitive_desc_t
A constant primitive descriptor handle.
typedef struct dnnl_primitive* dnnl_primitive_t
A primitive handle.
typedef const struct dnnl_primitive* const_dnnl_primitive_t
A constant primitive handle.
Global Functions¶
dnnl_primitive_kind_t dnnl::convert_to_c(primitive::kind akind)
Converts primitive kind enum value from C++ API to C API type.
Parameters:
akind |
C++ API primitive kind enum value. |
Returns:
Corresponding C API primitive kind enum value.
dnnl_normalization_flags_t dnnl::convert_to_c(normalization_flags flags)
Converts normalization flags enum value from C++ API to C API type.
Parameters:
flags |
C++ API normalization flags enum value. |
Returns:
Corresponding C API normalization flags enum value.
dnnl_query_t dnnl::convert_to_c(query aquery)
Converts query enum value from C++ API to C API type.
Parameters:
aquery |
C++ API query enum value. |
Returns:
Corresponding C API query enum value.
dnnl_status_t DNNL_API dnnl_primitive_desc_next_impl(dnnl_primitive_desc_t primitive_desc)
Changes the primitive descriptor to point to the next available implementation.
Parameters:
primitive_desc |
A primitive descriptor to change. |
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_last_impl_reached if no more implementations available, in which case the primitive descriptor itself is kept unchanged.
dnnl_status_t DNNL_API dnnl_primitive_desc_clone( dnnl_primitive_desc_t* primitive_desc, const_dnnl_primitive_desc_t existing_primitive_desc )
Clones a primitive descriptor.
The resulting primitive descriptor must be destroyed separately.
Parameters:
primitive_desc |
Output primitive descriptor. |
existing_primitive_desc |
Primitive descriptor to clone. |
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_primitive_desc_get_attr( const_dnnl_primitive_desc_t primitive_desc, const_dnnl_primitive_attr_t* attr )
Returns a constant reference to the attributes of a primitive descriptor.
Warning
It is an error to destroy the resulting attr
.
Warning
The lifetime of an attr
is the same as that of a primitive_desc
, so it is an error to use the attr
once the primitive_desc
has been destroyed.
Parameters:
primitive_desc |
Primitive descriptor. |
attr |
Output primitive attributes. |
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_primitive_desc_destroy(dnnl_primitive_desc_t primitive_desc)
Destroys a primitive descriptor.
Parameters:
primitive_desc |
Primitive descriptor to destroy. |
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_primitive_desc_query( const_dnnl_primitive_desc_t primitive_desc, dnnl_query_t what, int index, void* result )
Queries a primitive descriptor for various pieces of information.
The most common use case is to query a primitive descriptor, created with source, weights, and destination memory descriptors with format tags set to dnnl_format_tag_any, for the corresponding memory descriptors (in this case the what
is set to dnnl_query_src_md, dnnl_query_weights_md, and dnnl_query_dst_md respectively) so that it is possible to create memory objects and reorder primitives if necessary.
Another typical use case is to query a primitive descriptor for workspace memory descriptor (with what
set to dnnl_query_workspace_md). If this query returns dnnl_not_required status, then workspace memory is not required.
Note
When querying for a memory descriptor for a scratchpad, a workspace, or an optional parameter, the query will return a pointer to a zero memory descriptor if the parameter is not needed.
A few other use cases:
query a primitive descriptor for the implementation information string (dnnl_query_impl_info_str)
query a primitive descriptor for the number of inputs and outputs (dnnl_query_num_of_inputs_s32 and dnnl_query_num_of_outputs_s32 respectively)
Parameters:
primitive_desc |
Primitive descriptor. |
what |
Parameter to query. |
index |
Index of the parameter to query for. |
result |
Output result. The type depends on the query. For example, it must be a |
Returns:
dnnl_success on success and a status describing the error otherwise.
See also:
dnnl_query_t for more options
const_dnnl_memory_desc_t DNNL_API dnnl_primitive_desc_query_md( const_dnnl_primitive_desc_t primitive_desc, dnnl_query_t what, int index )
Queries primitive descriptor for a memory descriptor.
Note
This function is a convenience version of dnnl_primitive_desc_query().
Parameters:
primitive_desc |
Primitive descriptor. |
what |
Kind of memory descriptor parameter to query for. |
index |
Index of the parameter to query. |
Returns:
A pointer to the requested memory descriptor.
A pointer to a zero memory descriptor if the parameter is not needed.
NULL in case of any error.
int DNNL_API dnnl_primitive_desc_query_s32( const_dnnl_primitive_desc_t primitive_desc, dnnl_query_t what, int index )
Queries primitive descriptor for a signed 32bit int.
Note
This function is a convenience version of dnnl_primitive_desc_query().
Parameters:
primitive_desc |
Primitive descriptor. |
what |
Kind of the value to query for. |
index |
Index of the parameter to query. |
Returns:
The requested value.
0 in case of any error (in particular if the queried entity is not of type int32_t). Note that 0 may also be the actual returned value.
dnnl_status_t DNNL_API dnnl_primitive_create( dnnl_primitive_t* primitive, const_dnnl_primitive_desc_t primitive_desc )
Creates a primitive.
Parameters:
primitive |
Output primitive. |
primitive_desc |
Primitive descriptor used to create the primitive. |
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_primitive_create_from_cache_blob( dnnl_primitive_t* primitive, const_dnnl_primitive_desc_t primitive_desc, size_t size, const uint8_t* cache_blob )
Creates a primitive from a cache blob.
Parameters:
primitive |
Output primitive. |
primitive_desc |
Primitive descriptor used to create the primitive. |
size |
Size of the cache blob in bytes. |
cache_blob |
Cache blob of size |
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_primitive_execute( const_dnnl_primitive_t primitive, dnnl_stream_t stream, int nargs, const dnnl_exec_arg_t* args )
Executes a primitive.
Note
If any argument in args
is padded (padded_dims > dims), the primitive execution will assume properly zero-padded input arguments, and produce zero-padded output arguments.
Parameters:
primitive |
Primitive to execute. |
stream |
Stream to use. |
nargs |
Number of arguments. |
args |
Array of arguments. Each argument is an <index, dnnl_memory_t> pair. The index is one of the |
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_primitive_get_primitive_desc( const_dnnl_primitive_t primitive, const_dnnl_primitive_desc_t* primitive_desc )
Retrieves a constant reference to the primitive descriptor of a given primitive.
Warning
It is an error to destroy the returned object. It is owned by the primitive. The const
qualifier of the returned object prevents such attempts.
Parameters:
primitive |
Primitive to query for the primitive descriptor. |
primitive_desc |
Output primitive descriptor. |
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_primitive_get_cache_blob( const_dnnl_primitive_t primitive, size_t* size, uint8_t* cache_blob )
Retrieves a cache blob associated with the given primitive.
Note
The cache blob can be empty. It’s the user’s responsibility to check whether it’s empty prior to passing it to dnnl_primitive_create_from_cache_blob().
Parameters:
primitive |
Primitive to query for the cache blob. |
size |
Size of the cache blob in bytes. |
cache_blob |
Cache blob of size |
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_primitive_destroy(dnnl_primitive_t primitive)
Destroys a primitive.
Parameters:
primitive |
The primitive to destroy. |
Returns:
dnnl_success on success and a status describing the error otherwise.
Macros¶
#define DNNL_ARG_ATTR_DROPOUT_MASK
Dropout mask output buffer.
#define DNNL_ARG_ATTR_DROPOUT_PROBABILITY
Dropout probability value passed via a buffer.
#define DNNL_ARG_ATTR_DROPOUT_SEED
Dropout RNG seed value passed via a buffer.
#define DNNL_ARG_ATTR_MULTIPLE_POST_OP(idx)
Arguments for a binary post operation.
Up to 32 arguments are supported. See dev_guide_attributes_post_ops_binary_fusion
#define DNNL_ARG_ATTR_MULTIPLE_POST_OP_BASE
Starting point for a binary post operation.
#define DNNL_ARG_ATTR_OUTPUT_SCALES
Output scaling factors provided at execution time.
#define DNNL_ARG_ATTR_POST_OP_DW
Arguments for fused depthwise convolution.
See dev_guide_attributes_post_ops_depthwise_fusion
#define DNNL_ARG_ATTR_ROUNDING_SEED
Rounding mode seed for stochastic rounding Single seed needed independently of how many arguments need stochastic rounding.
#define DNNL_ARG_ATTR_SCALES
Scaling factors provided at execution time.
#define DNNL_ARG_ATTR_ZERO_POINTS
Zero points provided at execution time.
#define DNNL_ARG_AUGRU_ATTENTION
A special mnemonic for RNN input recurrent cell attention vector.
An alias for DNNL_ARG_SRC_3.
#define DNNL_ARG_BIAS
Bias tensor argument.
#define DNNL_ARG_DIFF_AUGRU_ATTENTION
A special mnemonic for gradient (diff) of RNN input recurrent cell attention vector.
An alias for DNNL_ARG_DIFF_SRC_3.
#define DNNL_ARG_DIFF_BIAS
Gradient (diff) of the bias tensor argument.
#define DNNL_ARG_DIFF_DST
A special mnemonic for primitives that have a single diff destination argument.
An alias for DNNL_ARG_DIFF_DST_0.
#define DNNL_ARG_DIFF_DST_0
Gradient (diff) of the destination argument #0.
#define DNNL_ARG_DIFF_DST_1
Gradient (diff) of the destination argument #1.
#define DNNL_ARG_DIFF_DST_2
Gradient (diff) of the destination argument #2.
#define DNNL_ARG_DIFF_DST_ITER
A special mnemonic for gradient (diff) of RNN input recurrent hidden state vector.
An alias for DNNL_ARG_DIFF_DST_1.
#define DNNL_ARG_DIFF_DST_ITER_C
A special mnemonic for gradient (diff) of RNN input recurrent cell state vector.
An alias for DNNL_ARG_DIFF_DST_2.
#define DNNL_ARG_DIFF_DST_LAYER
A special mnemonic for gradient (diff) of RNN output vector.
An alias for DNNL_ARG_DIFF_DST_0.
#define DNNL_ARG_DIFF_SCALE
A special mnemonic for scale argument of normalization primitives.
#define DNNL_ARG_DIFF_SHIFT
A special mnemonic for shift argument of normalization primitives.
#define DNNL_ARG_DIFF_SRC
A special mnemonic for primitives that have a single diff source argument.
An alias for DNNL_ARG_DIFF_SRC_0.
#define DNNL_ARG_DIFF_SRC_0
Gradient (diff) of the source argument #0.
#define DNNL_ARG_DIFF_SRC_1
Gradient (diff) of the source argument #1.
#define DNNL_ARG_DIFF_SRC_2
Gradient (diff) of the source argument #2.
#define DNNL_ARG_DIFF_SRC_3
Gradient (diff) of the source argument #3.
#define DNNL_ARG_DIFF_SRC_ITER
A special mnemonic for gradient (diff) of RNN input recurrent hidden state vector.
An alias for DNNL_ARG_DIFF_SRC_1.
#define DNNL_ARG_DIFF_SRC_ITER_C
A special mnemonic for gradient (diff) of RNN input recurrent cell state vector.
An alias for DNNL_ARG_DIFF_SRC_1.
#define DNNL_ARG_DIFF_SRC_LAYER
A special mnemonic for gradient (diff) of RNN input vector.
An alias for DNNL_ARG_DIFF_SRC_0.
#define DNNL_ARG_DIFF_WEIGHTS
A special mnemonic for primitives that have a single diff weights argument.
Alias for DNNL_ARG_DIFF_WEIGHTS_0.
#define DNNL_ARG_DIFF_WEIGHTS_0
Gradient (diff) of the weights argument #0.
#define DNNL_ARG_DIFF_WEIGHTS_1
Gradient (diff) of the weights argument #1.
#define DNNL_ARG_DIFF_WEIGHTS_2
Gradient (diff) of the weights argument #2.
#define DNNL_ARG_DIFF_WEIGHTS_3
Gradient (diff) of the weights argument #3.
#define DNNL_ARG_DIFF_WEIGHTS_ITER
A special mnemonic for diff of RNN weights applied to the recurrent input.
An alias for DNNL_ARG_DIFF_WEIGHTS_1.
#define DNNL_ARG_DIFF_WEIGHTS_LAYER
A special mnemonic for diff of RNN weights applied to the layer input.
An alias for DNNL_ARG_DIFF_WEIGHTS_0.
#define DNNL_ARG_DIFF_WEIGHTS_PEEPHOLE
A special mnemonic for diff of RNN weights applied to the peephole weights.
An alias for DNNL_ARG_DIFF_WEIGHTS_2.
#define DNNL_ARG_DIFF_WEIGHTS_PROJECTION
A special mnemonic for diff of RNN weights applied to the projection weights.
An alias for DNNL_ARG_DIFF_WEIGHTS_3.
#define DNNL_ARG_DST
A special mnemonic for destination argument for primitives that have a single destination.
An alias for DNNL_ARG_DST_0.
#define DNNL_ARG_DST_0
Destination argument #0.
#define DNNL_ARG_DST_1
Destination argument #1.
#define DNNL_ARG_DST_2
Destination argument #2.
#define DNNL_ARG_DST_ITER
A special mnemonic for RNN input recurrent hidden state vector.
An alias for DNNL_ARG_DST_1.
#define DNNL_ARG_DST_ITER_C
A special mnemonic for LSTM output recurrent cell state vector.
An alias for DNNL_ARG_DST_2.
#define DNNL_ARG_DST_LAYER
A special mnemonic for RNN output vector. An alias for DNNL_ARG_DST_0.
#define DNNL_ARG_FROM
A special mnemonic for reorder source argument.
An alias for DNNL_ARG_SRC_0.
#define DNNL_ARG_MEAN
Mean values tensor argument.
#define DNNL_ARG_MULTIPLE_DST
Starting index for destination arguments for primitives that produce a variable number of destination arguments.
#define DNNL_ARG_MULTIPLE_SRC
Starting index for source arguments for primitives that take a variable number of source arguments.
#define DNNL_ARG_SCALE
A special mnemonic for scale argument of normalization primitives.
#define DNNL_ARG_SCRATCHPAD
Scratchpad (temporary storage) tensor argument.
#define DNNL_ARG_SHIFT
A special mnemonic for shift argument of normalization primitives.
#define DNNL_ARG_SRC
A special mnemonic for source argument for primitives that have a single source.
An alias for DNNL_ARG_SRC_0.
#define DNNL_ARG_SRC_0
Source argument #0.
#define DNNL_ARG_SRC_1
Source argument #1.
#define DNNL_ARG_SRC_2
Source argument #2.
#define DNNL_ARG_SRC_3
Source argument #3.
#define DNNL_ARG_SRC_ITER
A special mnemonic for RNN input recurrent hidden state vector.
An alias for DNNL_ARG_SRC_1.
#define DNNL_ARG_SRC_ITER_C
A special mnemonic for RNN input recurrent cell state vector.
An alias for DNNL_ARG_SRC_2.
#define DNNL_ARG_SRC_LAYER
A special mnemonic for RNN input vector.
An alias for DNNL_ARG_SRC_0.
#define DNNL_ARG_TO
A special mnemonic for reorder destination argument.
An alias for DNNL_ARG_DST_0.
#define DNNL_ARG_UNDEF
Undefined argument.
#define DNNL_ARG_VARIANCE
Variance values tensor argument.
#define DNNL_ARG_WEIGHTS
A special mnemonic for primitives that have a single weights argument.
Alias for DNNL_ARG_WEIGHTS_0.
#define DNNL_ARG_WEIGHTS_0
Weights argument #0.
#define DNNL_ARG_WEIGHTS_1
Weights argument #1.
#define DNNL_ARG_WEIGHTS_2
Weights argument #2.
#define DNNL_ARG_WEIGHTS_3
Weights argument #3.
#define DNNL_ARG_WEIGHTS_ITER
A special mnemonic for RNN weights applied to the recurrent input.
An alias for DNNL_ARG_WEIGHTS_1.
#define DNNL_ARG_WEIGHTS_LAYER
A special mnemonic for RNN weights applied to the layer input.
An alias for DNNL_ARG_WEIGHTS_0.
#define DNNL_ARG_WEIGHTS_PEEPHOLE
A special mnemonic for RNN weights applied to the peephole weights.
An alias for DNNL_ARG_WEIGHTS_2.
#define DNNL_ARG_WEIGHTS_PROJECTION
A special mnemonic for RNN weights applied to the projection weights.
An alias for DNNL_ARG_WEIGHTS_3.
#define DNNL_ARG_WORKSPACE
Workspace tensor argument.
Workspace is used to pass information from forward propagation to backward propagation computations.