Intel® oneAPI Deep Neural Network Developer Guide and Reference
A newer version of this document is available. Customers should click here to go to the newest version.
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_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_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_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_WORKSPACEDetailed Documentation
Common operations to create, destroy and inspect primitives.
Typedefs
typedef struct dnnl_primitive_desc* dnnl_primitive_desc_tA primitive descriptor handle.
typedef const struct dnnl_primitive_desc* const_dnnl_primitive_desc_tA constant primitive descriptor handle.
typedef struct dnnl_primitive* dnnl_primitive_tA primitive handle.
typedef const struct dnnl_primitive* const_dnnl_primitive_tA 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.
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.
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 dnnl_memory_desc_t* if querying for a memory descriptor. | 
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.
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.
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 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.
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 DNNL_ARG_* values such as DNNL_ARG_SRC. Unless runtime shapes are used (see DNNL_RUNTIME_DIM_VAL), the memory object must have the same memory descriptor as that returned by dnnl_primitive_desc_query_md (dnnl_query_exec_arg_md, index). | 
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.
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.
Parameters:
| primitive | Primitive to query for the cache blob. | 
| size | Size of the cache blob in bytes. | 
| cache_blob | Cache blob of size size. If the cache_blob is nullptr then the size of the cache blob is returned in 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_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_BASEStarting point for a binary post operation.
#define DNNL_ARG_ATTR_OUTPUT_SCALESOutput scaling factors provided at execution time.
#define DNNL_ARG_ATTR_POST_OP_DWArguments for fused depthwise convolution.
See dev_guide_attributes_post_ops_depthwise_fusion
#define DNNL_ARG_ATTR_SCALESScaling factors provided at execution time.
#define DNNL_ARG_ATTR_ZERO_POINTSZero points provided at execution time.
#define DNNL_ARG_AUGRU_ATTENTIONA special mnemonic for RNN input recurrent cell attention vector.
An alias for DNNL_ARG_SRC_3.
#define DNNL_ARG_BIASBias tensor argument.
#define DNNL_ARG_DIFF_AUGRU_ATTENTIONA special mnemonic for gradient (diff) of RNN input recurrent cell attention vector.
An alias for DNNL_ARG_DIFF_SRC_3.
#define DNNL_ARG_DIFF_BIASGradient (diff) of the bias tensor argument.
#define DNNL_ARG_DIFF_DSTA special mnemonic for primitives that have a single diff destination argument.
An alias for DNNL_ARG_DIFF_DST_0.
#define DNNL_ARG_DIFF_DST_0Gradient (diff) of the destination argument #0.
#define DNNL_ARG_DIFF_DST_1Gradient (diff) of the destination argument #1.
#define DNNL_ARG_DIFF_DST_2Gradient (diff) of the destination argument #2.
#define DNNL_ARG_DIFF_DST_ITERA 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_CA 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_LAYERA special mnemonic for gradient (diff) of RNN output vector.
An alias for DNNL_ARG_DIFF_DST_0.
#define DNNL_ARG_DIFF_SCALEA special mnemonic for scale argument of normalization primitives.
#define DNNL_ARG_DIFF_SHIFTA special mnemonic for shift argument of normalization primitives.
#define DNNL_ARG_DIFF_SRCA special mnemonic for primitives that have a single diff source argument.
An alias for DNNL_ARG_DIFF_SRC_0.
#define DNNL_ARG_DIFF_SRC_0Gradient (diff) of the source argument #0.
#define DNNL_ARG_DIFF_SRC_1Gradient (diff) of the source argument #1.
#define DNNL_ARG_DIFF_SRC_2Gradient (diff) of the source argument #2.
#define DNNL_ARG_DIFF_SRC_3Gradient (diff) of the source argument #3.
#define DNNL_ARG_DIFF_SRC_ITERA 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_CA 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_LAYERA special mnemonic for gradient (diff) of RNN input vector.
An alias for DNNL_ARG_DIFF_SRC_0.
#define DNNL_ARG_DIFF_WEIGHTSA special mnemonic for primitives that have a single diff weights argument.
Alias for DNNL_ARG_DIFF_WEIGHTS_0.
#define DNNL_ARG_DIFF_WEIGHTS_0Gradient (diff) of the weights argument #0.
#define DNNL_ARG_DIFF_WEIGHTS_1Gradient (diff) of the weights argument #1.
#define DNNL_ARG_DIFF_WEIGHTS_2Gradient (diff) of the weights argument #2.
#define DNNL_ARG_DIFF_WEIGHTS_3Gradient (diff) of the weights argument #3.
#define DNNL_ARG_DIFF_WEIGHTS_ITERA 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_LAYERA 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_PEEPHOLEA 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_PROJECTIONA special mnemonic for diff of RNN weights applied to the projection weights.
An alias for DNNL_ARG_DIFF_WEIGHTS_3.
#define DNNL_ARG_DSTA special mnemonic for destination argument for primitives that have a single destination.
An alias for DNNL_ARG_DST_0.
#define DNNL_ARG_DST_0Destination argument #0.
#define DNNL_ARG_DST_1Destination argument #1.
#define DNNL_ARG_DST_2Destination argument #2.
#define DNNL_ARG_DST_ITERA special mnemonic for RNN input recurrent hidden state vector.
An alias for DNNL_ARG_DST_1.
#define DNNL_ARG_DST_ITER_CA special mnemonic for LSTM output recurrent cell state vector.
An alias for DNNL_ARG_DST_2.
#define DNNL_ARG_DST_LAYERA special mnemonic for RNN output vector. An alias for DNNL_ARG_DST_0.
#define DNNL_ARG_FROMA special mnemonic for reorder source argument.
An alias for DNNL_ARG_SRC_0.
#define DNNL_ARG_MEANMean values tensor argument.
#define DNNL_ARG_MULTIPLE_DSTStarting index for destination arguments for primitives that produce a variable number of destination arguments.
#define DNNL_ARG_MULTIPLE_SRCStarting index for source arguments for primitives that take a variable number of source arguments.
#define DNNL_ARG_SCALEA special mnemonic for scale argument of normalization primitives.
#define DNNL_ARG_SCRATCHPADScratchpad (temporary storage) tensor argument.
#define DNNL_ARG_SHIFTA special mnemonic for shift argument of normalization primitives.
#define DNNL_ARG_SRCA special mnemonic for source argument for primitives that have a single source.
An alias for DNNL_ARG_SRC_0.
#define DNNL_ARG_SRC_0Source argument #0.
#define DNNL_ARG_SRC_1Source argument #1.
#define DNNL_ARG_SRC_2Source argument #2.
#define DNNL_ARG_SRC_3Source argument #3.
#define DNNL_ARG_SRC_ITERA special mnemonic for RNN input recurrent hidden state vector.
An alias for DNNL_ARG_SRC_1.
#define DNNL_ARG_SRC_ITER_CA special mnemonic for RNN input recurrent cell state vector.
An alias for DNNL_ARG_SRC_2.
#define DNNL_ARG_SRC_LAYERA special mnemonic for RNN input vector.
An alias for DNNL_ARG_SRC_0.
#define DNNL_ARG_TOA special mnemonic for reorder destination argument.
An alias for DNNL_ARG_DST_0.
#define DNNL_ARG_VARIANCEVariance values tensor argument.
#define DNNL_ARG_WEIGHTSA special mnemonic for primitives that have a single weights argument.
Alias for DNNL_ARG_WEIGHTS_0.
#define DNNL_ARG_WEIGHTS_0Weights argument #0.
#define DNNL_ARG_WEIGHTS_1Weights argument #1.
#define DNNL_ARG_WEIGHTS_2Weights argument #2.
#define DNNL_ARG_WEIGHTS_3Weights argument #3.
#define DNNL_ARG_WEIGHTS_ITERA special mnemonic for RNN weights applied to the recurrent input.
An alias for DNNL_ARG_WEIGHTS_1.
#define DNNL_ARG_WEIGHTS_LAYERA special mnemonic for RNN weights applied to the layer input.
An alias for DNNL_ARG_WEIGHTS_0.
#define DNNL_ARG_WEIGHTS_PEEPHOLEA special mnemonic for RNN weights applied to the peephole weights.
An alias for DNNL_ARG_WEIGHTS_2.
#define DNNL_ARG_WEIGHTS_PROJECTIONA special mnemonic for RNN weights applied to the projection weights.
An alias for DNNL_ARG_WEIGHTS_3.
#define DNNL_ARG_WORKSPACEWorkspace tensor argument.
Workspace is used to pass information from forward propagation to backward propagation computations.