Service

Intel® oneAPI Deep Neural Network Developer Guide and Reference

Download PDF

ID 768875

Date 2/28/2024

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-25D16EDC-C105-40B8-9C1F-1265EB08851C

View Details

Service

Overview

A set of functions that aid in oneDNN debugging and profiling. More…

// typedefs

typedef dnnl_version_t dnnl::version_t;

// enums

enum dnnl::cpu_isa;
enum dnnl::cpu_isa_hints;
enum dnnl_cpu_isa_hints_t;
enum dnnl_cpu_isa_t;
enum dnnl::status;

// structs

struct dnnl_version_t;

// global functions

status dnnl::set_verbose(int level);
const version_t* dnnl::version();
fpmath_mode dnnl::get_default_fpmath_mode();
status dnnl::set_default_fpmath_mode(fpmath_mode mode);
status dnnl::set_jit_dump(int enable);
status dnnl::set_jit_profiling_flags(unsigned flags);
status dnnl::set_jit_profiling_jitdumpdir(const std::string& dir);
status dnnl::set_max_cpu_isa(cpu_isa isa);
cpu_isa dnnl::get_effective_cpu_isa();
status dnnl::set_cpu_isa_hints(cpu_isa_hints isa_hints);
cpu_isa_hints dnnl::get_cpu_isa_hints();
dnnl_status_t DNNL_API dnnl_set_jit_dump(int enable);
dnnl_status_t DNNL_API dnnl_set_jit_profiling_flags(unsigned flags);
dnnl_status_t DNNL_API dnnl_set_jit_profiling_jitdumpdir(const char* dir);
dnnl_status_t DNNL_API dnnl_set_max_cpu_isa(dnnl_cpu_isa_t isa);
dnnl_cpu_isa_t DNNL_API dnnl_get_effective_cpu_isa(void);
dnnl_status_t DNNL_API dnnl_set_cpu_isa_hints(dnnl_cpu_isa_hints_t isa_hints);
dnnl_cpu_isa_hints_t DNNL_API dnnl_get_cpu_isa_hints(void);
dnnl_status_t DNNL_API dnnl_set_verbose(int level);
const dnnl_version_t DNNL_API* dnnl_version(void);

// macros

#define DNNL_JIT_PROFILE_LINUX_JITDUMP
#define DNNL_JIT_PROFILE_LINUX_JITDUMP_USE_TSC
#define DNNL_JIT_PROFILE_LINUX_PERF
#define DNNL_JIT_PROFILE_LINUX_PERFMAP
#define DNNL_JIT_PROFILE_NONE
#define DNNL_JIT_PROFILE_VTUNE

Detailed Documentation

A set of functions that aid in oneDNN debugging and profiling.

Typedefs

typedef dnnl_version_t dnnl::version_t

Structure containing version information as per Semantic Versioning

Global Functions

status dnnl::set_verbose(int level)

Configures verbose output to stdout.

NOTE:

Enabling verbose output affects performance. This setting overrides the ONEDNN_VERBOSE environment variable.

Parameters:

level

Verbosity level:

0: no verbose output (default),
1: primitive and graph information at execution,
2: primitive and graph information at creation/compilation and execution.

Returns:

dnnl_invalid_arguments / dnnl::status::invalid_arguments if the level value is invalid, and dnnl_success / dnnl::status::success on success.

const version_t* dnnl::version()

Returns library version information.

Returns:

Pointer to a constant structure containing

major: major version number,
minor: minor version number,
patch: patch release number,
hash: git commit hash.

fpmath_mode dnnl::get_default_fpmath_mode()

Returns the floating-point math mode that will be used by default for all subsequently created primitives.

Returns:

Output FP math mode.

status dnnl::set_default_fpmath_mode(fpmath_mode mode)

Sets the floating-point math mode that will be used by default for all subsequently created primitives.

Parameters:

mode	FP math mode. The possible values are: dnnl_fpmath_mode_strict, dnnl_fpmath_mode_bf16, dnnl_fpmath_mode_f16, dnnl_fpmath_mode_tf32, dnnl_fpmath_mode_any.

Returns:

dnnl_success on success and a status describing the error otherwise.

status dnnl::set_jit_dump(int enable)

Configures dumping of JIT-generated code.

NOTE:

This setting overrides the DNNL_JIT_DUMP environment variable.

Parameters:

enable

