Outline ![]()
Files ![]()
loading...
SourceVu![]()
ESP-IDF Framework and Examples![]()
ESP-IDF![]()
components/nvs_flash/private_include/nvs_bootloader_private.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
/*
* SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include <stdint.h>
#include "nvs_constants.h" // NVS_CONST_ENTRY_SIZE and all size related constants shared with cpp implementation of NVS
#include "nvs_bootloader.h" // nvs_bootloader_read_list_t and function prototypes
#include "esp_partition.h" // esp_partition_t
#ifdef __cplusplus
extern "C" {
#endif
// evaluates to true for NVS types fitting single NVS entry. At the moment all NVS_TYPE_U* or NVS_TYPE_I* */
#define NVS_BOOTLOADER_TYPE_FITS_SINGLE_ENTRY(data_type) \
( (data_type == NVS_TYPE_U8) \
||(data_type == NVS_TYPE_I8) \
||(data_type == NVS_TYPE_U16) \
||(data_type == NVS_TYPE_I16) \
||(data_type == NVS_TYPE_U32) \
||(data_type == NVS_TYPE_I32) \
||(data_type == NVS_TYPE_U64) \
||(data_type == NVS_TYPE_I64) \
)
// evaluates to true for NVS types supported by the nvs bootloader code*/
#define NVS_BOOTLOADER_IS_SUPPORTED_TYPE(data_type) \
( (data_type == NVS_TYPE_STR) || NVS_BOOTLOADER_TYPE_FITS_SINGLE_ENTRY(data_type) \
)
// returns length of supported data field in bytes
#define NVS_BOOTLOADER_GET_TYPE_LEN(data_type) \
( (data_type == NVS_TYPE_U8) ? 1 \
:(data_type == NVS_TYPE_I8) ? 1 \
:(data_type == NVS_TYPE_U16) ? 2 \
:(data_type == NVS_TYPE_I16) ? 2 \
:(data_type == NVS_TYPE_U32) ? 4 \
:(data_type == NVS_TYPE_I32) ? 4 \
:(data_type == NVS_TYPE_U64) ? 8 \
:(data_type == NVS_TYPE_I64) ? 8 \
:0 \
)
esp_err_t nvs_bootloader_check_parameters(const char* partition_name,
const size_t read_list_count,
nvs_bootloader_read_list_t read_list[]);
// NVS page header structure
typedef struct {
uint32_t page_state; // page state
uint32_t sequence_number; // sequence number of this page
uint8_t nvs_format_version; // nvs format version
uint8_t reserved[19]; // unused, must be 0xff
uint32_t crc32; // crc32 of everything except page_state
} nvs_bootloader_page_header_t;
// NVS page entry state array structure
// Each entry state is represented by two bits
// There are 126 entries in a page
// The last 4 bits are reserved
typedef struct {
uint8_t entry_states[NVS_CONST_ENTRY_SIZE];
} nvs_bootloader_page_entry_states_t;
// Macro to extract the state of an entry from the entry state structure
#define NVS_BOOTLOADER_GET_ENTRY_STATE(page_entry_states, entry_index) \
((page_entry_states->entry_states[(entry_index) / 4] >> (((entry_index) % 4) * 2)) & 0x03)
typedef struct {
uint8_t data[8];
} nvs_bootloader_entry_data_primitive_type_t;
typedef struct {
uint16_t size;
uint16_t reserved;
uint32_t crc32;
} nvs_bootloader_entry_data_var_len_type_t;
typedef union {
nvs_bootloader_entry_data_primitive_type_t primitive_type;
nvs_bootloader_entry_data_var_len_type_t var_len_type;
} nvs_bootloader_entry_data_t;
// NVS single entry item definition
typedef struct {
uint8_t namespace_index; // namespace index
uint8_t data_type; // data type
uint8_t span; // span
uint8_t chunk_index; // chunk index
uint32_t crc32; // crc32 of the entry
char key[NVS_KEY_NAME_MAX_SIZE]; // key
nvs_bootloader_entry_data_t data; // data, interpreted based on data_type
} nvs_bootloader_single_entry_t;
#define MAX_KEY_LENGTH = (NVS_KEY_NAME_MAX_SIZE - 1);
// read a single entry item from a page
// only reads entries marked as written
// skips items spanning multiple entries
// entry_index is the index of the first entry to read
// item is the output parameter
// entry_index is updated to the index of the next entry
// returns ESP_ERR_NOT_FOUND if no more entries are found
// returns ESP_OK if an entry is found
// returns other error codes if an error occurs
esp_err_t nvs_bootloader_read_next_single_entry_item(const esp_partition_t *partition, const size_t page_index, const nvs_bootloader_page_entry_states_t *entry_states, uint8_t *entry_index, nvs_bootloader_single_entry_t *item);
// read a block of data from the entries from a page
// the block is read starting from the offset specified as entry_index of entry
// the length of the block is specified in bytes in parameter block_len
// the block is read into the buffer pointed to by block
// before accessing the entries, the entry states are checked and the entries are read only if they are marked as written
// if any of the entries that needs to be read is not in the state written, the function returns ESP_ERR_INVALID_STATE
// if the block is not fully read after reaching end of the page, the function returns ESP_ERR_INVALID_STATE
// if the block is fully read, the function returns ESP_OK
esp_err_t nvs_bootloader_read_entries_block(const esp_partition_t *partition, const size_t page_index, const nvs_bootloader_page_entry_states_t *entry_states, const size_t entry_index, const size_t block_len, uint8_t *block);
// visitor function parameters for reading the page header
typedef struct {
size_t no_active_pages;
size_t no_freeing_pages;
} nvs_bootloader_page_visitor_param_get_page_states_t;
// visitor function parameters for reading the namespaces from pages and the key - value pairs from pages
typedef struct {
const bool skip_active_page;
const size_t read_list_count;
nvs_bootloader_read_list_t *read_list;
} nvs_bootloader_page_visitor_param_read_entries_t;
// visitor function parameter union type declaration
typedef union {
nvs_bootloader_page_visitor_param_get_page_states_t *get_page_states;
nvs_bootloader_page_visitor_param_read_entries_t *read_entries;
} nvs_bootloader_page_visitor_param_t;
// visitor function type declaration
typedef esp_err_t (*nvs_bootloader_page_visitor_t)(nvs_bootloader_page_visitor_param_t *visitor_param,
const esp_partition_t *partition,
const size_t page_index,
const nvs_bootloader_page_header_t *page_header);
// visit all pages in the partition
esp_err_t nvs_bootloader_visit_pages(const esp_partition_t *partition,
nvs_bootloader_page_visitor_t visitor,
nvs_bootloader_page_visitor_param_t *visitor_param);
// read page header
esp_err_t nvs_bootloader_read_page_header(const esp_partition_t *partition,
const size_t page_index,
const nvs_bootloader_page_header_t *page_header);
// read entry states from a page
esp_err_t nvs_bootloader_read_page_entry_states(const esp_partition_t *partition,
const size_t page_index,
nvs_bootloader_page_entry_states_t *entry_states);
// populates the page header for a given page
esp_err_t nvs_bootloader_page_visitor_get_page_states(nvs_bootloader_page_visitor_param_t *visitor_param,
const esp_partition_t *partition,
const size_t page_index,
const nvs_bootloader_page_header_t *page_header);
// populates the namespace indexes found on a page
esp_err_t nvs_bootloader_page_visitor_get_namespaces(nvs_bootloader_page_visitor_param_t *visitor_param,
const esp_partition_t *partition,
const size_t page_index,
const nvs_bootloader_page_header_t *page_header);
// populates the key value pairs found on a page
esp_err_t nvs_bootloader_page_visitor_get_key_value_pairs(nvs_bootloader_page_visitor_param_t *visitor_param,
const esp_partition_t *partition,
const size_t page_index,
const nvs_bootloader_page_header_t *page_header);
// check if the item header is consistent - crc32 matches, namespace index is valid, data type is valid and other fields are consistent
bool nvs_bootloader_check_item_header_consistency(const nvs_bootloader_single_entry_t *item,
const uint8_t entry_index);
#ifdef __cplusplus
}
#endif
Details ![]()
Show: from Types: Columns: ![]( "Show Project Names")
![]( "Show Locations")
![]( "Show Referring Symbols")
![]( "Show Scope")
This file uses the notable symbols shown below. Click anywhere in the file to view more details.