1 /*
2 * Copyright (c) 2016-2021 Arm Limited.
3 *
4 * SPDX-License-Identifier: MIT
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in all
14 * copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 */
24 #ifndef ARM_COMPUTE_HELPERS_H
25 #define ARM_COMPUTE_HELPERS_H
26
27 #include "arm_compute/core/Error.h"
28 #include "arm_compute/core/IAccessWindow.h"
29 #include "arm_compute/core/ITensor.h"
30 #include "arm_compute/core/Types.h"
31 #include "arm_compute/core/Validate.h"
32 #include "arm_compute/core/Window.h"
33
34 #include <array>
35 #include <cstddef>
36 #include <cstdint>
37 #include <tuple>
38
39 namespace arm_compute
40 {
41 class IKernel;
42 class ITensor;
43 class ITensorInfo;
44
45 /** Iterator updated by @ref execute_window_loop for each window element */
46 class Iterator
47 {
48 public:
49 /** Default constructor to create an empty iterator */
50 constexpr Iterator();
51 /** Create a container iterator for the metadata and allocation contained in the ITensor
52 *
53 * @param[in] tensor The tensor to associate to the iterator.
54 * @param[in] window The window which will be used to iterate over the tensor.
55 */
56 Iterator(const ITensor *tensor, const Window &window);
57
58 /** Increment the iterator along the specified dimension of the step value associated to the dimension.
59 *
60 * @warning It is the caller's responsibility to call increment(dimension+1) when reaching the end of a dimension, the iterator will not check for overflow.
61 *
62 * @note When incrementing a dimension 'n' the coordinates of all the dimensions in the range (0,n-1) are reset. For example if you iterate over a 2D image, everytime you change row (dimension 1), the iterator for the width (dimension 0) is reset to its start.
63 *
64 * @param[in] dimension Dimension to increment
65 */
66 void increment(size_t dimension);
67
68 /** Return the offset in bytes from the first element to the current position of the iterator
69 *
70 * @return The current position of the iterator in bytes relative to the first element.
71 */
72 constexpr size_t offset() const;
73
74 /** Return a pointer to the current pixel.
75 *
76 * @warning Only works if the iterator was created with an ITensor.
77 *
78 * @return equivalent to buffer() + offset()
79 */
80 constexpr uint8_t *ptr() const;
81
82 /** Move the iterator back to the beginning of the specified dimension.
83 *
84 * @param[in] dimension Dimension to reset
85 */
86 void reset(size_t dimension);
87
88 private:
89 uint8_t *_ptr;
90
91 class Dimension
92 {
93 public:
Dimension()94 constexpr Dimension()
95 : _dim_start(0), _stride(0)
96 {
97 }
98
99 size_t _dim_start;
100 size_t _stride;
101 };
102
103 std::array<Dimension, Coordinates::num_max_dimensions> _dims;
104 };
105
106 /** Iterate through the passed window, automatically adjusting the iterators and calling the lambda_functino for each element.
107 * It passes the x and y positions to the lambda_function for each iteration
108 *
109 * @param[in] w Window to iterate through.
110 * @param[in] lambda_function The function of type void(function)( const Coordinates & id ) to call at each iteration.
111 * Where id represents the absolute coordinates of the item to process.
112 * @param[in,out] iterators Tensor iterators which will be updated by this function before calling lambda_function.
113 */
114 template <typename L, typename... Ts>
115 inline void execute_window_loop(const Window &w, L &&lambda_function, Ts &&... iterators);
116
117 /** Permutes given Dimensions according to a permutation vector
118 *
119 * @warning Validity of permutation is not checked
120 *
121 * @param[in, out] dimensions Dimensions to permute
122 * @param[in] perm Permutation vector
123 */
124 template <typename T>
permute(Dimensions<T> & dimensions,const PermutationVector & perm)125 inline void permute(Dimensions<T> &dimensions, const PermutationVector &perm)
126 {
127 auto dimensions_copy = utility::make_array<Dimensions<T>::num_max_dimensions>(dimensions.begin(), dimensions.end());
128 for(unsigned int i = 0; i < perm.num_dimensions(); ++i)
129 {
130 T dimension_val = (perm[i] < dimensions.num_dimensions()) ? dimensions_copy[perm[i]] : 0;
131 dimensions.set(i, dimension_val);
132 }
133 }
134
135 /** Permutes given TensorShape according to a permutation vector
136 *
137 * @warning Validity of permutation is not checked
138 *
139 * @param[in, out] shape Shape to permute
140 * @param[in] perm Permutation vector
141 */
permute(TensorShape & shape,const PermutationVector & perm)142 inline void permute(TensorShape &shape, const PermutationVector &perm)
143 {
144 TensorShape shape_copy = shape;
145 for(unsigned int i = 0; i < perm.num_dimensions(); ++i)
146 {
147 size_t dimension_val = (perm[i] < shape.num_dimensions()) ? shape_copy[perm[i]] : 1;
148 shape.set(i, dimension_val, false, false); // Avoid changes in _num_dimension
149 }
150 }
151
152 /** Helper function to calculate the Valid Region for Scale.
153 *
154 * @param[in] src_info Input tensor info used to check.
155 * @param[in] dst_shape Shape of the output.
156 * @param[in] interpolate_policy Interpolation policy.
157 * @param[in] sampling_policy Sampling policy.
158 * @param[in] border_undefined True if the border is undefined.
159 *
160 * @return The corresponding valid region
161 */
162 ValidRegion calculate_valid_region_scale(const ITensorInfo &src_info, const TensorShape &dst_shape,
163 InterpolationPolicy interpolate_policy, SamplingPolicy sampling_policy, bool border_undefined);
164
165 /** Convert a linear index into n-dimensional coordinates.
166 *
167 * @param[in] shape Shape of the n-dimensional tensor.
168 * @param[in] index Linear index specifying the i-th element.
169 *
170 * @return n-dimensional coordinates.
171 */
172 inline Coordinates index2coords(const TensorShape &shape, int index);
173
174 /** Convert n-dimensional coordinates into a linear index.
175 *
176 * @param[in] shape Shape of the n-dimensional tensor.
177 * @param[in] coord N-dimensional coordinates.
178 *
179 * @return linead index
180 */
181 inline int coords2index(const TensorShape &shape, const Coordinates &coord);
182
183 /** Returns a static map used to find an index or dimension based on a data layout
184 *
185 * *** Layouts ***
186 *
187 * *** 4D ***
188 * [N C H W]
189 * [3 2 1 0]
190 * [N H W C]
191 *
192 * * *** 5D ***
193 * [N C D H W]
194 * [4 3 2 1 0]
195 * [N D H W C]
196 */
197 const std::map<DataLayout, std::vector<DataLayoutDimension>> &get_layout_map();
198
199 /** Get the index of the given dimension.
200 *
201 * @param[in] data_layout The data layout.
202 * @param[in] data_layout_dimension The dimension which this index is requested for.
203 *
204 * @return The int conversion of the requested data layout index.
205 */
206 inline size_t get_data_layout_dimension_index(const DataLayout &data_layout, const DataLayoutDimension &data_layout_dimension);
207
208 /** Get the DataLayoutDimension of a given index and layout.
209 *
210 * @param[in] data_layout The data layout.
211 * @param[in] index The data layout index.
212 *
213 * @return The dimension which this index is requested for.
214 */
215 inline DataLayoutDimension get_index_data_layout_dimension(const DataLayout &data_layout, const size_t index);
216
217 /** Calculate the number of output tiles required by Winograd Convolution layer. This utility function can be used by the Winograd input transform
218 * to know the number of tiles on the x and y direction
219 *
220 * @param[in] in_dims Spatial dimensions of the input tensor of convolution layer
221 * @param[in] kernel_size Kernel size
222 * @param[in] output_tile_size Size of a single output tile
223 * @param[in] conv_info Convolution info (i.e. pad, stride,...)
224 *
225 * @return the number of output tiles along the x and y directions of size "output_tile_size"
226 */
compute_winograd_convolution_tiles(const Size2D & in_dims,const Size2D & kernel_size,const Size2D & output_tile_size,const PadStrideInfo & conv_info)227 inline Size2D compute_winograd_convolution_tiles(const Size2D &in_dims, const Size2D &kernel_size, const Size2D &output_tile_size, const PadStrideInfo &conv_info)
228 {
229 int num_tiles_x = std::ceil((in_dims.width - (kernel_size.width - 1) + conv_info.pad_left() + conv_info.pad_right()) / static_cast<float>(output_tile_size.width));
230 int num_tiles_y = std::ceil((in_dims.height - (kernel_size.height - 1) + conv_info.pad_top() + conv_info.pad_bottom()) / static_cast<float>(output_tile_size.height));
231
232 // Clamp in case we provide paddings but we have 1D convolution
233 num_tiles_x = std::min(num_tiles_x, static_cast<int>(in_dims.width));
234 num_tiles_y = std::min(num_tiles_y, static_cast<int>(in_dims.height));
235
236 return Size2D(num_tiles_x, num_tiles_y);
237 }
238
239 /** Wrap-around a number within the range 0 <= x < m
240 *
241 * @param[in] x Input value
242 * @param[in] m Range
243 *
244 * @return the wrapped-around number
245 */
246 template <typename T>
wrap_around(T x,T m)247 inline T wrap_around(T x, T m)
248 {
249 return x >= 0 ? x % m : (x % m + m) % m;
250 }
251
252 /** Convert negative coordinates to positive in the range [0, num_dims_input]
253 *
254 * @param[out] coords Array of coordinates to be converted.
255 * @param[in] max_value Maximum value to be used when wrapping the negative values in coords
256 */
convert_negative_axis(Coordinates & coords,int max_value)257 inline Coordinates &convert_negative_axis(Coordinates &coords, int max_value)
258 {
259 for(unsigned int i = 0; i < coords.num_dimensions(); ++i)
260 {
261 coords[i] = wrap_around(coords[i], max_value);
262 }
263 return coords;
264 }
265 } // namespace arm_compute
266
267 #include "arm_compute/core/Helpers.inl"
268 #endif /*ARM_COMPUTE_HELPERS_H */
269