Filesystem

Pebble File System (PFS) on the external NOR flash. More...

Modules
	App files
	Consistent naming of per-app files.
	Flash translation layer
	Contiguous virtual address space for PFS over several flash regions.

Data Structures
struct	PFSFileListEntry
	Entry of the list returned by pfs_create_file_list(). More...

Macros
#define	OP_FLAG_READ   (1 << 0)
	Open for reading; fails if the file does not exist.
#define	OP_FLAG_WRITE   (1 << 1)
	Open for writing, creating the file if it does not exist.
#define	OP_FLAG_OVERWRITE   (1 << 2)
	Write a new version of an existing file, committed on pfs_close().
#define	OP_FLAG_SKIP_HDR_CRC_CHECK   (1 << 3)
	Skip checking the on-flash header CRCs.
#define	OP_FLAG_USE_PAGE_CACHE   (1 << 4)
	Cache the translation from file pages to flash pages.
#define	FILE_TYPE_STATIC   (0xfe)
	File type of regular files.
#define	FILE_MAX_NAME_LEN   (255)
	Maximum length of a file name, without the NUL terminator.
#define	FILE_CHANGED_EVENT_CLOSED   (1 << 0)
	pfs_watch_file() event: the file was closed after being opened for writing.
#define	FILE_CHANGED_EVENT_REMOVED   (1 << 1)
	pfs_watch_file() event: the file was removed.
#define	FILE_CHANGED_EVENT_ALL   (FILE_CHANGED_EVENT_CLOSED | FILE_CHANGED_EVENT_REMOVED)
	pfs_watch_file() events: all of them.

Typedefs
typedef void(*	PFSFileChangedCallback) (void *data)
	Callback of pfs_watch_file().
typedef void *	PFSCallbackHandle
	Handle of a file watch, for pfs_unwatch_file().
typedef bool(*	PFSFilenameTestCallback) (const char *name)
	File name filter of pfs_create_file_list() and pfs_remove_files().

Enumerations
enum	FSeekType { FSeekSet , FSeekCur }
	Reference point of pfs_seek(). More...

Functions
int	pfs_open (const char *name, uint8_t op_flags, uint8_t file_type, size_t start_size)
	Open a file.
int	pfs_write (int fd, const void *buf, size_t size)
	Write at the current position, then advance it.
int	pfs_read (int fd, void *buf, size_t size)
	Read from the current position, then advance it.
int	pfs_seek (int fd, int offset, FSeekType seek_type)
	Set the current position.
status_t	pfs_close (int fd)
	Close a file.
status_t	pfs_close_and_remove (int fd)
	Close and remove a file.
status_t	pfs_remove (const char *name)
	Remove a file.
size_t	pfs_get_file_size (int fd)
	Get the size of a file, that is the number of bytes that can be read.
status_t	pfs_init (bool run_filesystem_check)
	Initialize PFS, before any other use.
void	pfs_reboot_cleanup (void)
	Clean up after a reboot, once and before any file operation.
void	pfs_format (bool write_erase_headers)
	Erase the whole filesystem and drop all open file descriptors.
uint32_t	pfs_get_size (void)
	Get the size of the filesystem.
void	pfs_set_size (uint32_t new_size, bool new_region_erased)
	Set the size of the filesystem, as regions are added to it.
bool	pfs_active (void)
	Check whether PFS is active on this device.
bool	pfs_active_in_region (uint32_t start_address, uint32_t ending_address)
	Check whether PFS is active in a range of the filesystem space.
int	pfs_sector_optimal_size (int min_size, int namelen)
	Get the optimal size of a file that can use space beyond a minimum.
uint32_t	get_available_pfs_space (void)
	Get the space available for new files.
PFSCallbackHandle	pfs_watch_file (const char *filename, PFSFileChangedCallback callback, uint8_t event_flags, void *data)
	Watch a file for changes.
void	pfs_unwatch_file (PFSCallbackHandle cb_handle)
	Stop watching a file.
