Branch data Line data Source code
1 : : /*
2 : : * This file is part of the MicroPython project, http://micropython.org/
3 : : *
4 : : * The MIT License (MIT)
5 : : *
6 : : * Copyright (c) 2022 Damien P. George
7 : : *
8 : : * Permission is hereby granted, free of charge, to any person obtaining a copy
9 : : * of this software and associated documentation files (the "Software"), to deal
10 : : * in the Software without restriction, including without limitation the rights
11 : : * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12 : : * copies of the Software, and to permit persons to whom the Software is
13 : : * furnished to do so, subject to the following conditions:
14 : : *
15 : : * The above copyright notice and this permission notice shall be included in
16 : : * all copies or substantial portions of the Software.
17 : : *
18 : : * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 : : * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 : : * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21 : : * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 : : * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23 : : * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
24 : : * THE SOFTWARE.
25 : : */
26 : :
27 : : // ROMFS filesystem format
28 : : // =======================
29 : : //
30 : : // ROMFS is a flexible and extensible filesystem format designed to represent a
31 : : // directory hierarchy with files, where those files are read-only and their data
32 : : // can be memory mapped.
33 : : //
34 : : // Concepts:
35 : : // - varuint: An unsigned integer that is encoded in a variable number of bytes. It is
36 : : // stored big-endian with the high bit of the byte set if there are following bytes.
37 : : // - record: A variable sized element with a type. It is stored as two varuint's and then
38 : : // a payload. The first varuint is the record kind and the second varuint is the
39 : : // payload length (which may be zero bytes long).
40 : : //
41 : : // A ROMFS filesystem is a record with record kind 0x14a6b1, chosen so the encoded value
42 : : // is 0xd2-0xcd-0x31 which is "RM1" with the first two bytes having their high bit set.
43 : : // If the ROMFS record's payload is non-empty then it contains records.
44 : : //
45 : : // Record types:
46 : : // - 0 = unused, can be used to detect corruption of the filesystem.
47 : : // - 1 = padding/comments, can contain any data in their payload.
48 : : // - 2 = verbatim data, used to store file data.
49 : : // - 3 = indirect data, pointer to offset within the ROMFS payload.
50 : : // - 4 = a directory: payload contains a varuint which is the length of the directory
51 : : // name in bytes, then the name, then optional nested records for the contents
52 : : // of the directory (including optional metadata).
53 : : // - 5 = a file: payload contains a varuint which is the length of the filename in bytes
54 : : // then the name, then optional nested records.
55 : : //
56 : : // Remarks:
57 : : // - A varuint can be padded if needed by prepending with one or more 0x80 bytes. This
58 : : // padding does not change any semantics.
59 : : // - The size of the ROMFS record (including kind and length and payload) must be a
60 : : // multiple of 2 (because it's not possible to add a padding record of one byte).
61 : : // - File data can be optionally aligned using padding records and/or indirect data
62 : : // records.
63 : : // - There is no limit to the size of directory/file names or file data.
64 : : //
65 : : // Unknown record types must be skipped over. They may in the future add optional
66 : : // features, while still retaining backwards compatibility. Such features may be:
67 : : // - Alignment requirements of the ROMFS record.
68 : : // - Timestamps on directories/files.
69 : : // - A precomputed hash of a file, or other metadata.
70 : : // - An optimised lookup table indexing the directory hierarchy.
71 : :
72 : : #include <string.h>
73 : :
74 : : #include "py/bc.h"
75 : : #include "py/runtime.h"
76 : : #include "py/mperrno.h"
77 : : #include "extmod/vfs.h"
78 : : #include "extmod/vfs_rom.h"
79 : :
80 : : #if MICROPY_VFS_ROM
81 : :
82 : : #define ROMFS_SIZE_MIN (4)
83 : : #define ROMFS_HEADER_BYTE0 (0x80 | 'R')
84 : : #define ROMFS_HEADER_BYTE1 (0x80 | 'M')
85 : : #define ROMFS_HEADER_BYTE2 (0x00 | '1')
86 : :
87 : : // Values for `record_kind_t`.
88 : : #define ROMFS_RECORD_KIND_UNUSED (0)
89 : : #define ROMFS_RECORD_KIND_PADDING (1)
90 : : #define ROMFS_RECORD_KIND_DATA_VERBATIM (2)
91 : : #define ROMFS_RECORD_KIND_DATA_POINTER (3)
92 : : #define ROMFS_RECORD_KIND_DIRECTORY (4)
93 : : #define ROMFS_RECORD_KIND_FILE (5)
94 : :
95 : : typedef mp_uint_t record_kind_t;
96 : :
97 : : struct _mp_obj_vfs_rom_t {
98 : : mp_obj_base_t base;
99 : : mp_obj_t memory;
100 : : const uint8_t *filesystem;
101 : : const uint8_t *filesystem_end;
102 : : };
103 : :
104 : 470 : static record_kind_t extract_record(const uint8_t **fs, const uint8_t **fs_next) {
105 : 470 : record_kind_t record_kind = mp_decode_uint(fs);
106 : 470 : mp_uint_t record_len = mp_decode_uint(fs);
107 : 470 : *fs_next = *fs + record_len;
108 : 470 : return record_kind;
109 : : }
110 : :
111 : 72 : static void extract_data(mp_obj_vfs_rom_t *self, const uint8_t *fs, const uint8_t *fs_top, size_t *size_out, const uint8_t **data_out) {
112 : 72 : *size_out = 0;
113 : 72 : *data_out = NULL;
114 [ + - ]: 76 : while (fs < fs_top) {
115 : 76 : const uint8_t *fs_next;
116 : 76 : record_kind_t record_kind = extract_record(&fs, &fs_next);
117 [ + + ]: 76 : if (record_kind == ROMFS_RECORD_KIND_DATA_VERBATIM) {
118 : : // Verbatim data.
119 : 58 : *size_out = fs_next - fs;
120 : 58 : *data_out = fs;
121 : 72 : break;
122 [ + + ]: 18 : } else if (record_kind == ROMFS_RECORD_KIND_DATA_POINTER) {
123 : : // Pointer to data.
124 : 14 : *size_out = mp_decode_uint(&fs);
125 : 14 : *data_out = self->filesystem + mp_decode_uint(&fs);
126 : 14 : break;
127 : : } else {
128 : : // Skip this record.
129 : 4 : fs = fs_next;
130 : : }
131 : : }
132 : 72 : }
133 : :
134 : : // Searches for `path` in the filesystem.
135 : : // `path` must be null-terminated.
136 : 102 : mp_import_stat_t mp_vfs_rom_search_filesystem(mp_obj_vfs_rom_t *self, const char *path, size_t *size_out, const uint8_t **data_out) {
137 : 102 : const uint8_t *fs = self->filesystem;
138 : 102 : const uint8_t *fs_top = self->filesystem_end;
139 : 102 : size_t path_len = strlen(path);
140 [ + + ]: 102 : if (*path == '/') {
141 : : // An optional slash at the start of the path enters the top-level filesystem.
142 : 84 : ++path;
143 : 84 : --path_len;
144 : : }
145 [ + + ]: 350 : while (path_len > 0 && fs < fs_top) {
146 : 292 : const uint8_t *fs_next;
147 : 292 : record_kind_t record_kind = extract_record(&fs, &fs_next);
148 [ + + ]: 292 : if (record_kind == ROMFS_RECORD_KIND_DIRECTORY || record_kind == ROMFS_RECORD_KIND_FILE) {
149 : : // A directory or file record.
150 : 228 : mp_uint_t name_len = mp_decode_uint(&fs);
151 [ + + ]: 228 : if ((name_len == path_len
152 [ + + + + ]: 126 : || (name_len < path_len && path[name_len] == '/'))
153 [ + + ]: 122 : && memcmp(path, fs, name_len) == 0) {
154 : : // Name matches, so enter this record.
155 : 74 : fs += name_len;
156 : 74 : fs_top = fs_next;
157 : 74 : path += name_len;
158 : 74 : path_len -= name_len;
159 [ + + ]: 74 : if (record_kind == ROMFS_RECORD_KIND_DIRECTORY) {
160 : : // Continue searching in this directory.
161 [ + + ]: 30 : if (*path == '/') {
162 : 20 : ++path;
163 : 20 : --path_len;
164 : : }
165 : : } else {
166 : : // Return this file.
167 [ + - ]: 44 : if (path_len != 0) {
168 : 44 : return MP_IMPORT_STAT_NO_EXIST;
169 : : }
170 [ + + ]: 44 : if (size_out != NULL) {
171 : 36 : extract_data(self, fs, fs_top, size_out, data_out);
172 : : }
173 : 44 : return MP_IMPORT_STAT_FILE;
174 : : }
175 : : } else {
176 : : // Skip this directory/file record.
177 : 154 : fs = fs_next;
178 : : }
179 : : } else {
180 : : // Skip this record.
181 : 64 : fs = fs_next;
182 : : }
183 : : }
184 [ + + ]: 58 : if (path_len == 0) {
185 [ + - ]: 38 : if (size_out != NULL) {
186 : 38 : *size_out = fs_top - fs;
187 : 38 : *data_out = fs;
188 : : }
189 : 38 : return MP_IMPORT_STAT_DIR;
190 : : }
191 : : return MP_IMPORT_STAT_NO_EXIST;
192 : : }
193 : :
194 : 48 : static mp_obj_t vfs_rom_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
195 : 48 : mp_arg_check_num(n_args, n_kw, 1, 1, false);
196 : :
197 : 48 : mp_obj_vfs_rom_t *self = m_new_obj(mp_obj_vfs_rom_t);
198 : 48 : self->base.type = type;
199 : 48 : self->memory = args[0];
200 : :
201 : : // Get the ROMFS memory region.
202 : 48 : mp_buffer_info_t bufinfo;
203 : 48 : mp_get_buffer_raise(self->memory, &bufinfo, MP_BUFFER_READ);
204 [ + + ]: 46 : if (bufinfo.len < ROMFS_SIZE_MIN) {
205 : 4 : mp_raise_OSError(MP_ENODEV);
206 : : }
207 : 42 : self->filesystem = bufinfo.buf;
208 : :
209 : : // Verify it is a ROMFS.
210 [ + + ]: 42 : if (!(self->filesystem[0] == ROMFS_HEADER_BYTE0
211 [ + - ]: 40 : && self->filesystem[1] == ROMFS_HEADER_BYTE1
212 [ - + ]: 40 : && self->filesystem[2] == ROMFS_HEADER_BYTE2)) {
213 : 2 : mp_raise_OSError(MP_ENODEV);
214 : : }
215 : :
216 : : // The ROMFS is a record itself, so enter into it and compute its limit.
217 : 40 : extract_record(&self->filesystem, &self->filesystem_end);
218 : :
219 : 40 : return MP_OBJ_FROM_PTR(self);
220 : : }
221 : :
222 : 22 : static mp_obj_t vfs_rom_mount(mp_obj_t self_in, mp_obj_t readonly, mp_obj_t mkfs) {
223 : 22 : (void)self_in;
224 : 22 : (void)readonly;
225 [ + + ]: 22 : if (mp_obj_is_true(mkfs)) {
226 : 2 : mp_raise_OSError(MP_EPERM);
227 : : }
228 : 20 : return mp_const_none;
229 : : }
230 : : static MP_DEFINE_CONST_FUN_OBJ_3(vfs_rom_mount_obj, vfs_rom_mount);
231 : :
232 : : // mp_vfs_rom_file_open is implemented in vfs_rom_file.c.
233 : : static MP_DEFINE_CONST_FUN_OBJ_3(vfs_rom_open_obj, mp_vfs_rom_file_open);
234 : :
235 : 6 : static mp_obj_t vfs_rom_chdir(mp_obj_t self_in, mp_obj_t path_in) {
236 : 6 : mp_obj_vfs_rom_t *self = MP_OBJ_TO_PTR(self_in);
237 : 6 : const char *path = mp_vfs_rom_get_path_str(self, path_in);
238 [ + - + + ]: 6 : if (path[0] == '/' && path[1] == '\0') {
239 : : // Allow chdir to the root of the filesystem.
240 : 4 : } else {
241 : : // Don't allow chdir to any subdirectory (not currently implemented).
242 : 2 : mp_raise_OSError(MP_EOPNOTSUPP);
243 : : }
244 : 4 : return mp_const_none;
245 : : }
246 : : static MP_DEFINE_CONST_FUN_OBJ_2(vfs_rom_chdir_obj, vfs_rom_chdir);
247 : :
248 : : typedef struct _vfs_rom_ilistdir_it_t {
249 : : mp_obj_base_t base;
250 : : mp_fun_1_t iternext;
251 : : mp_obj_vfs_rom_t *vfs_rom;
252 : : bool is_str;
253 : : const uint8_t *index;
254 : : const uint8_t *index_top;
255 : : } vfs_rom_ilistdir_it_t;
256 : :
257 : 68 : static mp_obj_t vfs_rom_ilistdir_it_iternext(mp_obj_t self_in) {
258 : 68 : vfs_rom_ilistdir_it_t *self = MP_OBJ_TO_PTR(self_in);
259 : :
260 [ + + ]: 82 : while (self->index < self->index_top) {
261 : 62 : const uint8_t *index_next;
262 : 62 : record_kind_t record_kind = extract_record(&self->index, &index_next);
263 : 62 : uint32_t type;
264 : 62 : mp_uint_t name_len;
265 : 62 : size_t data_len;
266 [ + + ]: 62 : if (record_kind == ROMFS_RECORD_KIND_DIRECTORY || record_kind == ROMFS_RECORD_KIND_FILE) {
267 : : // A directory or file record.
268 : 48 : name_len = mp_decode_uint(&self->index);
269 [ + + ]: 48 : if (record_kind == ROMFS_RECORD_KIND_DIRECTORY) {
270 : : // A directory.
271 : 12 : type = MP_S_IFDIR;
272 : 12 : data_len = index_next - self->index - name_len;
273 : : } else {
274 : : // A file.
275 : 36 : type = MP_S_IFREG;
276 : 36 : const uint8_t *data_value;
277 : 36 : extract_data(self->vfs_rom, self->index + name_len, index_next, &data_len, &data_value);
278 : : }
279 : : } else {
280 : : // Skip this record.
281 : 14 : self->index = index_next;
282 : 14 : continue;
283 : : }
284 : :
285 : 48 : const uint8_t *name_str = self->index;
286 : 48 : self->index = index_next;
287 : :
288 : : // Make 4-tuple with info about this entry: (name, attr, inode, size)
289 : 48 : mp_obj_tuple_t *t = MP_OBJ_TO_PTR(mp_obj_new_tuple(4, NULL));
290 : :
291 [ + + ]: 48 : if (self->is_str) {
292 : 42 : t->items[0] = mp_obj_new_str((const char *)name_str, name_len);
293 : : } else {
294 : 6 : t->items[0] = mp_obj_new_bytes(name_str, name_len);
295 : : }
296 : :
297 : 48 : t->items[1] = MP_OBJ_NEW_SMALL_INT(type);
298 : 48 : t->items[2] = MP_OBJ_NEW_SMALL_INT(0);
299 : 48 : t->items[3] = mp_obj_new_int(data_len);
300 : :
301 : 48 : return MP_OBJ_FROM_PTR(t);
302 : : }
303 : :
304 : : return MP_OBJ_STOP_ITERATION;
305 : : }
306 : :
307 : 22 : static mp_obj_t vfs_rom_ilistdir(mp_obj_t self_in, mp_obj_t path_in) {
308 : 22 : mp_obj_vfs_rom_t *self = MP_OBJ_TO_PTR(self_in);
309 : 22 : vfs_rom_ilistdir_it_t *iter = m_new_obj(vfs_rom_ilistdir_it_t);
310 : 22 : iter->base.type = &mp_type_polymorph_iter;
311 : 22 : iter->iternext = vfs_rom_ilistdir_it_iternext;
312 : 22 : iter->vfs_rom = self;
313 : 22 : iter->is_str = mp_obj_get_type(path_in) == &mp_type_str;
314 : 22 : const char *path = mp_vfs_rom_get_path_str(self, path_in);
315 : 22 : size_t size;
316 [ + + ]: 22 : if (mp_vfs_rom_search_filesystem(self, path, &size, &iter->index) != MP_IMPORT_STAT_DIR) {
317 : 2 : mp_raise_OSError(MP_ENOENT);
318 : : }
319 : 20 : iter->index_top = iter->index + size;
320 : 20 : return MP_OBJ_FROM_PTR(iter);
321 : : }
322 : : static MP_DEFINE_CONST_FUN_OBJ_2(vfs_rom_ilistdir_obj, vfs_rom_ilistdir);
323 : :
324 : 22 : static mp_obj_t vfs_rom_stat(mp_obj_t self_in, mp_obj_t path_in) {
325 : 22 : mp_obj_vfs_rom_t *self = MP_OBJ_TO_PTR(self_in);
326 : 22 : const char *path = mp_vfs_rom_get_path_str(self, path_in);
327 : 22 : size_t file_size;
328 : 22 : const uint8_t *file_data;
329 : 22 : mp_import_stat_t stat = mp_vfs_rom_search_filesystem(self, path, &file_size, &file_data);
330 [ + + ]: 22 : if (stat == MP_IMPORT_STAT_NO_EXIST) {
331 : 4 : mp_raise_OSError(MP_ENOENT);
332 : : }
333 : 18 : mp_obj_tuple_t *t = MP_OBJ_TO_PTR(mp_obj_new_tuple(10, NULL));
334 [ + + ]: 18 : t->items[0] = MP_OBJ_NEW_SMALL_INT(stat == MP_IMPORT_STAT_FILE ? MP_S_IFREG : MP_S_IFDIR); // st_mode
335 : 18 : t->items[1] = MP_OBJ_NEW_SMALL_INT(0); // st_ino
336 : 18 : t->items[2] = MP_OBJ_NEW_SMALL_INT(0); // st_dev
337 : 18 : t->items[3] = MP_OBJ_NEW_SMALL_INT(0); // st_nlink
338 : 18 : t->items[4] = MP_OBJ_NEW_SMALL_INT(0); // st_uid
339 : 18 : t->items[5] = MP_OBJ_NEW_SMALL_INT(0); // st_gid
340 : 18 : t->items[6] = MP_OBJ_NEW_SMALL_INT(file_size); // st_size
341 : 18 : t->items[7] = MP_OBJ_NEW_SMALL_INT(0); // st_atime
342 : 18 : t->items[8] = MP_OBJ_NEW_SMALL_INT(0); // st_mtime
343 : 18 : t->items[9] = MP_OBJ_NEW_SMALL_INT(0); // st_ctime
344 : 18 : return MP_OBJ_FROM_PTR(t);
345 : : }
346 : : static MP_DEFINE_CONST_FUN_OBJ_2(vfs_rom_stat_obj, vfs_rom_stat);
347 : :
348 : 4 : static mp_obj_t vfs_rom_statvfs(mp_obj_t self_in, mp_obj_t path_in) {
349 : 4 : mp_obj_vfs_rom_t *self = MP_OBJ_TO_PTR(self_in);
350 : 4 : (void)path_in;
351 : 4 : size_t filesystem_len = self->filesystem_end - self->filesystem;
352 : 4 : mp_obj_tuple_t *t = MP_OBJ_TO_PTR(mp_obj_new_tuple(10, NULL));
353 : 4 : t->items[0] = MP_OBJ_NEW_SMALL_INT(1); // f_bsize
354 : 4 : t->items[1] = MP_OBJ_NEW_SMALL_INT(0); // f_frsize
355 : 4 : t->items[2] = mp_obj_new_int_from_uint(filesystem_len); // f_blocks
356 : 4 : t->items[3] = MP_OBJ_NEW_SMALL_INT(0); // f_bfree
357 : 4 : t->items[4] = MP_OBJ_NEW_SMALL_INT(0); // f_bavail
358 : 4 : t->items[5] = MP_OBJ_NEW_SMALL_INT(0); // f_files
359 : 4 : t->items[6] = MP_OBJ_NEW_SMALL_INT(0); // f_ffree
360 : 4 : t->items[7] = MP_OBJ_NEW_SMALL_INT(0); // f_favail
361 : 4 : t->items[8] = MP_OBJ_NEW_SMALL_INT(0); // f_flags
362 : 4 : t->items[9] = MP_OBJ_NEW_SMALL_INT(32767); // f_namemax
363 : 4 : return MP_OBJ_FROM_PTR(t);
364 : : }
365 : : static MP_DEFINE_CONST_FUN_OBJ_2(vfs_rom_statvfs_obj, vfs_rom_statvfs);
366 : :
367 : : static const mp_rom_map_elem_t vfs_rom_locals_dict_table[] = {
368 : : { MP_ROM_QSTR(MP_QSTR_mount), MP_ROM_PTR(&vfs_rom_mount_obj) },
369 : : { MP_ROM_QSTR(MP_QSTR_umount), MP_ROM_PTR(&mp_identity_obj) },
370 : : { MP_ROM_QSTR(MP_QSTR_open), MP_ROM_PTR(&vfs_rom_open_obj) },
371 : :
372 : : { MP_ROM_QSTR(MP_QSTR_chdir), MP_ROM_PTR(&vfs_rom_chdir_obj) },
373 : : { MP_ROM_QSTR(MP_QSTR_ilistdir), MP_ROM_PTR(&vfs_rom_ilistdir_obj) },
374 : : { MP_ROM_QSTR(MP_QSTR_stat), MP_ROM_PTR(&vfs_rom_stat_obj) },
375 : : { MP_ROM_QSTR(MP_QSTR_statvfs), MP_ROM_PTR(&vfs_rom_statvfs_obj) },
376 : : };
377 : : static MP_DEFINE_CONST_DICT(vfs_rom_locals_dict, vfs_rom_locals_dict_table);
378 : :
379 : 18 : static mp_import_stat_t mp_vfs_rom_import_stat(void *self_in, const char *path) {
380 : 18 : mp_obj_vfs_rom_t *self = MP_OBJ_TO_PTR(self_in);
381 : 18 : return mp_vfs_rom_search_filesystem(self, path, NULL, NULL);
382 : : }
383 : :
384 : : static const mp_vfs_proto_t vfs_rom_proto = {
385 : : .import_stat = mp_vfs_rom_import_stat,
386 : : };
387 : :
388 : : MP_DEFINE_CONST_OBJ_TYPE(
389 : : mp_type_vfs_rom,
390 : : MP_QSTR_VfsRom,
391 : : MP_TYPE_FLAG_NONE,
392 : : make_new, vfs_rom_make_new,
393 : : protocol, &vfs_rom_proto,
394 : : locals_dict, &vfs_rom_locals_dict
395 : : );
396 : :
397 : : #endif // MICROPY_VFS_ROM
|
