Partition.h
Go to the documentation of this file.
1 /****
2  * Sming Framework Project - Open Source framework for high efficiency native ESP8266 development.
3  * Created 2015 by Skurydin Alexey
4  * http://github.com/SmingHub/Sming
5  * All files of the Sming Core are provided under the LGPL v3 license.
6  *
7  * Partition.h - C++ wrapper for universal partition table support
8  *
9  * Original license for IDF code:
10  *
11  * Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
12  *
13  * Licensed under the Apache License, Version 2.0 (the "License");
14  * you may not use this file except in compliance with the License.
15  * You may obtain a copy of the License at
16  *
17  * http://www.apache.org/licenses/LICENSE-2.0
18  *
19  * Unless required by applicable law or agreed to in writing, software
20  * distributed under the License is distributed on an "AS IS" BASIS,
21  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
22  * See the License for the specific language governing permissions and
23  * limitations under the License.
24  *
25  *
26  ****/
27 #pragma once
28 
29 #include <Data/BitSet.h>
30 #include <Data/CString.h>
31 #include <memory>
32 #include <cassert>
33 
34 #define PARTITION_APP_SUBTYPE_MAP(XX) \
35  XX(factory, 0x00, "Factory application") \
36  XX(ota0, 0x10, "OTA #0") \
37  XX(ota1, 0x11, "OTA #1") \
38  XX(ota2, 0x12, "OTA #2") \
39  XX(ota3, 0x13, "OTA #3") \
40  XX(ota4, 0x14, "OTA #4") \
41  XX(ota5, 0x15, "OTA #5") \
42  XX(ota6, 0x16, "OTA #6") \
43  XX(ota7, 0x17, "OTA #7") \
44  XX(ota8, 0x18, "OTA #8") \
45  XX(ota9, 0x19, "OTA #9") \
46  XX(ota10, 0x1a, "OTA #10") \
47  XX(ota11, 0x1b, "OTA #11") \
48  XX(ota12, 0x1c, "OTA #12") \
49  XX(ota13, 0x1d, "OTA #13") \
50  XX(ota14, 0x1e, "OTA #14") \
51  XX(ota15, 0x1f, "OTA #15") \
52  XX(test, 0x20, "Test application")
53 
54 #define PARTITION_DATA_SUBTYPE_MAP(XX) \
55  XX(ota, 0x00, "OTA selection") \
56  XX(phy, 0x01, "PHY init data") \
57  XX(nvs, 0x02, "NVS") \
58  XX(coreDump, 0x03, "Core Dump data") \
59  XX(nvsKeys, 0x04, "NVS key information") \
60  XX(eFuseEm, 0x05, "eFuse emulation") \
61  XX(sysParam, 0x40, "System Parameters") \
62  XX(rfCal, 0x41, "RF Calibration") \
63  XX(espHttpd, 0x80, "ESPHTTPD") \
64  XX(fat, 0x81, "FAT") \
65  XX(spiffs, 0x82, "SPIFFS") \
66  XX(fwfs, 0xF1, "FWFS") \
67  XX(littlefs, 0xF2, "LittleFS")
68 
69 namespace Storage
70 {
71 class Device;
72 class PartitionTable;
74 
78 class Partition
79 {
80 public:
81  enum class Type : uint8_t {
82  app = 0x00,
83  data = 0x01,
84  storage = 0x02,
85  userMin = 0x40,
86  userMax = 0xFE,
87  invalid = 0xff,
88  any = 0xff,
89  };
90 
91  struct SubType {
92  static constexpr uint8_t any{0xff};
93  static constexpr uint8_t invalid{0xff};
94 
98  enum class App : uint8_t {
99  partitionType = uint8_t(Type::app),
100 #define XX(type, value, desc) type = value,
102 #undef XX
103  ota_min = ota0,
104  ota_max = ota15,
105  any = 0xff
106  };
107 
111  enum class Data : uint8_t {
112  partitionType = uint8_t(Type::data),
113 #define XX(subtype, value, desc) subtype = value,
115 #undef XX
116  any = 0xff
117  };
118  };
119 
120  enum class Flag {
121  encrypted = 0,
122  readOnly = 31,
123  };
124 
125  static constexpr size_t nameSize{16};
126  using Name = char[nameSize];
128 
132  struct Info {
134  uint32_t offset{0};
135  uint32_t size{0};
137  uint8_t subtype{SubType::invalid};
139 
141  {
142  }
143 
144  Info(const String& name, Type type, uint8_t subtype, uint32_t offset, uint32_t size, Flags flags)
145  : name(name), offset(offset), size(size), type(type), subtype(subtype), flags(flags)
146  {
147  }
148  };
149 
151  {
152  }
153 
154  Partition(const Partition& other) : mDevice(other.mDevice), mPart(other.mPart)
155  {
156  }
157 
158  Partition(Device& device, const Info& info) : mDevice(&device), mPart(&info)
159  {
160  }
161 
170  bool verify(Type type, uint8_t subtype) const;
171 
172  bool verify(uint8_t type, uint8_t subtype) const
173  {
174  return verify(Type(type), subtype);
175  }
176 
177  template <typename T> bool verify(T subType) const
178  {
179  return verify(Type(T::partitionType), uint8_t(subType));
180  }
181 
187  static inline SubType::App apptypeOta(uint8_t i)
188  {
189  auto subtype = SubType::App(uint8_t(SubType::App::ota_min) + i);
190  assert(subtype >= SubType::App::ota_min && subtype <= SubType::App::ota_max);
191  return subtype;
192  }
193 
194  explicit operator bool() const
195  {
196  return mDevice != nullptr && mPart != nullptr;
197  }
198 
206  bool read(size_t offset, void* dst, size_t size);
207 
208  template <typename T> typename std::enable_if<std::is_pod<T>::value, bool>::type read(size_t offset, T& value)
209  {
210  return read(offset, &value, sizeof(value));
211  }
212 
221  bool write(size_t offset, const void* src, size_t size);
222 
230  bool erase_range(size_t offset, size_t size);
231 
236  {
238  }
239 
243  uint8_t subType() const
244  {
245  return mPart ? mPart->subtype : SubType::invalid;
246  }
247 
252  uint32_t address() const
253  {
254  return (mPart && mPart->type != Partition::Type::storage) ? mPart->offset : 0;
255  }
256 
261  uint32_t lastAddress() const
262  {
263  return mPart ? (mPart->offset + mPart->size - 1) : 0;
264  }
265 
270  uint32_t size() const
271  {
272  return mPart ? mPart->size : 0;
273  }
274 
278  String name() const
279  {
280  return mPart ? mPart->name.c_str() : nullptr;
281  }
282 
286  Flags flags() const
287  {
288  return mPart ? mPart->flags : 0;
289  }
290 
294  bool isEncrypted() const
295  {
296  return flags()[Flag::encrypted];
297  }
298 
302  bool isReadOnly() const
303  {
304  return mPart ? mPart->flags[Flag::readOnly] : true;
305  }
306 
311  String typeString() const;
312  String longTypeString() const;
322  bool getDeviceAddress(uint32_t& address, size_t size) const;
323 
328  String getDeviceName() const;
329 
334  Device* getDevice() const
335  {
336  return mDevice;
337  }
338 
342  bool contains(uint32_t addr) const
343  {
344  return mPart ? (addr >= mPart->offset && addr <= lastAddress()) : false;
345  }
346 
347  bool operator==(const Partition& other) const
348  {
349  return this == &other;
350  }
351 
352  bool operator==(const char* name) const
353  {
354  return mPart ? mPart->name.equals(name) : false;
355  }
356 
357  bool operator==(const String& name) const
358  {
359  return mPart ? mPart->name.equals(name) : false;
360  }
361 
365  size_t getBlockSize() const;
366 
367 protected:
368  Device* mDevice{nullptr};
369  const Info* mPart{nullptr};
370 
371 private:
372  bool allowRead();
373  bool allowWrite();
374 };
375 
376 } // namespace Storage
377 
379 String toLongString(Storage::Partition::Type type, uint8_t subType);
380 
381 template <typename E> typename std::enable_if<bool(E::partitionType), String>::type toString(E subType)
382 {
383  return toString(Storage::Partition::Type(E::partitionType), uint8_t(subType));
384 }
385 
386 template <typename E> typename std::enable_if<bool(E::partitionType), String>::type toLongString(E subType)
387 {
388  return toLongString(Storage::Partition::Type(E::partitionType), uint8_t(subType));
389 }
uint32_t lastAddress() const
Obtain address of last byte in this this partition.
Definition: Partition.h:261
bool contains(uint32_t addr) const
Determine if given address contained within this partition.
Definition: Partition.h:342
bool operator==(const char *name) const
Definition: Partition.h:352
static constexpr size_t nameSize
Definition: Partition.h:125
#define PARTITION_APP_SUBTYPE_MAP(XX)
Definition: Partition.h:34
std::enable_if< std::is_pod< T >::value, bool >::type read(size_t offset, T &value)
Definition: Partition.h:208
bool operator==(const String &name) const
Definition: Partition.h:357
Device * mDevice
Definition: Partition.h:368
Info(const String &name, Type type, uint8_t subtype, uint32_t offset, uint32_t size, Flags flags)
Definition: Partition.h:144
bool isEncrypted() const
Check state of partition encrypted flag.
Definition: Partition.h:294
bool verify(T subType) const
Definition: Partition.h:177
#define PARTITION_DATA_SUBTYPE_MAP(XX)
Definition: Partition.h:54
bool isReadOnly() const
Check state of partition readOnly flag.
Definition: Partition.h:302
Flag
Definition: Partition.h:120
uint32_t address() const
Obtain partition starting address.
Definition: Partition.h:252
bool getDeviceAddress(uint32_t &address, size_t size) const
Get corresponding storage device address for a given partition offset.
uint8_t subType() const
Obtain partition sub-type.
Definition: Partition.h:243
bool verify(Type type, uint8_t subtype) const
The String class.
Definition: WString.h:136
uint32_t size
Definition: Partition.h:135
uint8_t subtype
Definition: Partition.h:137
Write/erase prohibited.
String getDeviceName() const
Get name of storage device for this partition.
bool write(size_t offset, const void *src, size_t size)
Write data to the partition.
char[nameSize] Name
Definition: Partition.h:126
size_t getBlockSize() const
Obtain smallest allocation unit for erase operations.
bool operator==(const Partition &other) const
Definition: Partition.h:347
Partition::Type type() const
Obtain partition type.
Definition: Partition.h:235
Class to manage a NUL-terminated C-style string When storing persistent strings in RAM the regular St...
Definition: CString.h:26
Type type
Definition: Partition.h:136
String toString(Storage::Partition::Type type, uint8_t subType)
const char * c_str() const
Definition: CString.h:94
Info()
Definition: Partition.h:140
String name() const
Get partition name.
Definition: Partition.h:278
Flags flags() const
Get partition flags.
Definition: Partition.h:286
const Info * mPart
Definition: Partition.h:369
Device * getDevice() const
Get storage device containing this partition.
Definition: Partition.h:334
Type
Definition: Partition.h:81
Represents a storage device (e.g. flash memory)
Definition: Components/Storage/src/include/Storage/Device.h:32
Flags flags
Definition: Partition.h:138
CString name
Definition: Partition.h:133
Partition(const Partition &other)
Definition: Partition.h:154
String toLongString(Storage::Partition::Type type, uint8_t subType)
Partition(Device &device, const Info &info)
Definition: Partition.h:158
Represents a flash partition.
Definition: Partition.h:78
String typeString() const
bool verify(uint8_t type, uint8_t subtype) const
Definition: Partition.h:172
Internal structure describing the binary layout of a partition table entry.
Definition: partition.h:16
String longTypeString() const
uint32_t size() const
Obtain partition size.
Definition: Partition.h:270
bool equals(const CString &other) const
Definition: CString.h:99
static SubType::App apptypeOta(uint8_t i)
Convenience function to get SubType value for the i-th OTA partition.
Definition: Partition.h:187
bool read(size_t offset, void *dst, size_t size)
Read data from the partition.
static constexpr uint8_t invalid
Definition: Partition.h:93
Definition: FileDevice.h:23
App
Application partition type.
Definition: Partition.h:98
uint32_t offset
Definition: Partition.h:134
bool erase_range(size_t offset, size_t size)
Erase part of the partition.
Partition information.
Definition: Partition.h:132
Definition: Partition.h:91
Partition()
Definition: Partition.h:150
Data
Data partition type.
Definition: Partition.h:111
#define XX(name, comment)
Definition: DirectoryTemplate.h:47