inference-engine/include/ie_layouts.h

   1 // Copyright (C) 2018-2020 Intel Corporation
   2 // SPDX-License-Identifier: Apache-2.0
   3 //
   4
   5 /**
   6  * @brief A header file for data layouts and conversion between them
   7  *
   8  * @file ie_layouts.h
   9  */
  10 #pragma once
  11
  12 #include <algorithm>
  13
  14 #include "ie_api.h"
  15 #include "ie_common.h"
  16 #include "ie_precision.hpp"
  17
  18 namespace InferenceEngine {
  19
  20 /**
  21  * @brief This class describes blocking layouts
  22  */
  23 class INFERENCE_ENGINE_API_CLASS(BlockingDesc) {
  24 public:
  25     /**
  26      * @brief The default constructor which creates empty blocking descriptor
  27      */
  28     BlockingDesc();
  29     /**
  30      * @brief The constructor which allows to create blocking descriptors for standard layouts
  31      *
  32      * @param dims real dimensions
  33      * @param layout memory layout
  34      */
  35     BlockingDesc(const SizeVector& dims, Layout layout);
  36     /**
  37      * @brief The constructor allows to create blocking descriptors for blocked memory
  38      *
  39      * @param blocked_dims blocked dimensions
  40      * @param order the order of dimensions
  41      */
  42     BlockingDesc(const SizeVector& blocked_dims, const SizeVector& order);
  43     /**
  44      * @brief The constructor allows to create blocking descriptors for blocked memory
  45      *
  46      * @param blocked_dims blocked dimensions
  47      * @param order the order of dimensions
  48      * @param offset offset to the current memory block
  49      */
  50     BlockingDesc(const SizeVector& blocked_dims, const SizeVector& order, size_t offset);
  51     /**
  52      * @brief The constructor allows to create blocking descriptors for blocked memory
  53      *
  54      * @param blocked_dims blocked dimensions
  55      * @param order the order of dimensions
  56      * @param offset offset to the current memory block
  57      * @param dimOffsets per-dimension offset from the padding to actual data,
  58      */
  59     BlockingDesc(const SizeVector& blocked_dims, const SizeVector& order, size_t offset, const SizeVector& dimOffsets);
  60     /**
  61      * @brief The constructor allows to create blocking descriptors for blocked memory
  62      *
  63      * @param blocked_dims blocked dimensions
  64      * @param order the order of dimensions
  65      * @param offset offset to the current memory block
  66      * @param dimOffsets per-dimension offset from the padding to actual data,
  67      * @param strides strides for each dimension
  68      */
  69     BlockingDesc(const SizeVector& blocked_dims, const SizeVector& order, size_t offset,
  70                  const SizeVector& dimOffsets, const SizeVector& strides);
  71
  72     /**
  73      * @brief Returns the blocked dimensions vector
  74      *
  75      * @return blocked dimensions
  76      */
  77     const SizeVector& getBlockDims() const {
  78         return blockedDims;
  79     }
  80
  81     /**
  82      * @brief Returns the vector of order
  83      *
  84      * @return order
  85      */
  86     const SizeVector& getOrder() const {
  87         return order;
  88     }
  89
  90     /**
  91      * @brief Returns the per-dimension offset vector
  92      *
  93      * @return offsets
  94      */
  95     const SizeVector& getOffsetPaddingToData() const {
  96         return offsetPaddingToData;
  97     }
  98
  99     /**
 100      * @brief Returns the offset to the current memory block
 101      *
 102      * @return offset
 103      */
 104     size_t getOffsetPadding() const {
 105         return offsetPadding;
 106     }
 107
 108     /**
 109      * @brief Returns strides for each dimension
 110      *
 111      * @return strides
 112      */
 113     const SizeVector& getStrides() const {
 114         return strides;
 115     }
 116
 117     /**
 118      * @brief The comparison operator for the BlockingDesc
 119      *
 120      * @param rhs object to compare
 121      * @return true if objects are equal
 122      */
 123     bool operator==(const BlockingDesc& rhs) const;
 124     /**
 125      * @brief The comparison operator for the BlockingDesc
 126      *
 127      * @param rhs object to compare
 128      * @return true if objects aren't equal
 129      */
 130     bool operator!=(const BlockingDesc& rhs) const;
 131
 132 protected:
 133     void fillDesc(const SizeVector& blocked_dims, const SizeVector& order);
 134
 135 private:
 136     /** Blocked dimensions. */
 137     SizeVector blockedDims;
 138     /** Strides for blocked dimensions */
 139     SizeVector strides;
 140     /** The order of blocked dimensions **/
 141     SizeVector order;
 142     /** Per-dimension offset from the padding to actual data, the top-level
 143      * tensor with offsets applied must lie within the padding area. */
 144     SizeVector offsetPaddingToData;
 145     /** Offset from memory origin to the current block, non-zero only in
 146      * a description of a memory sub-block. */
 147     size_t offsetPadding;
 148 };
 149
 150 /**
 151  * @brief This class defines Tensor description
 152  */
 153 class INFERENCE_ENGINE_API_CLASS(TensorDesc) {
 154 public:
 155     /**
 156      * @brief The constructor creates the tensor descriptor using blocking descriptor
 157      *
 158      * @param precision memory precision
 159      * @param dims memory dimensions
 160      * @param blockDesc blocking descriptor
 161      */
 162     TensorDesc(const Precision& precision, const SizeVector& dims, const BlockingDesc& blockDesc);
 163     /**
 164      * @brief The constructor creates the tensor descriptor using standard layout
 165      *
 166      * @param precision memory precision
 167      * @param dims memory dimensions
 168      * @param layout memory layout
 169      */
 170     TensorDesc(const Precision& precision, const SizeVector& dims, Layout layout);
 171     /**
 172      * @brief The constructor creates the empty tensor descriptor with precision and layout
 173      *
 174      * @param precision memory precision
 175      * @param layout memory layout
 176      */
 177     TensorDesc(const Precision& precision, Layout layout);
 178     /**
 179      * @brief The default constructor which creates empty tensor descriptor
 180      */
 181     TensorDesc();
 182
 183     /**
 184      * @brief Reshapes the tensor descriptor
 185      *
 186      * @param dims new dimensions
 187      * @param layout new layout if it is necessary
 188      */
 189     void reshape(const SizeVector& dims, Layout layout = Layout::ANY);
 190     /**
 191      * @brief Reshapes the tensor descriptor
 192      *
 193      * @param dims new dimensions
 194      * @param blockDesc new blocking descriptor
 195      */
 196     void reshape(const SizeVector& dims, const BlockingDesc& blockDesc);
 197
 198     /**
 199      * @brief Returns the vector of dimensions
 200      *
 201      * @return dimensions
 202      */
 203     SizeVector& getDims() {
 204         return dims;
 205     }
 206     /**
 207      * @brief Returns the constant vector of dimensions
 208      *
 209      * @return dimensions
 210      */
 211     const SizeVector& getDims() const noexcept {
 212         return dims;
 213     }
 214     /**
 215      * @brief Sets dimensions
 216      *
 217      * @param dims new dimensions
 218      */
 219     void setDims(const SizeVector& dims);
 220
 221     /**
 222      * @brief Returns the memory layout
 223      *
 224      * @return layout
 225      */
 226     Layout getLayout() const {
 227         return layout;
 228     }
 229
 230     /**
 231      * @brief Sets the layout
 232      *
 233      * @param l memory layout
 234      */
 235     void setLayout(Layout l);
 236
 237     /**
 238      * @brief Returns the memory precision
 239      *
 240      * @return precision
 241      */
 242     const Precision& getPrecision() const {
 243         return precision;
 244     }
 245
 246     /**
 247      * @brief Sets the memory precision
 248      *
 249      * @param p precision
 250      */
 251     void setPrecision(const Precision& p) {
 252         precision = p;
 253     }
 254
 255     /**
 256      * @brief Returns the blocking descriptor
 257      *
 258      * @return blocking descriptor
 259      */
 260     const BlockingDesc& getBlockingDesc() const {
 261         return blockingDesc;
 262     }
 263
 264     /**
 265      * @brief The comparison operator for the TensorDesc
 266      *
 267      * @param rhs object to compare
 268      * @return true if objects are equal
 269      */
 270     bool operator==(const TensorDesc& rhs) const;
 271     /**
 272      * @brief The comparison operator for the TensorDesc
 273      *
 274      * @param rhs object to compare
 275      * @return true if objects aren't equal
 276      */
 277     bool operator!=(const TensorDesc& rhs) const;
 278
 279     /**
 280      * @brief Calculates offset for the vector of dimensions
 281      *
 282      * @param v vector of dimensions
 283      * @return offset
 284      */
 285     size_t offset(const SizeVector& v) const;
 286     /**
 287      * @brief Calculates offset for the local offset
 288      *
 289      * @param l local offset
 290      * @return offset
 291      */
 292     size_t offset(size_t l) const;
 293
 294     /**
 295      * @brief Returns the standard layout for dimensions
 296      *
 297      * @param dims the vector of dimensions
 298      * @return the standard memory layout
 299      */
 300     static Layout getLayoutByDims(const SizeVector& dims);
 301
 302 private:
 303     /**
 304      * Memory layout
 305      */
 306     Layout layout;
 307     /**
 308      * @brief blob's dimensions
 309      */
 310     SizeVector dims;
 311     /**
 312      * @brief memory precision
 313      */
 314     Precision precision;
 315     /**
 316      * Detailed information about layout construction
 317      */
 318     BlockingDesc blockingDesc;
 319 };
 320
 321 }  // namespace InferenceEngine