inference-engine/include/ie_layouts.h

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