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, 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, SizeVector dimOffsets,
  70                  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, 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, 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         bool inconsistentLayout = true;
 237         switch (l) {
 238         case Layout::SCALAR:
 239             inconsistentLayout = !dims.empty();
 240             break;
 241         case Layout::C:
 242             inconsistentLayout = dims.size() != 1;
 243             break;
 244         case Layout::BLOCKED:
 245         case Layout::ANY:
 246             inconsistentLayout = false;
 247             break;
 248         case Layout::GOIDHW:
 249             inconsistentLayout = dims.size() != 6;
 250             break;
 251         case Layout::NCDHW:
 252         case Layout::NDHWC:
 253         case Layout::OIDHW:
 254         case Layout::GOIHW:
 255             inconsistentLayout = dims.size() != 5;
 256             break;
 257         case Layout::OIHW:
 258         case Layout::NCHW:
 259         case Layout::NHWC:
 260             inconsistentLayout = dims.size() != 4;
 261             break;
 262         case Layout::CHW:
 263             inconsistentLayout = dims.size() != 3;
 264             break;
 265         case Layout::CN:
 266         case Layout::NC:
 267         case Layout::HW:
 268             inconsistentLayout = dims.size() != 2;
 269             break;
 270         default:
 271             break;
 272         }
 273         if (inconsistentLayout)
 274             THROW_IE_EXCEPTION << "Size of dims(" << std::to_string(dims.size()) << ") and format(" << l
 275                                << ") are inconsistent.";
 276         layout = l;
 277     }
 278
 279     /**
 280      * @brief Returns the memory precision
 281      *
 282      * @return precision
 283      */
 284     const Precision& getPrecision() const {
 285         return precision;
 286     }
 287
 288     /**
 289      * @brief Sets the memory precision
 290      *
 291      * @param p precision
 292      */
 293     void setPrecision(const Precision& p) {
 294         precision = p;
 295     }
 296
 297     /**
 298      * @brief Returns the blocking descriptor
 299      *
 300      * @return blocking descriptor
 301      */
 302     const BlockingDesc& getBlockingDesc() const {
 303         return blockingDesc;
 304     }
 305
 306     /**
 307      * @brief The comparison operator for the TensorDesc
 308      *
 309      * @param rhs object to compare
 310      * @return true if objects are equal
 311      */
 312     bool operator==(const TensorDesc& rhs) const;
 313     /**
 314      * @brief The comparison operator for the TensorDesc
 315      *
 316      * @param rhs object to compare
 317      * @return true if objects aren't equal
 318      */
 319     bool operator!=(const TensorDesc& rhs) const;
 320
 321     /**
 322      * @brief Calculates offset for the vector of dimensions
 323      *
 324      * @param v vector of dimensions
 325      * @return offset
 326      */
 327     size_t offset(const SizeVector& v) const;
 328     /**
 329      * @brief Calculates offset for the local offset
 330      *
 331      * @param l local offset
 332      * @return offset
 333      */
 334     size_t offset(size_t l) const;
 335
 336     /**
 337      * @brief Returns the standard layout for dimensions
 338      *
 339      * @param dims the vector of dimensions
 340      * @return the standard memory layout
 341      */
 342     static Layout getLayoutByDims(SizeVector dims);
 343
 344 private:
 345     /**
 346      * Memory layout
 347      */
 348     Layout layout;
 349     /**
 350      * @brief blob's dimensions
 351      */
 352     SizeVector dims;
 353     /**
 354      * @brief memory precision
 355      */
 356     Precision precision;
 357     /**
 358      * Detailed information about layout construction
 359      */
 360     BlockingDesc blockingDesc;
 361 };
 362
 363 }  // namespace InferenceEngine