Flag value. Set to 0 to disable and set to 1 to enable.

Returns:

dnnl_invalid_arguments / dnnl::status::invalid_arguments if the flag value is invalid, and dnnl_success / dnnl::status::success on success.

status dnnl::set_jit_profiling_flags(unsigned flags)

Sets library profiling flags.

The flags define which profilers are supported.

NOTE:

This setting overrides DNNL_JIT_PROFILE environment variable.

Passing DNNL_JIT_PROFILE_NONE disables profiling completely.

Parameters:

flags

Profiling flags that can contain the following bits:

DNNL_JIT_PROFILE_VTUNE integration with VTune Profiler (on by default)
DNNL_JIT_PROFILE_LINUX_JITDUMP produce Linux-specific jit-pid.dump output (off by default). The location of the output is controlled via JITDUMPDIR environment variable or via dnnl_set_jit_profiling_jitdumpdir() function.
DNNL_JIT_PROFILE_LINUX_PERFMAP produce Linux-specific perf-pid.map output (off by default). The output is always placed into /tmp.

Returns:

dnnl_invalid_arguments / dnnl::status::invalid_arguments if the flags value is invalid, and dnnl_success / dnnl::status::success on success.

See also:

Profiling oneDNN Performance

status dnnl::set_jit_profiling_jitdumpdir(const std::string& dir)

Sets JIT dump output path.

Only applicable to Linux and is only used when profiling flags have DNNL_JIT_PROFILE_LINUX_PERF bit set.

After the first JIT kernel is generated, the jitdump output will be placed into temporary directory created using the mkdtemp template ‘dir/.debug/jit/dnnl.XXXXXX’.

NOTE:

This setting overrides JITDUMPDIR environment variable. If JITDUMPDIR is not set, and this function is never called, the path defaults to HOME. Passing NULL reverts the value to default.

NOTE:

The directory is accessed only when the first JIT kernel is being created. JIT profiling will be disabled in case of any errors accessing or creating this directory.

Parameters:

dir	JIT dump output path.

Returns:

dnnl_success / dnnl::status::success if the output directory was set correctly and an error status otherwise.

dnnl_unimplemented / dnnl::status::unimplemented on Windows.

See also:

Profiling oneDNN Performance

status dnnl::set_max_cpu_isa(cpu_isa isa)

Sets the maximal ISA the library can dispatch to on the CPU.

See dnnl_cpu_isa_t and dnnl::cpu_isa for the list of the values accepted by the C and C++ API functions respectively.

This function has effect only once, and returns an error on subsequent calls. It should also be invoked before any other oneDNN API call, otherwise it may return an error.

This function overrides the DNNL_MAX_CPU_ISA environment variable. The environment variable can be set to the desired maximal ISA name in upper case and with dnnl_cpu_isa prefix removed. For example: DNNL_MAX_CPU_ISA=AVX2.

NOTE:

The ISAs are only partially ordered:

SSE41 < AVX < AVX2 < AVX2_VNNI < AVX2_VNNI_2,
AVX2 < AVX512_CORE < AVX512_CORE_VNNI < AVX512_CORE_BF16 < AVX512_CORE_FP16 < AVX512_CORE_AMX < AVX512_CORE_AMX_FP16,
AVX2_VNNI < AVX512_CORE_FP16.

Parameters:

isa	Maximal ISA the library should dispatch to. Pass dnnl_cpu_isa_default / dnnl::cpu_isa::isa_default to remove ISA restrictions (except for ISAs with initial support in the library).

Returns:

dnnl_success / dnnl::status::success on success and a dnnl_invalid_arguments / dnnl::status::invalid_arguments if the isa parameter is invalid or the ISA cannot be changed at this time.

dnnl_unimplemented / dnnl::status::unimplemented if the feature was disabled at build time (see Build Options for more details).

See also:

CPU Dispatcher Control for more details

cpu_isa dnnl::get_effective_cpu_isa()

Gets the maximal ISA the library can dispatch to on the CPU.

See dnnl_cpu_isa_t and dnnl::cpu_isa for the list of the values returned by the C and C++ API functions respectively.

Returns:

dnnl_cpu_isa_t value reflecting the maximal ISA the library may dispatch to.

See also:

CPU Dispatcher Control for more details

status dnnl::set_cpu_isa_hints(cpu_isa_hints isa_hints)

Sets the hints flag for the CPU ISA.

