1Reorder {#dev_guide_reorder} 2============================ 3 4> 5> [API Reference](@ref dnnl_api_reorder) 6> 7 8## General 9 10The reorder primitive copies data between different memory formats but doesn't 11change the tensor from mathematical perspective (the variable names follow the 12standard @ref dev_guide_conventions): 13 14\f[ 15 \dst(\overline{x}) = \src(\overline{x}) 16\f] 17 18As described in @ref dev_guide_basic_concepts in order to achieve the best 19performance some primitives (such as convolution) require special memory format 20which is typically referred to as an *optimized* memory format. The *optimized* 21memory format may match or may not match memory format that data is currently 22kept in. In this case a user can use reorder primitive to copy (reorder) the 23data between the memory formats. 24 25Using the attributes and post-ops users can also use reorder primitive to 26quantize the data (and if necessary change the memory format simultaneously). 27 28## Execution Arguments 29 30When executed, the inputs and outputs should be mapped to an execution 31argument index as specified by the following table. 32 33| Primitive input/output | Execution argument index | 34| --- | --- | 35| \src | DNNL_ARG_FROM | 36| \dst | DNNL_ARG_TO | 37 38## Implementation Details 39 40### General Notes 41 421. The reorder primitive requires the source and destination tensors to have 43 the same shape. Implicit broadcasting is not supported. 44 452. While in most of the cases the reorder should be able to handle arbitrary 46 source and destination memory formats and data types, it might happen than 47 some combinations are not implemented. For instance: 48 49 - Reorder implementations between weights in non-plain memory formats might 50 be limited (but if encountered in real practice should be treated as a 51 bug and reported to oneDNN team); 52 53 - Weights in one Winograd format cannot be reordered to the weights of the 54 other Winograd format; 55 56 - Quantized weights for convolution with #dnnl_s8 source data type cannot 57 be dequantized back to the #dnnl_f32 data type; 58 593. To alleviate the problem a user may rely on fact that the reorder from 60 original plain memory format and user's data type to the *optimized* format 61 with chosen data type should be always implemented. 62 63### Data Types Support 64 65The reorder primitive supports arbitrary data types for the source and 66destination according to the @ref dev_guide_data_types page. 67 68When converting the data from one data type to a smaller one 69saturation is used. For instance: 70 71~~~ 72 reorder(src={1024, data_type=f32}, dst={, data_type=s8}) 73 // dst == {127} 74 75 reorder(src={-124, data_type=f32}, dst={, data_type=u8}) 76 // dst == {0} 77~~~ 78 79### Data Representation 80 81The reorder primitive works with arbitrary data tensors. There is no special 82meaning associated with any logical dimensions. 83 84### Post-Ops and Attributes 85 86The reorder primitive support the following attributes and post-ops: 87 88| Attributes / Post-ops | Meaning 89| :-- | :-- 90| [Output scales](@ref dnnl_primitive_attr_set_output_scales) | Copy and scale the data according to the scaling factors 91| [Sum post-op](@ref dnnl_post_ops_append_sum) | Instead of copy the data accumulate it to the previous data 92 93For instance, the following pseudo-code 94 95~~~ 96 reorder( 97 src = {dims={N, C, H, W}, data_type=dt_src, memory_format=fmt_src}, 98 dst = {dims={N, C, H, W}, data_type=dt_dst, memory_format=fmt_dst}, 99 attr ={ 100 output_scale=alpha, 101 post-ops = { sum={scale=beta} }, 102 }) 103~~~ 104 105would lead to the following operation: 106 107\f[ 108 \dst(\overline{x}) = 109 \alpha \cdot \src(\overline{x}) + 110 \beta \cdot \dst(\overline{x}) 111\f] 112 113@note The intermediate operations are being done using single precision 114floating point data type. 115 116## Implementation Limitations 117 1181. No primitive specific limitations. Refer to @ref dev_guide_data_types for 119 limitations related to data types support. 120 121## Performance Tips 122 123N/A 124 125## Example 126 127[Reorder Primitive Example](@ref reorder_example_cpp) 128 129@copydetails reorder_example_cpp_short 130