This example demonstrates memory format propagation, which is critical for deep learning applications performance.
Example code: memory_format_propagation.cpp
Memory format propagation is one of the central notions that needs to be well-understood to use oneDNN correctly.
Convolution and inner product primitives choose the memory format when you create them with the placeholder memory format dnnl::memory::format_tag::any for input or output. The memory format chosen is based on different circumstances such as hardware and convolutional parameters. Using the placeholder memory format is the recommended practice for convolutions, since they are the most compute-intensive operations in most topologies where they are present.
Other primitives, such as Elementwise, LRN, batch normalization and other, on forward propagation should use the same memory format as the preceding layer thus propagating the memory format through multiple oneDNN primitives. This avoids unnecessary reorders which may be expensive and should be avoided unless a compute-intensive primitive requires a different format. For performance reasons, backward computations of such primitives requires consistent memory format with the corresponding forward computations. Hence, when initializing there primitives for backward computations you should use dnnl::memory::format_tag::any memory format tag as well.
Below is the short summary when to use and not to use memory format dnnl::memory::format_tag::any during operation description initialization:
| Primitive Kinds | Forward Propagation | Backward Propagation | No Propagation |
|---|---|---|---|
| Compute intensive: (De-)convolution, Inner product, RNN | Use dnnl::memory::format_tag::any | Use dnnl::memory::format_tag::any | N/A |
| Memory-bandwidth limited: Pooling, Layer and Batch Normalization, Local Response Normalization, Elementwise, Shuffle, Softmax | Use memory format from preceding layer for inputs, and dnnl::memory::format_tag::any for outputs | Use dnnl::memory::format_tag::any for gradient tensors, and actual memory formats for data tensors | N/A |
| Memory-bandwidth limited: Reorder, Concat, Sum, Binary | N/A | N/A | Use memory format from preceding layer for inputs, and dnnl::memory::format_tag::any for outputs |
Additional format synchronization is required between forward and backward computations when running training workloads. This topic is covered in Training-Specific Aspects.
For better understanding of the architecture and design of oneDNN as well as the concepts used in the library, please refer to Understanding Memory Formats.
This C++ API example demonstrates how to use optimized memory formats supported by oneDNN:
This tutorial assumes that the reader has already reviewed the Getting started tutorial.
The example is built around a CNN consisting of a convolution followed by a pooling and consists of the following steps:
These steps are implemented in the memory_format_propagation() function which in turn is called from main() which is also responsible for error handling.
We start by creating an engine and a stream that we will use when creating primitive descriptors and executing primitives.
To specify that a primitive should pick an optimized format for the specified computation parameters, we create memory descriptors with memory format set to dnnl::memory::format_tag::any.
This approach works only for a limited set of primitives: convolutions and inner products. Additionally, dnnl::memory::format_tag::any can be specified for destination memory descriptors which implies that destination will have the same memory format as the source.
Next, we pass the memory descriptors to primitive descriptors constructors.
We assume that the 'user' source and destination memory format is NCHW. Since there is no result validation in this tutorial, we do not bother with filling the data with some values and let oneDNN allocate the memory.
The idiomatic way to check if a reorder is necessary between the memory format expected a primitive (the convolution in our case) and the available memory format is to compare the corresponding memory descriptors.
We repeat the process for the weights and destination memory format descriptors as well.
Based on the flags computed before, we can now decide if we need extra intermediate buffers to hold the source and weights data for the convolution and the output of the pooling.
Memory objects for the intermediate buffers are created based on the memory descriptors obtained from the primitive descriptors to ensure consistency.
Now we get to the part where we actually start executing things. We check if reorders are necessary based on the flags computed before and create and execute them immediately.
After the reorders, we are now ready to compute convolution and pooling.
The only potentially remaining operation is a reorder from the pooling destination memory object to the user's one. Similarly to the reorders for the source and weights memory objects, it is performed depending on the value of the previously computed flag.
Upon compiling and run the example the output should be just:
It may be interesting to check what really happens during the run. We can use DNNL_VERBOSE environment variable for that (see also Verbose Mode). Here's an example output:
From this output we can deduce that:
