Fábio Coutada
ae6144a1c5
- Extract 37 of 45 PDFs under docs/ to docs-extracted/ - Preserve directory structure (apex, cdk, development, platform, etc.) - Add docs-extracted/index.md with navigation table - 8 PDFs were 0-byte/empty and could not be extracted
3189 lines
123 KiB
Markdown
3189 lines
123 KiB
Markdown
---
|
||
title: "Cfs Reference Manual"
|
||
source: "docs/development/cfs-reference-manual.pdf"
|
||
category: "development"
|
||
pages: 77
|
||
extracted: "2026-07-06T23:05:34.121920"
|
||
---
|
||
|
||
# Cfs Reference Manual
|
||
|
||
> Extracted from `docs/development/cfs-reference-manual.pdf` (77 pages).
|
||
> Figures, diagrams, and tables may not render accurately in plain text.
|
||
|
||
CFS - A Certifiable File System for
|
||
PikeOS
|
||
|
||
|
||
Am Pfaffenstein 14, D-55270 Klein-Winternheim
|
||
|
||
Notice: The contents of this document are proprietary to
|
||
SYSGO GmbH and shall not be disclosed, disseminated,
|
||
copied, or used except for purposes expressly
|
||
authorized in writing by SYSGO GmbH.
|
||
CFS - A Certifiable File System for PikeOS
|
||
PikeOS D5.0, Document Version D5.0-8
|
||
|
||
c 2005 – 2019 SYSGO GmbH
|
||
|
||
SYSGO GmbH Email: office@sysgo.com
|
||
Am Pfaffenstein 14
|
||
55270 Klein-Winternheim, Germany http://www.sysgo.com
|
||
|
||
All rights reserved.
|
||
PikeOS is a trademark of SYSGO GmbH. The designations used to identify other software or hardware products
|
||
in this publication may be trademarks of their manufacturers or sellers.
|
||
Contents
|
||
|
||
|
||
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
|
||
2 PikeOS Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
|
||
3 CFS PikeOS API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
|
||
3.1 Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
|
||
3.2 PikeOS Native API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
|
||
3.2.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
|
||
3.2.1.1 struct cfs_err_desc_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
|
||
3.2.1.2 struct cfs_mount_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
|
||
3.2.1.3 struct cfs_config_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
|
||
3.2.1.4 struct cfs_file_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
|
||
3.2.1.5 struct cfs_stat_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
|
||
3.2.1.6 struct cfs_utimbuf_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
|
||
3.2.1.7 struct cfs_statvfs_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
|
||
3.2.1.8 struct cfs_dirent_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
|
||
3.2.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
|
||
3.2.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
|
||
3.2.4 Function Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
|
||
3.2.4.1 cfs_err_callback_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
|
||
3.2.4.2 cfs_block_read_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
|
||
3.2.4.3 cfs_block_write_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
|
||
3.2.5 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
|
||
3.2.6 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
|
||
3.2.6.1 cfs_mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
|
||
3.2.6.2 cfs_unmount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
|
||
3.2.6.3 cfs_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
|
||
3.2.6.4 cfs_stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
|
||
3.2.6.5 cfs_access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
|
||
3.2.6.6 cfs_chmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
|
||
3.2.6.7 cfs_utime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
|
||
3.2.6.8 cfs_unlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
|
||
3.2.6.9 cfs_rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
|
||
3.2.6.10 cfs_statvfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
|
||
3.2.6.11 cfs_mkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
|
||
3.2.6.12 cfs_rmdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
|
||
3.2.6.13 cfs_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
|
||
3.2.6.14 cfs_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
|
||
3.2.6.15 cfs_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
|
||
3.2.6.16 cfs_lseek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
|
||
3.2.6.17 cfs_ftruncate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
|
||
3.2.6.18 cfs_fstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
|
||
3.2.6.19 cfs_getdents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
|
||
3.2.6.20 cfs_mkfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
4 CONTENTS
|
||
|
||
|
||
4 POSIX Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
|
||
5 CFS POSIX API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
|
||
5.1 Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
|
||
5.2 POSIX API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
|
||
5.2.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
|
||
5.2.1.1 struct cfs_err_desc_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
|
||
5.2.1.2 struct cfs_mount_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
|
||
5.2.1.3 struct cfs_config_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
|
||
5.2.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
|
||
5.2.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
|
||
5.2.4 Function Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
|
||
5.2.4.1 cfs_err_callback_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
|
||
5.2.4.2 cfs_block_read_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
|
||
5.2.4.3 cfs_block_write_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
|
||
5.2.5 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
|
||
5.2.6 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
|
||
5.2.6.1 mount_cfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
|
||
5.2.6.2 unmount_cfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
|
||
5.2.6.3 mkfs_cfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
|
||
6 cfs-tool Helper Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
|
||
7 CFS for PikeOS Native Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
|
||
7.1 Total CFS Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
|
||
7.2 Partial Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
|
||
7.2.1 CFS Configuration Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
|
||
7.2.2 Internal File Descripton Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
|
||
7.2.3 Memory Objects Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
|
||
7.2.4 Rollback Bistring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
|
||
7.2.5 Free Disk Resources Bitmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
|
||
7.2.6 Various helper buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
|
||
7.2.7 External file description pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
|
||
8 Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
|
||
8.1 CFS Design Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
|
||
8.2 CFS Mount Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
|
||
8.3 Write Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
|
||
8.4 Growing a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
|
||
8.5 Considerations When Used With Volume Providers . . . . . . . . . . . . . . . . . . . . . . . . . 74
|
||
8.6 Considerations When Used With SD Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
|
||
9 Limitations of the CFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
|
||
10 Copyright Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
1 Introduction
|
||
|
||
|
||
The Certifiable File System (CFS) is an optional PikeOS component that provides a fail safe file system with more
|
||
functionality than the PikeOS native file system. In addition to the basic file operations implemented by the internal
|
||
PikeOS file providers (open, close, read, write, map, ioctl, lseek, stat), the CFS can also handle directories and file
|
||
manipulations (create, delete, rename, truncate, chmod). It is still a simplified file system compared to standard
|
||
Linux file systems.
|
||
The CFS can be mounted and unmounted at runtime. It is possible to mount the CFS into the root directory of an
|
||
existing POSIX file system.
|
||
CFS is designed to run on block devices with a configurable block size. The device driver has to provide block
|
||
read and write functions to CFS. They are passed as callback functions to CFS upon mounting. In addition to the
|
||
callback functions, a handle is passed to CFS that will be provided as an argument at each call of the callback
|
||
functions. This handle can either represent the memory area on which the block device runs, or a PikeOS file
|
||
descriptor. This allows the block read and block write functions to be implemented by a PikeOS file provider. CFS
|
||
then resides within a PikeOS file, without PikeOS knowing anything about the CFS directory tree representation.
|
||
|
||
|
||
Figure 1: CFS linked to an application using a disk driver
|
||
|
||
|
||
Figure 2: CFS linked to an application using a PikeOS file provider
|
||
|
||
|
||
To assure a fail safe file system, all changes within the CFS lead to an immediate device access. Furthermore
|
||
integrity checks of the file system meta data are performed by the CFS at mounting.
|
||
CFS is provided as a library that can be linked to a PikeOS or POSIX process. Each CFS instance is mounted by
|
||
a single PikeOS process. Parallel access from different threads is forbidden. However, the PikeOS external file
|
||
provider concept makes it possible to use CFS in a more versatile way. If CFS is linked to an external file provider,
|
||
multiple threads can access the external file provider in parallel and so the CFS access is serialized.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
6 Introduction
|
||
|
||
|
||
Figure 3: 2 applications using an external file provider containing CFS
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
2 PikeOS Sample Application
|
||
|
||
|
||
A CFS sample application is included in the delivery. It is a simple application that sets up CFS using a simulated
|
||
disk on shared memory, then performs some basic file operations. When the CFS package is installed, you can
|
||
clone the CFS sample application and integration projects in CODEO or on command line like other PikeOS demo
|
||
projects.
|
||
The base directory for the sample is /opt/pikeos-D5.0/demo/pikeos-native.
|
||
|
||
|
||
Figure 4: Cloning the CFS demo project
|
||
|
||
|
||
The CFS sample uses the PikeOS remote shell (Pirsh) to load the disk and images to the target and to start
|
||
the application afterwards. The shell script copy_disk.sh located in the integration project does these operations
|
||
automatically.
|
||
The PikeOS remote shell uses a MUXA channel, so make sure you correctly set up the HostIP, TargetIP and
|
||
GatewayIP in the Project Configuration Editor.
|
||
If you run the demo on QEMU, the host side MUXA is automatically started with the simulation target. When using
|
||
a real target, start the host side MUXA manually before running copy_disk.sh.
|
||
When everything is setup correctly, the PikeOS console should show an output similar to this:
|
||
|
||
----- CFS demo starting up -----
|
||
|
||
Mount filesystem:
|
||
Device ’shm:/DISK’ successfully mounted: handle 0x8024014
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
8 PikeOS Sample Application
|
||
|
||
|
||
Figure 5: CFS demo MUXA configuration
|
||
|
||
|
||
----- ls -----
|
||
1 drw-r--r-- 1000 100 36 dir1
|
||
2 -rw-r--r-- 1000 100 26 text
|
||
3 -rw-r--r-- 1000 100 29 date
|
||
4 -rw-r--r-- 1000 100 757504 system.reg
|
||
5 -rw-r--r-- 1000 100 56 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
|
||
--------------
|
||
Dumping contents of file "dir1/text":
|
||
Hello World from your CFS
|
||
|
||
--------------
|
||
|
||
Opening "system.reg" for writing:
|
||
Write 26 bytes read from "dir1/text" at offset 479220
|
||
Successfully wrote 26 bytes to file.
|
||
|
||
----- ls -----
|
||
1 drw-r--r-- 1000 100 36 dir1
|
||
2 -rw-r--r-- 1000 100 26 text
|
||
3 -rw-r--r-- 1000 100 29 date
|
||
4 -rw-r--r-- 1000 100 757504 system.reg
|
||
5 -rw-r--r-- 1000 100 56 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
|
||
--------------
|
||
|
||
----- CFS demo finished -----
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
3 CFS PikeOS API Reference
|
||
|
||
|
||
This section presents the data types and functions available in the CFS PikeOS API. The CFS head-
|
||
ers and libraries are located in the PikeOS installation path for the target architecture (/opt/pikeos-
|
||
D5.0/target/<arch>/<proc>/include/cfs, /opt/pikeos-D5.0/target/<arch>/<proc>/lib).
|
||
|
||
|
||
3.1 Header File
|
||
|
||
Header file to include, providing CFS PikeOS API functions and definitions:
|
||
#include <cfs.h>
|
||
|
||
|
||
3.2 PikeOS Native API
|
||
|
||
This section describes API provided by the CFS library for the PikeOS native applications.
|
||
|
||
|
||
3.2.1 Structure Definitions
|
||
|
||
3.2.1.1 struct cfs_err_desc_s
|
||
|
||
Structure with error description.
|
||
Structure with detailed description of an error found by checks during the file system mount.
|
||
|
||
Synopsis:
|
||
struct cfs_err_desc_s {
|
||
cfs_err_type_t type;
|
||
const char * path;
|
||
cfs_ino_t dir_ino;
|
||
cfs_ino_t wrong_ino;
|
||
cfs_ino_t wrong_ino_value;
|
||
cfs_off_t size_old;
|
||
cfs_off_t size_new;
|
||
cfs_inode_type_t inode_type;
|
||
cfs_inode_type_t inode_type_expected;
|
||
cfs_file_type_t file_type;
|
||
P4_uint32_t old_count;
|
||
P4_uint32_t new_count;
|
||
cfs_blkno_t blkno;
|
||
cfs_off_t blocksize;
|
||
};
|
||
|
||
Structure Element Description:
|
||
type type of the found error
|
||
path path of the file in which the error was found
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
10 CFS PikeOS API Reference
|
||
|
||
|
||
dir_ino direct inode of the file in which the error was found
|
||
wrong_ino number of inode in which the error was found
|
||
wrong_ino_value wrong entry in the inode table
|
||
size_old current file size in the file system
|
||
size_new file size after truncating
|
||
inode_type incorrect type of the inode
|
||
inode_type_expected expected type of the inode
|
||
file_type incorrect type of file
|
||
old_count incorrect link count
|
||
new_count correct link count
|
||
blkno incorrect block number
|
||
blocksize incorrect block size
|
||
|
||
|
||
Associated Data Type
|
||
|
||
cfs_err_desc_t Structure with error description.
|
||
|
||
|
||
3.2.1.2 struct cfs_mount_s
|
||
|
||
File system parameters.
|
||
Describes operational parameters for a CFS instance to be mounted.
|
||
|
||
See also:
|
||
mount_cfs()
|
||
|
||
Synopsis:
|
||
|
||
struct cfs_mount_s {
|
||
P4_uint32_t base_block;
|
||
P4_uint32_t blk_size;
|
||
cfs_uid_t uid;
|
||
cfs_gid_t gid;
|
||
void * bparam;
|
||
cfs_block_read_t * bread;
|
||
cfs_block_write_t * bwrite;
|
||
cfs_err_callback_t * err_callback;
|
||
P4_uint32_t mount_options;
|
||
P4_uint32_t max_open_files;
|
||
void * storage;
|
||
P4_uint32_t storage_size;
|
||
};
|
||
|
||
|
||
Structure Element Description:
|
||
base_block First physical block where file system starts on the device.
|
||
blk_size Logical block size of the mounted image
|
||
|
||
Note:
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 11
|
||
|
||
|
||
Will be checked against the value read from master block. If different than the one from master block,
|
||
the mount will fail.
|
||
uid User ID (UID) to use for permission checks.
|
||
gid Group ID (GID) to use for permission checks.
|
||
bparam Parameter which is passed as first argument to block read and write functions.
|
||
bread Block read function.
|
||
|
||
Note:
|
||
The CFS implementation does not enter the bread and bwrite functions in parallel.
|
||
bwrite Block write function.
|
||
|
||
Note:
|
||
The CFS implementation does not enter the bread and bwrite functions in parallel.
|
||
err_callback Error callback function. This function is called if an error is found during the file system mount
|
||
checks. If set to NULL, the internal default error handler is used.
|
||
mount_options Mount options for the file system. CFS_MO_RO - mount file system read only
|
||
max_open_files Maximum number of simultaneously open files.
|
||
storage Storage memory.
|
||
|
||
Note:
|
||
CFS core part shall not allocate memory, therefore the PikeOS application shall provide sufficient
|
||
memory to the CFS core part.
|
||
storage_size Size of the storage memory.
|
||
|
||
|
||
Associated Data Type
|
||
|
||
cfs_mount_t File system parameters.
|
||
|
||
|
||
3.2.1.3 struct cfs_config_s
|
||
|
||
CFS mkfs parameters.
|
||
Provides parameters for a new CFS instance. The overall CFS image size can be calculated as follows: im-
|
||
age_size = block_size * (number_of_inodes + number_of_blocks + 2). The two extra blocks are for the master
|
||
block and the rename journal.
|
||
|
||
Synopsis:
|
||
|
||
struct cfs_config_s {
|
||
P4_uint32_t block_size;
|
||
P4_uint32_t payload_size;
|
||
P4_uint32_t number_of_inodes;
|
||
P4_uint32_t number_of_blocks;
|
||
P4_uint32_t file_name_max;
|
||
P4_uint32_t blocks_per_direct_inode;
|
||
P4_uint32_t uid;
|
||
P4_uint32_t gid;
|
||
cfs_endian_t endian;
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
12 CFS PikeOS API Reference
|
||
|
||
|
||
};
|
||
|
||
Structure Element Description:
|
||
block_size Block size
|
||
payload_size Payload size
|
||
number_of_inodes Number of inodes in file system
|
||
number_of_blocks Number of data blocks in file system
|
||
file_name_max Maximum size of file name
|
||
blocks_per_direct_inode Number of block pointers in direct inode
|
||
uid UID of the root directory
|
||
gid GID of the root directory
|
||
endian Endianness of the file system
|
||
|
||
|
||
Associated Data Type
|
||
|
||
cfs_config_t CFS mkfs parameters.
|
||
|
||
|
||
3.2.1.4 struct cfs_file_s
|
||
|
||
Open file description.
|
||
Structure holding data about an open file.
|
||
|
||
Synopsis:
|
||
|
||
struct cfs_file_s {
|
||
cfs_off_t fpos;
|
||
P4_uint32_t flags;
|
||
void * cfs;
|
||
void * ifd;
|
||
};
|
||
|
||
Structure Element Description:
|
||
fpos current position in the file
|
||
flags flags specified while opening the file
|
||
cfs CFS instance handler
|
||
ifd internal CFS file handler
|
||
|
||
|
||
Associated Data Type
|
||
|
||
cfs_file_t Open file description.
|
||
|
||
|
||
3.2.1.5 struct cfs_stat_s
|
||
|
||
File status.
|
||
Structure containing the file status information obtained by a call to cfs_stat() (see section 3.2.6.4).
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 13
|
||
|
||
|
||
Synopsis:
|
||
struct cfs_stat_s {
|
||
void * st_dev;
|
||
cfs_ino_t st_ino;
|
||
cfs_mode_t st_mode;
|
||
cfs_uid_t st_uid;
|
||
cfs_gid_t st_gid;
|
||
cfs_time_t st_mtime;
|
||
cfs_off_t st_size;
|
||
};
|
||
|
||
Structure Element Description:
|
||
st_dev mounted CFS instace handle
|
||
st_ino number of the file’s direct inode
|
||
st_mode file protection mode
|
||
st_uid user ID of the file’s owner
|
||
st_gid group ID of the file’s group
|
||
st_mtime time of the last data modification
|
||
st_size file size in bytes
|
||
|
||
|
||
Associated Data Type
|
||
|
||
cfs_stat_t File status.
|
||
|
||
|
||
3.2.1.6 struct cfs_utimbuf_s
|
||
|
||
File update times.
|
||
Structure containing access and modification time used for the manual file time update by a call to cfs_utime()
|
||
(see section 3.2.6.7).
|
||
|
||
Synopsis:
|
||
struct cfs_utimbuf_s {
|
||
cfs_time_t modtime;
|
||
};
|
||
|
||
Structure Element Description:
|
||
modtime modification time
|
||
|
||
|
||
Associated Data Type
|
||
|
||
cfs_utimbuf_t File update times.
|
||
|
||
|
||
3.2.1.7 struct cfs_statvfs_s
|
||
|
||
File system statistics.
|
||
Structure containing information about the file system obtained by a call to cfs_statvfs() (see section 3.2.6.10).
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
14 CFS PikeOS API Reference
|
||
|
||
|
||
Synopsis:
|
||
|
||
struct cfs_statvfs_s {
|
||
P4_uint32_t f_bfree;
|
||
P4_uint32_t f_blocks;
|
||
P4_uint32_t f_ffree;
|
||
P4_uint32_t f_files;
|
||
cfs_size_t f_bsize;
|
||
P4_uint32_t f_blks_per_dir_ino;
|
||
P4_uint32_t f_flag;
|
||
cfs_size_t f_frsize;
|
||
P4_address_t f_fsid;
|
||
cfs_size_t f_namemax;
|
||
};
|
||
|
||
|
||
Structure Element Description:
|
||
f_bfree number of free blocks on the file system
|
||
f_blocks total number of blocks on the file system
|
||
f_ffree number of free inodes on the file system
|
||
f_files total number of inodes on the file system
|
||
f_bsize file system block size (payload size in case of CFS)
|
||
f_blks_per_dir_ino number of blocks per direct inode
|
||
f_flag mount flags
|
||
f_frsize fragment size (payload size)
|
||
f_fsid file system ID (CFS handler)
|
||
f_namemax maximum filename length
|
||
|
||
|
||
Associated Data Type
|
||
|
||
cfs_statvfs_t File system statistics.
|
||
|
||
|
||
3.2.1.8 struct cfs_dirent_s
|
||
|
||
Directory entry description.
|
||
Structure containing information about a single directory entry.
|
||
|
||
Synopsis:
|
||
|
||
struct cfs_dirent_s {
|
||
cfs_size_t d_namlen;
|
||
char d_name[CFS_FILENAME_MAX+1];
|
||
};
|
||
|
||
|
||
Structure Element Description:
|
||
d_namlen length of the string in d_name
|
||
d_name file name of entry
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 15
|
||
|
||
|
||
Associated Data Type
|
||
|
||
cfs_dirent_t Directory entry description.
|
||
|
||
|
||
3.2.2 Defines
|
||
|
||
|
||
CFS_PATH_MAX
|
||
Path length.
|
||
Description:
|
||
Maximum length of the path on the CFS.
|
||
|
||
CFS_FILENAME_MAX
|
||
Maximum file name size upper limit.
|
||
Description:
|
||
The uppper limit for the maximum file name size.
|
||
|
||
CFS_FILENAME_MIN
|
||
Maximum file name size lower limit.
|
||
Description:
|
||
The lower limit for the maximum file name size.
|
||
|
||
CFS_OFF_T_MAX
|
||
Maximum value of cfs_off_t.
|
||
Description:
|
||
Maximum value representable by the cfs_off_t type.
|
||
|
||
CFS_MO_RO
|
||
Mount read only.
|
||
Description:
|
||
Mount the file system only for read access.
|
||
|
||
CFS_FREAD
|
||
Open file for reading only.
|
||
|
||
CFS_FWRITE
|
||
Open file for writing only.
|
||
|
||
CFS_FRDWR
|
||
Open file for both reading and writing.
|
||
|
||
CFS_FAPPEND
|
||
Append data at the end of the file.
|
||
|
||
CFS_FCREAT
|
||
Create file if it does not exist.
|
||
|
||
CFS_FTRUNC
|
||
Truncated the file to the zero size if it exists.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
16 CFS PikeOS API Reference
|
||
|
||
|
||
CFS_FEXCL
|
||
Make the cfs_open() function fail if the file exists and CFS_FCREAT is specified.
|
||
|
||
CFS_FDIRECTORY
|
||
Make the cfs_open() function fail if the file isn’t a directory.
|
||
|
||
CFS_IFDIR
|
||
File is a directory.
|
||
|
||
CFS_IFREG
|
||
File is a regular file.
|
||
|
||
CFS_IRUSR
|
||
Read permission for the file owner.
|
||
|
||
CFS_IWUSR
|
||
Write permission for the file owner.
|
||
|
||
CFS_IXUSR
|
||
Execute/search permission for the file owner.
|
||
|
||
CFS_IRGRP
|
||
Read permission for the group.
|
||
|
||
CFS_IWGRP
|
||
Write permission for the group.
|
||
|
||
CFS_IXGRP
|
||
Execute/search permission for the group.
|
||
|
||
CFS_IROTH
|
||
Read permission for others.
|
||
|
||
CFS_IWOTH
|
||
Write permission for others.
|
||
|
||
CFS_IXOTH
|
||
Execute/search permission for others.
|
||
|
||
CFS_F_OK
|
||
Test on the existence of the file.
|
||
|
||
CFS_X_OK
|
||
Test on the execute/search permission to the file.
|
||
|
||
CFS_W_OK
|
||
Test on the write permission to the file.
|
||
|
||
CFS_R_OK
|
||
Test on the read permission to the file.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 17
|
||
|
||
|
||
CFS_EIO
|
||
Input/output error.
|
||
|
||
CFS_EINVAL
|
||
Invalid value.
|
||
|
||
CFS_ENOMEM
|
||
No memory.
|
||
|
||
CFS_ENOENT
|
||
File not found.
|
||
|
||
CFS_EACCES
|
||
Mode invalid.
|
||
|
||
CFS_ENAMETOOLONG
|
||
File name too long.
|
||
|
||
CFS_EEXIST
|
||
File exists.
|
||
|
||
CFS_EROFS
|
||
Read-only file system.
|
||
|
||
CFS_EISDIR
|
||
Is a directory.
|
||
|
||
CFS_ENOTDIR
|
||
Not a directory.
|
||
|
||
CFS_ENOTEMPTY
|
||
Directory not empty.
|
||
|
||
CFS_ENOSPC
|
||
No space left on device.
|
||
|
||
CFS_EFBIG
|
||
File too large.
|
||
|
||
CFS_EMFILE
|
||
Too many open files.
|
||
|
||
CFS_EPERM
|
||
Operation not permited.
|
||
|
||
CFS_EOVERFLOW
|
||
Value too large to be stored in data type.
|
||
|
||
CFS_EBUSY
|
||
System is busy, operation cannot be performed.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
18 CFS PikeOS API Reference
|
||
|
||
|
||
CFS_ECANCELED
|
||
Operation canceled.
|
||
|
||
CFS_SEEK_SET
|
||
Set file offset to offset.
|
||
|
||
CFS_SEEK_CUR
|
||
Set file offset to current plus offset.
|
||
|
||
CFS_SEEK_END
|
||
Set file offset to EOF plus offset.
|
||
|
||
|
||
3.2.3 Data Type Definitions
|
||
|
||
cfs_inode_type_t CFS inode type.
|
||
cfs_file_type_t CFS file type.
|
||
cfs_blkno_t Block number.
|
||
Data type representing a number of a block.
|
||
cfs_ino_t Inode number.
|
||
Data type representing a number of an inode.
|
||
cfs_mode_t File mode and permission bits.
|
||
Data type used to store file access permission bits and the file type (regular file or directory).
|
||
cfs_uid_t User ID.
|
||
Data type representing an user ID.
|
||
cfs_gid_t Group ID.
|
||
Data type representing an group ID.
|
||
cfs_time_t Time stamp.
|
||
Data type representing a file update time stamp.
|
||
cfs_off_t File offset.
|
||
Data type representing a position in a file.
|
||
cfs_size_t Size.
|
||
Data type representing size of a file or block in bytes.
|
||
cfs_blk_type_t Enumeration of disk block types.
|
||
Enumeration type used to tag disk blocks according to the data they contain.
|
||
cfs_err_act_t Enumeration of file system recovery actions.
|
||
Enumeration type for actions that can be taken when a file system check discovers an error and calls a
|
||
user defined callback to determine how to proceed.
|
||
|
||
Note:
|
||
Not all actions make sense on all errors.
|
||
cfs_err_type_t Enumeration of mount check error types.
|
||
Enumeration type determining the type of error that was found during checks on the file system mount.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 19
|
||
|
||
|
||
Note:
|
||
For each item is noted which recovery actions are possible to take if that type of error ocured. If any
|
||
other action is requested it will be handled as CFS_ERR_ACT_ABORT.
|
||
cfs_err_desc_t Structure with error description.
|
||
Structure with detailed description of an error found by checks during the file system mount.
|
||
cfs_mount_t File system parameters.
|
||
Describes operational parameters for a CFS instance to be mounted.
|
||
|
||
See also:
|
||
mount_cfs()
|
||
cfs_endian_t CFS endianness type.
|
||
Enumeration type for endiannes of the file system.
|
||
cfs_config_t CFS mkfs parameters.
|
||
Provides parameters for a new CFS instance. The overall CFS image size can be calculated as follows:
|
||
image_size = block_size * (number_of_inodes + number_of_blocks + 2). The two extra blocks are for
|
||
the master block and the rename journal.
|
||
cfs_file_t Open file description.
|
||
Structure holding data about an open file.
|
||
cfs_stat_t File status.
|
||
Structure containing the file status information obtained by a call to cfs_stat() (see section 3.2.6.4).
|
||
cfs_utimbuf_t File update times.
|
||
Structure containing access and modification time used for the manual file time update by a call to
|
||
cfs_utime() (see section 3.2.6.7).
|
||
cfs_statvfs_t File system statistics.
|
||
Structure containing information about the file system obtained by a call to cfs_statvfs() (see section
|
||
3.2.6.10).
|
||
cfs_dirent_t Directory entry description.
|
||
Structure containing information about a single directory entry.
|
||
|
||
|
||
3.2.4 Function Type Definitions
|
||
|
||
3.2.4.1 cfs_err_callback_t
|
||
|
||
Tell CFS how to proceed if a file system error is found.
|
||
|
||
|
||
Synopsis:
|
||
|
||
|
||
typedef cfs_err_act_t cfs_err_callback_t(cfs_err_desc_t *err_desc)
|
||
|
||
|
||
Description:
|
||
If an error in the file system is found during mount checks, this callback is used to determine how to proceed.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
20 CFS PikeOS API Reference
|
||
|
||
|
||
Note:
|
||
If this function requests an action, that is not defined for the given error the mount operation will proceed like if
|
||
CFS_ERR_ACT_ABORT was returned.
|
||
|
||
Parameters:
|
||
err_desc The structure describing the discovered error.
|
||
|
||
Returns:
|
||
Type of action. This action will be taken to solve the found problem.
|
||
|
||
|
||
3.2.4.2 cfs_block_read_t
|
||
|
||
CFS read physical block interface.
|
||
|
||
|
||
Synopsis:
|
||
|
||
typedef P4_sint32_t cfs_block_read_t(void *s,
|
||
P4_uint32_t blkno,
|
||
void *buf,
|
||
P4_sint32_t nblocks,
|
||
cfs_blk_type_t flags)
|
||
|
||
Description:
|
||
Describes a function pointer for a read physical block function. A physical disk block contains 512 octets, block
|
||
numbers are absolute block numbers in the device, i.e. they already include the block offset specified by the
|
||
base_block member of cfs_mount_t.
|
||
|
||
Parameters:
|
||
s Private data passed to the block read function.
|
||
blkno Physical block number to start reading.
|
||
buf Buffer where to store read block data. This buffer is page aligned and can be directly used for DMA
|
||
transfer.
|
||
nblocks Number of contiguous blocks to be read.
|
||
flags Type of data to be read.
|
||
|
||
Returns:
|
||
The function returns 0 on success, -1 otherwise.
|
||
|
||
See also:
|
||
cfs_mount_t (see section 3.2.3)
|
||
|
||
|
||
3.2.4.3 cfs_block_write_t
|
||
|
||
CFS write physical block interface.
|
||
|
||
|
||
Synopsis:
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 21
|
||
|
||
|
||
typedef P4_sint32_t cfs_block_write_t(void *s,
|
||
P4_uint32_t blkno,
|
||
const void *buf,
|
||
P4_sint32_t nblocks,
|
||
cfs_blk_type_t flags)
|
||
|
||
Description:
|
||
Describes a function pointer for a write physical block function. A physical disk block contains 512 octets, block
|
||
numbers are absolute block numbers in the device, i.e. they already include the block offset specified by the
|
||
base_block member of cfs_mount_t.
|
||
|
||
Parameters:
|
||
s Private data passed to the block read function.
|
||
blkno Physical block number to start writing.
|
||
buf Buffer for block data. This buffer is page aligned and can be directly used for DMA transfer.
|
||
nblocks Number of contiguous blocks to be written.
|
||
flags Type of written data.
|
||
|
||
Returns:
|
||
The function returns 0 on success, -1 otherwise.
|
||
|
||
See also:
|
||
cfs_mount_t (see section 3.2.3)
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
22 CFS PikeOS API Reference
|
||
|
||
|
||
3.2.5 Enumerations
|
||
|
||
Enumeration type cfs_inode_type_e
|
||
|
||
CFS inode type.
|
||
|
||
Name Description
|
||
CFS_INODE_DIRECT Type for direct inodes.
|
||
|
||
CFS_INODE_INDIRECT Type for indirect inodes.
|
||
|
||
|
||
Enumeration type cfs_file_type_e
|
||
|
||
CFS file type.
|
||
|
||
Name Description
|
||
CFS_FILE_DIRECTORY File type for directory files.
|
||
|
||
CFS_FILE_REGULAR File type for regular files.
|
||
|
||
|
||
Enumeration type cfs_blk_type_e
|
||
|
||
Enumeration of disk block types.
|
||
Enumeration type used to tag disk blocks according to the data they contain.
|
||
|
||
Name Description
|
||
CFS_BLK_MASTER file system master block
|
||
|
||
CFS_BLK_JOURNAL journal block
|
||
|
||
CFS_BLK_INODE_DIR direct inode
|
||
|
||
CFS_BLK_INODE_INDIR indirect inode
|
||
|
||
CFS_BLK_DIR_DATA directory data block
|
||
|
||
CFS_BLK_DATA regular file data block
|
||
|
||
|
||
Enumeration type cfs_err_act_e
|
||
|
||
Enumeration of file system recovery actions.
|
||
Enumeration type for actions that can be taken when a file system check discovers an error and calls a user
|
||
defined callback to determine how to proceed.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 23
|
||
|
||
|
||
Note:
|
||
Not all actions make sense on all errors.
|
||
|
||
Name Description
|
||
CFS_ERR_ACT_TRUNC A defective file or directory will be truncated to the last valid block. (or to
|
||
zero size)
|
||
|
||
CFS_ERR_ACT_DEL A defective file or directory will be removed.
|
||
|
||
CFS_ERR_ACT_FIX If the error is fixable, it will be fixed.
|
||
|
||
CFS_ERR_ACT_ABORT The mount operation stops, no data is changed.
|
||
|
||
CFS_ERR_ACT_MAKE_IT_FILE Mark the unknown entry as a file.
|
||
|
||
CFS_ERR_ACT_MAKE_IT_DIR Mark the unknown entry as a directory.
|
||
|
||
|
||
Enumeration type cfs_err_type_e
|
||
|
||
Enumeration of mount check error types.
|
||
Enumeration type determining the type of error that was found during checks on the file system mount.
|
||
|
||
Note:
|
||
For each item is noted which recovery actions are possible to take if that type of error ocured. If any other action
|
||
is requested it will be handled as CFS_ERR_ACT_ABORT.
|
||
|
||
Name Description
|
||
CFS_ERR_INO_NUM Reference to an indirect inode in a direct inode out of range.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_BLK_NUM Reference to a block in an inode is out of range.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_INO_TYPE Wrong inode type.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
CFS_ERR_ACT_FIX
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
24 CFS PikeOS API Reference
|
||
|
||
|
||
CFS_ERR_INO_FTYPE Wrong file type in a direct inode.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_DEL
|
||
CFS_ERR_ACT_MAKE_IT_FILE
|
||
CFS_ERR_ACT_MAKE_IT_DIR
|
||
|
||
CFS_ERR_INO_USED Inode referenced more than once.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC (only for indirect inodes)
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_INO_PARENT Wrong parent inode reference in an indirect node.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
CFS_ERR_ACT_FIX
|
||
|
||
CFS_ERR_BLK_USED Block referenced more than once.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_FSIZE File size larger than remaining space.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_DIR_SIZE Size of a directory not a multiple of directory entry size.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_DIR_INO_NUM Out of range inode number in directory entry.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_DIR_END Empty items at the end of directory.
|
||
Valid action: CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 25
|
||
|
||
|
||
CFS_ERR_LINK_CNT Wrong count of links in a directory or regular file with a link count not
|
||
equal to 1.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_FIX
|
||
|
||
CFS_ERR_PATH_TOO_LONG Corrupted directory file that leads to too long path in pathname resolution.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_SLASH_IN_NAME Corrupted directory file that leads to a slash character in a file name
|
||
resolution.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_DEL
|
||
|
||
|
||
Enumeration type cfs_endian_e
|
||
|
||
CFS endianness type.
|
||
Enumeration type for endiannes of the file system.
|
||
|
||
Name Description
|
||
CFS_ENDIAN_LITTLE little endian
|
||
|
||
CFS_ENDIAN_BIG big endian
|
||
|
||
CFS_ENDIAN_NATIVE the native byte order of the running system
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
26 CFS PikeOS API Reference
|
||
|
||
|
||
3.2.6 Functions
|
||
|
||
3.2.6.1 cfs_mount
|
||
|
||
Mount a CFS file system.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_mount(void **handle,
|
||
cfs_mount_t *config)
|
||
|
||
Description:
|
||
Allocate and set up CFS static. Initialize all necessary structures.
|
||
|
||
Parameters:
|
||
handle [OUT] Handle to represent this instance of file system.
|
||
config [IN] Configuration of the file system to be mounted.
|
||
|
||
Returns:
|
||
0 On success.
|
||
CFS_ENOMEM If not enough resources to finish the initialisation available.
|
||
CFS_EINVAL Invalid configuration parameters given by "config", or invalid parameters read from the file
|
||
system, or different parameters in "config" and the file system.
|
||
CFS_ECANCELED Mount process aborted by the error callback in case of integrity error found.
|
||
CFS_EIO Block read callback function failed.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 27
|
||
|
||
|
||
3.2.6.2 cfs_unmount
|
||
|
||
Unmount a CFS file system.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_unmount(void *handle)
|
||
|
||
Description:
|
||
Unmount previously mounted CFS file system.
|
||
|
||
Parameters:
|
||
handle [IN] Handle to the CFS instance that will be unmounted.
|
||
|
||
Returns:
|
||
0 On success.
|
||
CFS_EBUSY A file is open in the file system instance.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
28 CFS PikeOS API Reference
|
||
|
||
|
||
3.2.6.3 cfs_open
|
||
|
||
Open file.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_open(void *handle,
|
||
const char *name,
|
||
cfs_file_t **f,
|
||
P4_uint32_t flags,
|
||
cfs_mode_t mode)
|
||
|
||
Description:
|
||
Opens file given by name and returns a open file description representing this file.
|
||
|
||
Parameters:
|
||
handle [IN] Handle representing instance of file system.
|
||
name [IN] Name of the file that will be open.
|
||
f [OUT] File structure for file access.
|
||
flags [IN] Access mode and file creation and status flags.
|
||
mode [IN] File permission bits used while creating a new file.
|
||
|
||
Returns:
|
||
0 On success.
|
||
CFS_EROFS Write access requested on read-only file system.
|
||
CFS_EINVAL Path given in name is invalid (contains trailing, leading or multiple adjacent slashes).
|
||
CFS_EMFILE Maximum number of files already open.
|
||
CFS_EISDIR Attemp to open a directory for writing.
|
||
CFS_EACCES Requested access to the file is not allowed, or read permission is denied for one of the
|
||
directories in the path prefix of pathname, or CFS_FTRUNC is specified together with CFS_FREAD.
|
||
CFS_ENAMETOOLONG Pathname or filename was too long
|
||
CFS_ENOENT CFS_FCREAT is not set in "flags" and the named file does not exist, or a directory component
|
||
in pathname does not exist.
|
||
CFS_EEXIST CFS_FCREAT and CFS_FEXCL flags set and the file already exists.
|
||
CFS_EFBIG Maximum size of the parent directory reached.
|
||
CFS_ENOTDIR A component of pathname is not a directory.
|
||
CFS_ENOSPC File is being created and there is no free space available.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 29
|
||
|
||
|
||
3.2.6.4 cfs_stat
|
||
|
||
Retrieve file status.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_stat(void *handle,
|
||
const char *name,
|
||
cfs_stat_t *stat)
|
||
|
||
Description:
|
||
Retrieve informations about a file.
|
||
|
||
Parameters:
|
||
handle [IN] Handle representing instance of file system.
|
||
name [IN] Name of the file it’s status will be retrieved.
|
||
stat [OUT] Retrieved status.
|
||
|
||
Returns:
|
||
0 On success.
|
||
CFS_EINVAL Path given in name is invalid (contains trailing, leading or multiple adjacent slashes).
|
||
CFS_EACCES Read permission is denied for one of the directories in the path prefix of pathname.
|
||
CFS_ENAMETOOLONG Pathname or filename was too long.
|
||
CFS_ENOTDIR A component used as a directory in pathname is not a directory.
|
||
CFS_ENOENT File does not exist, or a directory component in pathname does not exist.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
30 CFS PikeOS API Reference
|
||
|
||
|
||
3.2.6.5 cfs_access
|
||
|
||
Check file permission.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_access(void *handle,
|
||
const char *name,
|
||
P4_sint32_t access)
|
||
|
||
Description:
|
||
Check whether the file represented by path can be opened with the access mode requested by access.
|
||
|
||
Parameters:
|
||
handle [IN] Handle representing instance of file system.
|
||
name [IN] Name of the file which permission are to be checked.
|
||
access [IN] Accessibility that will be checked can be CFS_F_OK or bitwise OR of one or more of CFS_R_OK,
|
||
CFS_W_OK, CFS_X_OK.
|
||
|
||
Returns:
|
||
0 On success.
|
||
CFS_EROFS Write access requested on read-only file system.
|
||
CFS_EINVAL Path given in name is invalid (contains trailing, leading or multiple adjacent slashes) or invalid
|
||
flags specified in the "access" argument.
|
||
CFS_EACCES The requested access to the file would be denied, or read permission is denied for one of the
|
||
directories in the path prefix of name.
|
||
CFS_ENAMETOOLONG Pathname or filename was too long.
|
||
CFS_ENOTDIR A component used as a directory in pathname is not a directory.
|
||
CFS_ENOENT File does not exist, or a directory component in pathname does not exist.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 31
|
||
|
||
|
||
3.2.6.6 cfs_chmod
|
||
|
||
Change file permission.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_chmod(void *handle,
|
||
const char *name,
|
||
cfs_mode_t mode)
|
||
|
||
Description:
|
||
Changes the access permission for the file specified by name.
|
||
|
||
Parameters:
|
||
handle [IN] Handle representing instance of file system.
|
||
name [IN] Name of the file it’s permission will be changed.
|
||
mode [IN] Permissions to be set.
|
||
|
||
Returns:
|
||
0 On sucess.
|
||
CFS_EROFS If file system is read-only.
|
||
CFS_EINVAL Path given in name is invalid (contains trailing, leading or multiple adjacent slashes).
|
||
CFS_EACCES Read permission is denied for one of the directories in the path prefix of name.
|
||
CFS_ENAMETOOLONG Pathname or filename was too long.
|
||
CFS_ENOTDIR A component used as a directory in pathname is not a directory.
|
||
CFS_ENOENT File does not exist, or a directory component in pathname does not exist.
|
||
CFS_EPERM The UID doesn’t match the owner of the file.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
32 CFS PikeOS API Reference
|
||
|
||
|
||
3.2.6.7 cfs_utime
|
||
|
||
Change file modification time.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_utime(void *handle,
|
||
const char *name,
|
||
const cfs_utimbuf_t *time)
|
||
|
||
Description:
|
||
Change file modification time of the file given by name.
|
||
|
||
Parameters:
|
||
handle [IN] Handle representing instance of file system.
|
||
name [IN] Name of the file it’s modification time will be changed.
|
||
time [IN] Modification time to set.
|
||
|
||
Returns:
|
||
0 On success.
|
||
CFS_EROFS If file system is read-only.
|
||
CFS_EINVAL Path given in name is invalid (contains trailing, leading or multiple adjacent slashes).
|
||
CFS_EACCES Write access to the file is denied, or read permission is denied for one of the directories in the
|
||
path prefix of name.
|
||
CFS_ENAMETOOLONG Pathname or filename was too long.
|
||
CFS_ENOTDIR A component used as a directory in pathname is not a directory.
|
||
CFS_ENOENT File does not exist, or a directory component in pathname does not exist.
|
||
CFS_EPERM The file is not regular file.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 33
|
||
|
||
|
||
3.2.6.8 cfs_unlink
|
||
|
||
Delete a file.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_unlink(void *handle,
|
||
const char *name)
|
||
|
||
Description:
|
||
Delete a file given by name from the file system permanently.
|
||
|
||
Parameters:
|
||
handle [IN] Handle representing instance of file system.
|
||
name [IN] Name of the file that will be deleted.
|
||
|
||
Returns:
|
||
0 On success.
|
||
CFS_EROFS If file system is read-only.
|
||
CFS_EINVAL Path given in name is invalid (contains trailing, leading or multiple adjacent slashes).
|
||
CFS_EACCES Read permission is denied for one of the directories in the path prefix of name, or write
|
||
permission is denied for the parent directory of the file being removed.
|
||
CFS_ENAMETOOLONG Pathname or filename was too long.
|
||
CFS_ENOTDIR A component used as a directory in pathname is not a directory.
|
||
CFS_EPERM Named file is a directory.
|
||
CFS_ENOENT File does not exist, or a directory component in pathname does not exist.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
34 CFS PikeOS API Reference
|
||
|
||
|
||
3.2.6.9 cfs_rename
|
||
|
||
Rename or relocate a file.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_rename(void *handle,
|
||
const char *oldname,
|
||
const char *newname)
|
||
|
||
Description:
|
||
Rename a file, move it between directories if required.
|
||
|
||
Parameters:
|
||
handle [IN] Handle representing instance of file system.
|
||
oldname [IN] Name of the file that will be renamed.
|
||
newname [IN] New name of the file.
|
||
|
||
Returns:
|
||
0 On success.
|
||
CFS_EROFS If file system is read-only.
|
||
CFS_EINVAL Path given in oldname or newname is invalid (contains trailing, leading or multiple adjacent
|
||
slashes).
|
||
CFS_EACCES Write permission is denied for the directory containing oldname or newname, or read permis-
|
||
sion is denied for one of the directories in the path prefix of oldname or newname.
|
||
CFS_EPERM Attempt to rename the root directory was made.
|
||
CFS_ENAMETOOLONG Oldname or newname path or filename was too long.
|
||
CFS_ENOTDIR A component used as a directory in oldname or newname is not a directory, or file named by
|
||
oldname is a directory and newname is a regular file.
|
||
CFS_EISDIR File named by oldname is a regular file and newname is a directory.
|
||
CFS_ENOTEMPTY File named by oldname is a directory and newname is a directory which is not empty.
|
||
CFS_ENOENT Oldname does not exist, or a directory component in pathname does not exist.
|
||
CFS_EINVAL Pathname newname contains the pathname oldname.
|
||
CFS_EFBIG Newfile parent directory already at maximum size.
|
||
CFS_ENOSPC The CFS has no room for storing the data of the newfile parent directory.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 35
|
||
|
||
|
||
3.2.6.10 cfs_statvfs
|
||
|
||
Get file system statistics.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_statvfs(void *handle,
|
||
cfs_statvfs_t *statvfs)
|
||
|
||
Description:
|
||
This function returns informations about a file system.
|
||
|
||
Parameters:
|
||
handle [IN] Handle representing instance of file system.
|
||
statvfs [OUT] File system statistics.
|
||
|
||
Returns:
|
||
0 On success.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
36 CFS PikeOS API Reference
|
||
|
||
|
||
3.2.6.11 cfs_mkdir
|
||
|
||
Create a directory.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_mkdir(void *handle,
|
||
const char *name,
|
||
cfs_mode_t mode)
|
||
|
||
Description:
|
||
Attempt to create a directory named name.
|
||
|
||
Parameters:
|
||
handle [IN] Handle representing instance of file system.
|
||
name [IN] Name of the directory to be created.
|
||
mode [IN] Permissions to set on othe new directory.
|
||
|
||
Returns:
|
||
0 On success.
|
||
CFS_EROFS If file system is read-only.
|
||
CFS_EINVAL Path given in name is invalid (contains trailing, leading or multiple adjacent slashes).
|
||
CFS_EACCES Write permission denied for parent directory, or read permission is denied for one of the
|
||
directories in the path prefix of name.
|
||
CFS_ENAMETOOLONG Pathname or filename too long.
|
||
CFS_ENOTDIR A component used as a directory in pathname is not a directory.
|
||
CFS_ENOENT Directory component in pathname does not exist.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 37
|
||
|
||
|
||
3.2.6.12 cfs_rmdir
|
||
|
||
Remove a directory.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_rmdir(void *handle,
|
||
const char *name)
|
||
|
||
Description:
|
||
Remove a directory. The directory must be empty.
|
||
|
||
Parameters:
|
||
handle [IN] Handle representing instance of file system.
|
||
name [IN] Name of the directory to be removed.
|
||
|
||
Returns:
|
||
0 On success.
|
||
CFS_EROFS If file system is read-only.
|
||
CFS_EINVAL Path given in name is invalid (contains trailing, leading or multiple adjacent slashes).
|
||
CFS_EACCES Write permission denied for parent directory, or read permission is denied for one of the
|
||
directories in the path prefix of name.
|
||
CFS_ENAMETOOLONG Pathname or filename too long.
|
||
CFS_ENOTDIR A component used as a directory in pathname is not a directory.
|
||
CFS_ENOENT Directory component in pathname does not exist, or named directory does not exist.
|
||
CFS_ENOTEMPTY Directory not empty.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
38 CFS PikeOS API Reference
|
||
|
||
|
||
3.2.6.13 cfs_close
|
||
|
||
Close a file descriptor.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_close(cfs_file_t *f)
|
||
|
||
Description:
|
||
Close an open file represented by the file descriptor, return the descriptor to the internal free file descriptor pool.
|
||
|
||
Parameters:
|
||
f [IN] File structure representing the open file.
|
||
|
||
Returns:
|
||
0 On success.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 39
|
||
|
||
|
||
3.2.6.14 cfs_read
|
||
|
||
Read from an open file description.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_read(cfs_file_t *f,
|
||
void *buf,
|
||
cfs_size_t nbytes)
|
||
|
||
Description:
|
||
Attempt to read up to nbytes from file represented by file descriptor f into the buffer starting at buf.
|
||
|
||
Parameters:
|
||
f [IN] File structure representing the file.
|
||
buf [IN] Location where the read data will be stored.
|
||
nbytes [IN] Number of bytes to be read from the file.
|
||
|
||
Returns:
|
||
number of bytes read On success.
|
||
CFS_EACCES The file is not open for reading.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
40 CFS PikeOS API Reference
|
||
|
||
|
||
3.2.6.15 cfs_write
|
||
|
||
Write to a file descriptor.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_write(cfs_file_t *f,
|
||
const void *buf,
|
||
cfs_size_t nbytes)
|
||
|
||
Description:
|
||
Write up to nbytes bytes from the buffer pointed by buf to the file reffered by the file descriptor f.
|
||
|
||
Parameters:
|
||
f [IN] File structure representing the file.
|
||
buf [IN] Data that will be written to the file.
|
||
nbytes [IN] Number of bytes to write to the file.
|
||
|
||
Returns:
|
||
Number of bytes written On success.
|
||
CFS_EFBIG Attempting to write a file that exceed the maximum file size.
|
||
CFS_EACCES The file is not open for writing.
|
||
CFS_ENOSPC The CFS containing the file referred by f has no room for the data.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 41
|
||
|
||
|
||
3.2.6.16 cfs_lseek
|
||
|
||
Change read/write file offset.
|
||
|
||
|
||
Synopsis:
|
||
|
||
cfs_off_t cfs_lseek(cfs_file_t *f,
|
||
cfs_off_t off,
|
||
P4_sint32_t whence)
|
||
|
||
Description:
|
||
Reposition the offset of the open file represented by the open file descriptor f.
|
||
|
||
Parameters:
|
||
f [IN] File structure representing the file.
|
||
off [IN] File offset to seek to according to whence directive.
|
||
whence [IN] Seek method, can be one of CFS_SEEK_SET, CFS_SEEK_CUR, CFS_SEEK_END.
|
||
|
||
Returns:
|
||
Resulting offset location as measured in bytes from the beginning of the file on success.
|
||
CFS_EINVAL Invalid value specified in "whence", or the resulting offset would be negative.
|
||
CFS_EOVERFLOW The resulting offset cannot be represented with the cfs_off_t type.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
42 CFS PikeOS API Reference
|
||
|
||
|
||
3.2.6.17 cfs_ftruncate
|
||
|
||
Truncate a file to specified length.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_ftruncate(cfs_file_t *f,
|
||
cfs_off_t off)
|
||
|
||
Description:
|
||
Truncate a file represented by open file descriptor f to be precisely of size given by off. If the file previously was
|
||
larger than this size, the extra data is lost. If the file previously was shorter, it is extended, and the extended part
|
||
is zeroed.
|
||
|
||
Parameters:
|
||
f [IN] File structure representing the file.
|
||
off [IN] Requested new file size.
|
||
|
||
Returns:
|
||
0 On success.
|
||
CFS_EFBIG The off parameter exceed the maximum file size.
|
||
CFS_ENOSPC The CFS containing the file doesn’t contain enough free space.
|
||
CFS_EINVAL If the file not open for write.
|
||
CFS_EINVAL The new file size is less than zero.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 43
|
||
|
||
|
||
3.2.6.18 cfs_fstat
|
||
|
||
Retrieve file status.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_fstat(cfs_file_t *f,
|
||
cfs_stat_t *stat)
|
||
|
||
Description:
|
||
Retrieve informations about a file represented by open file descriptor f.
|
||
|
||
Parameters:
|
||
f [IN] File structure representing the file.
|
||
stat [OUT] Retrieved status.
|
||
|
||
Returns:
|
||
0 On success.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
44 CFS PikeOS API Reference
|
||
|
||
|
||
3.2.6.19 cfs_getdents
|
||
|
||
Get directory entries.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_getdents(cfs_file_t *f,
|
||
cfs_dirent_t *d,
|
||
P4_size_t size)
|
||
|
||
Description:
|
||
Read several directory entries from a directory file represented by f into the buffer d.
|
||
|
||
Parameters:
|
||
f [IN] File structure representing the file.
|
||
d [OUT] Buffer to store the result.
|
||
size [IN] Size of the buffer provided to store result in bytes.
|
||
|
||
Returns:
|
||
number of bytes read On success.
|
||
0 On end of directory.
|
||
CFS_EINVAL If the provided buffer is too small.
|
||
CFS_EIO Low-level I/O error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
PikeOS Native API 45
|
||
|
||
|
||
3.2.6.20 cfs_mkfs
|
||
|
||
Create an empty CFS file system image.
|
||
|
||
|
||
Synopsis:
|
||
|
||
P4_sint32_t cfs_mkfs(cfs_config_t *cfs_config,
|
||
void *buf,
|
||
P4_uint32_t size)
|
||
|
||
Description:
|
||
Function cfs_mkfs() (see section 3.2.6.20) creates an empty file system image containing the master block, an
|
||
empty journal block, and the root inode. This minimal file system image is stored in the buffer buf which has to
|
||
be large enough to hold three blocks of the desired block size. To ensure that, "mkfs_cfs" will check parameter
|
||
size before writing the image to the buffer. All information about the file system configuration will be specified by
|
||
parameter cfs_config.
|
||
|
||
Parameters:
|
||
cfs_config [IN] File system configuration.
|
||
buf [OUT] Buffer to store the created image in.
|
||
size [IN] Size of the buffer buf.
|
||
|
||
Returns:
|
||
The function return value is a completion status.
|
||
0 upon success
|
||
CFS_EINVAL if invalid parameters given
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
4 POSIX Sample Application
|
||
|
||
|
||
As for PikeOS native, a POSIX CFS sample application is provided. It can be cloned from CODEO or the command
|
||
line similar to the PikeOS native CFS demo. To set up the demo, follow the steps described above, but choose
|
||
"POSIX C project" instead of "PikeOS C project". The output will appear on the POSIX console which can be
|
||
accessed by connecting to MUXA port 1515.
|
||
The main difference to the PikeOS native demo is that in POSIX the CFS is configured as a POSIX file system
|
||
provider and mounted into the POSIX root directory.
|
||
The sample application also provides a simple user interface to allow performing some actions on the file system.
|
||
When everything is setup correctly, the POSIX console should show an output similar to this:
|
||
|
||
|
||
Mount filesystem to "/cfs01":
|
||
Device ’/DISK’ successfully mounted to ’/cfs01’: handle 0x8151200
|
||
|
||
Files on "/cfs01":
|
||
ino 1 1 -rw-r--r-- 1000 100 56 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
|
||
ino 2 2 drw-r--r-- 1000 100 36 dir1
|
||
ino 3 3 -rw-r--r-- 1000 100 26 text
|
||
ino 4 4 -rw-r--r-- 1000 100 29 date
|
||
ino 5 5 -rw-r--r-- 1000 100 757504 system.reg
|
||
|
||
Dumping contents of file "/cfs01/dir1/text":
|
||
Hello World from your CFS
|
||
|
||
Opening "/cfs01/system.reg" for writing:
|
||
Write 26 bytes read from "/cfs01/dir1/text" at offset 479220
|
||
Successfully wrote 26 bytes to disk.
|
||
|
||
File system navigator, enter ’help’ for a command list:
|
||
[/cfs01] help
|
||
Supported commands:
|
||
cd path
|
||
pwd
|
||
mkdir path
|
||
rmdir path
|
||
creat path
|
||
rm path
|
||
rename path1 path2
|
||
cat path
|
||
df [path]
|
||
ls [path/file]
|
||
exit
|
||
dbg [val|[+-^]level]
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
47
|
||
|
||
|
||
level: enterleave, trace, err, warn, assert, bmp, fp, mkfs, jour, dir,
|
||
scan, cfs, inode, fd, fsp, umount, mount, blk, pblk
|
||
help
|
||
?
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
5 CFS POSIX API Reference
|
||
|
||
|
||
This section presents the data types and functions available in the CFS POSIX API. The CFS head-
|
||
ers and libraries are located in the POSIX installation path for the target architecture (/opt/pikeos-
|
||
D5.0/target/<arch>/<proc>/posix/cfs).
|
||
|
||
|
||
5.1 Header File
|
||
|
||
Header file to include, providing CFS POSIX API functions and definitions:
|
||
#include <cfs.h>
|
||
|
||
|
||
5.2 POSIX API
|
||
|
||
This section describes API provided by the CFS library for the POSIX applications.
|
||
|
||
|
||
5.2.1 Structure Definitions
|
||
|
||
5.2.1.1 struct cfs_err_desc_s
|
||
|
||
Structure with error description.
|
||
Structure with detailed description of an error found by checks during the file system mount.
|
||
|
||
Synopsis:
|
||
struct cfs_err_desc_s {
|
||
cfs_err_type_t type;
|
||
const char * path;
|
||
uint32_t dir_ino;
|
||
uint32_t wrong_ino;
|
||
uint32_t wrong_ino_value;
|
||
off_t size_old;
|
||
off_t size_new;
|
||
cfs_inode_type_t inode_type;
|
||
cfs_inode_type_t inode_type_expected;
|
||
cfs_file_type_t file_type;
|
||
int32_t old_count;
|
||
int32_t new_count;
|
||
uint32_t blkno;
|
||
off_t blocksize;
|
||
};
|
||
|
||
Structure Element Description:
|
||
type type of the found error
|
||
path path of the file in which the error was found
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
POSIX API 49
|
||
|
||
|
||
dir_ino direct inode of the file in which the error was found
|
||
wrong_ino number of inode in which the error was found
|
||
wrong_ino_value wrong entry in the inode table
|
||
size_old current file size in the file system
|
||
size_new file size after truncating
|
||
inode_type incorrect type of the inode
|
||
inode_type_expected expected type of the inode
|
||
file_type incorrect type of file
|
||
old_count incorrect link count
|
||
new_count correct link count
|
||
blkno incorrect block number
|
||
blocksize incorrect block size
|
||
|
||
|
||
Associated Data Type
|
||
|
||
cfs_err_desc_t Structure with error description.
|
||
|
||
|
||
5.2.1.2 struct cfs_mount_s
|
||
|
||
File system parameters.
|
||
Describes operational parameters for a CFS instance to be mounted.
|
||
|
||
See also:
|
||
mount_cfs() (see section 5.2.6.1)
|
||
|
||
Synopsis:
|
||
struct cfs_mount_s {
|
||
uint32_t base_block;
|
||
uint32_t blk_size;
|
||
int32_t uid;
|
||
int32_t gid;
|
||
void * bparam;
|
||
cfs_block_read_t * bread;
|
||
cfs_block_write_t * bwrite;
|
||
cfs_err_callback_t * err_callback;
|
||
uint32_t mount_options;
|
||
unsigned char reserved[8];
|
||
};
|
||
|
||
Structure Element Description:
|
||
base_block First physical block where file system starts on the device.
|
||
blk_size Logical block size of the mounted image
|
||
|
||
Note:
|
||
Will be checked against the value read from master block. If different than the one from master block,
|
||
the mount will fail.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
50 CFS POSIX API Reference
|
||
|
||
|
||
uid User ID (UID) to use for permission checks.
|
||
gid Group ID (GID) to use for permission checks.
|
||
bparam Parameter which is passed as first argument to block read and write functions.
|
||
bread Block read function.
|
||
|
||
Note:
|
||
The CFS implementation does not enter the bread and bwrite functions in parallel.
|
||
bwrite Block write function.
|
||
|
||
Note:
|
||
The CFS implementation does not enter the bread and bwrite functions in parallel.
|
||
err_callback Error callback function. This function is called if an error is found during the file system mount
|
||
checks. If set to NULL, the internal default error handler is used.
|
||
mount_options Mount options for the file system. CFS_MO_RO - mount file system read only
|
||
reserved Reserved space in order to achieve the same size as for the PikeOS native version of this structure
|
||
|
||
|
||
Associated Data Type
|
||
|
||
cfs_mount_t File system parameters.
|
||
|
||
|
||
5.2.1.3 struct cfs_config_s
|
||
|
||
CFS mkfs parameters.
|
||
Provides parameters for a new CFS instance. The overall CFS image size can be calculated as follows: im-
|
||
age_size = block_size * (number_of_inodes + number_of_blocks + 2). The two extra blocks are for the master
|
||
block and the rename journal.
|
||
|
||
Synopsis:
|
||
struct cfs_config_s {
|
||
uint32_t block_size;
|
||
uint32_t payload_size;
|
||
uint32_t number_of_inodes;
|
||
uint32_t number_of_blocks;
|
||
uint32_t file_name_max;
|
||
uint32_t blocks_per_direct_inode;
|
||
uint32_t uid;
|
||
uint32_t gid;
|
||
cfs_endian_t endian;
|
||
};
|
||
|
||
Structure Element Description:
|
||
block_size Block size
|
||
payload_size Payload size
|
||
number_of_inodes Number of inodes in file system
|
||
number_of_blocks Number of data blocks in file system
|
||
file_name_max Maximum size of file name
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
POSIX API 51
|
||
|
||
|
||
blocks_per_direct_inode Number of block pointers in direct inode
|
||
uid UID of the root directory
|
||
gid GID of the root directory
|
||
endian Endianness of the file system
|
||
|
||
|
||
Associated Data Type
|
||
|
||
cfs_config_t CFS mkfs parameters.
|
||
|
||
|
||
5.2.2 Defines
|
||
|
||
|
||
CFS_FILENAME_MAX
|
||
Maximum file name size upper limit.
|
||
Description:
|
||
The uppper limit for the maximum file name size.
|
||
|
||
CFS_FILENAME_MIN
|
||
Maximum file name size lower limit.
|
||
Description:
|
||
The lower limit for the maximum file name size.
|
||
|
||
CFS_MO_RO
|
||
Mount read only.
|
||
Description:
|
||
Mount the file system only for read access.
|
||
|
||
|
||
5.2.3 Data Type Definitions
|
||
|
||
cfs_inode_type_t CFS inode type.
|
||
cfs_file_type_t CFS file type.
|
||
cfs_blk_type_t Enumeration of disk block types.
|
||
Enumeration type used to tag disk blocks according to the data they contain.
|
||
cfs_err_act_t Enumeration of file system recovery actions.
|
||
Enumeration type for actions that can be taken when a file system check discovers an error and calls a
|
||
user defined callback to determine how to proceed.
|
||
|
||
Note:
|
||
Not all actions make sense on all errors.
|
||
cfs_err_type_t Enumeration of mount check error types.
|
||
Enumeration type determining the type of error that was found during checks on the file system mount.
|
||
|
||
Note:
|
||
For each item is noted which recovery actions are possible to take if that type of error ocured. If any
|
||
other action is requested it will be handled as CFS_ERR_ACT_ABORT.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
52 CFS POSIX API Reference
|
||
|
||
|
||
cfs_err_desc_t Structure with error description.
|
||
Structure with detailed description of an error found by checks during the file system mount.
|
||
cfs_mount_t File system parameters.
|
||
Describes operational parameters for a CFS instance to be mounted.
|
||
|
||
See also:
|
||
mount_cfs() (see section 5.2.6.1)
|
||
cfs_endian_t CFS endianness type.
|
||
Enumeration type for endiannes of the file system.
|
||
cfs_config_t CFS mkfs parameters.
|
||
Provides parameters for a new CFS instance. The overall CFS image size can be calculated as follows:
|
||
image_size = block_size * (number_of_inodes + number_of_blocks + 2). The two extra blocks are for
|
||
the master block and the rename journal.
|
||
|
||
|
||
5.2.4 Function Type Definitions
|
||
|
||
5.2.4.1 cfs_err_callback_t
|
||
|
||
Tell CFS how to proceed if a file system error is found.
|
||
|
||
|
||
Synopsis:
|
||
|
||
typedef cfs_err_act_t cfs_err_callback_t(cfs_err_desc_t *err_desc)
|
||
|
||
Description:
|
||
If an error in the file system is found during mount checks, this callback is used to determine how to proceed.
|
||
|
||
Note:
|
||
If this function requests an action, that is not defined for the given error the mount operation will proceed like if
|
||
CFS_ERR_ACT_ABORT was returned.
|
||
|
||
Parameters:
|
||
err_desc The structure describing the discovered error.
|
||
|
||
Returns:
|
||
Type of action. This action will be taken to solve the found problem.
|
||
|
||
|
||
5.2.4.2 cfs_block_read_t
|
||
|
||
CFS read physical block interface.
|
||
|
||
|
||
Synopsis:
|
||
|
||
typedef int cfs_block_read_t(void *s,
|
||
unsigned int blkno,
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
POSIX API 53
|
||
|
||
|
||
void *buf,
|
||
int nblocks,
|
||
cfs_blk_type_t flags)
|
||
|
||
Description:
|
||
Describes a function pointer for a read physical block function. A physical disk block contains 512 octets, block
|
||
numbers are absolute block numbers in the device, i.e. they already include the block offset specified by the
|
||
base_block member of cfs_mount_t.
|
||
|
||
Parameters:
|
||
s Private data passed to the block read function.
|
||
blkno Physical block number to start reading.
|
||
buf Buffer where to store read block data. This buffer is page aligned and can be directly used for DMA
|
||
transfer.
|
||
nblocks Number of contiguous blocks to be read.
|
||
flags Type of data to be read.
|
||
|
||
Returns:
|
||
The function returns 0 on success, -1 otherwise.
|
||
|
||
See also:
|
||
cfs_mount_t (see section 5.2.3)
|
||
|
||
|
||
5.2.4.3 cfs_block_write_t
|
||
|
||
CFS write physical block interface.
|
||
|
||
|
||
Synopsis:
|
||
|
||
typedef int cfs_block_write_t(void *s,
|
||
unsigned int blkno,
|
||
const void *buf,
|
||
int nblocks,
|
||
cfs_blk_type_t flags)
|
||
|
||
Description:
|
||
Describes a function pointer for a write physical block function. A physical disk block contains 512 octets, block
|
||
numbers are absolute block numbers in the device, i.e. they already include the block offset specified by the
|
||
base_block member of cfs_mount_t.
|
||
|
||
Parameters:
|
||
s Private data passed to the block read function.
|
||
blkno Physical block number to start writing.
|
||
buf Buffer for block data. This buffer is page aligned and can be directly used for DMA transfer.
|
||
nblocks Number of contiguous blocks to be written.
|
||
flags Type of written data.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
54 CFS POSIX API Reference
|
||
|
||
|
||
Returns:
|
||
The function returns 0 on success, -1 otherwise.
|
||
|
||
See also:
|
||
cfs_mount_t (see section 5.2.3)
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
POSIX API 55
|
||
|
||
|
||
5.2.5 Enumerations
|
||
|
||
Enumeration type cfs_inode_type_e
|
||
|
||
CFS inode type.
|
||
|
||
Name Description
|
||
CFS_INODE_DIRECT Type for direct inodes.
|
||
|
||
CFS_INODE_INDIRECT Type for indirect inodes.
|
||
|
||
|
||
Enumeration type cfs_file_type_e
|
||
|
||
CFS file type.
|
||
|
||
Name Description
|
||
CFS_FILE_DIRECTORY File type for directory files.
|
||
|
||
CFS_FILE_REGULAR File type for regular files.
|
||
|
||
|
||
Enumeration type cfs_blk_type_e
|
||
|
||
Enumeration of disk block types.
|
||
Enumeration type used to tag disk blocks according to the data they contain.
|
||
|
||
Name Description
|
||
CFS_BLK_MASTER file system master block
|
||
|
||
CFS_BLK_JOURNAL journal block
|
||
|
||
CFS_BLK_INODE_DIR direct inode
|
||
|
||
CFS_BLK_INODE_INDIR indirect inode
|
||
|
||
CFS_BLK_DIR_DATA directory data block
|
||
|
||
CFS_BLK_DATA regular file data block
|
||
|
||
|
||
Enumeration type cfs_err_act_e
|
||
|
||
Enumeration of file system recovery actions.
|
||
Enumeration type for actions that can be taken when a file system check discovers an error and calls a user
|
||
defined callback to determine how to proceed.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
56 CFS POSIX API Reference
|
||
|
||
|
||
Note:
|
||
Not all actions make sense on all errors.
|
||
|
||
Name Description
|
||
CFS_ERR_ACT_TRUNC A defective file or directory will be truncated to the last valid block. (or to
|
||
zero size)
|
||
|
||
CFS_ERR_ACT_DEL A defective file or directory will be removed.
|
||
|
||
CFS_ERR_ACT_FIX If the error is fixable, it will be fixed.
|
||
|
||
CFS_ERR_ACT_ABORT The mount operation stops, no data is changed.
|
||
|
||
CFS_ERR_ACT_MAKE_IT_FILE Mark the unknown entry as a file.
|
||
|
||
CFS_ERR_ACT_MAKE_IT_DIR Mark the unknown entry as a directory.
|
||
|
||
|
||
Enumeration type cfs_err_type_e
|
||
|
||
Enumeration of mount check error types.
|
||
Enumeration type determining the type of error that was found during checks on the file system mount.
|
||
|
||
Note:
|
||
For each item is noted which recovery actions are possible to take if that type of error ocured. If any other action
|
||
is requested it will be handled as CFS_ERR_ACT_ABORT.
|
||
|
||
Name Description
|
||
CFS_ERR_INO_NUM Reference to an indirect inode in a direct inode out of range.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_BLK_NUM Reference to a block in an inode is out of range.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_INO_TYPE Wrong inode type.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
CFS_ERR_ACT_FIX
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
POSIX API 57
|
||
|
||
|
||
CFS_ERR_INO_FTYPE Wrong file type in a direct inode.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_DEL
|
||
CFS_ERR_ACT_MAKE_IT_FILE
|
||
CFS_ERR_ACT_MAKE_IT_DIR
|
||
|
||
CFS_ERR_INO_USED Inode referenced more than once.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC (only for indirect inodes)
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_INO_PARENT Wrong parent inode reference in an indirect node.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
CFS_ERR_ACT_FIX
|
||
|
||
CFS_ERR_BLK_USED Block referenced more than once.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_FSIZE File size larger than remaining space.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_DIR_SIZE Size of a directory not a multiple of directory entry size.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_DIR_INO_NUM Out of range inode number in directory entry.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_DIR_END Empty items at the end of directory.
|
||
Valid action: CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_TRUNC
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
58 CFS POSIX API Reference
|
||
|
||
|
||
CFS_ERR_LINK_CNT Wrong count of links in a directory or regular file with a link count not
|
||
equal to 1.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_FIX
|
||
|
||
CFS_ERR_PATH_TOO_LONG Corrupted directory file that leads to too long path in pathname resolution.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_DEL
|
||
|
||
CFS_ERR_SLASH_IN_NAME Corrupted directory file that leads to a slash characte in a file name
|
||
resolution.
|
||
Valid actions:
|
||
CFS_ERR_ACT_ABORT
|
||
CFS_ERR_ACT_DEL
|
||
|
||
|
||
Enumeration type cfs_endian_e
|
||
|
||
CFS endianness type.
|
||
Enumeration type for endiannes of the file system.
|
||
|
||
Name Description
|
||
CFS_ENDIAN_LITTLE little endian
|
||
|
||
CFS_ENDIAN_BIG big endian
|
||
|
||
CFS_ENDIAN_NATIVE the native byte order of the running system
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
POSIX API 59
|
||
|
||
|
||
5.2.6 Functions
|
||
|
||
5.2.6.1 mount_cfs
|
||
|
||
Mount a CFS file system.
|
||
|
||
|
||
Synopsis:
|
||
|
||
void* mount_cfs(const char *path,
|
||
cfs_mount_t *config)
|
||
|
||
Description:
|
||
Function mount_cfs() (see section 5.2.6.1) installs a new CFS instance at top-level directory name path. The file
|
||
system mount parameters are passed in config. The return value is a handle for the installed CFS instance which
|
||
can be used in a call to unmount_cfs() (see section 5.2.6.2) to remove this instance.
|
||
|
||
Returns:
|
||
The function returns a handle for the new file system instance.
|
||
!=NULL upon success
|
||
NULL upon failure, errno is set to describe the error.
|
||
[ENOMEM] Memory allocation failed
|
||
[EINVAL] Invalid parameter
|
||
[EBUSY] CFS instance already registered
|
||
[EAGAIN] Instance lock cannot be initialized
|
||
|
||
See also:
|
||
cfs_config_t (see section 5.2.3)
|
||
unmount_cfs() (see section 5.2.6.2)
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
60 CFS POSIX API Reference
|
||
|
||
|
||
5.2.6.2 unmount_cfs
|
||
|
||
Unmount a CFS file system.
|
||
|
||
|
||
Synopsis:
|
||
|
||
int unmount_cfs(void *handle)
|
||
|
||
Description:
|
||
Function unmount_cfs() (see section 5.2.6.2) removes a CFS instance previously installed by a successful call to
|
||
mount_cfs() (see section 5.2.6.1). Parameter handle is the handle returned by the call to mount_cfs() (see section
|
||
5.2.6.1) used to install the file system.
|
||
|
||
Returns:
|
||
The function return value is a completion status.
|
||
0 upon success
|
||
-1 upon failure, errno is set to describe the error.
|
||
[EBUSY] CFS instance still in use
|
||
[EINVAL] Invalid file system handle
|
||
|
||
See also:
|
||
mount_cfs() (see section 5.2.6.1)
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
POSIX API 61
|
||
|
||
|
||
5.2.6.3 mkfs_cfs
|
||
|
||
Create an empty CFS file system image.
|
||
|
||
|
||
Synopsis:
|
||
|
||
int mkfs_cfs(cfs_config_t *cfs_config,
|
||
void *buf,
|
||
uint32_t size)
|
||
|
||
Description:
|
||
Function mkfs_cfs() (see section 5.2.6.3) creates an empty file system image containing the master block, an
|
||
empty journal block, and the root inode. This minimal file system image is stored in the buffer buf which has to
|
||
be large enough to hold three blocks of the desired block size. To ensure that, "mkfs_cfs" will check parameter
|
||
size before writing the image to the buffer. All information about the file system configuration will be specified by
|
||
parameter cfs_config.
|
||
|
||
Parameters:
|
||
cfs_config [IN] File system configuration.
|
||
buf [OUT] Buffer to store the created image in.
|
||
size [IN] Size of the buffer buf.
|
||
|
||
Returns:
|
||
The function return value is a completion status.
|
||
0 upon success
|
||
-1 upon failure, errno is set to describe the error.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
6 cfs-tool Helper Application
|
||
|
||
|
||
NAME
|
||
|
||
cfs-tool – CFS manipulation tool
|
||
|
||
|
||
SYNOPSIS
|
||
|
||
cfs-tool -c cfs-image [--size n] [--inodes n] [--blocksize n]
|
||
[--payload n] [--blocks-per-direct-inode n]
|
||
[--file-name-max n] [--uid uid] [--gid gid]
|
||
[--little-endian] [--big-endian]
|
||
[--copy-files path] [--files-from list] [--grow]
|
||
[--deterministic]
|
||
|
||
cfs-tool [-i cfs-image] [-l cfs-image] [-lv cfs-image] [-lt cfs-image]
|
||
[-ltv cfs-image] [-x cfs-image path] [-e, --examine cfs-image]
|
||
[--uid uid] [--gid gid] [-v] [--help] [-V, --version]
|
||
|
||
|
||
DESCRIPTION
|
||
|
||
cfs-tool provides a collection of functionalities around the certifiable file system CFS. Functionality for creating
|
||
empty and populated file systems. Analysis of file system structure and repair of corrupted structures. Extraction
|
||
of file system content. Output of properties, attributes and contents of file systems.
|
||
|
||
|
||
OPTIONS
|
||
|
||
c, -c, --create cfs-image
|
||
Create a CFS image with name cfs-image and default settings
|
||
for user- and group ID (1000/100).
|
||
Optional subparameters of this option:
|
||
|
||
--size n
|
||
Total size in bytes of the CFS file system
|
||
when creating cfs-image (default 16Mb).
|
||
|
||
--inodes n
|
||
Number of inodes (default 1022).
|
||
|
||
--blocksize n
|
||
Size of blocks in bytes. (default 4096)
|
||
Supported sizes are 2^9 - 2^13 bytes
|
||
(512, 1024, 2048, 4096, 8192 bytes).
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
63
|
||
|
||
|
||
--payload n
|
||
Size of the payload in bytes (default 4096).
|
||
Payload size shall be an integral multiple of 64.
|
||
Payload size shall be between 128 bytes and the block size.
|
||
|
||
--blocks-per-direct-inode n
|
||
Number of block pointers in an direct inode (default 508).
|
||
Number of blocks shall be between 0 and table size of direct
|
||
inode.
|
||
|
||
--file-name-max n
|
||
Maximum file name length. (default 32)
|
||
Value shall be between 32 and (payload_size - 40).
|
||
Note: The journal record is file-name-max + 40 bytes long.
|
||
|
||
--uid uid
|
||
Override file / directory uid.
|
||
|
||
--gid gid
|
||
Override file / directory gid.
|
||
|
||
--little-endian
|
||
Use little endian byteorder.
|
||
|
||
--big-endian
|
||
Use big endian byteorder (default).
|
||
|
||
--files-from list
|
||
Copy local directories and files described by textfile list
|
||
from to CFS root directory. For list command syntax can be
|
||
used, see details in examples.
|
||
|
||
--copy-files path
|
||
Copy local directory structure and files from path
|
||
to CFS directory hierarchy.
|
||
|
||
--grow
|
||
Grow the image file to the defined image size.
|
||
|
||
--deterministic
|
||
Use ’0’ as timestamp while creating an image instead
|
||
of the file’s timestamp.
|
||
|
||
i, -i, --info cfs-image
|
||
List information about cfs-image.
|
||
CFS master record info, magic_id version, blocksize, blocknumber,
|
||
payload size, number of blocks, indodes, number of blocks per
|
||
dir/inode, maximum filename length, creation time and date,
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
64 cfs-tool Helper Application
|
||
|
||
|
||
endianess, used inodes, used blocks, number of directories,
|
||
number of files, max. deep of file system structure.
|
||
|
||
--uid uid
|
||
User ID used to access the files.
|
||
Use --uid 0 (default) for disabling access checks.
|
||
|
||
--gid gid
|
||
Group ID used to access the files.
|
||
|
||
l, -l, --list cfs-image
|
||
List contents of cfs-image in simple style.
|
||
Optional variants of this option:
|
||
|
||
lv, -lv
|
||
List content verbose with numbering, filetype, permissions,
|
||
user- and group ID, modification time,size and full path.
|
||
|
||
lt, -lt --list-tree
|
||
List content in a tree like style.
|
||
|
||
ltv, -ltv
|
||
List content in a tree like style verbose with name,
|
||
filetype, permissions, user- and group ID and size.
|
||
|
||
--uid uid
|
||
User ID used to access the files.
|
||
Use --uid 0 (default) for disabling access checks.
|
||
|
||
--gid gid
|
||
Group ID used to access the files.
|
||
|
||
x, -x, --extract cfs-image path
|
||
Extract the content of cfs-image to path.
|
||
If last subdirectory of path does not exist, it gets created.
|
||
|
||
--uid uid
|
||
User ID used to access the files.
|
||
Use --uid 0 (default) for disabling access checks.
|
||
|
||
--gid gid
|
||
Group ID used to access the files.
|
||
|
||
e, -e, --examine cfs-image
|
||
Examine the content of CFS image cfs-image and repair if
|
||
corrupted.
|
||
|
||
v, -v, --verbose
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
65
|
||
|
||
|
||
Increase verbosity level to explain what is being done.
|
||
Can be used as short-form postfix (see -lv or -ev) or
|
||
stand-alone with options c, i, l, lt, x and e. In that
|
||
case pay attention to the position of the argument.
|
||
|
||
-h, --help
|
||
Display this help manual and exit
|
||
|
||
-V, --version
|
||
Output version information and exit
|
||
|
||
|
||
EXAMPLES
|
||
|
||
cfs-tool -c my_cfs_image.cfs
|
||
Create an empty CFS image named my_cfs_image.cfs and default
|
||
values for properties size, inodes, blocksize, payload,
|
||
blocks-per-direct-inode, file-name-max and endianess.
|
||
|
||
cfs-tool -c my_cfs_image.cfs --size 8388608 --inodes 80 --blocksize 512
|
||
--payload 5632 --blocks-per-direct-inode 250 --file-name-max 64
|
||
--uid 88 --gid 1000 --little-endian
|
||
Create empty CFS image with name my_cfs_image.cfs
|
||
and user defined values for subparameters.
|
||
|
||
cfs-tool -c my_cfs_image.cfs --copy-files /home/user/mydir
|
||
Create a populated CFS image named my_cfs_image.cfs
|
||
and default values of properties.
|
||
Use the existing host file system structure beginning.
|
||
at /home/user/mydir and insert the structure to CFS image.
|
||
|
||
cfs-tool -c my_cfs_image.cfs --files-from list
|
||
Create a populated CFS image named my_cfs_image.cfs
|
||
and default values of properties.
|
||
The textfile named "list" is used as input to control which
|
||
directories and files shall be written to the CFS image.
|
||
|
||
The interpreter knows comment lines starting with "#" and the
|
||
special command "-C" for changing the host directory.
|
||
|
||
Entries in the list file can be files or directories.
|
||
The default host directory is the current working directory.
|
||
|
||
Example list file:
|
||
|
||
-C/home/usr/tmp/test1/
|
||
example.txt
|
||
test_10/hello.txt
|
||
dirchain/dirchain_a/dirchain_b
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
66 cfs-tool Helper Application
|
||
|
||
|
||
test_2
|
||
-C/home/usr/tmp/test2/
|
||
entry_debug/textfile_debug.txt
|
||
|
||
The first line of "list" changes to hostdir /home/usr/tmp/test1
|
||
Line 2 names a file with hostpath /home/usr/tmp/test1/example.txt
|
||
that gets copied to CFS without any subdirectory.
|
||
Line 3 names a textfile with hostpath
|
||
/home/usr/tmp/test1/test_10/hello.txt, that gets copied to CFS
|
||
with subdirectory /test_10, path at CFS image is
|
||
test_10/hello.txt. Then another change of dir with -C and one
|
||
more file.
|
||
|
||
cfs-tool -i my_cfs_image.cfs
|
||
List information about cfs-image my_cfs_image.cfs
|
||
|
||
cfs-tool -l my_cfs_image.cfs
|
||
List file system structure of cfs-image
|
||
my_cfs_image.cfs in a simplified format.
|
||
|
||
cfs-tool -lt my_cfs_image.cfs
|
||
List file system structure of cfs-image
|
||
my_cfs_image.cfs in a simple tree-like format.
|
||
|
||
cfs-tool -ltv my_cfs_image.cfs
|
||
List file system structure of cfs-image
|
||
my_cfs_image.cfs in a verbose tree-like format.
|
||
|
||
cfs-tool -x my_cfs_image.cfs /home/user/my_cfs_content
|
||
Extract the content of cfs-image my_cfs_image.cfs
|
||
to path /home/user/my_cfs_content.
|
||
If directory my_cfs_content does not exist, it gets created.
|
||
If directory /home/user does not exist an error occurs.
|
||
|
||
cfs-tool -e cfs_image.cfs
|
||
Examine the content of CFS image cfs_image.cfs
|
||
and repair if corrupted.
|
||
|
||
cfs-tool --help
|
||
Display this help and exit.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
7 CFS for PikeOS Native Memory Requirements
|
||
|
||
|
||
This section describes size requirements on the memory pool of CFS for PikeOS native. In POSIX version of
|
||
CFS, the size of memory pool is counted and the pool is allocated during mount time using malloc() function.
|
||
This calculation can be used for estimations for POSIX version of CFS but the size of external file pool has to be
|
||
subtracted, because the external file pool is PikeOS native version specific.
|
||
|
||
|
||
7.1 Total CFS Memory Usage
|
||
|
||
The memory pool needs to store all internal data structures so the amount of memory can be calculated as sum
|
||
of size of these data structures.
|
||
|
||
|
||
mem_needed = statics + int_f ile_pool + object_pool + rollback _bitstrings
|
||
+ f ree_resource_bitmaps + dir_entry _buf f ers
|
||
(1)
|
||
+ f ile_name_buf f ers
|
||
+ ext_f ile_pool + ext_f ile_pool_bitmap
|
||
|
||
If we express it with device parameters and mount options as explained in 7.2 the resulting summary formula is
|
||
as follows:
|
||
|
||
|
||
32dlog32 inodes _nume − 1 32d(log32 blocks _nume − 1
|
||
mem_needed = 2 ∗ +
|
||
31 31
|
||
+ 12 ∗ max _open _files ∗ sizeof (P4 _addess _t))
|
||
+ 4 ∗ max _open _files ∗ P4 _ARCH _ALIGN
|
||
+ 3 ∗ max _open _files ∗ logical _blk _size
|
||
+ 5 ∗ max _filename _size (2)
|
||
+ 36 ∗ max _open _files
|
||
+ 19 ∗ logical _blk _size
|
||
+ 79 ∗ sizeof (P4 _addess _t)
|
||
+ 19 ∗ sizeof (enum)
|
||
+ 31 ∗ P4 _ARCH _ALIGN + 2392
|
||
|
||
Where the items has following meaning:
|
||
inodes _num is configured amount of inodes on device
|
||
blocks _num is configured amount of data blocks on device
|
||
max _open _files is configured number of simultaneously open files
|
||
logical _blk _size size of logical block used on device
|
||
max _filename _size is configured maximum file name
|
||
P4 _addess _t is architecture specific size of pointer
|
||
P4 _ARCH _ALIGN is architecture specific page alignment
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
68 CFS for PikeOS Native Memory Requirements
|
||
|
||
|
||
7.2 Partial Memory Requirements
|
||
|
||
The CFS allocates all data structures in the memory pool during the mount time. Following data structures are
|
||
allocated out of the memory pool.
|
||
|
||
|
||
7.2.1 CFS Configuration Data
|
||
|
||
|
||
For each mounted device CFS keeps a structure with configuration.
|
||
|
||
|
||
statics = sizeof (cf s_t)
|
||
= 16 ∗ sizeof (void∗) + 21 ∗ sizeof (P 4_uint32_t) + sizeof (cf s_pblk _stat_t)
|
||
(3)
|
||
+ sizeof (cf s_blk _stat_t) + sizeof (cf s_mem_stat_t) + 2 ∗ CF S _P AT H _M AX
|
||
= 148 + 21 ∗ sizeof (P4 _addess _t) + 2 ∗ CF S _P AT H _M AX
|
||
|
||
|
||
7.2.2 Internal File Descripton Pool
|
||
|
||
|
||
Preallocated pool of internal files descriptors.
|
||
|
||
|
||
int_f ile_pool = (max _open _files + 3) ∗ (sizeof (cf s_f ile_int_t) + P4 _ARCH _ALIGN )
|
||
= (max _open _files + 3) ∗ (3 ∗ sizeof (P 4_uint32_t)
|
||
+ 4 ∗ sizeof (P4 _addess _t) + P4 _ARCH _ALIGN )
|
||
= (max _open _files + 3) ∗ (16 + 4 ∗ sizeof (P4 _addess _t) + P4 _ARCH _ALIGN )
|
||
(4)
|
||
|
||
|
||
7.2.3 Memory Objects Pool
|
||
|
||
|
||
CFS preallocates the pool of objects used to store data blocks and inodes before writing and after reading it to the
|
||
device.
|
||
|
||
|
||
object_pool = (3 ∗ (max _open _files + 3) + 10)
|
||
∗ (sizeof (cf s_po_t) + logical _blk _size + P4 _ARCH _ALIGN )
|
||
= (3 ∗ max _open _files + 19) (5)
|
||
∗ (sizeof (enum) + 4 + 2 ∗ sizeof (P4 _addess _t) + logical _blk _size
|
||
+ P4 _ARCH _ALIGN ))
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
Partial Memory Requirements 69
|
||
|
||
|
||
7.2.4 Rollback Bistring
|
||
|
||
Rollback bitstring used to store the bits allocated during disk operation. This bitstring are used for returning back
|
||
the resources in case the operation fails.
|
||
|
||
|
||
rollback _bitstrings = bitstring _data_size + sizeof (cf s_bitstr_t) + alignment
|
||
32dlog32 inodes _nume − 1 (6)
|
||
=
|
||
31
|
||
+ (12 + 2 ∗ sizeof (P4 _addess _t)) + P4 _ARCH _ALIGN
|
||
|
||
The dxe means ceiling function, dxe is the smallest integer not less than x. CFS uses level based lookup tree of
|
||
32bit wide words, that induces the ceiling function and the log32 function.
|
||
|
||
|
||
7.2.5 Free Disk Resources Bitmaps
|
||
|
||
For faster lookup for free disk resources CFS uses bitmaps. One bitmap is used for inodes one for data blocks.
|
||
Each bitmap consists of the lookup level tree bitstring holding the state of the bitmap elements and a data structure
|
||
describing the bitmap itself.
|
||
|
||
|
||
inodes_bitmap_size = (32d(log32 inodes _nume − 1)/31 + sizeof (struct_cf s_bitmap_t)
|
||
+ sizeof (cf s_bitstring _t) + P4 _ARCH _ALIGN
|
||
32d(log32 inodes _nume − 1
|
||
= + (12 + 2 ∗ sizeof (P4 _addess _t))
|
||
31 (7)
|
||
+ (12 + sizeof (P 4a ddresst )) + P4 _ARCH _ALIGN
|
||
32d(log32 inodes _nume − 1
|
||
= + 3 ∗ sizeof (P4 _addess _t)
|
||
31
|
||
+ 24 + P4 _ARCH _ALIGN
|
||
|
||
|
||
32d(log32 blocks _nume − 1
|
||
blocks_bitmap_size = + 3 ∗ sizeof (P4 _addess _t)
|
||
31 (8)
|
||
+ 24 + P4 _ARCH _ALIGN
|
||
|
||
|
||
f ree_resource_bitmaps = inodes_bitmap_size + blocks_bitmap_size
|
||
32d(log32 inodes _nume − 1 32d(log32 blocks _nume − 1 (9)
|
||
= +
|
||
31 31
|
||
+ 48 + 6 ∗ sizeof (P4 _addess _t) + 2 ∗ P4 _ARCH _ALIGN
|
||
|
||
|
||
7.2.6 Various helper buffers
|
||
|
||
For directory based operations CFS requires two directory entry buffers.
|
||
|
||
|
||
dir_entry _buf f ers = 2 ∗ (4 + max _filename _size + P4 _ARCH _ALIGN ) (10)
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
70 CFS for PikeOS Native Memory Requirements
|
||
|
||
|
||
For file name based operations CFS requires three file name buffers.
|
||
|
||
|
||
f ile_name_buf f ers = 3 ∗ (max _filename _size + 1 + P4 _ARCH _ALIGN ) (11)
|
||
|
||
|
||
7.2.7 External file description pool
|
||
|
||
In the PikeOS native version of the CFS there is also a pool of the external file descriptors. This pool consists of
|
||
memory holding the file descriptor data and a bitmap for managing the file structures.
|
||
|
||
|
||
32d(log32 max _open _filese − 1
|
||
ext_f ile_pool = + sizeof (cf s_bitstring _t) + sizeof (cf s_bitmap_t)
|
||
31
|
||
+ max _open _files ∗ sizeof (cf s_f ile_t) + P4 _ARCH _ALIGN
|
||
32d(log32 max _open _filese − 1
|
||
= + 24 + 3 ∗ sizeof (P4 _addess _t)
|
||
31
|
||
+ max _open _files ∗ (8 + 2 ∗ sizeof (P4 _addess _t)) + P4 _ARCH _ALIGN
|
||
(12)
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
8 Performance Considerations
|
||
|
||
|
||
8.1 CFS Design Overview
|
||
|
||
In this section a basic overview of the CFS design is given. Specifically it is explained how metadata/data is
|
||
arranged on disk by CFS so implications on performance can be provided in the following sections. In the Figure
|
||
6 it is shown how file/directory metadata is arranged in so called inodes.
|
||
|
||
Inode: (direct inode)
|
||
type: (enum) (direct) 4 bytes
|
||
ftype: (enum) (directory, file) 4 bytes
|
||
mtime: (int64) <modification time> 8 bytes
|
||
size: (uint64) <file size> 8 bytes
|
||
mode: (uint32) <acess rights> 4 bytes
|
||
uid: (int32) <user id> 4 bytes
|
||
gid: (int32) <group id> 4 bytes
|
||
link_count: (uint32) <num files in DIR> 4 bytes Data Block
|
||
Block Table[] blkno1 (uint32) 4 bytes
|
||
|
||
|
||
blocks_per_dir_inod e
|
||
Data
|
||
<Array of block numbers
|
||
blkno2 (uint32) 4 bytes
|
||
(blknos) used>
|
||
blknoN = last blkno .
|
||
.
|
||
.
|
||
blknoN (uint32) 4 bytes
|
||
Inode Table[] .
|
||
ino1 (uint32) 4 bytes
|
||
<Array of inode numbers .
|
||
ino2 (uint32) 4 bytes .
|
||
(inos) used>
|
||
inoN = last ino .
|
||
inoN (uint32) 4 bytes
|
||
|
||
|
||
Inode: (indirect inode)
|
||
type: (enum) (indirect) 4 bytes
|
||
ino_dir: (uint32) <ino of direct inode> 4 bytes Data Block
|
||
Block Table[] Blkno1 (uint32) 4 bytes Data
|
||
<Array of block numbers
|
||
blkno2 (uint32) 4 bytes
|
||
(blknos) used>
|
||
blknoN = last blkno .
|
||
.
|
||
blknoN (uint32) 4 bytes .
|
||
.
|
||
.
|
||
|
||
|
||
Figure 6: CFS metadata layout
|
||
|
||
|
||
Inodes hold the logical structure of the file system like directories and files. There are two types of inodes, direct
|
||
inodes and indirect inodes. Direct inodes are the start inodes for a file that hold the metadata of the file. That
|
||
metadata are the inode type, file type, modification time, size, file permissions, user id, group id and the link
|
||
count. The remaining space after this header until the payload size is used for the combined block inode table.
|
||
Depending on blks_per_dir_inode the virtual border between block pointers and inode pointers is shifted between
|
||
only blocks, only inodes and any intermediate value between. The indirect inodes are to expand the block table of
|
||
a file when it needs more blocks than fit into the direct inode. It needs a reduced set of metadata that are inode
|
||
type and number of the parent direct inode.
|
||
The CFS image has a designated area for inodes and a designated area for data blocks. Sizes of these areas are
|
||
define during file system creations and can’t be changed later during the CFS image life time.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
72 Performance Considerations
|
||
|
||
|
||
Each inodes occupies a whole logical block on disk regardless of whether their space is completely used or not.
|
||
Modifying an inode on disk means to write a whole block back to the storage even if only a part of an inode is
|
||
changed. No partial writes or updates are supported by the CFS. In order to reduce the read accesses to the
|
||
storage medium CFS holds three cache blocks for each open file or directory. One for the direct inode of the file,
|
||
one for the last accessed indirect inode and one for the last accessed data block. Consequently small amounts of
|
||
data (smaller than a logical block) can be read from a file in a loop without leading to performance drops introduced
|
||
by the block layer. CFS operates synchronously, every changes is propagated to the device before the end of the
|
||
operation. This means that every change to a file triggers immediate write operation(s) to the device.
|
||
|
||
|
||
8.2 CFS Mount Time
|
||
|
||
To know which disk resources (inodes, blocks) are in use and which can be used to add data to the disk there
|
||
are two resource lists per mounted CFS partition. They are only kept in system memory to avoid additional disk
|
||
access while reading or updating the lists. During mount time these lists are generated by scanning the whole file
|
||
system. Scanning the whole file system means that every used inode block and data blocks used by directories
|
||
have to be read from the storage medium which may lead to a significant mount time especially if the file system
|
||
contains many small files or a lot of directories.
|
||
|
||
|
||
8.3 Write Operation
|
||
|
||
Figure 7 shows the flow of write operation.
|
||
CFS expects the device to write blocks in an atomic manner and in the same order as the block write operations
|
||
was issued. If this is guaranteed, the CFS maintains consistency of data on the device in every moment and
|
||
assures that write operation is either completed or no change to the files already stored on device is done at all. If
|
||
the write operation requires the change of more blocks, the updated copy of the modified part of the file is created
|
||
and the last write of meta data block (expected to be done atomically by the device) replaces the old content with
|
||
the new one.
|
||
Because of this "copy on write" the write operation requires additional inode writes. This "copy on write" can be
|
||
spared if only one data block is changed during the write operation.
|
||
|
||
|
||
8.4 Growing a File
|
||
|
||
There might be a significant difference in write performance between writing to a newly created file and overwriting
|
||
an already existing file’s contents. This is caused by the fact that ’growing’ a file always triggers an update of the
|
||
metadata block(s). File size and inode and block tables needs to be updated in this case on every write operation.
|
||
On contrary if modifying existing file content the metadata blocks needs an update only if more data blocks are
|
||
changed.
|
||
If it is possible the write performance can be improved significantly by ’pre-growing’ the file before writing and then
|
||
writing in the way that only one block is changed at once:
|
||
|
||
ftruncate(&fd, TOTAL_SIZE);
|
||
do {
|
||
write(&fd, &buffer[offset], write_size, &sz);
|
||
} while(!finished);
|
||
|
||
As explained above the write_size and the current file offset needs to be set in the way that each write operation
|
||
modifies only one block in order to avoid the need of using the "copy on write" feature in the CFS library. The most
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
Growing a File 73
|
||
|
||
|
||
Function calls Open File
|
||
Data
|
||
Description
|
||
Data flow
|
||
|
||
|
||
Disk Resources Module Core Write Module
|
||
|
||
|
||
Load block on the
|
||
current offset
|
||
|
||
Create a
|
||
block reserve Calculate number of
|
||
containing all inodes and blocks to
|
||
new blocks be added to the file
|
||
|
||
|
||
Write data blocks
|
||
Allocate indirect from the reserve
|
||
inodes if needed
|
||
Data Block Module
|
||
|
||
Write indirect inodes Read data Write data
|
||
Store all changed if any
|
||
inodes and blocks in block block
|
||
the unroll bitstring to
|
||
enable reverting
|
||
changes in case of Update file direct
|
||
failure inode
|
||
|
||
|
||
Inode Module Physical Block Module
|
||
|
||
|
||
Read physical Write physical
|
||
Write inode
|
||
blocks blocks
|
||
|
||
|
||
Storage Device Driver
|
||
|
||
Block Read Block Write
|
||
Function Function
|
||
|
||
|
||
Figure 7: CFS writing procedure
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
74 Performance Considerations
|
||
|
||
|
||
significant speedup can be measured if the write is aligned to logical block boundary and the write_size matches
|
||
the logical block size.
|
||
|
||
|
||
8.5 Considerations When Used With Volume Providers
|
||
|
||
Each volume providers offer a configurable "Maximum Atomic Size". This is the amount of data which can be
|
||
transferred in one read() or write() operation. Ideally this value should be set to the block size or a multiple of it.
|
||
Further the application should align the read and write buffer size to this value.
|
||
|
||
|
||
8.6 Considerations When Used With SD Cards
|
||
|
||
The SD cards were originally designed to store data streams like audio or video data. They perform the best if
|
||
long blocks of data are read or written. This induces that CFS image with larger blocks (4kiB or 8kiB) performs
|
||
better than 512B large blocks on such cards.
|
||
On contrary many of the SD cards can’t write such blocks of data atomically. If the SD card can’t guarantee such
|
||
atomic writes the power failure may render the CFS image inconsistent. Moreover some SD cards may, if power
|
||
failure appears during write, even corrupt other data blocks then the currently written ones. If such card can’t be
|
||
avoided the user should at least consider to provide CFS with an error callback function.This error callback can
|
||
then instructs CFS library to prune such corrupted parts of the CFS image and allows recover and mount the CFS
|
||
image containing at least files not corrupted during the power failure.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
9 Limitations of the CFS
|
||
|
||
|
||
The current CFS implementation has the following limitations and known problems:
|
||
|
||
|
||
• Limited size of files
|
||
The maximum size of a file can be calculated the following way:
|
||
|
||
|
||
f ilesize = payload_size ∗ (blocks_per_direct_inode + indirect_table_size ∗ indirect_inodes)
|
||
(13)
|
||
|
||
|
||
If we express the indirect_inodes and indirect_table_size with the file system parameters we will get:
|
||
|
||
|
||
payload
|
||
f ilesizemax = payload ∗ (blocks_per_direct_inode + ( − 2)∗
|
||
sizeof (uint32_t)
|
||
(14)
|
||
payload
|
||
( − 10 − blocks_per_direct_inode))
|
||
sizeof (uint32_t)
|
||
|
||
• Limited size of directories
|
||
The size of a directory is limited to the size of a file. As mentioned earlier there is a limit for the file size
|
||
depending on the configured block size. The number of nodes per directory can be calculated the following
|
||
way:
|
||
|
||
maxf ilesize payload_size
|
||
max_dir_nodes = ∗b c (15)
|
||
payload_size f ilename_max + 4
|
||
|
||
The bxc function refers to a floor function that maps a real number to the largest integer number less than
|
||
or equal to x.
|
||
When adding nodes to a directory using creat() or mkdir() the functions return -1 and set errno to EFBIG to
|
||
indicate that error.
|
||
|
||
• Volume size limits
|
||
The size of a volume is limited by the amount of physical blocks that can be addressed using the P4_uint32_t
|
||
type.
|
||
|
||
|
||
max_volume_size = 512Bytes ∗ 232
|
||
(16)
|
||
= 242 Bytes = 2T iB
|
||
|
||
Note that CFS stores the disk resource usage maps in memory. For such large volumes these resource
|
||
maps will require a significant amount of memory. For details how to calculate memory requirements of the
|
||
CFS library for the selected image geometry refer to chapter 7.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
76 Limitations of the CFS
|
||
|
||
|
||
• Duplicate file names are not handled by file system check
|
||
When an error occurs in the file system so that two (or more) files within one directory have the same name,
|
||
the file system check will not detect this. The second (and further) file(s) won’t be accessible - until the first
|
||
one is deleted.
|
||
Note: Check for this type of error may take significant time during mount. This situation cannot happen
|
||
during a regular operation. Duplicated file names will be rejected during file/directory creation.
|
||
|
||
|
||
Please see the document releasenotes-cfs.pdf for the most recent information about the current CFS release.
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
10 Copyright Notices
|
||
|
||
|
||
The implementation of CFS uses a reduced version of the file <sys/queue.h> from FreeBSD source code. This
|
||
requires us to state here the following copyright notices.
|
||
|
||
|
||
/*-
|
||
* Copyright (c) 1991, 1993
|
||
* The Regents of the University of California. All rights reserved.
|
||
*
|
||
* Redistribution and use in source and binary forms, with or without
|
||
* modification, are permitted provided that the following conditions
|
||
* are met:
|
||
* 1. Redistributions of source code must retain the above copyright
|
||
* notice, this list of conditions and the following disclaimer.
|
||
* 2. Redistributions in binary form must reproduce the above copyright
|
||
* notice, this list of conditions and the following disclaimer in the
|
||
* documentation and/or other materials provided with the distribution.
|
||
* 4. Neither the name of the University nor the names of its contributors
|
||
* may be used to endorse or promote products derived from this software
|
||
* without specific prior written permission.
|
||
*
|
||
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ‘‘AS IS’’ AND
|
||
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||
* ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
||
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||
* SUCH DAMAGE.
|
||
*
|
||
* @(#)queue.h 8.5 (Berkeley) 8/20/94
|
||
* $FreeBSD: src/sys/sys/queue.h,v 1.68 2006/10/24 11:20:29 ru Exp $
|
||
*/
|
||
|
||
|
||
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
|
||
|