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
123 KiB
| title | source | category | pages | extracted |
|---|---|---|---|---|
| Cfs Reference Manual | docs/development/cfs-reference-manual.pdf | development | 77 | 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///include/cfs, /opt/pikeos-D5.0/target///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///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:
-
- Redistributions of source code must retain the above copyright
-
notice, this list of conditions and the following disclaimer.
-
- 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.
-
- 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.