+/rtos
git clone https://git.julia.blue/+/rtos
ee4080a
master
1/* 2* The little filesystem 3* 4* Copyright (c) 2017, Arm Limited. All rights reserved. 5* SPDX-License-Identifier: BSD-3-Clause 6*/ 7#ifndef LFS_H 8#define LFS_H 9 10#include <stdbool.h> 11#include <stdint.h> 12 13#ifdef __cplusplus 14extern "C" { 15#endif 16 17/// Version info /// 18 19// Software library version 20// Major (top-nibble), incremented on backwards incompatible changes 21// Minor (bottom-nibble), incremented on feature additions 22#define LFS_VERSION 0x00020002 23#define LFS_VERSION_MAJOR (0xffff & (LFS_VERSION >> 16)) 24#define LFS_VERSION_MINOR (0xffff & (LFS_VERSION >> 0)) 25 26// Version of On-disk data structures 27// Major (top-nibble), incremented on backwards incompatible changes 28// Minor (bottom-nibble), incremented on feature additions 29#define LFS_DISK_VERSION 0x00020000 30#define LFS_DISK_VERSION_MAJOR (0xffff & (LFS_DISK_VERSION >> 16)) 31#define LFS_DISK_VERSION_MINOR (0xffff & (LFS_DISK_VERSION >> 0)) 32 33/// Definitions /// 34 35// Type definitions 36typedef uint32_t lfs_size_t ; 37typedef uint32_t lfs_off_t ; 38 39typedef int32_t lfs_ssize_t ; 40typedef int32_t lfs_soff_t ; 41 42typedef uint32_t lfs_block_t ; 43 44// Maximum name size in bytes, may be redefined to reduce the size of the 45// info struct. Limited to <= 1022. Stored in superblock and must be 46// respected by other littlefs drivers. 47#ifndef LFS_NAME_MAX 48#define LFS_NAME_MAX 255 49#endif 50 51// Maximum size of a file in bytes, may be redefined to limit to support other 52// drivers. Limited on disk to <= 4294967296. However, above 2147483647 the 53// functions lfs_file_seek, lfs_file_size, and lfs_file_tell will return 54// incorrect values due to using signed integers. Stored in superblock and 55// must be respected by other littlefs drivers. 56#ifndef LFS_FILE_MAX 57#define LFS_FILE_MAX 2147483647 58#endif 59 60// Maximum size of custom attributes in bytes, may be redefined, but there is 61// no real benefit to using a smaller LFS_ATTR_MAX. Limited to <= 1022. 62#ifndef LFS_ATTR_MAX 63#define LFS_ATTR_MAX 1022 64#endif 65 66// Possible error codes, these are negative to allow 67// valid positive return values 68enum lfs_error { 69LFS_ERR_OK = 0 ,// No error 70LFS_ERR_IO = -5 ,// Error during device operation 71LFS_ERR_CORRUPT = -84 ,// Corrupted 72LFS_ERR_NOENT = -2 ,// No directory entry 73LFS_ERR_EXIST = -17 ,// Entry already exists 74LFS_ERR_NOTDIR = -20 ,// Entry is not a dir 75LFS_ERR_ISDIR = -21 ,// Entry is a dir 76LFS_ERR_NOTEMPTY = -39 ,// Dir is not empty 77LFS_ERR_BADF = -9 ,// Bad file number 78LFS_ERR_FBIG = -27 ,// File too large 79LFS_ERR_INVAL = -22 ,// Invalid parameter 80LFS_ERR_NOSPC = -28 ,// No space left on device 81LFS_ERR_NOMEM = -12 ,// No more memory available 82LFS_ERR_NOATTR = -61 ,// No data/attr available 83LFS_ERR_NAMETOOLONG = -36 ,// File name too long 84}; 85 86// File types 87enum lfs_type { 88// file types 89LFS_TYPE_REG = 0x001 , 90LFS_TYPE_DIR = 0x002 , 91 92// internally used types 93LFS_TYPE_SPLICE = 0x400 , 94LFS_TYPE_NAME = 0x000 , 95LFS_TYPE_STRUCT = 0x200 , 96LFS_TYPE_USERATTR = 0x300 , 97LFS_TYPE_FROM = 0x100 , 98LFS_TYPE_TAIL = 0x600 , 99LFS_TYPE_GLOBALS = 0x700 , 100LFS_TYPE_CRC = 0x500 , 101 102// internally used type specializations 103LFS_TYPE_CREATE = 0x401 , 104LFS_TYPE_DELETE = 0x4ff , 105LFS_TYPE_SUPERBLOCK = 0x0ff , 106LFS_TYPE_DIRSTRUCT = 0x200 , 107LFS_TYPE_CTZSTRUCT = 0x202 , 108LFS_TYPE_INLINESTRUCT = 0x201 , 109LFS_TYPE_SOFTTAIL = 0x600 , 110LFS_TYPE_HARDTAIL = 0x601 , 111LFS_TYPE_MOVESTATE = 0x7ff , 112 113// internal chip sources 114LFS_FROM_NOOP = 0x000 , 115LFS_FROM_MOVE = 0x101 , 116LFS_FROM_USERATTRS = 0x102 , 117}; 118 119// File open flags 120enum lfs_open_flags { 121// open flags 122LFS_O_RDONLY = 1 ,// Open a file as read only 123LFS_O_WRONLY = 2 ,// Open a file as write only 124LFS_O_RDWR = 3 ,// Open a file as read and write 125LFS_O_CREAT = 0x0100 ,// Create a file if it does not exist 126LFS_O_EXCL = 0x0200 ,// Fail if a file already exists 127LFS_O_TRUNC = 0x0400 ,// Truncate the existing file to zero size 128LFS_O_APPEND = 0x0800 ,// Move to end of file on every write 129 130// internally used flags 131LFS_F_DIRTY = 0x010000 ,// File does not match storage 132LFS_F_WRITING = 0x020000 ,// File has been written since last flush 133LFS_F_READING = 0x040000 ,// File has been read since last flush 134LFS_F_ERRED = 0x080000 ,// An error occured during write 135LFS_F_INLINE = 0x100000 ,// Currently inlined in directory entry 136LFS_F_OPENED = 0x200000 ,// File has been opened 137}; 138 139// File seek flags 140enum lfs_whence_flags { 141LFS_SEEK_SET = 0 ,// Seek relative to an absolute position 142LFS_SEEK_CUR = 1 ,// Seek relative to the current file position 143LFS_SEEK_END = 2 ,// Seek relative to the end of the file 144}; 145 146// Configuration provided during initialization of the littlefs 147struct lfs_config { 148// Opaque user provided context that can be used to pass 149// information to the block device operations 150void * context ; 151 152// Read a region in a block. Negative error codes are propogated 153// to the user. 154int (* read )(const struct lfs_config * c ,lfs_block_t block ,lfs_off_t off , 155void * buffer ,lfs_size_t size ); 156 157// Program a region in a block. The block must have previously 158// been erased. Negative error codes are propogated to the user. 159// May return LFS_ERR_CORRUPT if the block should be considered bad. 160int (* prog )(const struct lfs_config * c ,lfs_block_t block ,lfs_off_t off , 161const void * buffer ,lfs_size_t size ); 162 163// Erase a block. A block must be erased before being programmed. 164// The state of an erased block is undefined. Negative error codes 165// are propogated to the user. 166// May return LFS_ERR_CORRUPT if the block should be considered bad. 167int (* erase )(const struct lfs_config * c ,lfs_block_t block ); 168 169// Sync the state of the underlying block device. Negative error codes 170// are propogated to the user. 171int (* sync )(const struct lfs_config * c ); 172 173// Minimum size of a block read. All read operations will be a 174// multiple of this value. 175lfs_size_t read_size ; 176 177// Minimum size of a block program. All program operations will be a 178// multiple of this value. 179lfs_size_t prog_size ; 180 181// Size of an erasable block. This does not impact ram consumption and 182// may be larger than the physical erase size. However, non-inlined files 183// take up at minimum one block. Must be a multiple of the read 184// and program sizes. 185lfs_size_t block_size ; 186 187// Number of erasable blocks on the device. 188lfs_size_t block_count ; 189 190// Number of erase cycles before littlefs evicts metadata logs and moves 191// the metadata to another block. Suggested values are in the 192// range 100-1000, with large values having better performance at the cost 193// of less consistent wear distribution. 194// 195// Set to -1 to disable block-level wear-leveling. 196int32_t block_cycles ; 197 198// Size of block caches. Each cache buffers a portion of a block in RAM. 199// The littlefs needs a read cache, a program cache, and one additional 200// cache per file. Larger caches can improve performance by storing more 201// data and reducing the number of disk accesses. Must be a multiple of 202// the read and program sizes, and a factor of the block size. 203lfs_size_t cache_size ; 204 205// Size of the lookahead buffer in bytes. A larger lookahead buffer 206// increases the number of blocks found during an allocation pass. The 207// lookahead buffer is stored as a compact bitmap, so each byte of RAM 208// can track 8 blocks. Must be a multiple of 8. 209lfs_size_t lookahead_size ; 210 211// Optional statically allocated read buffer. Must be cache_size. 212// By default lfs_malloc is used to allocate this buffer. 213void * read_buffer ; 214 215// Optional statically allocated program buffer. Must be cache_size. 216// By default lfs_malloc is used to allocate this buffer. 217void * prog_buffer ; 218 219// Optional statically allocated lookahead buffer. Must be lookahead_size 220// and aligned to a 32-bit boundary. By default lfs_malloc is used to 221// allocate this buffer. 222void * lookahead_buffer ; 223 224// Optional upper limit on length of file names in bytes. No downside for 225// larger names except the size of the info struct which is controlled by 226// the LFS_NAME_MAX define. Defaults to LFS_NAME_MAX when zero. Stored in 227// superblock and must be respected by other littlefs drivers. 228lfs_size_t name_max ; 229 230// Optional upper limit on files in bytes. No downside for larger files 231// but must be <= LFS_FILE_MAX. Defaults to LFS_FILE_MAX when zero. Stored 232// in superblock and must be respected by other littlefs drivers. 233lfs_size_t file_max ; 234 235// Optional upper limit on custom attributes in bytes. No downside for 236// larger attributes size but must be <= LFS_ATTR_MAX. Defaults to 237// LFS_ATTR_MAX when zero. 238lfs_size_t attr_max ; 239}; 240 241// File info structure 242struct lfs_info { 243// Type of the file, either LFS_TYPE_REG or LFS_TYPE_DIR 244uint8_t type ; 245 246// Size of the file, only valid for REG files. Limited to 32-bits. 247lfs_size_t size ; 248// Name of the file stored as a null-terminated string. Limited to 249// LFS_NAME_MAX+1, which can be changed by redefining LFS_NAME_MAX to 250// reduce RAM. LFS_NAME_MAX is stored in superblock and must be 251// respected by other littlefs drivers. 252char name [LFS_NAME_MAX + 1 ]; 253}; 254 255// Custom attribute structure, used to describe custom attributes 256// committed atomically during file writes. 257struct lfs_attr { 258// 8-bit type of attribute, provided by user and used to 259// identify the attribute 260uint8_t type ; 261 262// Pointer to buffer containing the attribute 263void * buffer ; 264 265// Size of attribute in bytes, limited to LFS_ATTR_MAX 266lfs_size_t size ; 267}; 268 269// Optional configuration provided during lfs_file_opencfg 270struct lfs_file_config { 271// Optional statically allocated file buffer. Must be cache_size. 272// By default lfs_malloc is used to allocate this buffer. 273void * buffer ; 274 275// Optional list of custom attributes related to the file. If the file 276// is opened with read access, these attributes will be read from disk 277// during the open call. If the file is opened with write access, the 278// attributes will be written to disk every file sync or close. This 279// write occurs atomically with update to the file's contents. 280// 281// Custom attributes are uniquely identified by an 8-bit type and limited 282// to LFS_ATTR_MAX bytes. When read, if the stored attribute is smaller 283// than the buffer, it will be padded with zeros. If the stored attribute 284// is larger, then it will be silently truncated. If the attribute is not 285// found, it will be created implicitly. 286struct lfs_attr * attrs ; 287 288// Number of custom attributes in the list 289lfs_size_t attr_count ; 290}; 291 292/// internal littlefs data structures /// 293typedef struct lfs_cache { 294lfs_block_t block ; 295lfs_off_t off ; 296lfs_size_t size ; 297uint8_t * buffer ; 298}lfs_cache_t ; 299 300typedef struct lfs_mdir { 301lfs_block_t pair [2 ]; 302uint32_t rev ; 303lfs_off_t off ; 304uint32_t etag ; 305uint16_t count ; 306bool erased ; 307bool split ; 308lfs_block_t tail [2 ]; 309}lfs_mdir_t ; 310 311// littlefs directory type 312typedef struct lfs_dir { 313struct lfs_dir * next ; 314uint16_t id ; 315uint8_t type ; 316lfs_mdir_t m ; 317 318lfs_off_t pos ; 319lfs_block_t head [2 ]; 320}lfs_dir_t ; 321 322// littlefs file type 323typedef struct lfs_file { 324struct lfs_file * next ; 325uint16_t id ; 326uint8_t type ; 327lfs_mdir_t m ; 328 329struct lfs_ctz { 330lfs_block_t head ; 331lfs_size_t size ; 332 }ctz ; 333 334uint32_t flags ; 335lfs_off_t pos ; 336lfs_block_t block ; 337lfs_off_t off ; 338lfs_cache_t cache ; 339 340const struct lfs_file_config * cfg ; 341}lfs_file_t ; 342 343typedef struct lfs_superblock { 344uint32_t version ; 345lfs_size_t block_size ; 346lfs_size_t block_count ; 347lfs_size_t name_max ; 348lfs_size_t file_max ; 349lfs_size_t attr_max ; 350}lfs_superblock_t ; 351 352typedef struct lfs_gstate { 353uint32_t tag ; 354lfs_block_t pair [2 ]; 355}lfs_gstate_t ; 356 357// The littlefs filesystem type 358typedef struct lfs { 359lfs_cache_t rcache ; 360lfs_cache_t pcache ; 361 362lfs_block_t root [2 ]; 363struct lfs_mlist { 364struct lfs_mlist * next ; 365uint16_t id ; 366uint8_t type ; 367lfs_mdir_t m ; 368 }* mlist ; 369uint32_t seed ; 370 371lfs_gstate_t gstate ; 372lfs_gstate_t gdisk ; 373lfs_gstate_t gdelta ; 374 375struct lfs_free { 376lfs_block_t off ; 377lfs_block_t size ; 378lfs_block_t i ; 379lfs_block_t ack ; 380uint32_t * buffer ; 381 }free ; 382 383const struct lfs_config * cfg ; 384lfs_size_t name_max ; 385lfs_size_t file_max ; 386lfs_size_t attr_max ; 387 388#ifdef LFS_MIGRATE 389struct lfs1 * lfs1 ; 390#endif 391}lfs_t ; 392 393/// Filesystem functions /// 394 395// Format a block device with the littlefs 396// 397// Requires a littlefs object and config struct. This clobbers the littlefs 398// object, and does not leave the filesystem mounted. The config struct must 399// be zeroed for defaults and backwards compatibility. 400// 401// Returns a negative error code on failure. 402int lfs_format (lfs_t * lfs ,const struct lfs_config * config ); 403 404// Mounts a littlefs 405// 406// Requires a littlefs object and config struct. Multiple filesystems 407// may be mounted simultaneously with multiple littlefs objects. Both 408// lfs and config must be allocated while mounted. The config struct must 409// be zeroed for defaults and backwards compatibility. 410// 411// Returns a negative error code on failure. 412int lfs_mount (lfs_t * lfs ,const struct lfs_config * config ); 413 414// Unmounts a littlefs 415// 416// Does nothing besides releasing any allocated resources. 417// Returns a negative error code on failure. 418int lfs_unmount (lfs_t * lfs ); 419 420/// General operations /// 421 422// Removes a file or directory 423// 424// If removing a directory, the directory must be empty. 425// Returns a negative error code on failure. 426int lfs_remove (lfs_t * lfs ,const char * path ); 427 428// Rename or move a file or directory 429// 430// If the destination exists, it must match the source in type. 431// If the destination is a directory, the directory must be empty. 432// 433// Returns a negative error code on failure. 434int lfs_rename (lfs_t * lfs ,const char * oldpath ,const char * newpath ); 435 436// Find info about a file or directory 437// 438// Fills out the info structure, based on the specified file or directory. 439// Returns a negative error code on failure. 440int lfs_stat (lfs_t * lfs ,const char * path ,struct lfs_info * info ); 441 442// Get a custom attribute 443// 444// Custom attributes are uniquely identified by an 8-bit type and limited 445// to LFS_ATTR_MAX bytes. When read, if the stored attribute is smaller than 446// the buffer, it will be padded with zeros. If the stored attribute is larger, 447// then it will be silently truncated. If no attribute is found, the error 448// LFS_ERR_NOATTR is returned and the buffer is filled with zeros. 449// 450// Returns the size of the attribute, or a negative error code on failure. 451// Note, the returned size is the size of the attribute on disk, irrespective 452// of the size of the buffer. This can be used to dynamically allocate a buffer 453// or check for existance. 454lfs_ssize_t lfs_getattr (lfs_t * lfs ,const char * path ,uint8_t type , 455void * buffer ,lfs_size_t size ); 456 457// Set custom attributes 458// 459// Custom attributes are uniquely identified by an 8-bit type and limited 460// to LFS_ATTR_MAX bytes. If an attribute is not found, it will be 461// implicitly created. 462// 463// Returns a negative error code on failure. 464int lfs_setattr (lfs_t * lfs ,const char * path ,uint8_t type ,const void * buffer , 465lfs_size_t size ); 466 467// Removes a custom attribute 468// 469// If an attribute is not found, nothing happens. 470// 471// Returns a negative error code on failure. 472int lfs_removeattr (lfs_t * lfs ,const char * path ,uint8_t type ); 473 474/// File operations /// 475 476// Open a file 477// 478// The mode that the file is opened in is determined by the flags, which 479// are values from the enum lfs_open_flags that are bitwise-ored together. 480// 481// Returns a negative error code on failure. 482int lfs_file_open (lfs_t * lfs ,lfs_file_t * file ,const char * path ,int flags ); 483 484// Open a file with extra configuration 485// 486// The mode that the file is opened in is determined by the flags, which 487// are values from the enum lfs_open_flags that are bitwise-ored together. 488// 489// The config struct provides additional config options per file as described 490// above. The config struct must be allocated while the file is open, and the 491// config struct must be zeroed for defaults and backwards compatibility. 492// 493// Returns a negative error code on failure. 494int lfs_file_opencfg (lfs_t * lfs ,lfs_file_t * file ,const char * path ,int flags , 495const struct lfs_file_config * config ); 496 497// Close a file 498// 499// Any pending writes are written out to storage as though 500// sync had been called and releases any allocated resources. 501// 502// Returns a negative error code on failure. 503int lfs_file_close (lfs_t * lfs ,lfs_file_t * file ); 504 505// Synchronize a file on storage 506// 507// Any pending writes are written out to storage. 508// Returns a negative error code on failure. 509int lfs_file_sync (lfs_t * lfs ,lfs_file_t * file ); 510 511// Read data from file 512// 513// Takes a buffer and size indicating where to store the read data. 514// Returns the number of bytes read, or a negative error code on failure. 515lfs_ssize_t lfs_file_read (lfs_t * lfs ,lfs_file_t * file ,void * buffer , 516lfs_size_t size ); 517 518// Write data to file 519// 520// Takes a buffer and size indicating the data to write. The file will not 521// actually be updated on the storage until either sync or close is called. 522// 523// Returns the number of bytes written, or a negative error code on failure. 524lfs_ssize_t lfs_file_write (lfs_t * lfs ,lfs_file_t * file ,const void * buffer , 525lfs_size_t size ); 526 527// Change the position of the file 528// 529// The change in position is determined by the offset and whence flag. 530// Returns the new position of the file, or a negative error code on failure. 531lfs_soff_t lfs_file_seek (lfs_t * lfs ,lfs_file_t * file ,lfs_soff_t off , 532int whence ); 533 534// Truncates the size of the file to the specified size 535// 536// Returns a negative error code on failure. 537int lfs_file_truncate (lfs_t * lfs ,lfs_file_t * file ,lfs_off_t size ); 538 539// Return the position of the file 540// 541// Equivalent to lfs_file_seek(lfs, file, 0, LFS_SEEK_CUR) 542// Returns the position of the file, or a negative error code on failure. 543lfs_soff_t lfs_file_tell (lfs_t * lfs ,lfs_file_t * file ); 544 545// Change the position of the file to the beginning of the file 546// 547// Equivalent to lfs_file_seek(lfs, file, 0, LFS_SEEK_SET) 548// Returns a negative error code on failure. 549int lfs_file_rewind (lfs_t * lfs ,lfs_file_t * file ); 550 551// Return the size of the file 552// 553// Similar to lfs_file_seek(lfs, file, 0, LFS_SEEK_END) 554// Returns the size of the file, or a negative error code on failure. 555lfs_soff_t lfs_file_size (lfs_t * lfs ,lfs_file_t * file ); 556 557/// Directory operations /// 558 559// Create a directory 560// 561// Returns a negative error code on failure. 562int lfs_mkdir (lfs_t * lfs ,const char * path ); 563 564// Open a directory 565// 566// Once open a directory can be used with read to iterate over files. 567// Returns a negative error code on failure. 568int lfs_dir_open (lfs_t * lfs ,lfs_dir_t * dir ,const char * path ); 569 570// Close a directory 571// 572// Releases any allocated resources. 573// Returns a negative error code on failure. 574int lfs_dir_close (lfs_t * lfs ,lfs_dir_t * dir ); 575 576// Read an entry in the directory 577// 578// Fills out the info structure, based on the specified file or directory. 579// Returns a positive value on success, 0 at the end of directory, 580// or a negative error code on failure. 581int lfs_dir_read (lfs_t * lfs ,lfs_dir_t * dir ,struct lfs_info * info ); 582 583// Change the position of the directory 584// 585// The new off must be a value previous returned from tell and specifies 586// an absolute offset in the directory seek. 587// 588// Returns a negative error code on failure. 589int lfs_dir_seek (lfs_t * lfs ,lfs_dir_t * dir ,lfs_off_t off ); 590 591// Return the position of the directory 592// 593// The returned offset is only meant to be consumed by seek and may not make 594// sense, but does indicate the current position in the directory iteration. 595// 596// Returns the position of the directory, or a negative error code on failure. 597lfs_soff_t lfs_dir_tell (lfs_t * lfs ,lfs_dir_t * dir ); 598 599// Change the position of the directory to the beginning of the directory 600// 601// Returns a negative error code on failure. 602int lfs_dir_rewind (lfs_t * lfs ,lfs_dir_t * dir ); 603 604/// Filesystem-level filesystem operations 605 606// Finds the current size of the filesystem 607// 608// Note: Result is best effort. If files share COW structures, the returned 609// size may be larger than the filesystem actually is. 610// 611// Returns the number of allocated blocks, or a negative error code on failure. 612lfs_ssize_t lfs_fs_size (lfs_t * lfs ); 613 614// Traverse through all blocks in use by the filesystem 615// 616// The provided callback will be called with each block address that is 617// currently in use by the filesystem. This can be used to determine which 618// blocks are in use or how much of the storage is available. 619// 620// Returns a negative error code on failure. 621int lfs_fs_traverse (lfs_t * lfs ,int (* cb )(void * ,lfs_block_t ),void * data ); 622 623#ifdef LFS_MIGRATE 624// Attempts to migrate a previous version of littlefs 625// 626// Behaves similarly to the lfs_format function. Attempts to mount 627// the previous version of littlefs and update the filesystem so it can be 628// mounted with the current version of littlefs. 629// 630// Requires a littlefs object and config struct. This clobbers the littlefs 631// object, and does not leave the filesystem mounted. The config struct must 632// be zeroed for defaults and backwards compatibility. 633// 634// Returns a negative error code on failure. 635int lfs_migrate (lfs_t * lfs ,const struct lfs_config * cfg ); 636#endif 637 638#ifdef __cplusplus 639} /* extern "C" */ 640#endif 641 642#endif