-
-
Notifications
You must be signed in to change notification settings - Fork 2
/
flash_fs.txt
446 lines (368 loc) · 20.1 KB
/
flash_fs.txt
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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
=================================================================================================
File....... flash_fs.spin2
Purpose.... This object is the full flash file system driver for the P2
it manages all but the first 512KB of the flash chip (where the boot image is stored)
it provides a standard (ANSI C like) file system interface to the flash chip
Author..... Chip Gracey
Conrtributions..... Jon McPhalen, Stephen M Moraco
-- see below for terms of use
E-mail..... stephen@ironsheep.biz
Started.... AUG 2023
Updated.... 22 DEC 2023
=================================================================================================
v1.2.0 - initial release of flash_fs with full API
v1.2.1 - revised seek() method parameters - can now seek relative to current position in file
v1.3.0 - update for flexspin compatibility, seek() returns file position, write() returns bytes written
v1.3.1 - more update for flexspin compatibility, adjusted seek(), read() and write() add file_size_for_handle()
v1.4.0 - Adjustments allowing multi-cog support
v2.0.0 - Add read/modify/write, non-destructive mount check can_mount(), and create_file()
-------------------------------------------------------------------------------------------------
Object "flash_fs" Interface:
PUB null()
PUB version() : result
PUB serial_number() : sn_hi, sn_lo
PUB format() : status
PUB mount() : status
PUB can_mount() : bool
PUB mounted() : bool
PUB unmount() : status
PUB error() : status
PUB open(p_filename, mode) : handle
PUB open_circular(p_filename, mode, max_file_length) : handle
PUB flush(handle) : status
PUB close(handle) : status
PUB rename(p_cur_filename, p_new_filename) : status
PUB delete(p_filename) : status
PUB create_file(p_filename, fill_value, byte_count) : status
PUB exists(p_filename) : bool
PUB file_size(p_filename) : size_in_bytes
PUB file_size_for_handle(handle) : size_in_bytes
PUB file_size_unused(p_filename) : size_in_bytes_unused
PUB seek(handle, position, whence) : end_position
PUB write(handle, p_buffer, count) : bytes_written
PUB wr_byte(handle, byte_value) : status
PUB wr_word(handle, word_value) : status
PUB wr_long(handle, long_value) : status
PUB wr_str(handle, p_str) : status
PUB read(handle, p_buffer, count) : bytes_read
PUB rd_byte(handle) : byte_value
PUB rd_word(handle) : word_value
PUB rd_long(handle) : long_value
PUB rd_str(handle, p_str, count) : bytes_read
PUB directory(p_block_id, p_filename, p_file_size) : status
PUB stats() : used_blocks, free_blocks, file_count
PUB string_for_error(status) : p_interpretation
__________
PUB null()
This is not an application
-- (invoke format() or mount() to use the flash file system)
______________________
PUB version() : result
Returns flash file system library version as integer
-- e.g., version 120 is 1.2.0 (major, minor, bugfix)
__________________________________
PUB serial_number() : sn_hi, sn_lo
Returns 64-bit unique id of flash chip
@returns sn_hi - high 32 bits of 64-bit unique id of flash chip (0 when error return)
@returns sn_lo - low 32 bits of 64-bit unique id of flash chip (0 when error return)
(sets error() to E_NOT_MOUNTED and returns 0,0 if filesystem has not been mounted)
_____________________
PUB format() : status
Format the file system blocks and (re)mount it
@returns status - 0 (SUCCESS) if successful,
.. E_BAD_BLOCKS_REMOVED if BAD blocks were found and fixed,
.. E_NO_LOCK_AVAIL if all 16 LOCKs are in use,
.. E_NOT_MOUNTED if filesystem has not been mounted
____________________
PUB mount() : status
Mount the filesystem so it is ready to use after scanning all blocks and initilizing internal tables and buffers
@returns status - E_BAD_BLOCKS_REMOVED if BAD blocks were found and fixed,
.. E_NO_LOCK_AVAIL if all 16 LOCKs are in use, otherwise 0 for success
______________________
PUB can_mount() : bool
Check entire flash - to see if it would mount without modifying any blocks
@returns bool - True/False where True means no blocks would be changed by mount
____________________
PUB mounted() : bool
Returns the mounted status of the filesystem
-- (saves us from having to find creative ways to get an error code telling us this)
@returns bool - True/False where True means the filesystem has already been successfully mounted
______________________
PUB unmount() : status
Prepare for shutdown / power-off by closing any open files
-- (no further access allowed until a subsequent mount())
@returns status - 0 (SUCCESS) if successful,
.. E_NOT_MOUNTED if filesystem had not been mounted
____________________
PUB error() : status
Returns the error code from most recent operation
@returns result - latest error code (SUCCESS, for no error)
___________________________________
PUB open(p_filename, mode) : handle
Open file in mode; return handle (0..MAX_FILES_OPEN-1) if successful
@param p_filename - address of a zstring containing the filename
@param mode - the mode in which to open the file:
-- mode "r", "R" to read from an existing file
-- mode "w", "W" to write to a new file (overwrites existing file)
-- mode "a", "A" to append to the end of an existing file (file is created if doesn't exist)
-- mode "r+", "R+" to read/modify/write within an existing file
-- mode "w+", "W+" to read/modify/write within a new file (overwrites existing file)
@returns handle - handle to open file if successful,
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_NO_HANDLE if no handle is available,
.. E_FILE_MODE if mode letter(s) is/are invalid,
.. E_DRIVE_FULL if flash filesystem is full (write/append mode),
.. E_FILE_OPEN if file is already open,
.. E_FILE_NOT_FOUND if file does not exist (read mode)
_____________________________________________________________
PUB open_circular(p_filename, mode, max_file_length) : handle
Open circular file of max_file_length in mode; return handle (0..MAX_FILES_OPEN-1) if successful
@param p_filename - address of a zstring containing the filename
@param mode - the mode in which to open the file:
-- mode "a", "A" to append to the end of an existing circular file (file created if doesn't exist)
-- mode "r", "R" to read from an existing circular file
@param max_file_length - constrain the file to this length (in bytes)
@returns handle - handle to open file if successful,
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_NO_HANDLE if no handle is available,
.. E_BAD_FILE_LENGTH if file length is negative or zero,
.. E_FILE_MODE if mode letter(s) is/are invalid,
.. E_FILE_NOT_FOUND if file does not exist (read mode),
.. E_DRIVE_FULL if flash filesystem is full (write/append mode),
.. E_FILE_OPEN if file is already open
__________________________
PUB flush(handle) : status
Logically, "close", then "reopen file in same mode" (but you don't lose the file handle)
-- (forces any pending writes to be completed)
@param handle - a handle to an open file
@returns status - 0 (SUCCESS) if successful,
.. E_FILE_MODE if close doesn't recognize this file mode (internal error),
.. E_BAD_HANDLE if the handle is not valid
Flush write buffer, completes any write operation, but leaves file open
__________________________
PUB close(handle) : status
Close an open file, completes any pending writes then frees the handle
@param handle - a handle to an open file
@returns status - 0 (SUCCESS) if successful,
.. E_FILE_MODE if close doesn't recognize this file mode (internal error),
.. E_BAD_HANDLE if the handle is not valid
___________________________________________________
PUB rename(p_cur_filename, p_new_filename) : status
Rename a file named {p_cur_filename} to {p_new_filename}
@param p_cur_filename - address of a zstring containing the existing filename
@param p_new_filename - address of a zstring containing the new filename
@returns status - 0 (SUCCESS) if successful,
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_FILE_NOT_FOUND if old file doesn't exist,
.. E_FILE_OPEN if either file is open,
.. E_FILE_EXISTS if new file already exists,
.. E_DRIVE_FULL if no available space left in filesystem
_______________________________
PUB delete(p_filename) : status
Delete a named file
@param p_filename - address of a zstring containing the filename
@returns status - 0 (SUCCESS) if successful,
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_FILE_NOT_FOUND if file doesn't exist,
.. E_FILE_OPEN if file is open
____________________________________________________________
PUB create_file(p_filename, fill_value, byte_count) : status
Make a file of a byte_count size filled with fill_value bytes - "open read/write extended" to rewrite contents
@param p_filename - address of a zstring containing the filename
@param fill_value - initial value for all bytes in the new file
@param byte_count - desired length of file in bytes
@returns status - 0 (SUCCESS) if successful,
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_FILE_OPEN if file is open,
.. E_DRIVE_FULL if no available space left in filesystem,
.. E_FILE_EXISTS if the file already exists
_____________________________
PUB exists(p_filename) : bool
Determine if named file is present in the file system
@param p_filename - address of a zstring containing the filename
@returns bool - True/False where True means the file exists
(sets error() to E_NOT_MOUNTED and returns false if filesystem has not been mounted)
_________________________________________
PUB file_size(p_filename) : size_in_bytes
Return size of file in bytes
@param p_filename - address of a zstring containing the filename
@returns size_in_bytes - either the count of bytes contained in the file or
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_FILE_NOT_FOUND if the file doesn't exist
________________________________________________
PUB file_size_for_handle(handle) : size_in_bytes
Return size of file in bytes
@param handle - a handle to an open file
@returns size_in_bytes - either the count of bytes contained in the file or
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_FILE_NOT_FOUND if the file doesn't exist
_______________________________________________________
PUB file_size_unused(p_filename) : size_in_bytes_unused
Return the number of bytes not yet written in the last allocated block
@param p_filename - address of a zstring containing the filename
@returns size_in_bytes_unused - either the count of unwritten bytes of the file or
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_FILE_NOT_FOUND if the file doesn't exist
_________________________________________________
PUB seek(handle, position, whence) : end_position
Postion seek file pointer to position within the file or at the end of the file
-- use 0, SK_FILE_START for position to seek to the START of the file
-- use POSX, SK_FILE_START (largest positive LONG value) for position to seek to the current END of the file
-- use +/- value, SK_CURRENT_POSN to move RELATIVE to the current position within the file
@param handle - a handle to an open file
@param position - position (in bytes) within the file (0 to length-1, posx)
use seek(handle, POSX, SK_FILE_START) to seek to end of the file
@param whence - meaning of position: [SK_FILE_START, SK_CURRENT_POSN]
@returns end_position - within the file to which the file pointer was set, or
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_BAD_HANDLE if the handle is not valid,
.. E_BAD_SEEK_ARG if invalid whence value,
.. E_FILE_MODE if the file is not open in a mode supporting seeks,
.. E_FILE_SEEK if attempted seek past either end of file (and didn't use POSX for tail)
__________________________________________________
PUB write(handle, p_buffer, count) : bytes_written
Write count bytes from p_buffer to the file (open for write/append) associated with the handle
@param handle - the handle to the file to which to write byte(s)
@param p_buffer - the address of the buffer containing the users' data to write
@param count - the number of bytes to write to the file
@returns bytes_written - the count of bytes written to the file or,
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_BAD_HANDLE if the handle is not valid,
.. E_FILE_MODE if the file is not open for writing,
________________________________________
PUB wr_byte(handle, byte_value) : status
Write a byte to the file (open for write/append) associated with the handle
@param handle - handle to a file that is open for write or rewrite
@param byte_value - value to write to the file
@returns status - 0 (SUCCESS) if successful,
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_BAD_HANDLE if the handle is not valid,
.. E_FILE_MODE if the file is not open for writing
________________________________________
PUB wr_word(handle, word_value) : status
Write WORD (16-bits) to the file (open for write/append) associated with the handle
-- order is Little Endian
@param handle - the handle of the file to which to write the WORD
@param word_value - the 16 bit WORD to write to the file
@returns status - 0 (SUCCESS) if successful,
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_BAD_HANDLE if the handle is not valid,
.. E_FILE_MODE if the file is not open for writing
________________________________________
PUB wr_long(handle, long_value) : status
Write LONG (32-bits) to the file (open for write/append) associated with the handle
-- order is Little Endian
@param handle - the handle of the file to which to write the LONG
@param long_value - the 32 bit LONG to write to the file
@returns status - 0 (SUCCESS) if successful,
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_BAD_HANDLE if the handle is not valid,
.. E_FILE_MODE if the file is not open for writing
__________________________________
PUB wr_str(handle, p_str) : status
Write string (including the terminator) from p_str to the file (open for write/append) associated with the handle
@param handle - the handle of the file to which to write the zString
@param p_str - the address of the zString to write to the file
@returns status - 0 (SUCCESS) if successful,
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_BAD_HANDLE if the handle is not valid,
.. E_FILE_MODE if the file is not open for writing
______________________________________________
PUB read(handle, p_buffer, count) : bytes_read
Read count bytes from the file associated with handle into p_buffer
-- returns count of bytes read (may be less than requested if reached end of file)
-- check for error() == SUCCESS before using contents of p_buffer
-- if error() <> SUCCESS then bytes_read is number of bytes read before error occurred
-- "bytes_read < expected" indicates an E_END_OF_FILE or another non-SUCCESS value in error()
@param handle - the handle to the file from which to read bytes
@param p_buffer - address of the buffer into which to place the bytes read
@param count - the maximum number of bytes to place into the buffer
@returns bytes_read - the number of bytes actually read from the file
--> If error() <> SUCCESS then it will be one of the following reasons:
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_BAD_HANDLE if the handle is not valid,
.. E_FILE_MODE if the file is not open for reading,
.. E_END_OF_FILE if attempted read beyond written data
________________________________
PUB rd_byte(handle) : byte_value
Read next byte from file associated with handle
-- negative value indicates error or end of file
@param handle - the handle to the file from which to read a byte
@returns byte_value - the next byte [0-255] from the file, or
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_BAD_HANDLE if the handle is not valid,
.. E_FILE_MODE if the file is not open for reading,
.. E_END_OF_FILE if no more data
________________________________
PUB rd_word(handle) : word_value
Read next WORD from file associated with the handle
-- negative value indicates error or end of file
@param handle - the handle to the file from which to read a WORD
@returns result - the WORD value read from the file, or:
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_BAD_HANDLE if the handle is not valid,
.. E_FILE_WRITING if the file is not open for reading,
.. E_END_OF_FILE if attempted read beyond written data
________________________________
PUB rd_long(handle) : long_value
Read next LONG from file associated with the handle
-- NOTE: negative values can be legitimate values, so
-- check for error() == SUCCESS before using value
@param handle - the handle to the file from which to read a LONG
@returns value - the LONG value read from the file
error() when not SUCCESS could be:
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_BAD_HANDLE if the handle is not valid,
.. E_FILE_WRITING if the file is not open for reading,
.. E_END_OF_FILE if attempted read beyond written data
_____________________________________________
PUB rd_str(handle, p_str, count) : bytes_read
Read zstring from file at handle into buffer at p_str (count is max length of string + terminator)
-- check for error() == SUCCESS before using value
@param handle - the handle to the file from which to read a zstring
@param p_str - the address of the buffer into which to place the zstring
@param count - the maximum number of bytes to place into the buffer (including the terminator)
@returns bytes_read - the number of bytes placed into the buffer (strsize() of the string read)
error() when not SUCCESS could be:
.. E_NOT_MOUNTED if filesystem has not been mounted,
.. E_BAD_HANDLE if the handle is not valid,
.. E_FILE_MODE if the file is not open for reading,
.. E_END_OF_FILE if attempted read beyond written data
___________________________________________________________
PUB directory(p_block_id, p_filename, p_file_size) : status
Get next file's filename and size in bytes via current blockID
-- NOTE: p_filename must be address of a 128 byte buffer!
@param p_block_id - the next block ID to check for a file head. (Initialize to 0, will be auto-advanced by each call to this method)
@param p_filename - the filename of the file found (or a zero length string if no more files, must be address of 128 byte buffer!)
@param p_file_size - the number of bytes in the file found (or 0 when no more files)
@returns status - 0 (SUCCESS) if successful,
.. E_NOT_MOUNTED if filesystem has not been mounted
__________________________________________________
PUB stats() : used_blocks, free_blocks, file_count
Get filesystem status: used/free block counts and file count
@returns used_blocks - the number of blocks in use (or E_NOT_MOUNTED if the file system is NOT mounted)
@returns free_blocks - the number of free blocks (or 0 if there is an error)
@returns file_count - the number of files recorded in filesystem (or 0 if there is an error)
_______________________________________________
PUB string_for_error(status) : p_interpretation
Return an address of a zstring describing the error code
@param status - the error code to translate
@returns p_interpretation - interpretation of the errcode
=================================================================================================
Terms of Use: MIT License
Copyright (c) 2023 Iron Sheep Productions, LLC
Permission is hereby granted, free of charge, to any person obtaining a copy of this
software and associated documentation files (the "Software"), to deal in the Software
without restriction, including without limitation the rights to use, copy, modify,
merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice shall be included in all copies
or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
=================================================================================================