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
9#pragma once
10
54
55#include <stdint.h>
56#include <sys/stat.h> /* for struct stat */
57#include <sys/types.h> /* for off_t etc. */
58#include <sys/statvfs.h> /* for struct statvfs */
59
60#include "sched.h"
61#include "clist.h"
62#include "iolist.h"
63#include "macros/utils.h"
64#include "mtd.h"
65#ifdef MODULE_NANOCOAP_FS
66#include "net/sock/config.h"
67#endif
68#include "xfa.h"
69
70#ifdef __cplusplus
71extern "C" {
72/* restrict is a C99 keyword, not valid in C++, but GCC and Clang have the
73 * __restrict__ extension keyword which can be used instead */
74#define restrict __restrict__
75/* If the above is not supported by the compiler, you can replace it with an
76 * empty definition instead: */
77/* #define restrict */
78#endif
79
83#ifndef MAX6
84#define MAX6(a, b, c, d, e, f) MAX(MAX(MAX(MAX((a), (b)), MAX((c), (d))), (e)), (f))
85#endif
86
91#ifdef MODULE_FATFS_VFS
92#include "ffconf.h"
93
94# if FF_FS_TINY
95# define _FATFS_FILE_CACHE (0)
96# else
97# define _FATFS_FILE_CACHE FF_MAX_SS
98# endif
99
100# if FF_USE_FASTSEEK
101# if (__SIZEOF_POINTER__ == 8)
102# define _FATFS_FILE_SEEK_PTR (8)
103# else
104# define _FATFS_FILE_SEEK_PTR (4)
105# endif
106# else
107# define _FATFS_FILE_SEEK_PTR (0)
108# endif
109
110# if FF_FS_EXFAT
111# define _FATFS_FILE_EXFAT (48)
112# define _FATFS_DIR_EXFAT (32)
113# else
114# define _FATFS_FILE_EXFAT (0)
115# define _FATFS_DIR_EXFAT (0)
116# endif
117
118# if FF_USE_LFN
119# if (__SIZEOF_POINTER__ == 8)
120# define _FATFS_DIR_LFN (8)
121# else
122# define _FATFS_DIR_LFN (4)
123# endif
124# else
125# define _FATFS_DIR_LFN (0)
126# endif
127
128# if (__SIZEOF_POINTER__ == 8)
129# define FATFS_VFS_DIR_BUFFER_SIZE (64 + _FATFS_DIR_LFN + _FATFS_DIR_EXFAT)
130# define FATFS_VFS_FILE_BUFFER_SIZE (64 + VFS_NAME_MAX + _FATFS_FILE_CACHE + \
131 _FATFS_FILE_SEEK_PTR + _FATFS_FILE_EXFAT)
132# else
133# define FATFS_VFS_DIR_BUFFER_SIZE (44 + _FATFS_DIR_LFN + _FATFS_DIR_EXFAT)
134# define FATFS_VFS_FILE_BUFFER_SIZE (44 + VFS_NAME_MAX + _FATFS_FILE_CACHE + \
135 _FATFS_FILE_SEEK_PTR + _FATFS_FILE_EXFAT)
136# endif
137#else
138# define FATFS_VFS_DIR_BUFFER_SIZE (1)
139# define FATFS_VFS_FILE_BUFFER_SIZE (1)
140#endif
142
147#ifdef MODULE_LITTLEFS
148# if (__SIZEOF_POINTER__ == 8)
149# define LITTLEFS_VFS_DIR_BUFFER_SIZE (48)
150# define LITTLEFS_VFS_FILE_BUFFER_SIZE (72)
151# else
152# define LITTLEFS_VFS_DIR_BUFFER_SIZE (44)
153# define LITTLEFS_VFS_FILE_BUFFER_SIZE (56)
154# endif
155#else
156# define LITTLEFS_VFS_DIR_BUFFER_SIZE (1)
157# define LITTLEFS_VFS_FILE_BUFFER_SIZE (1)
158#endif
160
165#ifdef MODULE_LITTLEFS2
166# if (__SIZEOF_POINTER__ == 8)
167# define LITTLEFS2_VFS_DIR_BUFFER_SIZE (56)
168# define LITTLEFS2_VFS_FILE_BUFFER_SIZE (104)
169# else
170# define LITTLEFS2_VFS_DIR_BUFFER_SIZE (52)
171# define LITTLEFS2_VFS_FILE_BUFFER_SIZE (84)
172# endif
173#else
174# define LITTLEFS2_VFS_DIR_BUFFER_SIZE (1)
175# define LITTLEFS2_VFS_FILE_BUFFER_SIZE (1)
176#endif
178
183#ifdef MODULE_SPIFFS
184# define SPIFFS_VFS_DIR_BUFFER_SIZE (12)
185# define SPIFFS_VFS_FILE_BUFFER_SIZE (1)
186#else
187# define SPIFFS_VFS_DIR_BUFFER_SIZE (1)
188# define SPIFFS_VFS_FILE_BUFFER_SIZE (1)
189#endif
191
196#if defined(MODULE_LWEXT4) || DOXYGEN
197# define LWEXT4_VFS_DIR_BUFFER_SIZE (308)
198# define LWEXT4_VFS_FILE_BUFFER_SIZE (32)
199#else
200# define LWEXT4_VFS_DIR_BUFFER_SIZE (1)
201# define LWEXT4_VFS_FILE_BUFFER_SIZE (1)
202#endif
204
209#if defined(MODULE_NANOCOAP_FS) || DOXYGEN
210# define NANOCOAP_FS_VFS_DIR_BUFFER_SIZE \
211 (4 + CONFIG_SOCK_URLPATH_MAXLEN)
212# define NANOCOAP_FS_VFS_FILE_BUFFER_SIZE \
213 (4 + CONFIG_SOCK_URLPATH_MAXLEN)
214#else
215# define NANOCOAP_FS_VFS_DIR_BUFFER_SIZE (1)
216# define NANOCOAP_FS_VFS_FILE_BUFFER_SIZE (1)
217#endif
219
220#ifndef VFS_MAX_OPEN_FILES
224#define VFS_MAX_OPEN_FILES (16)
225#endif
226
227#ifndef VFS_DIR_BUFFER_SIZE
255#define VFS_DIR_BUFFER_SIZE MAX6(FATFS_VFS_DIR_BUFFER_SIZE, \
256 LITTLEFS_VFS_DIR_BUFFER_SIZE, \
257 LITTLEFS2_VFS_DIR_BUFFER_SIZE, \
258 SPIFFS_VFS_DIR_BUFFER_SIZE, \
259 LWEXT4_VFS_DIR_BUFFER_SIZE, \
260 NANOCOAP_FS_VFS_DIR_BUFFER_SIZE \
261 )
262#endif
263
264#ifndef VFS_FILE_BUFFER_SIZE
284#define VFS_FILE_BUFFER_SIZE MAX6(FATFS_VFS_FILE_BUFFER_SIZE, \
285 LITTLEFS_VFS_FILE_BUFFER_SIZE, \
286 LITTLEFS2_VFS_FILE_BUFFER_SIZE, \
287 SPIFFS_VFS_FILE_BUFFER_SIZE, \
288 LWEXT4_VFS_FILE_BUFFER_SIZE, \
289 NANOCOAP_FS_VFS_FILE_BUFFER_SIZE \
290 )
291#endif
292
293#ifndef VFS_NAME_MAX
301#define VFS_NAME_MAX (31)
302#endif
303
307#define VFS_ANY_FD (-1)
308
314#define VFS_MTD(mtd) { .dev = &mtd.base }
315
329#define VFS_AUTO_MOUNT(type, mtd, path, idx) \
330 static type ## _desc_t fs_desc_ ## idx = mtd; \
331 \
332 XFA(vfs_mount_t, vfs_mountpoints_xfa, 0) \
333 _mount_mtd_ ## idx = { \
334 .fs = &type ## _file_system, \
335 .mount_point = path, \
336 .private_data = &fs_desc_ ## idx, \
337 }
338
339/* Forward declarations */
344
349
354
358/* not struct vfs_mount because of name collision with the function */
360
364extern const vfs_file_ops_t mtd_vfs_ops;
365
369#define VFS_FS_FLAG_WANT_ABS_PATH (1 << 0)
370
374typedef struct {
378 const uint32_t flags;
380
392
398typedef struct {
401 int flags;
402 off_t pos;
404 union {
405 void *ptr;
406 int value;
408 } private_data;
409} vfs_file_t;
410
419typedef struct {
422 union {
423 void *ptr;
424 int value;
426 } private_data;
427} vfs_DIR;
428
437typedef struct {
438 ino_t d_ino;
441
466 int (*close) (vfs_file_t *filp);
467
478 int (*fcntl) (vfs_file_t *filp, int cmd, int arg);
479
489 int (*fstat) (vfs_file_t *filp, struct stat *buf);
490
508 off_t (*lseek) (vfs_file_t *filp, off_t off, int whence);
509
536 int (*open) (vfs_file_t *filp, const char *name, int flags, mode_t mode);
537
548 ssize_t (*read) (vfs_file_t *filp, void *dest, size_t nbytes);
549
560 ssize_t (*write) (vfs_file_t *filp, const void *src, size_t nbytes);
561
571 int (*fsync) (vfs_file_t *filp);
572};
573
587 int (*opendir) (vfs_DIR *dirp, const char *dirname);
588
608 int (*readdir) (vfs_DIR *dirp, vfs_dirent_t *entry);
609
618 int (*closedir) (vfs_DIR *dirp);
619};
620
635 int (*format) (vfs_mount_t *mountp);
636
651 int (*mount) (vfs_mount_t *mountp);
652
661 int (*umount) (vfs_mount_t *mountp);
662
677 int (*rename) (vfs_mount_t *mountp, const char *from_path, const char *to_path);
678
688 int (*unlink) (vfs_mount_t *mountp, const char *name);
689
700 int (*mkdir) (vfs_mount_t *mountp, const char *name, mode_t mode);
701
713 int (*rmdir) (vfs_mount_t *mountp, const char *name);
714
725 int (*stat) (vfs_mount_t *mountp, const char *restrict path, struct stat *restrict buf);
726
742 int (*statvfs) (vfs_mount_t *mountp, const char *restrict path, struct statvfs *restrict buf);
743};
744
752void vfs_bind_stdio(void);
753
762int vfs_close(int fd);
763
774int vfs_fcntl(int fd, int cmd, int arg);
775
785int vfs_fstat(int fd, struct stat *buf);
786
796int vfs_fstatvfs(int fd, struct statvfs *buf);
797
807int vfs_dstatvfs(vfs_DIR *dirp, struct statvfs *buf);
808
826off_t vfs_lseek(int fd, off_t off, int whence);
827
838int vfs_open(const char *name, int flags, mode_t mode);
839
853ssize_t vfs_read(int fd, void *dest, size_t count);
854
867ssize_t vfs_readline(int fd, char *dest, size_t count);
868
882ssize_t vfs_write(int fd, const void *src, size_t count);
883
893ssize_t vfs_write_iol(int fd, const iolist_t *iolist);
894
904int vfs_fsync(int fd);
905
917int vfs_opendir(vfs_DIR *dirp, const char *dirname);
918
937
950
965
979int vfs_format_by_path(const char *path);
980
993
1007int vfs_mount_by_path(const char *path);
1008
1020int vfs_unmount_by_path(const char *path, bool force);
1021
1035int vfs_rename(const char *from_path, const char *to_path);
1036
1048int vfs_umount(vfs_mount_t *mountp, bool force);
1049
1058int vfs_unlink(const char *name);
1059
1069int vfs_mkdir(const char *name, mode_t mode);
1070
1081int vfs_rmdir(const char *name);
1082
1092int vfs_stat(const char *restrict path, struct stat *restrict buf);
1093
1106int vfs_statvfs(const char *restrict path, struct statvfs *restrict buf);
1107
1127int vfs_bind(int fd, int flags, const vfs_file_ops_t *f_op, void *private_data);
1128
1146int vfs_normalize_path(char *buf, const char *path, size_t buflen);
1147
1178
1193
1205 const char *restrict path,
1206 struct stat *restrict buf);
1207
1208#ifdef __cplusplus
1209}
1210#endif
1211
Circular linked list.
list_node_t clist_node_t
List node structure.
Definition clist.h:106
Various helper macros.
int16_t kernel_pid_t
Unique process identifier.
Definition sched.h:138
struct iolist iolist_t
iolist forward declaration
Definition iolist.h:33
#define VFS_DIR_BUFFER_SIZE
Size of buffer space in vfs_DIR.
Definition vfs.h:255
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.
struct vfs_file_system_ops vfs_file_system_ops_t
struct vfs_file_system_ops typedef
Definition vfs.h:353
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:284
int vfs_sysop_stat_from_fstat(vfs_mount_t *mountp, const char *restrict path, struct stat *restrict buf)
Implementation of stat using fstat
#define VFS_NAME_MAX
Maximum length of the name in a vfs_dirent_t (not including terminating null)
Definition vfs.h:301
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.
ssize_t vfs_readline(int fd, char *dest, size_t count)
Read a line from an open text file.
struct vfs_mount_struct vfs_mount_t
struct vfs_mount_struct typedef
Definition vfs.h:359
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.
struct vfs_file_ops vfs_file_ops_t
struct vfs_file_ops typedef
Definition vfs.h:343
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.
struct vfs_dir_ops vfs_dir_ops_t
struct vfs_dir_ops typedef
Definition vfs.h:348
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.
iolist structure definition
Definition iolist.h:38
File system information.
Definition statvfs.h:46
Internal representation of a file system directory entry.
Definition vfs.h:419
const vfs_dir_ops_t * d_op
Directory operations table.
Definition vfs.h:420
int value
alternatively, you can use private_data as an int
Definition vfs.h:424
uint8_t buffer[VFS_DIR_BUFFER_SIZE]
Buffer space, in case a single pointer is not enough.
Definition vfs.h:425
vfs_mount_t * mp
Pointer to mount table entry.
Definition vfs.h:421
void * ptr
pointer to private data
Definition vfs.h:423
Operations on open directories.
Definition vfs.h:577
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:608
int(* opendir)(vfs_DIR *dirp, const char *dirname)
Open a directory for reading with readdir.
Definition vfs.h:587
int(* closedir)(vfs_DIR *dirp)
Close an open directory.
Definition vfs.h:618
User facing directory entry.
Definition vfs.h:437
ino_t d_ino
file serial number, unique for the file system ("inode" in Linux)
Definition vfs.h:438
char d_name[VFS_NAME_MAX+1]
file name, relative to its containing directory
Definition vfs.h:439
Operations on open files.
Definition vfs.h:447
int(* fcntl)(vfs_file_t *filp, int cmd, int arg)
Query/set options on an open file.
Definition vfs.h:478
int(* close)(vfs_file_t *filp)
Close an open file.
Definition vfs.h:466
int(* fstat)(vfs_file_t *filp, struct stat *buf)
Get status of an open file.
Definition vfs.h:489
int(* fsync)(vfs_file_t *filp)
Synchronize a file on storage Any pending writes are written out to storage.
Definition vfs.h:571
off_t(* lseek)(vfs_file_t *filp, off_t off, int whence)
Seek to position in file.
Definition vfs.h:508
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:536
ssize_t(* read)(vfs_file_t *filp, void *dest, size_t nbytes)
Read bytes from an open file.
Definition vfs.h:548
ssize_t(* write)(vfs_file_t *filp, const void *src, size_t nbytes)
Write bytes to an open file.
Definition vfs.h:560
Operations on mounted file systems.
Definition vfs.h:626
int(* statvfs)(vfs_mount_t *mountp, const char *restrict path, struct statvfs *restrict buf)
Get file system status.
Definition vfs.h:742
int(* mount)(vfs_mount_t *mountp)
Perform any extra processing needed after mounting a file system.
Definition vfs.h:651
int(* unlink)(vfs_mount_t *mountp, const char *name)
Unlink (delete) a file from the file system.
Definition vfs.h:688
int(* rename)(vfs_mount_t *mountp, const char *from_path, const char *to_path)
Rename a file.
Definition vfs.h:677
int(* stat)(vfs_mount_t *mountp, const char *restrict path, struct stat *restrict buf)
Get file status.
Definition vfs.h:725
int(* mkdir)(vfs_mount_t *mountp, const char *name, mode_t mode)
Create a directory on the file system.
Definition vfs.h:700
int(* format)(vfs_mount_t *mountp)
Format the file system on the given mount point.
Definition vfs.h:635
int(* rmdir)(vfs_mount_t *mountp, const char *name)
Remove a directory from the file system.
Definition vfs.h:713
int(* umount)(vfs_mount_t *mountp)
Perform the necessary clean up for unmounting a file system.
Definition vfs.h:661
A file system driver.
Definition vfs.h:374
const vfs_file_system_ops_t * fs_op
File system operations table.
Definition vfs.h:377
const vfs_dir_ops_t * d_op
Directory operations table.
Definition vfs.h:376
const vfs_file_ops_t * f_op
File operations table.
Definition vfs.h:375
const uint32_t flags
File system flags.
Definition vfs.h:378
Information about an open file.
Definition vfs.h:398
void * ptr
pointer to private data
Definition vfs.h:405
vfs_mount_t * mp
Pointer to mount table entry.
Definition vfs.h:400
kernel_pid_t pid
PID of the process that opened the file.
Definition vfs.h:403
int value
alternatively, you can use private_data as an int
Definition vfs.h:406
int flags
File flags.
Definition vfs.h:401
const vfs_file_ops_t * f_op
File operations table.
Definition vfs.h:399
uint8_t buffer[VFS_FILE_BUFFER_SIZE]
Buffer space, in case a single pointer is not enough.
Definition vfs.h:407
off_t pos
Current position in the file.
Definition vfs.h:402
A mounted file system.
Definition vfs.h:384
const vfs_file_system_t * fs
The file system driver for the mount point.
Definition vfs.h:386
clist_node_t list_entry
List entry for the _vfs_mount_list list.
Definition vfs.h:385
size_t mount_point_len
Length of mount_point string (set by vfs_mount)
Definition vfs.h:388
uint16_t open_files
Number of currently open files and directories.
Definition vfs.h:389
void * private_data
File system driver private data, implementation defined.
Definition vfs.h:390
const char * mount_point
Mount point, e.g.
Definition vfs.h:387
Cross File Arrays.