See dnnl_cpu_isa_hints_t and dnnl::cpu_isa_hints for the list of the values accepted by the C and C++ API functions respectively.

This function has effect only once, and returns an error on subsequent calls. It should also be invoked before any other oneDNN API call, otherwise it may return an error.

This function overrides the DNNL_CPU_ISA_HINTS environment variable.

Parameters:

isa_hints

CPU ISA hints to be passed over to the implementation. Pass dnnl_cpu_isa_no_hints / dnnl::cpu_isa_hints::no_hints to use default features i.e. no hints.

Returns:

dnnl_success / dnnl::status::success on success and a dnnl_runtime_error / dnnl::status::runtime_error if the ISA hints cannot be specified at the current time.

dnnl_unimplemented / dnnl::status::unimplemented if the feature was disabled at build time (see Build Options for more details).

See also:

CPU ISA Hints for more details

cpu_isa_hints dnnl::get_cpu_isa_hints()

Gets the ISA specific hints that library can follow.

See dnnl_cpu_isa_hints_t and dnnl::cpu_isa_hints for the list of the values returned by the C and C++ API functions respectively.

Returns:

dnnl_cpu_isa_hints_t value reflecting the ISA specific hints the library can follow.

See also:

CPU ISA Hints for more details

dnnl_status_t DNNL_API dnnl_set_jit_dump(int enable)

Configures dumping of JIT-generated code.

NOTE:

This setting overrides the DNNL_JIT_DUMP environment variable.

Parameters:

enable

Flag value. Set to 0 to disable and set to 1 to enable.

Returns:

dnnl_invalid_arguments / dnnl::status::invalid_arguments if the flag value is invalid, and dnnl_success / dnnl::status::success on success.

dnnl_status_t DNNL_API dnnl_set_jit_profiling_flags(unsigned flags)

Sets library profiling flags.

The flags define which profilers are supported.

NOTE:

This setting overrides DNNL_JIT_PROFILE environment variable.

Passing DNNL_JIT_PROFILE_NONE disables profiling completely.

Parameters:

flags

Profiling flags that can contain the following bits:

DNNL_JIT_PROFILE_VTUNE integration with VTune Profiler (on by default)
DNNL_JIT_PROFILE_LINUX_JITDUMP produce Linux-specific jit-pid.dump output (off by default). The location of the output is controlled via JITDUMPDIR environment variable or via dnnl_set_jit_profiling_jitdumpdir() function.
DNNL_JIT_PROFILE_LINUX_PERFMAP produce Linux-specific perf-pid.map output (off by default). The output is always placed into /tmp.

Returns:

dnnl_invalid_arguments / dnnl::status::invalid_arguments if the flags value is invalid, and dnnl_success / dnnl::status::success on success.

See also:

Profiling oneDNN Performance

dnnl_status_t DNNL_API dnnl_set_jit_profiling_jitdumpdir(const char* dir)

Sets JIT dump output path.

Only applicable to Linux and is only used when profiling flags have DNNL_JIT_PROFILE_LINUX_PERF bit set.

After the first JIT kernel is generated, the jitdump output will be placed into temporary directory created using the mkdtemp template ‘dir/.debug/jit/dnnl.XXXXXX’.

NOTE:

This setting overrides JITDUMPDIR environment variable. If JITDUMPDIR is not set, and this function is never called, the path defaults to HOME. Passing NULL reverts the value to default.

NOTE:

The directory is accessed only when the first JIT kernel is being created. JIT profiling will be disabled in case of any errors accessing or creating this directory.

Parameters:

dir	JIT dump output path.

Returns:

dnnl_success / dnnl::status::success if the output directory was set correctly and an error status otherwise.

dnnl_unimplemented / dnnl::status::unimplemented on Windows.

See also:

Profiling oneDNN Performance

dnnl_status_t DNNL_API dnnl_set_max_cpu_isa(dnnl_cpu_isa_t isa)

Sets the maximal ISA the library can dispatch to on the CPU.

See dnnl_cpu_isa_t and dnnl::cpu_isa for the list of the values accepted by the C and C++ API functions respectively.

This function has effect only once, and returns an error on subsequent calls. It should also be invoked before any other oneDNN API call, otherwise it may return an error.

NOTE:

The ISAs are only partially ordered:

