FreeCalypso > hg > freecalypso-citrine

comparison services/ffs/core.h @ 0:75a11d740a02

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial import of gsm-fw from freecalypso-sw rev 1033:5ab737ac3ad7
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 09 Jun 2016 00:02:41 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:75a11d740a02
1 /******************************************************************************
2 * Flash File System (ffs)
3 * Idea, design and coding by Mads Meisner-Jensen, mmj@ti.com
4 *
5 * ffs core functions
6 *
7 * $Id: core.h 1.80.1.15.1.36 Thu, 08 Jan 2004 15:05:23 +0100 tsj $
8 *
9 ******************************************************************************/
10
11 #if (TARGET == 1)
12 #include "../../riviera/rv/rv_defined_swe.h"
13 #endif
14
15 /******************************************************************************
16 * Compile option switches
17 ******************************************************************************/
18
19 // FFS compiled with extra test functionality
20 #define FFS_TEST 1
21
22 // Default max number of simultaneous open files
23 #ifdef RVM_MSFE_SWE
24 #define FFS_FD_MAX 20
25 #else
26 #define FFS_FD_MAX 4
27 #endif
28
29 #define FFS_RECLAIM_NEW 1
30
31 /******************************************************************************
32 * Compile constants
33 ******************************************************************************/
34
35 // FFS API version (in four-digit BCD format)
36 #define FFS_API_VERSION ((uint16) 0x0642)
37
38 // FFS_DRV_VERSION is in drv.h
39
40 // TMFFS protocol version is in tmffs.h
41
42 // Magic for determining (formatted) file system version. First two digits
43 // represent major version, bottom two digits represent minor version. An
44 // ffs code compiled for one major version X is compatible with any other
45 // format version with major = X. Minor version is incremented when adding
46 // new features that does not break compatibility.
47 #define FFS_FORMAT_VERSION (0x0210)
48 #define BLOCK_MAGIC_LOW ('f'<<8|'F') // "Ffs#"
49 #define BLOCK_MAGIC_HIGH ('#'<<8|'s')
50 #define BLOCK_MAGIC ((BLOCK_MAGIC_HIGH << 8)|(BLOCK_MAGIC_LOW))
51
52 // Absolute maximum number of inodes allowed
53 #define FFS_INODES_MAX 2048
54
55 // Default maximum number of inodes allowed
56 #define FFS_INODES_MAX_DEFAULT 1024
57
58 // Default number of path components (limit due to recursiveness of
59 // inodes_reclaim())
60 #define FFS_PATH_DEPTH_MAX 6
61
62 // Maximum number of blocks (flash sectors) in a ffs system. FFS_BLOCKS_MAX
63 // must be >= the number of blocks in the largest flash device memory
64 // map. It is used to allocate the number of entries in the static bstat
65 // array.
66 #define FFS_BLOCKS_MAX 128
67 // Default size of journal file (represented as 256'ths of the blocksize)
68 #define FFS_JOURNAL_SIZE_IN256THS 16 // one 16'ths of the block size.
69
70 // Without the min size will the maximum of files (fs.blocks_files_max) in
71 // one block be 32 files if the blocksize is 8kB!
72 #define FFS_JOURNAL_SIZE_MIN 1024
73
74 #define FFS_JOURNAL_NAME ".journal"
75
76 // Default max size of file name (excluding null terminator)
77 #define FFS_FILENAME_MAX 20
78
79 // Maximum distance in age between youngest and oldest blocks
80 #define FFS_DAGE_MAX 256
81 #define FFS_DAGE_GAIN_MIN (FFS_DAGE_MAX / 4)
82 #define FFS_DAGE_EARLY_WIDTH 64
83
84 // Offset on file descriptors
85 #define FFS_FD_OFFSET '1'
86
87 // Macros to set flags and test bits in flash memory words (negative logic)
88 #define BIT_SET(value, bits) ((value) & (~bits))
89 #define IS_BIT_SET(value, bits) (~(value) & (bits))
90
91 // Number of free inodes and journal entries to keep for "emergencies"
92 #define FFS_INODES_MARGIN 4
93 #define FFS_JOURNAL_MARGIN 4
94
95
96 /******************************************************************************
97 * Macros used in both drv.c and core.c
98 ******************************************************************************/
99
100 // Convert a offset_t value to a block index
101 #define offset2block(offset) (((uint32) offset) >> dev.binfo[0].size_ld)
102
103 // Convert between offset and address
104 #define offset2addr(offset) (dev.base + (offset))
105
106 // Size of a block
107 #define blocksize(block) (1 << dev.binfo[block].size_ld)
108
109 // Test if flag is set
110 #define is_open_option(options, flags) ((options & flags) == flags)
111
112 // Amount of reserved space.
113 #define RESERVED_LOW 2 * fs.journal_size
114 #define RESERVED_NONE 0
115
116 // We have to saturate because a recently reclaimed inodes block could
117 // theoretically possess a high age
118 #define saturate_dage(dage) (dage > (2*FFS_DAGE_MAX) ? (2*FFS_DAGE_MAX) : dage)
119
120
121 /******************************************************************************
122 * Block Types
123 ******************************************************************************/
124
125 // Block age, ie. number of times block has been erased
126 typedef uint16 age_t;
127
128 // Maximum age a block can have
129 #define BLOCK_AGE_MAX 0xFFFF
130
131 // ffs block status flags. These are stored in the first 2 bytes of
132 // the ffs block in the flash sector.
133 enum BLOCK_FLAGS {
134 BF_LOST = 0x80, // block is lost and will soon be erased
135 BF_FREE = 0x40, // free (preformatted and with block magic)
136 BF_DATA = 0x02, // data
137 BF_CLEANING = 0x01, // block is being cleaned
138 BF_INODES = 0x10, // block contains inodes
139 BF_COPYING = 0x04 // block is a coming inodes block
140 };
141 enum BLOCK_STATES {
142 BF_IS_EMPTY = ~(0),
143 BF_IS_FREE = ~(BF_FREE),
144 BF_IS_DATA = ~(BF_FREE | BF_DATA),
145 BF_IS_CLEANING = ~(BF_FREE | BF_DATA | BF_CLEANING),
146 BF_IS_COPYING = ~(BF_FREE | BF_COPYING),
147 BF_IS_INODES = ~(BF_FREE | BF_COPYING | BF_INODES),
148 BF_IS_INODES_LOST = ~(BF_FREE | BF_COPYING | BF_INODES | BF_LOST)
149 };
150
151 // Header of each FFS block
152 struct block_header_s {
153 uint16 magic_low; // 32-bit magic number
154 uint16 magic_high;
155 uint16 version; // FFS_FORMAT_VERSION used for formatting
156 age_t age; // number of times this block has been erased
157 uint16 flags; // status flags of this block (BLOCK_FLAGS)
158 uint16 reserved0;
159 uint16 reserved1;
160 uint16 reserved2;
161 };
162
163 // Important the below define MUST fit to the size of the header that is written
164 #define BHEADER_SIZE sizeof(struct block_header_s)
165
166 #define OLD_BLOCK_MAGIC_LOW ('S'<<8|'F') // "FS"
167 #define OLD_FFS_FORMAT_VERSION (0x0100) // 1.00 (in four-digit BCD format)
168
169 // Old header of each FFS block. From old/previous FFS format version
170 struct block_header_old_s {
171 uint8 flags;
172 uint8 copied;
173 uint8 magicflags;
174 uint8 reserved0;
175 uint16 magic_low;
176 uint16 magic_high;
177 uint16 reserved1;
178 uint16 reserved2;
179 };
180
181 // Block status. This struct holds the status of one ffs block This relation
182 // is always valid: <block size> = <used> + <lost> + <free>. The block size
183 // is obtained from the corresponding block_info structure. <used> and
184 // <lost> variables always holds a value which is a multiple of
185 // FFS_GRANULARITY. For inodes, <used> is number of inodes in active use,
186 // <lost> is number of deleted/lost inodes, <numfiles> is the index of the
187 // first free inode.
188 struct block_stat_s {
189 blocksize_t used; // number of used bytes
190 blocksize_t lost; // number of lost bytes
191 uint16 flags; // flash block flags (first 16 bits of each block)
192 uint16 objects; // number of valid objects
193 };
194
195 /******************************************************************************
196 * External declarations
197 ******************************************************************************/
198
199 extern struct fs_s fs;
200 extern struct block_stat_s bstat[FFS_BLOCKS_MAX];
201
202 extern struct ffs_stats_s stats;
203
204 extern const struct block_info_s *binfo;
205
206
207 /******************************************************************************
208 * Object Types
209 ******************************************************************************/
210
211 // This enum MUST be in sync with the one in ffs.h.
212 enum OBJECT_TYPE_E {
213 // remaining filetypes are in ffs.h
214 OT_ERASED = 0,
215 OT_NULL = 7,
216 OT_MASK = 7,
217 OT_MAX = 4
218 };
219
220 // This enum MUST be in sync with the one in ffs.h.
221 enum OBJECT_FLAGS_E {
222 // remaining object flags are in ffs.h
223 OF_UNDEF0 = 1<<5,
224 OF_UNDEF1 = 1<<6,
225 OF_EXACT = 1<<7, // used by control()/update_commit() interaction. This
226 // is *not* an object flag!
227 OF_ALL = OF_READONLY, // all flags allowed to be changed by user
228 OF_MASK = 0xF0
229 };
230
231 struct inode_s {
232 uint16 size;
233 uint8 reserved; // size extension?
234 objflags_t flags;
235 iref_t child; // link to first inode in dir (this inode is a dir)
236 iref_t sibling; // link to next inode in same directory
237 location_t location; // location of object
238 uint16 sequence; //
239 uint16 updates; // times this object has been updated
240 };
241
242 struct file_descriptor_s {
243 char *buf; // Write buffer
244 iref_t seghead; // First chunk. Contain file name and optional data
245 iref_t wch; // Inode of work chunk (if chunk is read to buf)
246 int fp; // File pointer
247 int wfp; // Work file pointer always points to start of wch
248 int size; // Size of object (all chunks and data from buf)
249 int8 options; // Open options
250 int dirty; // Indicate if buf contain valid data or not
251 };
252
253
254 /******************************************************************************
255 * Journal types and global fs structure
256 ******************************************************************************/
257
258 enum JOURNAL_FLAGS {
259 JOURNAL_WRITING = 0x02, // journal is being written to journal file
260 JOURNAL_READY = 0x04, // journal has been written to journal file
261 JOURNAL_DONE = 0x08 // journal has been written to ffs
262 };
263
264 enum JOURNAL_STATES {
265 JOURNAL_IS_EMPTY = ~(0),
266 JOURNAL_IS_WRITING = ~(JOURNAL_WRITING),
267 JOURNAL_IS_READY = ~(JOURNAL_WRITING | JOURNAL_READY),
268 JOURNAL_IS_DONE = ~(JOURNAL_WRITING | JOURNAL_READY | JOURNAL_DONE)
269 };
270
271 // Journal entry structure. Note that the state byte *MUST* be the first
272 // byte of the structure!
273 struct journal_s {
274 uint8 state; // state of journal entry.
275 objflags_t flags; // type of object
276 iref_t i; // iref of object
277 iref_t diri; // iref of object that is this object's parent/sibling
278 iref_t oldi; // iref of object being replaced (only for updates)
279 location_t location; // object's location
280 uint16 size; // object's size
281 iref_t repli; // inode which is replaced
282 };
283
284 // Main ffs info struct (initialised by ffs_initialize())
285 struct fs_s {
286 struct inode_s *inodes_addr; // base address of inodes
287 iref_t root; // iref of root directory
288 bref_t inodes; // index into bstat containing inode block
289 bref_t newinodes; // index into bstat containing new inode block
290 bref_t blocks_free_min; // Number of spare blocks (0 or 1)
291 int filesize_max; // Max size of object data
292 int reserved_space; // Byte size of space reserved for journal relocation
293 iref_t inodes_max; // Max number of inodes possible
294 iref_t inodes_high; // number of inodes triggering an inodes_reclaim()
295 iref_t objects_max; // Max number of objects (valid inodes) allowed
296 age_t age_max; // Max block age found by blocks_fsck()
297 iref_t block_files_max; // max number of files in a block
298 iref_t block_files_reserved; // Reserved for journals
299 uint16 format; // FFS version as formatted in flash blocks
300 uint16 sequence; // Object sequence number (for debug only)
301 effs_t initerror; // ffs_initialize() return code
302 uint8 lost_threshold; // Threshold percentage for data block reclaim
303 uint8 flags; // Global FFS options/flags
304 uint8 filename_max; // Max length of a filename
305 uint8 path_depth_max; // Max path componenents allowed
306 uint8 numfds; // Mumber of available file descriptors
307 uint8 testflags;
308 int8 journal_depth; // Current journal nesting depth (0 or 1)
309 iref_t ijournal; // iref of journal file
310 uint32 journal_size; // Byte size of journal file
311 uint32 journal_pos; // Byte offset to first free entry in journal file
312 struct journal_s journal;
313 uint8 fd_max; // number of max available file descriptors
314 int fd_buf_size; // size of stream buffer
315 struct file_descriptor_s fd[FFS_FD_MAX];
316 struct journal_s ojournal; // "Old" journal
317 int link_child; // Link child in journal or not
318 iref_t i_backup; // Used by ffs_file_write()
319 int chunk_size_max; // Max size of one chunk
320 int chunk_size_min; // Min size of one chunk
321 uint32 debug[4];
322 };
323
324 // This is the layout of the FFS performance statistics file. The file is
325 // created with the name ".statistics" in the root directory at format. It
326 // is updated after each data and inodes reclaim (after writing the file
327 // that provoked the reclaim). The file is only updated if it exists, so if
328 // the user does not want the file, she can erase it after the initial
329 // format. FIXME: The use of the .statistics file is not yet implemented
330 struct ffs_stats_s {
331 uint32 data_allocated; // implemented
332
333 struct { // Not yet implemented
334 uint32 created;
335 uint32 updated;
336 uint32 read;
337 } files;
338 struct { // Not yet implemented
339 uint32 written[2];
340 uint32 read[2];
341 } bytes;
342 struct {
343 uint32 most_lost; // Block candidate
344 uint32 most_unused; // Block candidate
345 uint32 youngest; // Block candidate
346 uint32 valid[2]; // Amount of valid reclaimed data
347 uint32 lost[2]; // Amount of lost reclaimed data
348 } drec;
349 struct {
350 uint32 num; // Number of inode reclaims
351 uint32 valid; // Number of valid reclaimed inodes
352 uint32 lost; // Number of lost reclaimed inodes
353 } irec;
354 };
355 extern struct ffs_stats_s stats;
356
357
358 /******************************************************************************
359 * Miscellaneous types
360 ******************************************************************************/
361
362 // only used with (FFS_TEST == 1)
363 enum TEST_RECOVERY {
364 JOURNAL_TEST_BASE = 0x10,
365 JOURNAL_TEST_EMPTY,
366 JOURNAL_TEST_WRITING,
367 JOURNAL_TEST_READY,
368 JOURNAL_TEST_COMMITTING,
369 JOURNAL_TEST_COMMITTED,
370 JOURNAL_TEST_DONE,
371 BLOCK_COMMIT_BASE = 0x20,
372 BLOCK_COMMIT_BEFORE,
373 BLOCK_COMMIT_NO_VALID,
374 BLOCK_COMMIT_OLD_FREE,
375 BLOCK_COMMIT_AFTER,
376 BLOCK_RECLAIM_BASE = 0x40,
377 BLOCK_RECLAIM_ALLOC,
378 BLOCK_RECLAIM_CLEANING,
379 BLOCK_RECLAIM_NO_CLEAN,
380 BLOCK_RECOVER_OBJECTS
381 };
382
383 enum FLASH_DATA {
384 FLASH_NULL8 = 0xFF,
385 FLASH_NULL16 = 0xFFFF,
386 FLASH_NULL32 = 0xFFFFFFFFL,
387 IREF_NULL = FLASH_NULL16
388 };
389
390
391 // This enum MUST be in sync with the one in ffs.h.
392 enum OBJECT_CONTROL {
393 // remaining object control codes are in ffs.h
394 OC_FS_FLAGS = 80,
395 OC_TRACE_INIT = 82,
396 OC_DEV_MANUFACT = 88,
397 OC_DEV_DEVICE = 89,
398
399 OC_DEBUG_FIRST = 120,
400 OC_DEBUG_0 = 120,
401 OC_DEBUG_1 = 121,
402 OC_DEBUG_2 = 122,
403 OC_DEBUG_3 = 123,
404 OC_DEBUG_LAST = 123,
405
406 OC_FS_TESTFLAGS = 127
407 };
408
409 enum FS_FLAGS {
410 FS_DIR_DATA = 0x01 // allow directory objects to contain data.
411 };
412
413 enum RECLAIM_CANDIDATE {
414 MOST_LOST,
415 MOST_UNUSED,
416 YOUNGEST
417 };
418
419 /******************************************************************************
420 * Macros
421 ******************************************************************************/
422
423 // Convert between location and offset
424 #define location2offset(location) ((location) << dev.atomlog2)
425 #define offset2location(offset) (((uint32) offset) >> dev.atomlog2)
426
427 // test if object is of a specific type
428 #define is_object(objp, type) (((objp)->flags & OT_MASK) == (type))
429
430 // test if object is valid (directory, file or symlink)
431 #define is_object_valid(ip) ((ip->flags & OT_MASK) <= OT_MAX && (ip->flags & OT_MASK) != OT_ERASED)
432
433 // test if block is in a specific state
434 #define is_block(block, state) (bstat[block].flags == (uint16) (state))
435
436 // test if block has certain flags set
437 #define is_block_flag(block, bits) (IS_BIT_SET(bstat[block].flags, (bits)))
438
439 // convert an object's data address to the address of the object's name
440 #define addr2name(addr) (addr)
441
442 // Convert a size to an aligned size
443 #define atomalign(size) (((size) + dev.atomsize-1) & ~dev.atomnotmask)
444 #define wordalign(size) (((size) + 3) & ~3)
445 #define halfwordalign(size) (((size) + 1) & ~1)
446
447 #define inode_addr(i) (fs.inodes_addr + i)
448
449 #define JOURNAL_POS_INITIAL (wordalign(2 + sizeof(FFS_JOURNAL_NAME) + 1))
450
451
452 /******************************************************************************
453 * Function prototypes
454 ******************************************************************************/
455
456 // Helper functions
457
458 effs_t is_filename(const char *s);
459 int ffs_strlen(const char *s);
460 int ffs_strcmp(const char *s, const char *p);
461 char *addr2data(const char *addr, const struct inode_s *ip);
462
463 int object_datasize(iref_t i);
464 iref_t is_readonly(iref_t i, const char *name);
465 iref_t dir_traverse(iref_t i, iref_t *entries);
466
467 bref_t block_alloc(bref_t n, uint16 flags);
468 bref_t block_alloc_try(bref_t *n);
469 void block_flags_write(uint8 block, uint8 flags);
470
471 offset_t data_alloc(int size);
472 offset_t data_alloc_try(int size);
473 offset_t data_reserved_alloc(int size);
474
475 iref_t inode_alloc(void);
476
477 effs_t is_fd_valid(fd_t fdi);
478 effs_t is_offset_in_buf(int offset, fd_t fdi);
479
480 iref_t chunk_alloc(int realsize, int is_journal, offset_t *offset);
481
482 iref_t inode_alloc_try(void);
483 fd_t get_fdi(iref_t i);
484
485 offset_t data_prealloc(int realsize);
486
487 // Functions used by API
488
489 effs_t object_update(iref_t oldi);
490 iref_t object_create(const char *name, const char *buf, int size,
491 iref_t dir);
492 int file_read(const char *name, void *addr, int size);
493 int stream_read(fd_t fdi, void *src, int size);
494 int object_read(const char *name, char *buf, int size, int linkflag);
495
496 iref_t object_stat(const char *name, struct xstat_s *stat,
497 int linkflag, int fdi, int extended);
498 effs_t object_remove(iref_t i);
499 iref_t object_rename(iref_t oldi, const char *newname, iref_t newdir);
500 effs_t object_control(iref_t i, int8 action, int value);
501 int object_truncate(const char *pathname, fd_t fdi, offset_t length);
502 iref_t object_lookup(const char *path, char **leaf, iref_t *dir);
503 iref_t object_lookup_once(const char *path, char **leaf, iref_t *dir);
504 iref_t dir_open(const char *name);
505 iref_t dir_next (iref_t dir, iref_t i, char *name, int8 size);
506
507
508 // Journalling
509
510 void journal_begin(iref_t oldi);
511 void journal_end(uint8 type);
512 void journal_commit(uint8 type);
513 int journal_push(void);
514 int journal_pop(void);
515 iref_t journal_create(iref_t oldi);
516 effs_t journal_init(iref_t i);
517
518
519 // Format, Init and Reclaim
520
521 void block_preformat(bref_t b, age_t age);
522 effs_t fs_preformat(void);
523 effs_t is_formattable(int8 flag);
524 effs_t fs_format(const char *fsname_and_options);
525
526 effs_t ffs_initialize(void);
527 void fs_params_init(const char *p);
528 blocksize_t block_used(bref_t b);
529
530 effs_t ffs_begin(void);
531 int ffs_end(int error);
532
533 int block_reclaim(bref_t b);
534 int blocks_reclaim(void);
535 void block_commit(void);
536
537 iref_t data_reclaim(int space);
538 int data_reclaim_try(int space);
539 iref_t data_block_reclaim(bref_t b, int reclaim_candidate);
540 iref_t object_relocate(iref_t oldi);
541 iref_t block_clean(bref_t b);
542
543 void block_free(bref_t block);
544
545 void inodes_set(iref_t i);
546 effs_t inodes_reclaim(void);
547
548 int reclaim(void);
549
550 // Internally used functions
551
552 effs_t file_read_int(const char *path, void *src, int size);
553 effs_t file_update(const char *path, void *src, int size);
554
555 int statistics_file_create(void);
556 int statistics_write(void);
557 void statistics_init(void);
558 void statistics_update_drec(int valid, int lost, int candidate);
559 void statistics_update_irec(int valid, int lost);
560
561 // Chunk Operations
562 iref_t segment_create(const char *buf, int size, iref_t dir);
563 int segment_datasize(const struct inode_s *ip);
564 int segment_read(iref_t i, char *buf, int size, int offset);
565 iref_t segment_next(iref_t i);
566 iref_t segment_traverse(iref_t i, iref_t *entries);
567 int segfile_seek(iref_t in_i, int in_pos,
568 iref_t *out_i, int *out_pos_i);
569 iref_t chunk_traverse(iref_t i);
570 effs_t datasync(fd_t fdi);
571 // debug/test functions
572
573 void tr_bstat(void);
574 void tr_fd(fd_t fdi);
575
576 // These prototypes really belong in ffs.h but as they have not been
577 // implemented, we will not show these prototypes to application
578 // programmers.
579 effs_t fcntl(fd_t fd, int8 action, uint32 *param);