uint32_t	pfs_crc_calculate_file (int fd, uint32_t offset, uint32_t num_bytes)
	Compute the legacy CRC-32 of a part of a file.
PFSFileListEntry *	pfs_create_file_list (PFSFilenameTestCallback callback)
	List the files whose name matches a filter.
void	pfs_delete_file_list (PFSFileListEntry *list)
	Free a list returned by pfs_create_file_list().
void	pfs_remove_files (PFSFilenameTestCallback callback)
	Remove all files whose name matches a filter.

Detailed Description

Pebble File System (PFS) on the external NOR flash.

• All functions are thread-safe.
• PFS implements basic wear leveling to extend the life of the flash part.
• A file is a block of space of fixed size, set when it is created, that appears to the caller as a contiguous region. Reads and writes past the end of the file fail. How the space is used is up to the caller.
• The flash is NOR: once a bit is written to 0, the file must be erased or rewritten to set it back to 1. Opening with OP_FLAG_OVERWRITE provides a safe way to do this.
• Erasing flash sectors is slow and costs power: avoid repeatedly deleting and creating files.

int fd = pfs_open("myfile", OP_FLAG_WRITE | OP_FLAG_READ, FILE_TYPE_STATIC, 128);
if (fd >= 0) {
  pfs_write(fd, data, sizeof(data));
  pfs_seek(fd, 0, FSeekSet);
  pfs_read(fd, buf, sizeof(data));
  pfs_close(fd);
}

---

Data Structure Documentation

PFSFileListEntry

struct PFSFileListEntry

Entry of the list returned by pfs_create_file_list().

Data Fields
ListNode	list_node	List node.
char	name[]	NUL-terminated file name.

Macro Definition Documentation

FILE_CHANGED_EVENT_ALL

#define FILE_CHANGED_EVENT_ALL   (FILE_CHANGED_EVENT_CLOSED | FILE_CHANGED_EVENT_REMOVED)

pfs_watch_file() events: all of them.

FILE_CHANGED_EVENT_CLOSED

#define FILE_CHANGED_EVENT_CLOSED   (1 << 0)

pfs_watch_file() event: the file was closed after being opened for writing.

FILE_CHANGED_EVENT_REMOVED

#define FILE_CHANGED_EVENT_REMOVED   (1 << 1)

pfs_watch_file() event: the file was removed.

FILE_MAX_NAME_LEN

#define FILE_MAX_NAME_LEN   (255)

Maximum length of a file name, without the NUL terminator.

FILE_TYPE_STATIC

#define FILE_TYPE_STATIC   (0xfe)

File type of regular files.

OP_FLAG_OVERWRITE

#define OP_FLAG_OVERWRITE   (1 << 2)

Write a new version of an existing file, committed on pfs_close().

OP_FLAG_READ

#define OP_FLAG_READ   (1 << 0)

Open for reading; fails if the file does not exist.

OP_FLAG_SKIP_HDR_CRC_CHECK

#define OP_FLAG_SKIP_HDR_CRC_CHECK   (1 << 3)

Skip checking the on-flash header CRCs.

OP_FLAG_USE_PAGE_CACHE

#define OP_FLAG_USE_PAGE_CACHE   (1 << 4)

Cache the translation from file pages to flash pages.

OP_FLAG_WRITE

#define OP_FLAG_WRITE   (1 << 1)

Open for writing, creating the file if it does not exist.

Typedef Documentation

PFSCallbackHandle

typedef void* PFSCallbackHandle

Handle of a file watch, for pfs_unwatch_file().

PFSFileChangedCallback

typedef void(* PFSFileChangedCallback) (void *data)

Callback of pfs_watch_file().

Runs on the task that closed or removed the file, with the PFS lock held: it must not call PFS.

Parameters

data	Data passed to pfs_watch_file().

PFSFilenameTestCallback

typedef bool(* PFSFilenameTestCallback) (const char *name)

File name filter of pfs_create_file_list() and pfs_remove_files().

Parameters

name	File name.

Returns

true if the file matches.

Enumeration Type Documentation

FSeekType

enum FSeekType

Reference point of pfs_seek().