SSE41 < AVX < AVX2 < AVX2_VNNI < AVX2_VNNI_2,
AVX2 < AVX512_CORE < AVX512_CORE_VNNI < AVX512_CORE_BF16 < AVX512_CORE_FP16 < AVX512_CORE_AMX < AVX512_CORE_AMX_FP16,
AVX2_VNNI < AVX512_CORE_FP16.

Parameters:

isa	Maximal ISA the library should dispatch to. Pass dnnl_cpu_isa_default / dnnl::cpu_isa::isa_default to remove ISA restrictions (except for ISAs with initial support in the library).

Returns:

dnnl_success / dnnl::status::success on success and a dnnl_invalid_arguments / dnnl::status::invalid_arguments if the isa parameter is invalid or the ISA cannot be changed at this time.

dnnl_unimplemented / dnnl::status::unimplemented if the feature was disabled at build time (see Build Options for more details).

See also:

CPU Dispatcher Control for more details

dnnl_cpu_isa_t DNNL_API dnnl_get_effective_cpu_isa(void)

Gets the maximal ISA the library can dispatch to on the CPU.

See dnnl_cpu_isa_t and dnnl::cpu_isa for the list of the values returned by the C and C++ API functions respectively.

Returns:

dnnl_cpu_isa_t value reflecting the maximal ISA the library may dispatch to.

See also:

CPU Dispatcher Control for more details

dnnl_status_t DNNL_API dnnl_set_cpu_isa_hints(dnnl_cpu_isa_hints_t isa_hints)

Sets the hints flag for the CPU ISA.

See dnnl_cpu_isa_hints_t and dnnl::cpu_isa_hints for the list of the values accepted by the C and C++ API functions respectively.

This function has effect only once, and returns an error on subsequent calls. It should also be invoked before any other oneDNN API call, otherwise it may return an error.

This function overrides the DNNL_CPU_ISA_HINTS environment variable.

Parameters:

isa_hints

CPU ISA hints to be passed over to the implementation. Pass dnnl_cpu_isa_no_hints / dnnl::cpu_isa_hints::no_hints to use default features i.e. no hints.

Returns:

dnnl_success / dnnl::status::success on success and a dnnl_runtime_error / dnnl::status::runtime_error if the ISA hints cannot be specified at the current time.

dnnl_unimplemented / dnnl::status::unimplemented if the feature was disabled at build time (see Build Options for more details).

See also:

CPU ISA Hints for more details

dnnl_cpu_isa_hints_t DNNL_API dnnl_get_cpu_isa_hints(void)

Gets the ISA specific hints that library can follow.

See dnnl_cpu_isa_hints_t and dnnl::cpu_isa_hints for the list of the values returned by the C and C++ API functions respectively.

Returns:

dnnl_cpu_isa_hints_t value reflecting the ISA specific hints the library can follow.

See also:

CPU ISA Hints for more details

dnnl_status_t DNNL_API dnnl_set_verbose(int level)

Configures verbose output to stdout.

NOTE:

Enabling verbose output affects performance. This setting overrides the ONEDNN_VERBOSE environment variable.

Parameters:

level

Verbosity level:

0: no verbose output (default),
1: primitive and graph information at execution,
2: primitive and graph information at creation/compilation and execution.

Returns:

dnnl_invalid_arguments / dnnl::status::invalid_arguments if the level value is invalid, and dnnl_success / dnnl::status::success on success.

const dnnl_version_t DNNL_API* dnnl_version(void)

Returns library version information.

Returns:

Pointer to a constant structure containing

major: major version number,
minor: minor version number,
patch: patch release number,
hash: git commit hash.

Macros

#define DNNL_JIT_PROFILE_LINUX_JITDUMP

Enable Linux perf integration via jitdump files.

#define DNNL_JIT_PROFILE_LINUX_JITDUMP_USE_TSC

Instruct Linux perf integration via jitdump files to use TSC.

DNNL_JIT_PROFILE_LINUX_JITDUMP must be set too for this to take effect.

#define DNNL_JIT_PROFILE_LINUX_PERF

Enable Linux perf integration (both jitdump and perfmap)

#define DNNL_JIT_PROFILE_LINUX_PERFMAP

Enable Linux perf integration via perfmap files.

#define DNNL_JIT_PROFILE_NONE

Disable profiling completely.

#define DNNL_JIT_PROFILE_VTUNE

Enable VTune Profiler integration.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® oneAPI Deep Neural Network Developer Guide and Reference

Service

Overview

Detailed Documentation