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_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:

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.

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 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 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.

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 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_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_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_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.