Enumerator
FSeekSet	Offset from the start of the file.
FSeekCur	Offset from the current position.

Function Documentation

get_available_pfs_space()

uint32_t get_available_pfs_space ( void  )

extern

Get the space available for new files.

Only 80% of the filesystem is considered usable, to leave room for wear leveling.

Returns

Available space in bytes.

pfs_active()

bool pfs_active ( void  )

extern

Check whether PFS is active on this device.

Returns

true if PFS is active.

pfs_active_in_region()

bool pfs_active_in_region ( uint32_t  start_address, uint32_t  ending_address  )

extern

Check whether PFS is active in a range of the filesystem space.

Parameters

start_address	Start of the range.
ending_address	End of the range, exclusive.

Returns

true if PFS is active in the range.

pfs_close()

status_t pfs_close ( int  fd )

extern

Close a file.

Commits an overwrite and notifies watchers if the file was opened for writing.

Parameters

fd	File descriptor.

Return values

S_SUCCESS	File closed.
E_INVALID_ARGUMENT	Invalid descriptor.

pfs_close_and_remove()

status_t pfs_close_and_remove ( int  fd )

extern

Close and remove a file.

Parameters

fd	File descriptor.

Returns

S_SUCCESS or negative status_t, as pfs_close() and pfs_remove().

pfs_crc_calculate_file()

uint32_t pfs_crc_calculate_file ( int  fd, uint32_t  offset, uint32_t  num_bytes  )

extern

Compute the legacy CRC-32 of a part of a file.

Moves the current position of fd.

Parameters

fd	File descriptor opened for reading.
offset	Start offset.
num_bytes	Number of bytes.

Returns

Checksum, see pbl_crc32_legacy().

pfs_create_file_list()

PFSFileListEntry * pfs_create_file_list ( PFSFilenameTestCallback  callback )

extern

List the files whose name matches a filter.

Parameters

callback

Name filter, or NULL to include all files.

Returns

Head of a list of matching names, or NULL if none match. Free it with pfs_delete_file_list().

pfs_delete_file_list()

void pfs_delete_file_list ( PFSFileListEntry *  list )

extern

Free a list returned by pfs_create_file_list().

Parameters

list	Head of the list.

pfs_format()

void pfs_format ( bool  write_erase_headers )

extern

Erase the whole filesystem and drop all open file descriptors.

Requires pfs_init() to have been called.

Parameters

write_erase_headers

Mark all pages as erased.

pfs_get_file_size()

size_t pfs_get_file_size ( int  fd )

extern

Get the size of a file, that is the number of bytes that can be read.

Parameters

fd	File descriptor.

Returns

Size in bytes, 0 for an invalid descriptor.

pfs_get_size()

uint32_t pfs_get_size ( void  )

extern

Get the size of the filesystem.

Returns

Size in bytes.

pfs_init()

status_t pfs_init ( bool  run_filesystem_check )

extern

Initialize PFS, before any other use.

Builds the flash translation layer, recovers from an interrupted garbage collection, and pre-erases some space.

Parameters

run_filesystem_check

Format the flash if PFS is not active on it.

Return values

S_SUCCESS

Always.

pfs_open()

int pfs_open ( const char *  name, uint8_t  op_flags, uint8_t  file_type, size_t  start_size  )

extern

Open a file.

Flags:

• OP_FLAG_READ - pfs_read() works. With only this flag, fails if the file does not exist.
• OP_FLAG_WRITE - creates the file if it does not exist; pfs_write() works. The caller seeks to the desired offset.
• OP_FLAG_OVERWRITE - safely and incrementally overwrites an existing file; fails if the file does not exist. The new version is committed by pfs_close(); until then, opening name returns the original file. There is always a valid version to read, and the caller can copy parts of the original file in chunks instead of allocating a lot of RAM.
• OP_FLAG_SKIP_HDR_CRC_CHECK - skips the sanity check of the on-flash header CRCs, worth it for files opened thousands of times.
• OP_FLAG_USE_PAGE_CACHE - caches the translation from file pages to flash pages, which speeds up random access to large files. Best limited to reads, so that heap corruption cannot corrupt the file.

