Loading...
Searching...
No Matches
vfs.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 2016 Eistec AB
3 *
4 * This file is subject to the terms and conditions of the GNU Lesser
5 * General Public License v2.1. See the file LICENSE in the top level
6 * directory for more details.
7 */
8
53#ifndef VFS_H
54#define VFS_H
55
56#include <stdint.h>
57/* The stdatomic.h in GCC gives compilation errors with C++
58 * see: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=60932
59 */
60#ifdef __cplusplus
62#else
63#include <stdatomic.h> /* for atomic_int */
64#endif
65#include <sys/stat.h> /* for struct stat */
66#include <sys/types.h> /* for off_t etc. */
67#include <sys/statvfs.h> /* for struct statvfs */
68
69#include "sched.h"
70#include "clist.h"
71#include "iolist.h"
72#include "mtd.h"
73#include "xfa.h"
74
75#ifdef __cplusplus
76extern "C" {
77/* restrict is a C99 keyword, not valid in C++, but GCC and Clang have the
78 * __restrict__ extension keyword which can be used instead */
79#define restrict __restrict__
80/* If the above is not supported by the compiler, you can replace it with an
81 * empty definition instead: */
82/* #define restrict */
83#endif
84
89#ifndef _MAX
90#define _MAX(a, b) ((a) > (b) ? (a) : (b))
91#endif
92
93#ifndef MAX5
97#define MAX5(a, b, c, d, e) _MAX(_MAX(_MAX((a), (b)), _MAX((c),(d))), (e))
98#endif
105#ifdef MODULE_FATFS_VFS
106#include "ffconf.h"
107
108# if FF_FS_TINY
109# define _FATFS_FILE_CACHE (0)
110# else
111# define _FATFS_FILE_CACHE FF_MAX_SS
112# endif
113
114# if FF_USE_FASTSEEK
115# if (__SIZEOF_POINTER__ == 8)
116# define _FATFS_FILE_SEEK_PTR (8)
117# else
118# define _FATFS_FILE_SEEK_PTR (4)
119# endif
120# else
121# define _FATFS_FILE_SEEK_PTR (0)
122# endif
123
124# if FF_FS_EXFAT
125# define _FATFS_FILE_EXFAT (44)
126# define _FATFS_DIR_EXFAT (32)
127# else
128# define _FATFS_FILE_EXFAT (0)
129# define _FATFS_DIR_EXFAT (0)
130# endif
131
132# if FF_USE_LFN
133# if (__SIZEOF_POINTER__ == 8)
134# define _FATFS_DIR_LFN (8)
135# else
136# define _FATFS_DIR_LFN (4)
137# endif
138# else
139# define _FATFS_DIR_LFN (0)
140# endif
141
142# if (__SIZEOF_POINTER__ == 8)
143# define FATFS_VFS_DIR_BUFFER_SIZE (64 + _FATFS_DIR_LFN + _FATFS_DIR_EXFAT)
144# define FATFS_VFS_FILE_BUFFER_SIZE (64 + VFS_NAME_MAX + _FATFS_FILE_CACHE + \
145 _FATFS_FILE_SEEK_PTR + _FATFS_FILE_EXFAT)
146# else
147# define FATFS_VFS_DIR_BUFFER_SIZE (44 + _FATFS_DIR_LFN + _FATFS_DIR_EXFAT)
148# define FATFS_VFS_FILE_BUFFER_SIZE (44 + VFS_NAME_MAX + _FATFS_FILE_CACHE + \
149 _FATFS_FILE_SEEK_PTR + _FATFS_FILE_EXFAT)
150# endif
151#else
152# define FATFS_VFS_DIR_BUFFER_SIZE (1)
153# define FATFS_VFS_FILE_BUFFER_SIZE (1)
154#endif
161#ifdef MODULE_LITTLEFS
162# if (__SIZEOF_POINTER__ == 8)
163# define LITTLEFS_VFS_DIR_BUFFER_SIZE (48)
164# define LITTLEFS_VFS_FILE_BUFFER_SIZE (72)
165# else
166# define LITTLEFS_VFS_DIR_BUFFER_SIZE (44)
167# define LITTLEFS_VFS_FILE_BUFFER_SIZE (56)
168# endif
169#else
170# define LITTLEFS_VFS_DIR_BUFFER_SIZE (1)
171# define LITTLEFS_VFS_FILE_BUFFER_SIZE (1)
172#endif
179#ifdef MODULE_LITTLEFS2
180# if (__SIZEOF_POINTER__ == 8)
181# define LITTLEFS2_VFS_DIR_BUFFER_SIZE (56)
182# define LITTLEFS2_VFS_FILE_BUFFER_SIZE (104)
183# else
184# define LITTLEFS2_VFS_DIR_BUFFER_SIZE (52)
185# define LITTLEFS2_VFS_FILE_BUFFER_SIZE (84)
186# endif
187#else
188# define LITTLEFS2_VFS_DIR_BUFFER_SIZE (1)
189# define LITTLEFS2_VFS_FILE_BUFFER_SIZE (1)
190#endif
197#ifdef MODULE_SPIFFS
198# define SPIFFS_VFS_DIR_BUFFER_SIZE (12)
199# define SPIFFS_VFS_FILE_BUFFER_SIZE (1)
200#else
201# define SPIFFS_VFS_DIR_BUFFER_SIZE (1)
202# define SPIFFS_VFS_FILE_BUFFER_SIZE (1)
203#endif
210#if defined(MODULE_LWEXT4) || DOXYGEN
211# define LWEXT4_VFS_DIR_BUFFER_SIZE (308)
212# define LWEXT4_VFS_FILE_BUFFER_SIZE (32)
213#else
214# define LWEXT4_VFS_DIR_BUFFER_SIZE (1)
215# define LWEXT4_VFS_FILE_BUFFER_SIZE (1)
216#endif
219#ifndef VFS_MAX_OPEN_FILES
223#define VFS_MAX_OPEN_FILES (16)
224#endif
225
226#ifndef VFS_DIR_BUFFER_SIZE
254#define VFS_DIR_BUFFER_SIZE MAX5(FATFS_VFS_DIR_BUFFER_SIZE, \
255 LITTLEFS_VFS_DIR_BUFFER_SIZE, \
256 LITTLEFS2_VFS_DIR_BUFFER_SIZE, \
257 SPIFFS_VFS_DIR_BUFFER_SIZE, \
258 LWEXT4_VFS_DIR_BUFFER_SIZE \
259 )
260#endif
261
262#ifndef VFS_FILE_BUFFER_SIZE
282#define VFS_FILE_BUFFER_SIZE MAX5(FATFS_VFS_FILE_BUFFER_SIZE, \
283 LITTLEFS_VFS_FILE_BUFFER_SIZE, \
284 LITTLEFS2_VFS_FILE_BUFFER_SIZE,\
285 SPIFFS_VFS_FILE_BUFFER_SIZE, \
286 LWEXT4_VFS_FILE_BUFFER_SIZE \
287 )
288#endif
289
290#ifndef VFS_NAME_MAX
298#define VFS_NAME_MAX (31)
299#endif
300
304#define VFS_ANY_FD (-1)
305
311#define VFS_MTD(mtd) { .dev = &mtd.base }
312
326#define VFS_AUTO_MOUNT(type, mtd, path, idx) \
327 static type ## _desc_t fs_desc_ ## idx = mtd; \
328 \
329 XFA(vfs_mountpoints_xfa, 0) \
330 vfs_mount_t _mount_mtd_ ## idx = { \
331 .fs = &type ## _file_system, \
332 .mount_point = path, \
333 .private_data = &fs_desc_ ## idx, \
334 }
335
336/* Forward declarations */
341
346
351
355/* not struct vfs_mount because of name collision with the function */
357
361extern const vfs_file_ops_t mtd_vfs_ops;
362
366#define VFS_FS_FLAG_WANT_ABS_PATH (1 << 0)
367
371typedef struct {
375 const uint32_t flags;
377
389
395typedef struct {
398 int flags;
399 off_t pos;
401 union {
402 void *ptr;
403 int value;
404 uint8_t buffer[VFS_FILE_BUFFER_SIZE];
405 } private_data;
406} vfs_file_t;
407
416typedef struct {
419 union {
420 void *ptr;
421 int value;
422 uint8_t buffer[VFS_DIR_BUFFER_SIZE];
423 } private_data;
424} vfs_DIR;
425
434typedef struct {
435 ino_t d_ino;
436 char d_name[VFS_NAME_MAX + 1];
438
463 int (*close) (vfs_file_t *filp);
464
475 int (*fcntl) (vfs_file_t *filp, int cmd, int arg);
476
486 int (*fstat) (vfs_file_t *filp, struct stat *buf);
487
505 off_t (*lseek) (vfs_file_t *filp, off_t off, int whence);
506
533 int (*open) (vfs_file_t *filp, const char *name, int flags, mode_t mode);
534
545 ssize_t (*read) (vfs_file_t *filp, void *dest, size_t nbytes);
546
557 ssize_t (*write) (vfs_file_t *filp, const void *src, size_t nbytes);
558
568 int (*fsync) (vfs_file_t *filp);
569};
570
584 int (*opendir) (vfs_DIR *dirp, const char *dirname);
585
605 int (*readdir) (vfs_DIR *dirp, vfs_dirent_t *entry);
606
615 int (*closedir) (vfs_DIR *dirp);
616};
617
632 int (*format) (vfs_mount_t *mountp);
633
648 int (*mount) (vfs_mount_t *mountp);
649
658 int (*umount) (vfs_mount_t *mountp);
659
674 int (*rename) (vfs_mount_t *mountp, const char *from_path, const char *to_path);
675
685 int (*unlink) (vfs_mount_t *mountp, const char *name);
686
697 int (*mkdir) (vfs_mount_t *mountp, const char *name, mode_t mode);
698
710 int (*rmdir) (vfs_mount_t *mountp, const char *name);
711
722 int (*stat) (vfs_mount_t *mountp, const char *restrict path, struct stat *restrict buf);
723
739 int (*statvfs) (vfs_mount_t *mountp, const char *restrict path, struct statvfs *restrict buf);
740};
741
749void vfs_bind_stdio(void);
750
759int vfs_close(int fd);
760
771int vfs_fcntl(int fd, int cmd, int arg);
772
782int vfs_fstat(int fd, struct stat *buf);
783
793int vfs_fstatvfs(int fd, struct statvfs *buf);
794
804int vfs_dstatvfs(vfs_DIR *dirp, struct statvfs *buf);
805
823off_t vfs_lseek(int fd, off_t off, int whence);
824
835int vfs_open(const char *name, int flags, mode_t mode);
836
850ssize_t vfs_read(int fd, void *dest, size_t count);
851
865ssize_t vfs_write(int fd, const void *src, size_t count);
866
876ssize_t vfs_write_iol(int fd, const iolist_t *iolist);
877
887int vfs_fsync(int fd);
888
900int vfs_opendir(vfs_DIR *dirp, const char *dirname);
901
920
933
948
962int vfs_format_by_path(const char *path);
963
976
990int vfs_mount_by_path(const char *path);
991
1003int vfs_unmount_by_path(const char *path, bool force);
1004
1018int vfs_rename(const char *from_path, const char *to_path);
1019
1031int vfs_umount(vfs_mount_t *mountp, bool force);
1032
1041int vfs_unlink(const char *name);
1042
1052int vfs_mkdir(const char *name, mode_t mode);
1053
1064int vfs_rmdir(const char *name);
1065
1075int vfs_stat(const char *restrict path, struct stat *restrict buf);
1076
1089int vfs_statvfs(const char *restrict path, struct statvfs *restrict buf);
1090
1110int vfs_bind(int fd, int flags, const vfs_file_ops_t *f_op, void *private_data);
1111
1129int vfs_normalize_path(char *buf, const char *path, size_t buflen);
1130
1148
1179
1194
1206 const char *restrict path,
1207 struct stat *restrict buf);
1208
1209#ifdef __cplusplus
1210}
1211#endif
1212
1213#endif /* VFS_H */
1214
C++ compatibility of default C11 atomics types.
Circular linked list.
int16_t kernel_pid_t
Unique process identifier.
Definition sched.h:139
#define VFS_DIR_BUFFER_SIZE
Size of buffer space in vfs_DIR.
Definition vfs.h:254
int vfs_mount(vfs_mount_t *mountp)
Mount a file system.
int vfs_normalize_path(char *buf, const char *path, size_t buflen)
Normalize a path.
int vfs_open(const char *name, int flags, mode_t mode)
Open a file.
int vfs_statvfs(const char *restrict path, struct statvfs *restrict buf)
Get file system status.
ssize_t vfs_write(int fd, const void *src, size_t count)
Write bytes to an open file.
int vfs_mkdir(const char *name, mode_t mode)
Create a directory on the file system.
int vfs_umount(vfs_mount_t *mountp, bool force)
Unmount a mounted file system.
int vfs_close(int fd)
Close an open file.
#define VFS_FILE_BUFFER_SIZE
Size of buffer space in vfs_file_t.
Definition vfs.h:282
int vfs_sysop_stat_from_fstat(vfs_mount_t *mountp, const char *restrict path, struct stat *restrict buf)
Implementation of stat using fstat
const vfs_mount_t * vfs_iterate_mounts(const vfs_mount_t *cur)
Iterate through all mounted file systems.
#define VFS_NAME_MAX
Maximum length of the name in a vfs_dirent_t (not including terminating null)
Definition vfs.h:298
int vfs_readdir(vfs_DIR *dirp, vfs_dirent_t *entry)
Read a single entry from the open directory dirp and advance the read position by one.
off_t vfs_lseek(int fd, off_t off, int whence)
Seek to position in file.
int vfs_format(vfs_mount_t *mountp)
Format a file system.
int vfs_bind(int fd, int flags, const vfs_file_ops_t *f_op, void *private_data)
Allocate a new file descriptor and give it file operations.
int vfs_format_by_path(const char *path)
Format a file system.
int vfs_rename(const char *from_path, const char *to_path)
Rename a file.
ssize_t vfs_write_iol(int fd, const iolist_t *iolist)
Write bytes from an iolist to an open file.
int vfs_stat(const char *restrict path, struct stat *restrict buf)
Get file status.
void vfs_bind_stdio(void)
Allocate and bind file descriptors for STDIN, STDERR, and STDOUT.
const vfs_file_t * vfs_file_get(int fd)
Get information about the file for internal purposes.
int vfs_unlink(const char *name)
Unlink (delete) a file from a mounted file system.
int vfs_fsync(int fd)
Synchronize a file on storage Any pending writes are written out to storage.
int vfs_opendir(vfs_DIR *dirp, const char *dirname)
Open a directory for reading with readdir.
const vfs_file_ops_t mtd_vfs_ops
MTD driver for VFS.
int vfs_dstatvfs(vfs_DIR *dirp, struct statvfs *buf)
Get file system status of the file system containing an open directory.
int vfs_rmdir(const char *name)
Remove a directory from the file system.
int vfs_fcntl(int fd, int cmd, int arg)
Query/set options on an open file.
int vfs_fstat(int fd, struct stat *buf)
Get status of an open file.
ssize_t vfs_read(int fd, void *dest, size_t count)
Read bytes from an open file.
bool vfs_iterate_mount_dirs(vfs_DIR *dir)
Iterate through all mounted file systems by their root directories.
int vfs_closedir(vfs_DIR *dirp)
Close an open directory.
int vfs_fstatvfs(int fd, struct statvfs *buf)
Get file system status of the file system containing an open file.
int vfs_mount_by_path(const char *path)
Mount a file system with a pre-configured mount path.
int vfs_unmount_by_path(const char *path, bool force)
Unmount a file system with a pre-configured mount path.
iolist scatter / gather IO
Scheduler API definition.
POSIX compatible sys/statvfs.h definitions.
Type with the same alignment and size as atomic_int
iolist structure definition
Definition iolist.h:39
List node structure.
Definition list.h:40
File system information.
Definition statvfs.h:46
Internal representation of a file system directory entry.
Definition vfs.h:416
const vfs_dir_ops_t * d_op
Directory operations table.
Definition vfs.h:417
int value
alternatively, you can use private_data as an int
Definition vfs.h:421
vfs_mount_t * mp
Pointer to mount table entry.
Definition vfs.h:418
void * ptr
pointer to private data
Definition vfs.h:420
Operations on open directories.
Definition vfs.h:574
int(* readdir)(vfs_DIR *dirp, vfs_dirent_t *entry)
Read a single entry from the open directory dirp and advance the read position by one.
Definition vfs.h:605
int(* opendir)(vfs_DIR *dirp, const char *dirname)
Open a directory for reading with readdir.
Definition vfs.h:584
int(* closedir)(vfs_DIR *dirp)
Close an open directory.
Definition vfs.h:615
User facing directory entry.
Definition vfs.h:434
ino_t d_ino
file serial number, unique for the file system ("inode" in Linux)
Definition vfs.h:435
Operations on open files.
Definition vfs.h:444
int(* fcntl)(vfs_file_t *filp, int cmd, int arg)
Query/set options on an open file.
Definition vfs.h:475
int(* close)(vfs_file_t *filp)
Close an open file.
Definition vfs.h:463
int(* fstat)(vfs_file_t *filp, struct stat *buf)
Get status of an open file.
Definition vfs.h:486
int(* fsync)(vfs_file_t *filp)
Synchronize a file on storage Any pending writes are written out to storage.
Definition vfs.h:568
off_t(* lseek)(vfs_file_t *filp, off_t off, int whence)
Seek to position in file.
Definition vfs.h:505
int(* open)(vfs_file_t *filp, const char *name, int flags, mode_t mode)
Attempt to open a file in the file system at rel_path.
Definition vfs.h:533
ssize_t(* read)(vfs_file_t *filp, void *dest, size_t nbytes)
Read bytes from an open file.
Definition vfs.h:545
ssize_t(* write)(vfs_file_t *filp, const void *src, size_t nbytes)
Write bytes to an open file.
Definition vfs.h:557
Operations on mounted file systems.
Definition vfs.h:623
int(* mount)(vfs_mount_t *mountp)
Perform any extra processing needed after mounting a file system.
Definition vfs.h:648
int(* unlink)(vfs_mount_t *mountp, const char *name)
Unlink (delete) a file from the file system.
Definition vfs.h:685
int(* rename)(vfs_mount_t *mountp, const char *from_path, const char *to_path)
Rename a file.
Definition vfs.h:674
int(* stat)(vfs_mount_t *mountp, const char *restrict path, struct stat *restrict buf)
Get file status.
Definition vfs.h:722
int(* mkdir)(vfs_mount_t *mountp, const char *name, mode_t mode)
Create a directory on the file system.
Definition vfs.h:697
int(* format)(vfs_mount_t *mountp)
Format the file system on the given mount point.
Definition vfs.h:632
int(* rmdir)(vfs_mount_t *mountp, const char *name)
Remove a directory from the file system.
Definition vfs.h:710
int(* umount)(vfs_mount_t *mountp)
Perform the necessary clean up for unmounting a file system.
Definition vfs.h:658
A file system driver.
Definition vfs.h:371
const vfs_file_system_ops_t * fs_op
File system operations table.
Definition vfs.h:374
const vfs_dir_ops_t * d_op
Directory operations table.
Definition vfs.h:373
const vfs_file_ops_t * f_op
File operations table.
Definition vfs.h:372
const uint32_t flags
File system flags.
Definition vfs.h:375
Information about an open file.
Definition vfs.h:395
void * ptr
pointer to private data
Definition vfs.h:402
vfs_mount_t * mp
Pointer to mount table entry.
Definition vfs.h:397
kernel_pid_t pid
PID of the process that opened the file.
Definition vfs.h:400
int value
alternatively, you can use private_data as an int
Definition vfs.h:403
int flags
File flags.
Definition vfs.h:398
const vfs_file_ops_t * f_op
File operations table.
Definition vfs.h:396
off_t pos
Current position in the file.
Definition vfs.h:399
A mounted file system.
Definition vfs.h:381
const vfs_file_system_t * fs
The file system driver for the mount point.
Definition vfs.h:383
atomic_int open_files
Number of currently open files and directories.
Definition vfs.h:386
clist_node_t list_entry
List entry for the _vfs_mount_list list.
Definition vfs.h:382
size_t mount_point_len
Length of mount_point string (set by vfs_mount)
Definition vfs.h:385
void * private_data
File system driver private data, implementation defined.
Definition vfs.h:387
const char * mount_point
Mount point, e.g.
Definition vfs.h:384
Cross File Arrays.