Parameters

name	File name, 1 to FILE_MAX_NAME_LEN characters.
op_flags	OP_FLAG_* flags.
file_type	File type, used only when the file is created or overwritten.
start_size	File size in bytes, used only when the file is created or overwritten.

Returns

File descriptor (>= 0) on success, negative status_t on failure.

Return values

E_INVALID_ARGUMENT	Invalid name, or invalid type or zero size on creation.
E_DOES_NOT_EXIST	The file does not exist and was not to be created.
E_BUSY	The file is already open.
E_OUT_OF_RESOURCES	No free file descriptor.
E_OUT_OF_STORAGE	Not enough space to create the file.

pfs_read()

int pfs_read ( int  fd, void *  buf, size_t  size  )

extern

Read from the current position, then advance it.

Parameters

	fd	File descriptor opened for reading.
[out]	buf	Destination buffer.
	size	Number of bytes to read, at most the size of buf.

Returns

Number of bytes read, or negative status_t on failure.

Return values

E_INVALID_ARGUMENT	Invalid descriptor, not readable, or empty buffer.
E_RANGE	The read goes past the end of the file.

pfs_reboot_cleanup()

void pfs_reboot_cleanup ( void  )

extern

Clean up after a reboot, once and before any file operation.

Finishes or rolls back operations interrupted by the reboot.

pfs_remove()

status_t pfs_remove ( const char *  name )

extern

Remove a file.

Parameters

name	File name.

Return values

S_SUCCESS	File removed.
E_INVALID_ARGUMENT	Invalid name.

Returns

Other negative status_t on failure.

pfs_remove_files()

void pfs_remove_files ( PFSFilenameTestCallback  callback )

extern

Remove all files whose name matches a filter.

Parameters

callback

Name filter.

pfs_sector_optimal_size()

int pfs_sector_optimal_size ( int  min_size, int  namelen  )

extern

Get the optimal size of a file that can use space beyond a minimum.

Rounds min_size up to use all the space of the pages the file occupies anyway.

Parameters

min_size	Minimum file size in bytes.
namelen	Length of the file name.

Returns

Optimal file size in bytes.

pfs_seek()

int pfs_seek ( int  fd, int  offset, FSeekType  seek_type  )

extern

Set the current position.

Parameters

fd	File descriptor.
offset	Offset relative to seek_type.
seek_type	Reference point.

Returns

New position on success, negative status_t on failure.

Return values

E_INVALID_ARGUMENT	Invalid descriptor.
E_RANGE	Position outside 0 to the file size.

pfs_set_size()

void pfs_set_size ( uint32_t  new_size, bool  new_region_erased  )

extern

Set the size of the filesystem, as regions are added to it.

Parameters

new_size	New size in bytes.
new_region_erased	The added pages are erased and should be marked as such.

pfs_unwatch_file()

void pfs_unwatch_file

(

PFSCallbackHandle

cb_handle

)

Stop watching a file.

Parameters

cb_handle

Handle returned by pfs_watch_file().

pfs_watch_file()

PFSCallbackHandle pfs_watch_file	(	const char *	filename,
		PFSFileChangedCallback	callback,
		uint8_t	event_flags,
		void *	data
	)

Watch a file for changes.

Parameters

filename	Name of the file to watch.
callback	Function called on the selected events.
event_flags	FILE_CHANGED_EVENT_* flags selecting the events.
data	Pointer passed to callback.

Returns

Handle for pfs_unwatch_file().

pfs_write()

int pfs_write ( int  fd, const void *  buf, size_t  size  )

extern

Write at the current position, then advance it.

Parameters

fd	File descriptor opened for writing or overwriting.
buf	Data to write.
size	Number of bytes to write, at most the size of buf.

Returns

Number of bytes written, or negative status_t on failure.

Return values

E_INVALID_ARGUMENT	Invalid descriptor, not writable, or empty buffer.
E_RANGE	The write goes past the end of the file.