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
159 KiB
| title | source | category | pages | extracted |
|---|---|---|---|---|
| Volume Provider Reference Manual | docs/development/volume-provider-reference-manual.pdf | development | 92 | 2026-07-06T23:05:35.598108 |
Volume Provider Reference Manual
Extracted from
docs/development/volume-provider-reference-manual.pdf(92 pages). Figures, diagrams, and tables may not render accurately in plain text.
PikeOS Volume Provider Reference Manual
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. PikeOS Volume Provider Reference Manual PikeOS D5.0, Document Version D5.0-368
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 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1.2 VMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.2 Configuration Using Component Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.2.1 Volume Provider Configuration Component . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.2.2 Volume Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.2.3 Volume Partition Access Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3 Available Demo Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2 Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3 Concurrent Access to Volume Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4 Developing a Volume Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.1 Developing a File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.2 Developing an Internal Block Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.3 Volume Provider Fusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.3.1 Pool Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.3.2 Exporting Symbols in Volume Provider Objects . . . . . . . . . . . . . . . . . . . . . . . . 15 5 FS Library API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.1 Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.2 FSlib API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.2.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.2.1.1 struct vp_fs_file_desc_str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.2.1.2 struct vp_fs_dir_str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.2.1.3 struct vp_fs_mount_context_str . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.2.1.4 struct fs_desc_str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.2.1.5 struct fs_register_volume_params_str . . . . . . . . . . . . . . . . . . . . . . . . 20 5.2.1.6 struct vp_fs_desc_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.2.2 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.2.3 Function Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.2.3.1 vp_fs_init_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.2.3.2 vp_fs_open_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.2.3.3 vp_fs_unlink_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 5.2.3.4 vp_fs_rename_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.2.3.5 vp_fs_statvfs_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.2.3.6 vp_fs_read_at_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.2.3.7 vp_fs_write_at_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 5.2.3.8 vp_fs_lseek_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 5.2.3.9 vp_fs_fstat_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 5.2.3.10 vp_fs_close_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 5.2.3.11 vp_fs_map_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 5.2.3.12 vp_fs_ioctl_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 5.2.3.13 vp_fs_fsync_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
4 CONTENTS
5.2.3.14 vp_fs_ftruncate_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.2.3.15 vp_fs_dir_create_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.2.3.16 vp_fs_dir_open_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.2.3.17 vp_fs_dir_read_at_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.2.3.18 vp_fs_dir_sync_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.2.3.19 vp_fs_dir_close_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.2.3.20 vp_fs_mount_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.2.3.21 vp_fs_umount_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.2.3.22 fs_register_volume_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.2.3.23 fs_init_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.2.4 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.3 FSlib Service API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.3.1 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.3.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.3.2.1 vp_fs_vmem_alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.3.2.2 vp_fs_malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.3.2.3 vp_fs_free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.3.2.4 vp_fs_get_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5.3.2.5 vp_fs_tls_set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.3.2.6 vp_fs_tls_get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.3.2.7 vp_fs_next_fd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.3.2.8 vp_fs_next_dd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.3.2.9 vp_fs_get_client_uid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.3.2.10 vp_fs_get_locking_flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
5.3.2.11 vp_log_printf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.3.2.12 vp_log_get_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.4 Block/MTD device API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.4.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.4.1.1 struct vmio_blk_info_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.4.1.2 union vmio_blk_handle_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.4.1.3 struct vmio_blk_io_options_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.4.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.4.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.4.4 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.4.5 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.4.6 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.4.6.1 vmio_blk_register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.4.6.2 vmio_blk_deregister . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.4.6.3 vmio_blk_erase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.4.6.4 vmio_blk_trim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.4.6.5 vmio_blk_flush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.4.6.6 vmio_blk_check_bad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.4.6.7 vmio_blk_mark_bad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.4.6.8 vmio_blk_get_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.4.6.9 vmio_blk_read_page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
5.4.6.10 vmio_blk_write_page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
5.5 Interaction of File Systems and Block Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
CONTENTS 5
6 APEX Error Indications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 6.1 REMOVE_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 6.2 RENAME_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 6.3 RENAME_DIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 6.4 GET_VOLUME_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 6.5 SYNC_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 6.6 RESIZE_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 6.7 MAKE_DIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 6.8 REMOVE_DIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 6.9 OPEN_DIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 6.10 READ_DIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 6.11 SYNC_DIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 6.12 CLOSE_DIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 6.13 OPEN_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 6.14 READ_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 6.15 WRITE_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 6.16 GET_FILE_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 6.17 SEEK_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 6.18 CLOSE_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 6.19 REWIND_DIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 6.20 OPEN_NEW_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 7 CFS Volume Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 7.1 Binaries Available in PikeOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 7.2 Volume Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 7.3 CFS Error Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 7.4 CFS Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 7.5 CFS Volume Provider Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 7.5.1 Compliance to ARINC653 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 7.6 Copyright and Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 8 FAT Volume Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 8.1 Binaries Available in PikeOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 8.2 Volume Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 8.3 FAT Volume Provider Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 8.4 Copyright and Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 9 YAFFS Volume Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 9.1 Binaries Available in PikeOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 9.2 Volume Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 9.3 YAFFS Volume Provider Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 9.4 Copyright and Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 10 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
1 Overview
The volume provider handles and manages the access to volumes. Thereby, its services are implemented via the file provider API and the libvp represents the functional part which is independent of any specific file system type or provider. Via this implementation strategy, the libvp API can be interfaced to various type specific code of different files system providers. This document contains the required information for the libvp to integrate as well as configure existing volume providers, and a reference for the file provider API to develop new volume providers and block drivers. See Figure 1 for an overview.
Client Partition Volume Provider Partition
Client Process Volume Provider Process
File System (e.g Block External
CFS, YAFFS, Driver Block driver
FAT)
Process entry
FS wrapper
apex/posix libvp (process entry)
HW
libvm libvm
PSSW
Figure 1: Volume Provider and libvp
1.1 Configuration
The following subsections describe the details of the configuration.
1.1.1 Properties
Configuration is performed via properties:
[...] c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Configuration 7
<prop_dir name="VolumeList">
[...]
</prop_dir>
<prop_uint32 name="LockDiscipline"/>
<prop_uint32 name="LogLevel"/>
</prop_dir>
LockDiscipline defines discipline for queuing of waiters on internal locks. Using volume providers can cause priority inversion on a module global base if a requests of a low priority thread is served on a resource which can’t be shared (e.g. a volume, a block device or the global malloc pool) while a high priority thread is gaining access as well. This configuration item is used to configure how volume provider internal locks (mainly intended for mutexes) queue waiters. The default configuration is FIFO in order to ensure a more deterministic behavior in case time partitioning is used and threads of different time partitions are accessing the same resources. Priority based queuing might be used to mitigate priority inversion situations in case accesses are not queued from different time partitions. Please also refer to section 3 for more information about concurrent access to volume providers. LogLevel defines the logging verbosity level of the volume provider. The following levels are available:
• 0 - No Logging
• 1 - Fatal Errors only
• 2 - Errors and Warnings (default)
• 3 - Errors and Verbose Information
• 4 - Errors and Verbose Information
• 5 - Error, Information and Debugging
PartList contains the configuration per partition:
• Maximum number of open files (for each volume)
• Maximum number of open directories (for each volume)
• Priority of the Partition worker (for each volume)
VolumeList contains the configuration per volume:
<prop_dir name="vol1"> <prop_string data="shm:DISK" name="Device"/> <prop_uint32 data="10" name="VolumeWorkerPrio"/> <prop_uint32 data="1024" name="MaxAtomicSize"/> <prop_string data="CFS" name="FsName"/> <prop_dir name="FsSpecific"> [...FS specific config data...] </prop_dir> </prop_dir>
Device: Path to the device (including partition) where file system is stored. The device is represented by a string. How and if this string is actually parsed depends on the file system implementation and the block driver which is used. In some cases the device string may even be left empty (in simple cases, where e.g. only one device is
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
8 Overview
available in the system). It is even possible that special file systems need more complex properties in order to choose the device. In that case the device string may be empty and special "FsSpecific" properties point to the used device. In any case the device property must be existent, because it is read by the volume provider library (libvp) and passed to the file system during initialization of the volume. VolumeWorkerPrio: PikeOS priority of the volume worker thread. Mount and unmount requests are served at this priority in the time partition of the client. MaxAtomicSize: Maximum atomic transaction size in bytes FsName: Type of the file system, e.g. CFS or YAFFS FsSpecific: Sub tree with file system specific configuration elements
1.1.2 VMIT
Inside the VMIT the list of volume providers is configured as follows:
<MemoryRequirement [...] Name="POOL_${volume_provider_name}" PhysicalAddress="-1" Size="0x00400000">
MemoryRequirement configures a memory pool which is large enough for all configured volumes (for malloc). This memory pool must exist and must have a non zero size even if the file system implementation does not make use of the malloc service. Generic volume provider data structures (like file or volume descriptors) are allocated from that pool during initialization of the volume provider.
1.2 Configuration Using Component Files
With an increasing number of volumes and clients in the system the manual configuration of properties gets complex and error prone. The complex property tree needed for the configuration of a volume provider has been split into a set of component files available in the PikeOS pool. These component files can be added to any integration project. The files are located in the PikeOS pool in and under the root folder volume-provider/.
1.2.1 Volume Provider Configuration Component
The volume provider configuration component contains the definition of the volume provider process entry. This includes e.g. the definition of memory pools used by the volume provider process and file access rights required by the volume provider to e.g. access the property file system or to declare the volumes. The PikeOS installation can include several different volume providers (e.g. one for each file system type). Thus a minimal configuration example is usually given as a DOM file (configuration domain file, contains definitions of groups and boards to be used inside PikeOS integration and fusion projects), including the configuration of the process as well as a sample volume configuration. See Figure 2 for an overview.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Available Demo Projects 9
Client Partition VP Partition
Legend:
belongs to
volume
depends on
volume-
partition-
Client Process access VP Process
Figure 2: Volume Provider Configuration Components
1.2.2 Volume Component
The volume component defines a concrete volume served by a certain volume provider. It provides all property file system entries needed to e.g. configure the maximum number of open files or file system specific configuration entries. This component is added to the volume provider partition and has a dependency on a volume provider component, see Figure 3.
1.2.3 Volume Partition Access Component
The volume partition access component is used to define properties for the access of a certain client partition to a certain volume of a volume provider. It defines the priority of the partition worker thread for the given volume, configures the maximum number of open files/directories and grants the file access to the client partition. This component is added to the client partition and has a dependency on a volume component, see Figure 4.
1.3 Available Demo Projects
Projects demonstrating access to a ramdisk are available in:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
10 Overview
Figure 3: Volume Component
• PikeOS native: PIKEOS_PREFIX/demo/integration/volume-provider-pikeos-native/
POSIX:PIKEOS_PREFIX/demo/integration/volume-provider-posix
APEX: PIKEOS_PREFIX/demo/integration/volume-provider-multi-apex
• PikeOS native: PIKEOS_PREFIX/demo/pikeos-native/volume-provider-client/
POSIX: PIKEOS_PREFIX/demo/posix/volume-provider-client
APEX: PIKEOS_PREFIX/demo/apex/volume-provider-client
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Available Demo Projects 11
Figure 4: Volume Partition Access Component
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
2 Licensing
Linking a volume provider process binary in a volume provider fusion projects introduces possible infections of volume provider code with third party licenses like GPL. As an example YAFFS is available under GPLv2 or a commercial license. If no commercial license for YAFFS is purchased a separate YAFFS volume provider can be used in order to e.g. not infect CFS by fusing both file systems together. For more information on the license of the available file systems please refer to the Copyright and Licensing sections of the concrete file systems later in this document (section 7.6 (CFS), section 9.4 (YAFFS), section 8.4 (FAT)).
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
3 Concurrent Access to Volume Providers
Concurrent access from different clients to volume providers is limited. In general volume providers start the following worker threads in the initialization phase:
• A volume worker for each volume
• A resource partition worker for each client partition per accessed volume.
Volume Worker threads are running in the time partition configured for the volume provider partition. The affinity mask of those worker threads is set to the CPU mask of the volume provider partition. Thus, they are started on the first CPU which is enabled in this mask (least significant bit set) and may be migrated to the the current CPU of the partition daemon during IPC. Volume workers handle all mount and unmount requests which are routed from the client partition through the PSSW to the volume provider. Partition Workers are started in the time partition of the client partition, if the ability VM_AB_TIMEPART_CHANGE is given in the volume provider partion’s set of abilities, or otherwise in the time partition configured for the volume provider partition. The priority for these workers is given in the configuration. The affinity mask of those worker threads is set to the CPU mask of the volume provider partition. Thus, they are started on the first CPU which is enabled in this mask (least significant bit set) and may be migrated to the the current CPU of the client during IPC. After successfully mounting a volume all further requests are served by the resource partition workers. In case the ability VM_AB_TIMEPART_CHANGE is granted for the volume provider partition and time partitioning is used in the system, the CPU mask of the volume provider should at least include one CPU of all client partitions. This is due to the fact, that certain time partitions may not be scheduled on all CPUs in the system. All worker threads execute an infinite IPC loop. Thus concurrent accesses to volumes (mount, unmount) by different client partitions are serialized which means that clients may get blocked until requests of other clients are fully processed. The same constraint applies to clients which are accessing on of their corresponding resource partition worker in parallel (by multiple accesses to the same volume). Further constraints may come from the design of the specific file systems. Depending on the granularity of the locking of file system internal data structures different resource partition workers may interfere each other while e.g. waiting for a mutex. Especially if time partitioning is used clients may be locked out for a longer amount of time due to other partitions holding locks beyond the end of their time partition slices. Therefore a system in which concurrent access to volume providers occurs has to be carefully designed with these constraints in mind. If volumes are accessed from different resource partitions in different time partitions, the use of the VM_AB_TIMEPART_CHANGE abilitiy for the volume provider partition is generally discouraged.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
4 Developing a Volume Provider
This section gives an introduction on how to develop a new libvp based volume provider and how to reuse existing volume provider parts from the PikeOS installation.
4.1 Developing a File System
In this section it is explained how a new file system is developed based on the API documentation later in this document. A starting point is given by the demo: PIKEOS_PREFIX/demo/volume-provider/dummy-file- system/ It demonstrates the mandatory hooks which a file system has to provide to the libvp in order to provide volumes. The resulting binary file is installed into a specified location and can be used later in a volume provider fusion project where it could be fused together with e.g. a block driver or other file systems if agreeable with license considerations. The API which is used for file system development is described beginning with section 5.2.
4.2 Developing an Internal Block Driver
A starting point for developing an internal block driver object (directly linked in a volume provider process binary) is given by the following demo: PIKEOS_PREFIX/demo/volume-provider/simple-blk-driver/ Like file system objects a block driver object is compiled and installed into a specified location for later fusion. For the internal block driver API reference see section 5.4. It is described in section 5.5 how PikeOS product file systems like CFS interact with such a block driver.
4.3 Volume Provider Fusion
A volume provider process binary is created in a volume provider fusion project. It can be derived from the empty volume provider fusion project. There are three volume provider binaries of the same volume provider created. Custom fusible volume provider parts are typically installed into the CUSTOM_POOL while parts shipped with the PikeOS images are found in the PIKEOS_POOL. Both parts can be combined in a fusion project. A fusion project typically provides a volume provider process binary which is suitable to be used with a volume provider process component file in an integration project. Volume providers shipped with PikeOS usually provide a DOM file which includes the process and a resource partition with sufficient privileges and a sample volume configuration.
4.3.1 Pool Structure
This section describes the directory layout and file naming conventions used when installing a file system or block driver object into a pool. It is the layout used by the PikeOS pool and also the default layout used by the driver build environment when installing into a custom pool. When installing into a custom pool, the build interface al- lows the driver Makefile to specify a custom directory layout.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Volume Provider Fusion 15
Example pool layout: / | |— fusion-volume-provider/ | |— object/ | | | |— blk | | |— disksim.obj | | |— extblk-proxy.obj | | |— extmtd-proxy.obj | | | |— fs | | |— cfs.vp | | |— fat.vp | | |— yaffs.vp | |— extra-fs.cmp |— volume-provider.cmp
• object/. In this folder (or sub folders) the object files needed for the fusion of the process binary are
installed. Sub folders like blk and fs indicate where to find file system or block driver objects.
• volume-provider.cmp. This is the standard component file used in volume provider fusion projects. It has
parameters to point to a single file system object from a pool or the host file systems and also to a single
block driver object. It is usually located in the PikeOS pool.
• extra-fs.cmp. This component file can be used to add more file system objects to the fusion. It is usually
located in the PikeOS pool.
Please refer to section 4.3.2 for information about the difference of the .vp and .obj file name extensions of volume provider object files. Final volume-provider process binaries (ready to be used in integration projects) usually hold the .elf file name extension and are usually found in the "volume-provider/object" folder in the pool.
4.3.2 Exporting Symbols in Volume Provider Objects
By default, all functions defined in a volume provider object (with the .vp file extension) are localized when a file system driver is linked into a driver ELF object. I.e., even with ’extern’ declarations in C, the final driver ELF object will not export any symbols. To export symbols from an object, a special file with all exported symbols needs to be maintained: symbol-global.txt. This file is a text file that contains a newline separated list of symbols that will be exported from the final VP ELF object. Comments are allowed by introducing them with #. The file needs to be in the same directory as the makefile.defs file. Example symbol-global.txt file:
export function to read/write from other VP objects
xyz_read xyz_write
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
16 Developing a Volume Provider
However block driver objects (serving the vmio_blk* functions) are usually linked as object files with the .obj extension and without localization of exported symbols. Thus explicit globalization is not needed if the volume provider ELF object is created with the .obj file extension. Therefore adding two block driver objects in a volume provider fusion always leads to duplicated symbols linker error.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
5 FS Library API Reference
This section presents the data types and functions available in the FS Library API.
5.1 Header File
Header files to include: #include <vp/vmio_blk.h> #include <vp/vp_fslib.h> #include <vp/vp_fslib_svc.h>
5.2 FSlib API
This section presents the data types and functions available in the FS Library API used for accessing the file system.
5.2.1 Structure Definitions
5.2.1.1 struct vp_fs_file_desc_str
Defines volume specific File Descriptor container type. Allocated from file descriptor pool on each file open operation. Size of this container is FS specific and depends on its configuration.
Synopsis: struct vp_fs_file_desc_str { char * dummy; };
Structure Element Description: dummy
Associated Data Type
vp_fs_file_desc_t Defines volume specific File Descriptor container type.
5.2.1.2 struct vp_fs_dir_str
Defines volume specific Directory Descriptor container type. Allocated from directory descriptor pool on each directory open operation. Size of this container is FS specific and depends on its configuration.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
18 FS Library API Reference
Synopsis: struct vp_fs_dir_str { char * dummy; };
Structure Element Description: dummy
Associated Data Type
vp_fs_dir_t Defines volume specific Directory Descriptor container type.
5.2.1.3 struct vp_fs_mount_context_str
Mount specific context (open descriptors) Mount specific context allows iteration through its open file and directory descriptors. It is used from umount handler.
Synopsis: struct vp_fs_mount_context_str { char * dummy; };
Structure Element Description: dummy
Associated Data Type
vp_fs_mount_context_t Mount specific context (open descriptors)
5.2.1.4 struct fs_desc_str
Structure describing file system volume handling for the Volume Provider
Synopsis: struct fs_desc_str { void * handle; P4_uint32_t file_desc_size; P4_uint32_t dir_desc_size; vp_fs_init_t * init; vp_fs_open_t * open; vp_fs_unlink_t * unlink; vp_fs_rename_t * rename; vp_fs_statvfs_t * statvfs; vp_fs_read_at_t * read_at; vp_fs_write_at_t * write_at; vp_fs_lseek_t * lseek;
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib API 19
vp_fs_fstat_t * fstat;
vp_fs_close_t * close;
vp_fs_map_t * map;
vp_fs_ioctl_t * ioctl;
vp_fs_fsync_t * fsync;
vp_fs_ftruncate_t * ftruncate;
vp_fs_dir_create_t * dir_create;
vp_fs_dir_open_t * dir_open;
vp_fs_dir_read_at_t * dir_read_at;
vp_fs_dir_sync_t * dir_sync;
vp_fs_dir_close_t * dir_close;
vp_fs_mount_t * mount;
vp_fs_umount_t * umount;
};
Structure Element Description: handle Handle to the volume. This handle is provided in the handle parameter to the library calls. file_desc_size Size of file descriptor in bytes. dir_desc_size Size of directory descriptor in bytes. init Initialization method (optional), if defined it will be called from volume worker thread upon its start. open Open method, will be called when vm_open() was called from client application. unlink Unlink method, will be called when vm_unlink() was called from client application. rename Rename method, will be called when vm_rename() was called from client application. statvfs File system status method, will be called when vm_statvfs() was called from client application. read_at Read at given position method, will be called when vm_read_at() was called from client application. write_at Write at position method, will be called when vm_write_at() was called from client application. lseek lseek() (see section 5.2.4) method, will be called when vm_lseek() was called from client application. This callback is optional. If not set by the FS a default implementation is used. fstat Get file status method, will be called when vm_fstat() was called from client application. close Close method, will be called when vm_close() was called from client application. map File map method, will be called when vm_map() was called from client application. ioctl I/O control method, will be called when vm_ioctl() was called from client application. fsync Synchronize file data method, will be called when vm_fsync() was called from client application. ftruncate Truncate method, will be called when vm_ftruncate() was called from client application. dir_create Create directory method, will be called when vm_dir_create() was called from client application. dir_open Open directory method, will be called when vm_dir_open() was called from client application. dir_read_at Read directory method, will be called when vm_dir_read_at() was called from client application. dir_sync Sync directory method, will be called when vm_dir_sync() was called from client application. dir_close Close directory method, will be called when vm_dir_close() was called from client application. mount Volume mount method, will be called when vm_mount() was called from client application. umount Volume unmount method, will be called when vm_umount() was called from client application.
Associated Data Type
fs_desc_t
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
20 FS Library API Reference
5.2.1.5 struct fs_register_volume_params_str
Structure describing configured parameters for the volume
Synopsis:
struct fs_register_volume_params_str { P4_uint32_t max_open_files; P4_uint32_t max_open_dirs; P4_size_t max_atomic_size; char * fstype; char * device; char * config_path; };
Structure Element Description: max_open_files Maximum number of open files max_open_dirs Maximum number of open directories max_atomic_size Maximum atomic size fstype File System name device Device identifier config_path Path to File System configuration (file system specific arguments)
Associated Data Type
fs_register_volume_params_t
5.2.1.6 struct vp_fs_desc_t
Structure defining a File System descriptor. During initialization the libvp calls the file system specific volume registration function for each configured volume.
Synopsis:
struct vp_fs_desc_t { const char * name; fs_init_t * init; fs_register_volume_t * register_volume; };
Structure Element Description: name File System Name (e.g. CFS). init File System init function. register_volume File System volume registration function.
5.2.2 Data Type Definitions
vp_fs_file_desc_t Defines volume specific File Descriptor container type.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib API 21
Allocated from file descriptor pool on each file open operation. Size of this container is FS specific and
depends on its configuration.
vp_fs_dir_t Defines volume specific Directory Descriptor container type. Allocated from directory descriptor pool on each directory open operation. Size of this container is FS specific and depends on its configuration. vp_fs_mount_context_t Mount specific context (open descriptors) Mount specific context allows iteration through its open file and directory descriptors. It is used from umount handler. fs_desc_t Structure describing file system volume handling for the Volume Provider fs_register_volume_params_t Structure describing configured parameters for the volume
5.2.3 Function Type Definitions
5.2.3.1 vp_fs_init_t
File System initialization method.
Synopsis:
typedef P4_e_t vp_fs_init_t(void *handle)
Description: This function is called upon the start of the volume worker thread. If the function returns an error, the Volume Provider raises health monitoring exception and then deletes volume worker thread.
Parameters: handle [IN] File System Specific volume handle.
Returns: P4_E_OK upon success P4_E_CONFIG if the file system is not configured correctly. P4_E_IO if there was an error upon access to file system.
5.2.3.2 vp_fs_open_t
File System library open method.
Synopsis:
typedef P4_e_t vp_fs_open_t(void *handle, const char *name, P4_uint32_t oflags, vp_fs_file_desc_t fd)
Description:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
22 FS Library API Reference
The vm_open() call is used to convert a pathname into a file descriptor. Upon success the function initializes a file handle which is used during subsequent calls to file services to identify the file name. The file position is set to the beginning of the file.
Parameters: handle [IN] File System Specific volume handle. name [IN] File or pathname to open. oflags [IN] The parameter oflags is a logical combination of one or more of the following constants:
• 0 for opening file name for obtaining statistics using vm_fstat() (this flag is included in all other
constants for convenience),
• VM_O_RD for opening file name for reading,
• VM_O_WR for opening file name for writing,
• VM_O_RD_WR for opening file name for reading and writing,
• VM_O_EXEC for opening file name to be executed,
• VM_O_RD_WR_EXEC for opening file name for reading, writing and executing,
• VM_O_MAP for opening file name for mapping it into memory.
• VM_O_CREAT create the file if it doesn’t exist.
• if VM_O_EXCL is used together with VM_O_CREAT the call fails if the file already exists
fd [IN] File descriptor in fd to be initialized by open. The size of the structure is defined in the file system
descriptor by file_desc_size. In case of error, the content of fd might be undefined.
Returns: P4_E_OK upon success P4_E_NOENT if a file with the name name does not exist. P4_E_PERM if the caller does not have oflags access rights to file name. if VM_O_RD_WR is given in oflags and the file is already opened for writing (ARINC). P4_E_INVAL if name is not a valid filename. P4_E_NOCONTAINER if a component of the path prefix of name is not a directory. P4_E_MISMATCH if name is an existing directory (ARINC). P4_E_LIMIT if there is not enough space available on volume. P4_E_EXIST if VM_O_CREAT and VM_O_NEW was used and name is an existing file. P4_E_IO if the storage device containing the file reports a failure. P4_E_RESTRICTED The volume is currently write protected and write access is requested.
5.2.3.3 vp_fs_unlink_t
File System library unlink method.
Synopsis:
typedef P4_e_t vp_fs_unlink_t(void *handle, const char *path, P4_unlink_flags_t flags)
Description:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib API 23
Delete the name from the file system. If the name was the last link to a file and the file is not open the file is deleted and the space the file was using is made available. If the name referred to a symbolic link the link is removed. If P4_UNLINK_DIR_ONLY is set in flags, the path must refer to a directory and an error is return otherwise. This corresponds to the POSIX rmdir() function. If P4_UNLINK_NO_DIR is set in flags the path must not refer to a directory. If none of the flags is set it is file system implementation dependent whether the operation succeeds or not if the path refers to a directory.
Parameters: handle [IN] File System Specific volume handle. path [IN] Path to the file which will be deleted. flags [IN] flags for the unlink operation.
Returns: P4_E_OK upon success P4_E_NOENT if file name does not exist. P4_E_PERM if access to the file is denied, or search permission is denied for one of the directories in the path prefix in name. P4_E_INVAL if name is not a valid filename P4_E_MISMATCH if path is not a directory and P4_UNLINK_DIR_ONLY is set in flags. P4_E_MISMATCH if path is a directory and P4_UNLINK_NO_DIR is set in flags. P4_E_MISMATCH if path is a directory and file system implementation requires P4_UNLINK_DIR_ONLY set in flags to unlink the directory and it is not set. P4_E_STATE if path is a directory and it is not empty. P4_E_OOMEM if system resources have been exhausted, e.g. there is no free file descriptor. P4_E_NOTIMPL if refers to a directory and the file system does not support unlinking of directories. P4_E_IO if the storage device containing path reports failure. P4_E_NOCONTAINER if a component of the path prefix of name is not a volume or directory. P4_E_RESTRICTED if the volume is currently write protected. P4_E_BUSY if the directory is opened for writing by the owning partition (ARINC).
5.2.3.4 vp_fs_rename_t
File System library rename method.
Synopsis:
typedef P4_e_t vp_fs_rename_t(void *handle, const char *old_path, const char *new_path, P4_rename_flags_t flags)
Description: Rename a file, move it between directories if required. Other hard links to the file are unaffected. Open file descriptors are unaffected as well.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
24 FS Library API Reference
The semantics of this call depends on the flags parameter. If P4_RENAME_FILE is set in flags the function renames a file according to the ARINC 653 RENAME_FILE() service. The flag P4_RENAME_DIR is used to rename a directory according to RENAME_DIRECTORY(). Both flags cannot be used together. If none of them is specified the function renames a file or directory according to the POSIX rename() service.
Parameters: handle [IN] File System Specific volume handle. old_path [IN] The file that will be renamed. new_path [IN] The path the file be will be renamed to. flags [IN] flags for the rename operation.
Returns: P4_E_OK upon success P4_E_NOENT if old_path does not exist. P4_E_PERM Permission is denied for one of the directories in the path prefix in old_path or new_path. P4_E_LIMIT There is not enough space on the device to store the new directory entry. P4_E_MISMATCH if new_path is an existing directory but old_path is not a directory and P4_RE- NAME_NO_DIR is not set in flags. P4_E_MISMATCH if old_path is an existing directory and P4_RENAME_NO_DIR is set in flags. P4_E_MISMATCH if old_path is an existing file and P4_RENAME_DIR_ONLY is set in flags. P4_E_NOCONTAINER old_path is a directory but new_path is not a directory, or if a component of the path prefix of old_path or new_path is not a volume or directory. P4_E_INVAL if new_path is a subdirectory of old_path P4_E_OOMEM if system resources have been exhausted, e.g. there is no free file descriptor. P4_E_NOTIMPL if old_path specifies the root directory of the volume and the file system implementation does not permit renaming of the root directory. P4_E_STATE if new_path is an existing directory and it is not empty. P4_E_STATE if new_path is an existing directory and P4_RENAME_NO_DIR is set in flags. P4_E_IO if the storage device containing old_path and new_path reports failure. P4_E_RESTRICTED if the volume is currently write protected.
5.2.3.5 vp_fs_statvfs_t
File System library statvfs method.
Synopsis:
typedef P4_e_t vp_fs_statvfs_t(void *handle, const char *path, P4_statvfs_t *buf)
Description: The function retrieves information about the files system. During the execution of this call one file descriptor is allocated, and freed before the call returns.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib API 25
Parameters: handle [IN] File System Specific volume handle. path [IN] The path name of any file within the file system. buf [OUT] The pointer to the structure containing the retrieved file system statistics.
Returns: P4_E_OK upon success P4_E_NOENT if file name does not exist. P4_E_PERM Permission is denied for one of the directories in the path prefix in old_path or new_path. P4_E_INVAL if name is not a valid filename P4_E_OOMEM if system resources have been exhausted, e.g. there is no free file descriptor. P4_E_IO if the storage device containing path reports failure. P4_E_NOCONTAINER a component of the path prefix of name is not a volume or directory.
5.2.3.6 vp_fs_read_at_t
File System library read at position method.
Synopsis:
typedef P4_e_t vp_fs_read_at_t(void *handle, vp_fs_file_desc_t fd, void *buf, P4_size_t buf_size, P4_off_t offset, P4_size_t *read_size)
Description: The vm_read_at() attempts to read up to buf_size bytes from file offset offset. The function does not alter the logical file position.
Parameters: handle [IN] File System Specific volume handle. fd [IN] File descriptor for reading. buf [IN] Pointer to the receive buffer. It must have at least a size of buf_size bytes. buf_size [IN] Number of bytes to read. offset [IN] Offset from which to read. read_size [OUT] The number of bytes actually read is stored in
Returns: P4_E_OK upon success P4_E_INVAL if fd is not a valid file descriptor. P4_E_PERM if the file fd was not opened for reading. P4_E_OOMEM if system resources have been exhausted. P4_E_IO if the storage device containing the file reports a failure.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
26 FS Library API Reference
P4_E_STATE if the file handle is invalid due to unlinking or renaming.
P4_E_OVERFLOW arithmetic overflow of the seek position, which means that the position is outside of what
the file system can handle.
5.2.3.7 vp_fs_write_at_t
File System library write at position method.
Synopsis:
typedef P4_e_t vp_fs_write_at_t(void *handle, vp_fs_file_desc_t fd, const void *buf, P4_size_t buf_size, P4_off_t offset, P4_size_t *written_size)
Description: The vm_write_at() attempts to write up to buf_size bytes from file offset offset. The function does not alter the logical file position.
Parameters: handle [IN] File System Specific volume handle. fd [IN] File descriptor for writing. buf [IN] Pointer to the transmit buffer. buf_size [IN] Number of bytes to read. offset [IN] Offset at which to write. written_size [OUT] The number of bytes actually written is stored in written_size.
Returns: P4_E_OK upon success P4_E_INVAL if fd is not a valid file descriptor, or if an invalid buf_size == 0 was given. P4_E_PERM if the caller does not have the permission to access file fd, or fd is attached to an object which is unsuitable for writing. P4_E_IO if the storage device containing the file reports a failure. P4_E_LIMIT if no space left on volume to write the data. P4_E_STATE if the file handle is invalid due to unlinking or renaming. P4_E_OVERFLOW arithmetic overflow of the seek position, which means that the position is outside of what the file system can handle.
5.2.3.8 vp_fs_lseek_t
File System library lseek method (optional).
Synopsis:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib API 27
typedef P4_e_t vp_fs_lseek_t(void *handle, vp_fs_file_desc_t fd, P4_off_t offset, P4_origin_t origin, P4_off_t *pos)
Description: The lseek() method repositions the offset of the a file descriptor to the argument offset according to the parameter origin as follows: • P4_SEEK_SET Set the new file position to offset units from the beginning of the file, starting at 0. • P4_SEEK_CUR Set the new file position to old file position plus offset units. • P4_SEEK_END Set the new file position to file size plus offset units.
A reference to the current and new file position is passed to the entry point via the argument *pos. This entry point is optional to be implemented by the file sytem. If it is not implemented, a default lseek() implementation is used by the libvp. This default implementation does e.g. not check whether the new file offset would lie beyond the file size. As ARINC 653 requires such a check a conform file system may provide an own lseek method to enforce that restriction. If this condition is detected, an ARINC 653 compliant FS should return P4_E_TRUNC, but update the position pointer (to the position behind the file size) at the same time. This is needed by implementation of SEEK_FILE that does a vm_lseek() call to retrieve the current file position.
Parameters: handle [IN] File System Specific volume handle. fd [IN] File descriptor for seeking. offset [IN] Offset for the seek operation. origin [IN] Origin for the seek operation. pos [IN/OUT] Position pointer. Updated by the FS.
Returns: P4_E_OK upon success P4_E_INVAL if fd is not a valid file descriptor, or if another parameter is invalid (e.g. if the new position would be beyond the file size and the file system does not support it) P4_E_IO if the storage device containing the file reports a failure. P4_E_STATE if the file handle is invalid due to unlinking or renaming. P4_E_TRUNC if the file system implements ARINC 653 behavior and the new file position is behind the file size. The position pos is to be updated by the FS in that case. P4_E_OVERFLOW arithmetic overflow of the seek position, which means that the position is outside of what the file system can handle.
5.2.3.9 vp_fs_fstat_t
File System library file status method.
Synopsis:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
28 FS Library API Reference
typedef P4_e_t vp_fs_fstat_t(void *handle, vp_fs_file_desc_t fd, vm_file_stat_t *status)
Description: Provide several information about the current status of file given by fd. See the description of vm_file_stat_t for the list of properties available.
Parameters: handle [IN] File System Specific volume handle. fd [IN] File descriptor status [OUT] Upon success, the structure elements at status are filled in. In case of error, the content is undefined.
Returns: P4_E_OK upon success P4_E_INVAL if fd is not a valid file descriptor. P4_E_IO if the storage device containing the file reports a failure. P4_E_STATE if the file handle is invalid due to unlinking or renaming
5.2.3.10 vp_fs_close_t
File System library file close method.
Synopsis:
typedef P4_e_t vp_fs_close_t(void *handle, vp_fs_file_desc_t fd)
Description: This function closes an open file descriptor fd, so that it no longer refers to any file and may be reused.
Parameters: handle [IN] File System Specific volume handle. fd [IN] File descriptor
Returns: P4_E_OK upon success P4_E_INVAL if fd is not a valid file descriptor. P4_E_IO if the underlying file system reports an I/O error when trying to complete outstanding file operations.
Note: The file is not closed when P4_E_BUSY is returned.
5.2.3.11 vp_fs_map_t
File System library file map method.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib API 29
Synopsis:
typedef P4_e_t vp_fs_map_t(void *handle, vp_fs_file_desc_t fd, P4_off_t offset, P4_size_t size, vm_memory_access_mode_t prot, P4_uint32_t flags, P4_address_t *map_base, P4_size_t *map_size, vm_memory_access_mode_t *map_access, vm_memory_cache_mode_t *map_cache)
Description: The function tries to map size bytes starting at offset offset from file given by fd into the caller’s address space at start. The currently available file providers support mapping of files in ROM file systems and in shared memory. The target virtual address start, the offset into the file as well as the map size must be a multiple of P4_PAGESIZE.
Parameters: handle [IN] File System Specific volume handle. fd [IN] File descriptor. offset [IN] Offset in bytes from beginning in file where to start mapping. size [IN] Length to map, given in bytes. prot [IN] Page protection attributes, or access permissions: The parameter prot is one of:
• VM_MEM_ACCESS_RD for mapping the file for reading
• VM_MEM_ACCESS_WR for mapping the file for writing
• VM_MEM_ACCESS_RD_WR for mapping the file for reading and writing
• VM_MEM_ACCESS_RD_EXEC for mapping the file for reading and execution
• VM_MEM_ACCESS_RD_WR_EXEC for mapping the file for reading, writing and execution. The
interpretation of this parameter depends on the underlying file provider. A file mapped write-only
may still be read without causing an exception.
flags [IN] A combination of flags specified by the caller to be interpreted by the file provider. map_base [OUT] Virtual address in the file provider’s task to map from. To be set by the file provider entry point. map_size [OUT] Size of the mapping transferred to the client. To be set by the file provider entry point. map_access [OUT] Access mode to qualify the returned mapping for. map_cache [OUT] Cache mode to qualify the returned mapping for.
Warning: If the map entry point implementation returns invalid values in map_access or map_cache or inappropraite values in map_base or map_size, the map operation may fail. Whilst the requesting client is returned an error, the file provider has no direct means to detect this failure.
Returns: P4_E_OK upon success P4_E_INVAL if fd is not a valid file descriptor, or the file is not suited for memory mapping, or at least one of the parameters offset, size, start or prot is invalid.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
30 FS Library API Reference
P4_E_PERM if the partition does not have prot access rights to file fd.
P4_E_OOMEM if the file could not be mapped completely.
P4_E_NOTIMPL if the responsible provider does not support this operation.
5.2.3.12 vp_fs_ioctl_t
File System library I/O control method.
Synopsis:
typedef P4_e_t vp_fs_ioctl_t(void *handle, vp_fs_file_desc_t fd, vm_file_ioctl_t iocmd, P4_address_t data_in, P4_address_t data_out)
Description: This function offers a general purpose interface to file providers. Each provider is free to support vm_ioctl() and can define its own commands, offered through the appropriate header file. The cmd has encoded whether data is copied to the provider, returned from the provider or if no data is transferred at all.
Parameters: handle [IN] File System Specific volume handle. fd [IN] File descriptor of an open file iocmd [IN] The I/O control command identifier specified by the client. data_in [IN] The I/O control command buffer sent by the client. data_out [IN] The I/O control response buffer to be filled by the file provider.
Returns: P4_E_OK upon success P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_PERM if the file was opened without read or write permissions. P4_E_INVAL if fd does not belong to an open file. P4_E_IO if the storage device containing the file reports a failure.
5.2.3.13 vp_fs_fsync_t
File System library synchronize file data method.
Synopsis:
typedef P4_e_t vp_fs_fsync_t(void *handle, vp_fs_file_desc_t fd)
Description:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib API 31
The function writes to storage device all modified data and meta data of the file. The call blocks until the device reports that the transfer was completed.
Parameters: handle [IN] File System Specific volume handle. fd [IN] File descriptor.
Returns: P4_E_OK upon success P4_E_PERM Permission is denied for one of the directories in the path prefix in old_path or new_path. P4_E_INVAL if fd is not a valid file descriptor P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_IO if the storage device containing the file reports failure.
5.2.3.14 vp_fs_ftruncate_t
File System library file truncate method.
Synopsis:
typedef P4_e_t vp_fs_ftruncate_t(void *handle, vp_fs_file_desc_t fd, P4_off_t length)
Description: Changing the size of the regular file represented by the fd file descriptor to the size of new_size in bytes.
Parameters: handle [IN] File System Specific volume handle. fd [IN] File descriptor. new_size [IN] The size in bytes the file will be set to . flags [IN] flags for the truncate operation.
Returns: P4_E_OK upon success P4_E_INVAL if fd is not a valid file descriptor P4_E_OOMEM if system resources have been exhausted, e.g. there is no free file descriptor. P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_LIMIT There is not enough space on the device to extend the file. P4_E_PERM File not open for writing. P4_E_IO if the storage device containing the file reports failure.
5.2.3.15 vp_fs_dir_create_t
File System library create directory method.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
32 FS Library API Reference
Synopsis:
typedef P4_e_t vp_fs_dir_create_t(void *handle, const char *path)
Description: The call is used to create new directory. The directory will be empty.
Parameters: handle [IN] File System Specific volume handle. path [IN] Path name to the directory that will be created.
Returns: P4_E_OK upon success P4_E_PERM The parent directory does not allow write permission to the caller, or one of the directories in path did not allow search permission. P4_E_LIMIT There is not enough space on the device to store the new file. P4_E_INVAL if path is not a valid filename. P4_E_IO if the storage device containing path reports failure. P4_E_NOCONTAINER a component of the path prefix of name is not a volume or directory. P4_E_EXIST if path already exists (not necessarily a directory) (POSIX). if path is an existing file (ARINC). P4_E_MISMATCH if path is an existing directory (ARINC). P4_E_RESTRICTED the volume is currently write protected.
5.2.3.16 vp_fs_dir_open_t
File System library open directory method.
Synopsis:
typedef P4_e_t vp_fs_dir_open_t(void *handle, const char *path, vp_fs_dir_t dir)
Description: The call opens a directory stream corresponding to the directory path. The file position is set to the beginning of the file.
Parameters: handle [IN] File System Specific volume handle. path [IN] Path of the directory being opened. dir [IN] File descriptor in dir to be initialized by open. The size of the structure is defined in the file system descriptor by dir_desc_size. In case of error, the content of dir might be undefined.
Returns: P4_E_OK upon success
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib API 33
P4_E_NOENT if a file with the name name does not exist. P4_E_PERM if the caller does not have oflags access rights to file name. P4_E_INVAL if name is not a valid filename. P4_E_NOCONTAINER path is not a directory or a component of the path prefix of name is not a volume or directory. P4_E_IO if the storage device containing path reports failure.
5.2.3.17 vp_fs_dir_read_at_t
File System library read directory method.
Synopsis:
typedef P4_e_t vp_fs_dir_read_at_t(void *handle, vp_fs_dir_t dir, P4_dirent_t *dire, P4_off_t *pos)
Description: The call reads a directory entry structure from the directory file at the given location. If the end of the directory was reached the d_name item of the dire parameter contains empty string.
Parameters: handle [IN] File System Specific volume handle. dir [IN] The open directory pos [IN/OUT] The directory position of the entry that will be read. After successful completion position of next directory entry will be stored in this value. In case of error, this value will not be modified. Only value retrieved by previous call of vm_dir_read_at() or zero can be provided in this parameter. dire [OUT] The buffer that will be filled with the retrieved directory entry
Returns: P4_E_OK upon success P4_E_INVAL if dir is not a valid open directory. P4_E_OOMEM if system resources have been exhausted. P4_E_STATE if the directory handle is not valid anymore because of removing or or renaming.
5.2.3.18 vp_fs_dir_sync_t
File System library sync directory method.
Synopsis:
typedef P4_e_t vp_fs_dir_sync_t(void *handle, vp_fs_dir_t dir)
Description:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
34 FS Library API Reference
The call blocks until all directory data are stored on the storage device.
Parameters: handle [IN] File System Specific volume handle. dir [IN] The open directory
Returns: P4_E_OK upon success P4_E_INVAL if dir is not a valid open directory. P4_E_OOMEM if system resources have been exhausted.
5.2.3.19 vp_fs_dir_close_t
File System library close directory method.
Synopsis:
typedef P4_e_t vp_fs_dir_close_t(void *handle, vp_fs_dir_t dir)
Description: This function closes an open directory dir.
Parameters: handle [IN] File System Specific volume handle. dir [IN] open directory
Returns: P4_E_OK upon success P4_E_INVAL if dir is not a valid open directory. P4_E_IO if the underlying file system reports an I/O error when trying to complete outstanding file operations.
5.2.3.20 vp_fs_mount_t
File System library file system mount method.
Synopsis:
typedef P4_e_t vp_fs_mount_t(void *handle, P4_uint32_t mflags)
Description: The call mounts the file system represented by given by prefix according the configuration from the property file system.
Parameters:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib API 35
handle [OUT] File System Specific volume handle. mflags [IN] mount flags.
Returns: P4_E_OK upon success P4_E_INVAL if a parameter is invalid. It may also be returned if no valid file system structure is found by the file system during mount. Reasons for that may be that the volume is not yet formatted or has been formatted using parameters differing from the parameters configured for the volume provider and passed during mount (e.g. using a different blocksize). Furthermore it may be returned in case an invalid device string is configured for the volume. P4_E_NOENT if the device does not exist. This error may be used e.g. to indicate that removable media is not present or the partition referenced by the configured device string does not exist on the storage media. P4_E_OOMEM if system resources have been exhausted. P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_IO if the storage device containing the volume represented with prefix reports failure.
5.2.3.21 vp_fs_umount_t
File System library file system unmount method.
Synopsis:
typedef P4_e_t vp_fs_umount_t(void *handle, vp_fs_mount_context_t context)
Description: The call unmounts the file system represented by prefix.
Parameters: handle [IN] File System Specific volume handle. context [IN] Mount context that allows iteration through open file and directory descriptors opened within this mount.
Returns: P4_E_OK upon success P4_E_INVAL if prefix is not a valid PikeOS FS prefix. P4_E_OOMEM if system resources have been exhausted. P4_E_NOTIMPL if the responsible provider does not support this operation.
5.2.3.22 fs_register_volume_t
Initialize FS volume.
Synopsis:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
36 FS Library API Reference
typedef P4_e_t fs_register_volume_t(const fs_register_volume_params_t *params, fs_desc_t *desc)
Description: This function is called once for each configured volume at the startup of Volume Provider. The FS library should initialize all handlers in the desc. Pointers to handlers that are not provided should be set to NULL.
Parameters: fstype [IN] File System name. Defined in the configuration of Volume Provider. device [IN] Device identifier. Defined in the configuration of Volume Provider. directory [IN] Directory to be mounted (optional). Defined in the configuration of Volume Provider. config_path [IN] Path to File System configuration. Defined in the configuration of Volume Provider. desc [OUT] File System descriptor. The call must fill all fields of this descriptor.
Returns: P4_E_OK upon success P4_E_CONFIG if invalid configuration is detected P4_E_IO if I/O error has occurred on the device
Note: This function must be provided by the FS library.
5.2.3.23 fs_init_t
Initialize File System.
Synopsis:
typedef P4_e_t fs_init_t(void)
Description: This function is called once for each File System which is present and specified an initialization fucntion.
Returns: P4_E_OK upon success P4_E_CONFIG if invalid configuration is detected
Note: This function must be provided by the FS library.
5.2.4 Variables
dummy
dummy
dummy
handle Handle to the volume. This handle is provided in the handle parameter to the library calls.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib API 37
file_desc_size Size of file descriptor in bytes. dir_desc_size Size of directory descriptor in bytes. init Initialization method (optional), if defined it will be called from volume worker thread upon its start. open Open method, will be called when vm_open() was called from client application. unlink Unlink method, will be called when vm_unlink() was called from client application. rename Rename method, will be called when vm_rename() was called from client application. statvfs File system status method, will be called when vm_statvfs() was called from client application. read_at Read at given position method, will be called when vm_read_at() was called from client application. write_at Write at position method, will be called when vm_write_at() was called from client application. lseek lseek() (see section 5.2.4) method, will be called when vm_lseek() was called from client application. This callback is optional. If not set by the FS a default implementation is used. fstat Get file status method, will be called when vm_fstat() was called from client application. close Close method, will be called when vm_close() was called from client application. map File map method, will be called when vm_map() was called from client application. ioctl I/O control method, will be called when vm_ioctl() was called from client application. fsync Synchronize file data method, will be called when vm_fsync() was called from client application. ftruncate Truncate method, will be called when vm_ftruncate() was called from client application. dir_create Create directory method, will be called when vm_dir_create() was called from client application. dir_open Open directory method, will be called when vm_dir_open() was called from client application. dir_read_at Read directory method, will be called when vm_dir_read_at() was called from client application. dir_sync Sync directory method, will be called when vm_dir_sync() was called from client application. dir_close Close directory method, will be called when vm_dir_close() was called from client application. mount Volume mount method, will be called when vm_mount() was called from client application. umount Volume unmount method, will be called when vm_umount() was called from client application. max_open_files Maximum number of open files max_open_dirs Maximum number of open directories max_atomic_size Maximum atomic size fstype File System name device Device identifier config_path Path to File System configuration (file system specific arguments) name File System Name (e.g. CFS). init File System init function. register_volume File System volume registration function.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
38 FS Library API Reference
5.3 FSlib Service API
This section presents the data types and functions available for the FS Library service API.
5.3.1 Defines
VP_LOG_TYPE_NONE
Description:
absolute silence
VP_LOG_TYPE_FATAL
Description:
log fatal errors
VP_LOG_TYPE_ERROR
Description:
log errors
VP_LOG_TYPE_MESSAGE
Description:
log common messages
VP_LOG_TYPE_INFO
Description:
log info messages
VP_LOG_TYPE_DEBUG
Description:
log debug messages
VP_LOG_TYPE_ALL
Description:
log everything
VP_LOG_FATAL (fmt, args...)
Print FATAL type message on PikeOS console.
Description:
The macro formats and prints arguments on the PikeOS console according to the C printf-like format
string fmt. The output string is prefixed with a string indicating a "FATAL" type message, and the driver
name.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib Service API 39
Note:
The actual display of the output string on the PikeOS console is controlled by the logging verbosity
threshold, set via the driver configuration. FATAL type messages are printed if the threshold is set to 1
or higher.
VP_LOG_ERROR (fmt, args...) Print ERROR type message on PikeOS console. Description: The macro formats and prints arguments on the PikeOS console according to the C printf-like format string fmt. The output string is prefixed with a string indicating an "ERROR" type message, and the driver name.
Note:
The actual display of the output string on the PikeOS console is controlled by the logging verbosity
threshold, set via the driver configuration. ERROR type messages are printed if the threshold is set to
2 or higher.
VP_LOG_MESSAGE (fmt, args...) Print MESSAGE type message on PikeOS console log_svc. Description: The macro formats and prints arguments on the PikeOS console according to the C printf-like format string fmt. The output string is prefixed with a string indicating a "MESSAGE" type message, and the driver name.
Note:
The actual display of the output string on the PikeOS console is controlled by the logging verbosity
threshold, set via the driver configuration. MESSAGE type messages are printed if the threshold is set
to 3 or higher.
VP_LOG_INFO (fmt, args...) Print INFO type message on PikeOS console. Description: The macro formats and prints arguments on the PikeOS console according to the C printf-like format string fmt.
Note:
The actual display of the output string on the PikeOS console is controlled by the logging verbosity
threshold, set via the driver configuration. INFO type messages are printed if the threshold is set to 4 or
higher.
VP_LOG_DEBUG (fmt, args...) Print DEBUG type message on PikeOS console. Description: The macro formats and prints arguments on the PikeOS console according to the C printf-like format string fmt. The output string is prefixed with a string indicating the message type, and the driver name.
Note:
The actual display of the output string on the PikeOS console is controlled by the logging verbosity
threshold, set via the driver configuration. DEBUG type messages are printed if the threshold is set to
5 or higher.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
40 FS Library API Reference
VP_LOG_MAX_BUFF_SIZE
Maximum size of a log message, including terminating NUL character.
Description:
Log messages exceeding this limit are truncated.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib Service API 41
5.3.2 Functions
5.3.2.1 vp_fs_vmem_alloc
Allocate unmapped virtual memory.
Synopsis:
P4_address_t vp_fs_vmem_alloc(P4_size_t size)
Description: Returns address of area of page aligned size size and which does not contain memory mapping.
Parameters: size [IN] requested size of unmapped memory in bytes
Returns: starting address of the allocated area NULL if there is not enough of virtual memory
Note: The requested size will be rounded up to whole page size.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
42 FS Library API Reference
5.3.2.2 vp_fs_malloc
Allocate memory area from the volume provider memory pool.
Synopsis:
void* vp_fs_malloc(P4_size_t size, P4_address_t alignment)
Description: Allocate size bytes of physical memory conforming to the specified alignment constraint.
Parameters: size [IN] Size of physical memory to allocate in bytes. alignment [IN] Alignment constraint.
Returns: base address of allocated memory NULL if there is not enough of contiguous memory in the pool
Note: The content of the allocated memory is undefined.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib Service API 43
5.3.2.3 vp_fs_free
Free memory back to the volume provider memory pool.
Synopsis:
void vp_fs_free(void *buf)
Description: free the buffer allocated by vp_fs_malloc() (see section 5.3.2.2) function
Parameters: buf [IN] Base address of memory previously allocated by vp_fs_malloc() (see section 5.3.2.2) that will be freed.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
44 FS Library API Reference
5.3.2.4 vp_fs_get_time
Get current time.
Synopsis:
P4_time_t vp_fs_get_time(void)
Description: Get the current system time if supported.
Returns: current system time 0 if the system time is not supported on the system.
Note: The FS library should use this time only for time stamping operations like file creation or modification. The function does not assure that the value will be greater than or equal to the return value of the previous call of this function.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib Service API 45
5.3.2.5 vp_fs_tls_set
Set thread local value.
Synopsis:
void vp_fs_tls_set(P4_cpureg_t value)
Description: Set thread local value for FS worker thread.
Parameters: value [IN] Value to set
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
46 FS Library API Reference
5.3.2.6 vp_fs_tls_get
Retrieve thread local value.
Synopsis:
P4_cpureg_t vp_fs_tls_get(void)
Description: Retrieve thread local value for FS worker thread.
Returns: thread local value
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib Service API 47
5.3.2.7 vp_fs_next_fd
Get next open file descriptor.
Synopsis:
vp_fs_file_desc_t vp_fs_next_fd(vp_fs_mount_context_t context)
Description: Iterate through opened file descriptors within the same mount.
Parameters: context [IN] Mount context provided passed to umount handler.
Returns: next open file descriptor or NULL after the last
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
48 FS Library API Reference
5.3.2.8 vp_fs_next_dd
Get next open directory descriptor.
Synopsis:
vp_fs_dir_t vp_fs_next_dd(vp_fs_mount_context_t context)
Description: Iterate through opened directory descriptors within the same mount.
Parameters: context [IN] Mount context provided passed to umount handler.
Returns: next open directory descriptor or NULL after the last
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib Service API 49
5.3.2.9 vp_fs_get_client_uid
Retrieve the UID of the client for the current request.
Synopsis:
P4_uid_t vp_fs_get_client_uid(void)
Description: Retrieve the UID of the client for the current request
Returns: the UID of the client
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
50 FS Library API Reference
5.3.2.10 vp_fs_get_locking_flags
Retrieve the flags used for resource locks within a volume provider.
Synopsis:
P4_uint32_t vp_fs_get_locking_flags(void)
Description: Retrieve the flags used for resource locks within a volume provider. These can be used e.g. when initializing mutexes guarding volumes, file descriptors etc. Flags are given by configuration. If priority based queuing is configured the flags contain P4_MUTEX_PRIO.
Returns: locking flags to be used e.g. with p4_mutex_init()
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
FSlib Service API 51
5.3.2.11 vp_log_printf
Print formatted output on PikeOS console.
Synopsis:
void vp_log_printf(vp_log_type_t type, const char *fmt, ...) __printflike(2
Description: The function formats and prints arguments on the PikeOS console according to the C printf-like format string fmt. Depending on type, the message may be prefixed with a string indicating type message, the integer value code and the driver name. Refer to the descriptions of the logging macros for details of message prefixes.
Note: The actual display of the output string on the PikeOS console is controlled by the logging verbosity threshold, set via the driver configuration. Refer to the descriptions of the logging macros for details of the threshold values.
Parameters: type [IN] Message type fmt [IN] C printf-like format string ... [IN] arguments for format string
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
52 FS Library API Reference
5.3.2.12 vp_log_get_level
Retrieve debug messages verbosity level set for VP application. This is intended for case when the FS library has its own system of debug messages, that allows setting verbosity in a similar way as other VP parts.
Synopsis:
P4_uint32_t vp_log_get_level(void)
Returns: Logging verbosity level. One or more (logical or) of VP_LOG_TYPE_xxxx.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block/MTD device API 53
5.4 Block/MTD device API
This section presents the data types and functions expected in the Block/MTD driver API by File System Provider applications. Because the terminology for block and MTD devices slightly differs this document and API uses terms page and block with following meaning:
• The term page is used for smallest unit that can be read or written at once. This means a physical block in
scope of block devices and chunk or page in scope of MTD devices.
• The term block is used for a group of chunks that can be erased at once.
5.4.1 Structure Definitions
5.4.1.1 struct vmio_blk_info_t
MTD/BLK device information.
Synopsis: struct vmio_blk_info_t { vmio_blk_dev_type_t type; P4_uint32_t flags; P4_uint64_t size; P4_size_t erase_size; P4_size_t wr_page_size; P4_size_t max_wr_pages; P4_size_t rd_page_size; P4_size_t max_rd_pages; P4_size_t physical_block_size; P4_size_t oob_size; P4_bool_t ecc_in_drv; };
Structure Element Description: type type of the device flags flags denoting things like that device is writable size total device size in bytes erase_size size of erase block wr_page_size minimal writable unit, the blk_write offset means the amount of this units from start of the device max_wr_pages number of the pages that driver can write at once rd_page_size minimal readable unit, the blk_read offset means the amount of this units from start of the device max_rd_pages number of the pages that driver can read at once physical_block_size Physical block size in bytes. This value is valid for devices without erase requirements and it will be within both ranges [rd_page_size, rd_page_size * max_rd_pages] and also [wr_page_size, wr_page_size * max_wr_pages]. If device does not report value of physical block size, then this value will match the logical block size.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
54 FS Library API Reference
oob_size amount of OOB data per block if zero, device has no OOB area
ecc_in_drv ECC is evaluated in HW/driver
5.4.1.2 union vmio_blk_handle_t
MTD/BLK device handle.
Note: There is no need to access items of this union by user, the union is used as a device representation.
Synopsis:
union vmio_blk_handle_t { vm_file_desc_t fd; P4_uint32_t dev_id; };
Union Element Description: fd file description used by libvm in case that the driver is standalone dev_id device ID provided by the blk_driver to reference the device
5.4.1.3 struct vmio_blk_io_options_t
MTD/BLK read and write functions parameters.
Synopsis:
struct vmio_blk_io_options_t { P4_off_t page; P4_uint32_t flags; P4_size_t len; P4_size_t ret_len; P4_size_t oob_len; P4_size_t oob_ret_len; P4_uint8_t * data_buf; P4_uint8_t * oob_buf; };
Structure Element Description: page position of the file access in writesize units (filled by caller) flags flags further specifying requested file access either zero or VMIO_BLK_IO_FUA (filled by caller) len size of the data buffer (filled by caller) ret_len amount of data really processed (filled by called function) oob_len size of the oob buffer (filled by caller) oob_ret_len amount of oob data really processed (filled by called function) data_buf data buffer oob_buf OOB buffer
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block/MTD device API 55
5.4.2 Defines
VMIO_BLK_IO_FUA Force Unit Access, if used as a flag for write command. If used, the data shall be written all the way down to stable storage prior the call returns. This flag has no effect in case of read.
Note:
The driver may always write the data to the stable storage prior the call returns. In that case this flag
has no effect.
VMIO_BLK_IO_RO
Description:
Read-Only device (e.g. EEPROM or SD card with write lock)
5.4.3 Data Type Definitions
vmio_blk_dev_type_t type of block device vmio_blk_ecc_res_t results of ECC check in device or driver
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
56 FS Library API Reference
5.4.4 Enumerations
Enumeration type vmio_blk_dev_type_e
type of block device
Name Description VMIO_BLK_TYPE_BLK mass storage block device (e.g. SATA disk, SD card, USB mass storage device)
VMIO_BLK_TYPE_NAND NAND FLASH device with ECC stored in OOB to detect bad blocks
VMIO_BLK_TYPE_NOR Parallel NOR FLASH device (e.g. CFI compliant memories ) or serial NOR FLASH device connected via SPI
VMIO_BLK_TYPE_SRAM SRAM or MRAM device (no need to erase before write)
Enumeration type vmio_blk_ecc_res_t
results of ECC check in device or driver
Name Description VMIO_BLK_ECC_RES_UNKNOWN ECC was not performed
VMIO_BLK_ECC_RES_NO_ERROR ECC check passed without error
VMIO_BLK_ECC_RES_FIXED ECC check run, wrong data was corrected
VMIO_BLK_ECC_RES_UNFIXED ECC check run, unfixed wrong data was not corrected
5.4.5 Variables
type type of the device
flags flags denoting things like that device is writable
size total device size in bytes
erase_size size of erase block
wr_page_size minimal writable unit, the blk_write offset means the amount of this units from start of the
device
max_wr_pages number of the pages that driver can write at once
rd_page_size minimal readable unit, the blk_read offset means the amount of this units from start of the
device
max_rd_pages number of the pages that driver can read at once
physical_block_size Physical block size in bytes.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block/MTD device API 57
This value is valid for devices without erase requirements and it will be within both ranges [rd_page_size,
rd_page_size * max_rd_pages] and also [wr_page_size, wr_page_size * max_wr_pages].
If device does not report value of physical block size, then this value will match the logical block size.
oob_size amount of OOB data per block if zero, device has no OOB area ecc_in_drv ECC is evaluated in HW/driver fd file description used by libvm in case that the driver is standalone dev_id device ID provided by the blk_driver to reference the device page position of the file access in writesize units (filled by caller) flags flags further specifying requested file access either zero or VMIO_BLK_IO_FUA (filled by caller) len size of the data buffer (filled by caller) ret_len amount of data really processed (filled by called function) oob_len size of the oob buffer (filled by caller) oob_ret_len amount of oob data really processed (filled by called function) data_buf data buffer oob_buf OOB buffer
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
58 FS Library API Reference
5.4.6 Functions
5.4.6.1 vmio_blk_register
MTD/BLK device driver register.
Synopsis:
P4_e_t vmio_blk_register(const char *device, vmio_blk_handle_t *handle)
Description: This function is expected to initialize the driver and the hardware device.
Parameters: device name of the device used for storing data handle pointer to vm_blk_handle_t that will be filled with valid device handle in case of success content is undefined in case of failure
Returns: P4_E_OK if success. P4_E_NOENT in case the device does not exist. This error may be used e.g. to indicate that removable media is not present or the partition referenced by the device string does not exist on the storage media. P4_E_INVAL in case an invalid name is given by device. P4_E_PERM access permission for the device is not granted (e.g. due to missing file access rights in the VMIT). P4_E_IO in case of an miscellaneous error.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block/MTD device API 59
5.4.6.2 vmio_blk_deregister
MTD/BLK device driver deregister function.
Synopsis:
P4_e_t vmio_blk_deregister(vmio_blk_handle_t *handle)
Description: This function is expected to write pending changes to the device, return all resources and prepare device for eventual new registering.
Parameters: handle Valid BLK device handle
Returns: P4_E_OK if success P4_E_IO in case of error
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
60 FS Library API Reference
5.4.6.3 vmio_blk_erase
Erase block and prepare it for future use.
Synopsis:
P4_e_t vmio_blk_erase(vmio_blk_handle_t *handle, P4_off_t block)
Description: Erase block and prepare it for future write operation. Only MTD driver may optionally implement this function.
Parameters: handle Valid BLK device handle block number of the block to be erased.
Returns: P4_E_OK if success P4_E_IO in case of error
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block/MTD device API 61
5.4.6.4 vmio_blk_trim
Mark page of block device as unused.
Synopsis:
P4_e_t vmio_blk_trim(vmio_blk_handle_t *handle, P4_off_t page)
Description: This function is used to tell the block driver that the page is no longer used and its content doesn’t need to be preserved. Only the Block Device driver should implement this function.
Parameters: handle Valid BLK device handle page number of the page to mark as unused
Returns: P4_E_OK if success P4_E_IO in case of error
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
62 FS Library API Reference
5.4.6.5 vmio_blk_flush
Flush device caches.
Synopsis:
P4_e_t vmio_blk_flush(vmio_blk_handle_t *handle)
Description: This function is used to flush all caches and should not return until all data are persistently stored on device.
Note: This function may eventually trigger a cache flush on other devices managed by the same driver.
Parameters: handle Valid BLK device handle page number of the page to mark as unused
Returns: P4_E_OK if success P4_E_IO in case of error
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block/MTD device API 63
5.4.6.6 vmio_blk_check_bad
Query state of the block of the device.
Synopsis:
P4_e_t vmio_blk_check_bad(vmio_blk_handle_t *handle, P4_off_t block, P4_bool_t *is_bad)
Description: Check if the block wasn’t marked as bad. Only MTD driver should implement this function.
Parameters: handle Valid BLK device handle block number of the block to query is_bad will be set to FALSE if block is usable will be set to TRUE if block was marked as bad
Returns: P4_E_OK if success P4_E_IO in case of error
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
64 FS Library API Reference
5.4.6.7 vmio_blk_mark_bad
Mark block as bad.
Synopsis:
P4_e_t vmio_blk_mark_bad(vmio_blk_handle_t *handle, P4_off_t block)
Description: Mark the block as defective. Only MTD driver should implement this function.
Parameters: handle Valid BLK device handle block number of the block to mark as bad
Returns: P4_E_OK if success P4_E_IO in case of error
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block/MTD device API 65
5.4.6.8 vmio_blk_get_info
Query driver configuration.
Synopsis:
P4_e_t vmio_blk_get_info(vmio_blk_handle_t *handle, vmio_blk_info_t *info)
Description: Retrieve the vmio_blk_info_t structure with configuration of the driver.
Parameters: handle Valid BLK device handle info pointer to the vmio_blk_info_t structure that will be filled
Returns: P4_E_OK if success P4_E_IO in case of error
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
66 FS Library API Reference
5.4.6.9 vmio_blk_read_page
Read chunk from the MTD device. Read page from the BLK device.
Synopsis:
P4_e_t vmio_blk_read_page(vmio_blk_handle_t *handle, vmio_blk_io_options_t *opt, vmio_blk_ecc_res_t *ecc)
Description: This function reads data (and OOB in case of MTD NAND driver). If one of the opt->databuf or opt->oobbuf is NULL, only the other one is read. Block device driver shall ignore the OOB related items of the opt parameter.
Note: If the driver allows it, more contiguous pages can be read at once. How many pages are requested to be read can be calculated out of the opt->len parameter. The opt->len parameter shall be a multiple of writesize and shall not be larger then the writebufsize.
Parameters: handle Valid BLK device handle opt structure with payload and OOB data buffer description ecc result of the ECC check (if performed by the device or driver, or VMIO_BLK_ECC_RES_UNKNOWN if check not performed)
Returns: P4_E_OK if success P4_E_IO in case of error
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Block/MTD device API 67
5.4.6.10 vmio_blk_write_page
Write chunk to MTD device, write page to Block device.
Synopsis:
P4_e_t vmio_blk_write_page(vmio_blk_handle_t *handle, vmio_blk_io_options_t *opt)
Description: This function writes data (and OOB in case of MTD driver). If one of the opt->databuf or opt->oobbuf is NULL, only the other one is written. Block device driver shall ignore the OOB related items of the opt parameter.
Note: If the driver allows it, more contiguous pages can be written at once. How many pages are requested to be written can be calculated out of the opt->len parameter. The opt->len parameter shall be a multiple of vmio_blk_info_t::writesize and shall not be larger then the vmio_blk_info_t::writebufsize.
Parameters: handle Valid BLK device handle opt structure with payload and OOB data buffer description
Returns: P4_E_OK if success P4_E_IO in case of error
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
68 FS Library API Reference
5.5 Interaction of File Systems and Block Drivers
When writing a block driver for one of the stock file systems it is necessary to know which mandatory functions have to be implemented and how these functions are used by the file system during run time. This section provides an overview about this topic. Figure 5 shows a minimal example of a control/data flow between a file system and a block driver.
VP Volume Worker VP Respart Worker FS Block driver
enter listen loop parse device string,
mount() vmio_blk_register(dev_name, &handle) initialize device,
return handle.
associate volume
with blk device
handle vmio_blk_get_info(&handle, &info)
vmio_blk_read_page(...)
validate config
against HW vmio_blk_read_page(...)
capabilities
...
enter listen loop
...
read()
vmio_blk_read_page(...)
...
umount() vmio_blk_deregister()
free device handle,
free associated
resources
Figure 5: Control/Data Flow between VP, File System and Block Driver
When the first mount request for a volume (independently from the calling partition) is received by the endless loop in the volume worker thread the vmio_blk_register() function of the block driver is called. During this call the plain device name (how it was configured in the device property in the volume) is passed to the driver. Depending on the use case the driver may parse the device name to e.g. determine the partition of the hardware device which is used. The driver has to return a handle back to the file system which is used in later requests for identifying the device. After the vmio_blk_register function was called the file system may call vm_blk_get_info() to retrieve information about the device. CFS as an example always calls this function to retrieve the hardware block size and to match this block size with the block size configured for the volume in the properties. Only if these sizes match the volume can be successfully mounted. During runtime all file system functions are called from within the endless service dispatching loops of the volume worker and partition worker threads. The file systems will call the
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Interaction of File Systems and Block Drivers 69
vmio_blk_read_page() and vmio_blk_write_page() functions in order to read blocks or write blocks to the storage medium. For each volume typically a mount counter is maintained, which is incremented on each mount() call and decremented on each umount() call. If the mount counter reaches 0 (meaning that no partition has currently mounted the volume anymore), vmio_blk_deregister() might be called by the file system in order to completely detach from the block device. The next subsequent mount() request will have to issue a vmio_blk_register() again in case vmio_blk_deregister() has been called. If a block based file system like CFS or FAT is used the mandatory set of functions a block driver has to provide is the following:
• vmio_blk_register()
• vmio_blk_deregister()
• vmio_blk_get_info()
• vmio_blk_read_page()
• vmio_blk_write_page()
For YAFFS additional functions have to be implemented (like vmio_blk_mark_bad) in order to enable YAFFS to use special functionality which is required for using raw flash hardware devices.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
6 APEX Error Indications
In this section the mapping of VM error codes to APEX (ERRNO/RETURN CODE) combinations is given in detail. Furthermore it is explained which software part (APEX, libvp, FS) is responsible to detect the error and to pass it up to the user.
• An A in the column "returning module" means, that the APEX personality is checking the error condition
and passes the error to the user.
• The letter V indicates that the error is checked by the libvp.
• An F indicates that the concrete File System Implementation needs to detect the error and pass it up to the
user. In this case the P4 error code which is used is given in the table as well.
• The letter P is used to indicate that the PSSW detects/returns this error.
Also combinations are possible. More than one error letter means that the error can potentially be detected at more than one layer.
6.1 REMOVE_FILE
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/F
INVALID_MODE EACCES P4_E_PERM A
INVALID_CONFIG EACCES P4_E_PERM A
INVALID_PARAM ENOENT P4_E_NOENT F
INVALID_PARAM EINVAL P4_E_INVAL A/P/F
NOT_AVAILABLE EBUSY P4_E_BUSY F
NOT_AVAILABLE EIO P4_E_IO F
INVALID_PARAM ENOTDIR P4_E_NOCONTAINER F
INVALID_PARAM EROFS P4_E_RESTRICTED F
INVALID_PARAM ENAMETOOLONG P4_E_NAME A/P/F
Table 4: Error codes of function REMOVE_FILE
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
RENAME_FILE 71
6.2 RENAME_FILE
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH F
INVALID_MODE EACCES P4_E_PERM A
INVALID_CONFIG EACCES P4_E_PERM A
INVALID_PARAM ENOENT P4_E_NOENT F
INVALID_PARAM EINVAL P4_E_INVAL A/F
NOT_AVAILABLE EBUSY P4_E_BUSY F
NOT_AVAILABLE EIO P4_E_IO F
INVALID_PARAM ENOTDIR P4_E_NOCONTAINER F
INVALID_PARAM EISDIR P4_E_STATE F
INVALID_CONFIG ENOSPC P4_E_LIMIT F
INVALID_PARAM EEXIST P4_E_EXIST F
INVALID_PARAM EROFS P4_E_RESTRICTED K/F
INVALID_PARAM ENAMETOOLONG P4_E_NAME A/P/F
Table 6: Error codes of function RENAME_FILE
6.3 RENAME_DIRECTORY
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
72 APEX Error Indications
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH F
INVALID_MODE EACCES P4_E_PERM A
INVALID_CONFIG EACCES P4_E_PERM A
INVALID_PARAM ENOENT P4_E_NOENT F
INVALID_PARAM EINVAL P4_E_INVAL A/F
NOT_AVAILABLE EBUSY P4_E_BUSY F
NOT_AVAILABLE EIO P4_E_IO F
INVALID_PARAM ENOTDIR P4_E_NOCONTAINER F
INVALID_CONFIG ENOSPC P4_E_LIMIT F
INVALID_TBD ENOTEMPTY P4_E_STATE F
INVALID_PARAM EEXIST P4_E_STATE F
INVALID_PARAM EROFS P4_E_RESTRICTED F
INVALID_PARAM ENAMETOOLONG P4_E_NAME A/P/F
Table 8: Error codes of function RENAME_DIRECTORY
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
GET_VOLUME_STATUS 73
6.4 GET_VOLUME_STATUS
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
INVALID_PARAM ENOENT P4_E_NOENT A/F
INVALID_PARAM EINVAL P4_E_INVAL A/F
NOT_AVAILABLE EIO P4_E_IO F
INVALID_PARAM ENOTDIR P4_E_NOCONTAINER F
INVALID_PARAM ENAMETOOLONG P4_E_NAME A/(F)
Table 10: Error codes of function GET_VOLUME_STATUS
6.5 SYNC_FILE
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
INVALID_PARAM EACCES P4_E_PERM F
NOT_AVAILABLE EBUSY P4_E_BUSY A
NOT_AVAILABLE EIO P4_E_IO F
INVALID_PARAM EBADF A
Table 12: Error codes of function SYNC_FILE
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
74 APEX Error Indications
6.6 RESIZE_FILE
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
INVALID_PARAM EACCES P4_E_PERM F
INVALID_CONFIG EACCES P4_E_PERM A
INVALID_PARAM EINVAL P4_E_INVAL F
NOT_AVAILABLE EBUSY P4_E_BUSY A
NOT_AVAILABLE EIO P4_E_IO F
INVALID_CONFIG ENOSPC P4_E_LIMIT F
INVALID_PARAM EBADF A
Table 14: Error codes of function RESIZE_FILE
6.7 MAKE_DIRECTORY
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
INVALID_CONFIG EACCES P4_E_PERM A
INVALID_PARAM EINVAL P4_E_INVAL A/F
NOT_AVAILABLE EIO P4_E_IO F
INVALID_PARAM ENOTDIR P4_E_NOCONTAINER F
INVALID_PARAM EISDIR P4_E_MISMATCH F
INVALID_CONFIG ENOSPC P4_E_LIMIT F
INVALID_PARAM EEXIST P4_E_EXIST F
INVALID_PARAM EROFS P4_E_RESTRICTED F
INVALID_PARAM ENAMETOOLONG P4_E_NAME A/(F)
Table 16: Error codes of function MAKE_DIRECTORY
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
REMOVE_DIRECTORY 75
6.8 REMOVE_DIRECTORY
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH F
INVALID_MODE EACCES P4_E_PERM A
INVALID_CONFIG EACCES P4_E_PERM A
INVALID_PARAM ENOENT P4_E_NOENT F
INVALID_PARAM EINVAL P4_E_INVAL A/F
NOT_AVAILABLE EBUSY P4_E_BUSY F
NOT_AVAILABLE EIO P4_E_IO F
INVALID_PARAM ENOTDIR P4_E_NOCONTAINER F
INVALID_TBD ENOTEMPTY P4_E_STATE F
INVALID_PARAM EROFS P4_E_RESTRICTED F
INVALID_PARAM ENAMETOOLONG P4_E_NAME A/(F)
Table 18: Error codes of function REMOVE_DIRECTORY
6.9 OPEN_DIRECTORY
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_CONFIG EMFILE P4_E_OOFILE A/V/(F)
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
INVALID_PARAM ENOENT P4_E_NOENT F
INVALID_PARAM EINVAL P4_E_INVAL A/F
NOT_AVAILABLE EIO P4_E_IO F
INVALID_PARAM ENOTDIR P4_E_NOCONTAINER F
INVALID_PARAM ENAMETOOLONG P4_E_NAME A/P/F
Table 20: Error codes of function OPEN_DIRECTORY
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
76 APEX Error Indications
6.10 READ_DIRECTORY
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
NOT_AVAILABLE EIO P4_E_IO F
NOT_AVAILABLE ESTALE P4_E_STATE F
INVALID_PARAM ENAMETOOLONG P4_E_NAME A
INVALID_PARAM EBADF A
Table 22: Error codes of function READ_DIRECTORY
6.11 SYNC_DIRECTORY
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
NOT_AVAILABLE EBUSY P4_E_BUSY A
NOT_AVAILABLE EIO P4_E_IO F
INVALID_PARAM EBADF A
Table 24: Error codes of function SYNC_DIRECTORY
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
CLOSE_DIRECTORY 77
6.12 CLOSE_DIRECTORY
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
NOT_AVAILABLE EBUSY P4_E_BUSY A
INVALID_PARAM EBADF A
Table 26: Error codes of function CLOSE_DIRECTORY
6.13 OPEN_FILE
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_CONFIG EMFILE P4_E_OOFILE A/V/(F)
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
INVALID_PARAM EACCES P4_E_PERM A/F
INVALID_PARAM ENOENT P4_E_NOENT P/F/D
INVALID_PARAM EINVAL P4_E_INVAL A/F
NOT_AVAILABLE EIO P4_E_IO F
INVALID_PARAM ENOTDIR P4_E_NOCONTAINER F
INVALID_PARAM EISDIR P4_E_MISMATCH F
INVALID_PARAM EROFS P4_E_RESTRICTED F
INVALID_PARAM ENAMETOOLONG P4_E_NAME A/P/F
Table 28: Error codes of function OPEN_FILE
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
78 APEX Error Indications
6.14 READ_FILE
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
INVALID_PARAM EINVAL P4_E_INVAL A
INVALID_PARAM EFBIG P4_E_SIZE A
NOT_AVAILABLE EBUSY P4_E_BUSY A
NOT_AVAILABLE EIO P4_E_IO F
NOT_AVAILABLE ESTALE P4_E_STATE F
NOT_AVAILABLE EOVERFLOW P4_E_OVERFLOW (A)/F
INVALID_PARAM EBADF A
Table 30: Error codes of function READ_FILE
6.15 WRITE_FILE
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
INVALID_PARAM EACCES P4_E_PERM V
INVALID_PARAM EINVAL P4_E_INVAL A
INVALID_PARAM EFBIG P4_E_SIZE A
NOT_AVAILABLE EBUSY P4_E_BUSY A
NOT_AVAILABLE EIO P4_E_IO F
INVALID_CONFIG ENOSPC P4_E_LIMIT F
INVALID_PARAM EBADF A
Table 32: Error codes of function WRITE_FILE
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
GET_FILE_STATUS 79
6.16 GET_FILE_STATUS
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
NOT_AVAILABLE EBUSY P4_E_BUSY A
NOT_AVAILABLE EIO P4_E_IO F
INVALID_CONFIG ENOSPC P4_E_LIMIT F
NOT_AVAILABLE ESTALE P4_E_STATE F
INVALID_PARAM EBADF A
Table 34: Error codes of function GET_FILE_STATUS
6.17 SEEK_FILE
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
INVALID_PARAM EINVAL P4_E_INVAL A
NOT_AVAILABLE EBUSY P4_E_BUSY A
NOT_AVAILABLE ESTALE P4_E_STATE F
INVALID_PARAM EBADF A
Table 36: Error codes of function SEEK_FILE
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
80 APEX Error Indications
6.18 CLOSE_FILE
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
NOT_AVAILABLE EBUSY P4_E_BUSY A
NOT_AVAILABLE EIO P4_E_IO F
INVALID_PARAM EBADF A
Table 38: Error codes of function CLOSE_FILE
6.19 REWIND_DIRECTORY
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK A
INVALID_MODE EACCES P4_E_PERM A
NOT_AVAILABLE EBUSY P4_E_BUSY A
INVALID_PARAM EBADF A
Table 40: Error codes of function REWIND_DIRECTORY
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
OPEN_NEW_FILE 81
6.20 OPEN_NEW_FILE
APEX return code APEX ERRNO P4 error code returning module
NO_ERROR P4_E_OK F
INVALID_CONFIG EMFILE P4_E_OOFILE A/V/(F)
INVALID_PARAM EPERM P4_E_MISMATCH P/V/(F)
INVALID_MODE EACCES P4_E_PERM A
INVALID_CONFIG EACCES P4_E_PERM A
INVALID_PARAM EINVAL P4_E_INVAL A/F
NOT_AVAILABLE EIO P4_E_IO F
INVALID_PARAM ENOTDIR P4_E_NOCONTAINER F
INVALID_PARAM EISDIR P4_E_MISMATCH F
INVALID_CONFIG ENOSPC P4_E_LIMIT F
INVALID_PARAM EEXIST P4_E_EXIST F
INVALID_PARAM EROFS P4_E_RESTRICTED F
INVALID_PARAM ENAMETOOLONG P4_E_NAME A/(F)
Table 42: Error codes of function OPEN_NEW_FILE
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
7 CFS Volume Provider
The Certifiable File System (CFS) is an optional PikeOS component that provides fail safe file system. CFS is implemented as a standalone library that can be linked together with PikeOS native or POSIX application. The CFS Volume Provider uses this library to provide a complete volume provider on top of CFS file system. For details about CFS library see CFS - A certifiable file system for PikeOS document.
7.1 Binaries Available in PikeOS
CFS Volume Provider is available as a binary application fused together with device driver.
CFS Volume Provider with RAM Disk
In this binary application the CFS Volume Provider is fused together with disk simulation over SHM based RAM disk.
CFS Volume Provider with extblk-proxy
In this binary application the CFS Volume Provider is fused together with external block driver proxy.
7.2 Volume Configuration
The volume component defines a concrete volume served by a certain volume provider. In case of CFS it’s divided into two parts.
CFS specific configuration
This part provides parameters required by the CFS library.
Block Size Logical block size of the mounted CFS image
Storage Size Size of the memory pool to be used by the CFS
Base Block Offset of the CFS image from the beginning of storage device (in Block Size units)
UID User ID used for accessing the CFS image
GID Group ID used for accessing the CFS image
For details about Block Size, Storage Size, Base Block, UID, GID and Maximum Opened Files please see CFS - A certifiable file system for PikeOS, section CFS PikeOS API Reference.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Volume Configuration 83
Generic volume configuration
These items define how the volume provider should handle the device.
Volume name PikeOS prefix that will be used by clients to access the volume.
Use ramdisk This option will prepare a SHM ramdisk for the device driver ( used e.g. by the disksim module).
Ramdisk size RAM disk size in bytes (for disksim module it needs to be multiple of Block Size).
External device Check this if the volume provider is fused the way that it uses external device (e.g. together with extblk-proxy module). If set to True this will enable a dependency on external device.
Internal device This a string identification of the storage device in case when the Volume Provider is fused with a device driver that needs to distinguish multiple storage devices it provides.
Volume Worker Priority PikeOS priority of the volume worker thread
Maximum Atomic Size Maximum atomic transaction size in bytes
Storage initialization
These items define how the storage device will be initialized on startup.
Storage initialization Selects if and how the device will be initialized on startup.
Preload Image Path to the file on PikeOS file system (e.g. in ROM file system) that the Volume Provider will load to storage device before it initializes the CFS library.
Use default parameters If set to True the Volume Provider will evaluate the CFS specific configuration parame- ters and set the CFS image so it fits the volume (This may be suboptimal for some special use cases). If set to False, the CFS image format can be fine tuned.
Block size Size of the logical block that will be used on the image.
Block payload size Logical block payload size that will be used on the image.
Number of inodes The CFS image will be created with this amount of logical blocks used as inodes. The logical size of the image will be the number of logical blocks plus the number of data blocks. (This sum should match the size of the device.)
Number of data blocks The CFS image will be created with this amount of logical blocks used for data blocks. The logical size of the image will be the number of blocks plus the number of data blocks. (This sum should match the size of the device.)
Block per direct inode Amount of blocks that can be addressed directly from direct inodes without additional indirect inodes. If this value is too large it limits the file size. If it is too small it slightly decreases the performance for smaller files.
Maximum file name size Maximum size of file names.
UID for the root directory User ID that will be used for the root directory.
GID for the root directory Group ID that will be used for the root directory.
Endianity of the file system Endianity of the image that will be created.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
84 CFS Volume Provider
7.3 CFS Error Callback
The CFS library may be provided with a mount check error callback. This callback tells the library how to handle the CFS image inconsistencies discovered during mount process (e.g. caused by driver that can not write whole logical block during power failure). In the CFS Volume Provider there is a default callback used. If any inconsistency is found the default error callback aborts the mount without any attempts to bring the file system to consistent state. If different behavior is expected custom error callback can be provided by overriding global variable cfs_err_callback_t *cfs_error_callback with a pointer to a custom error callback function. For details about cfs_err_callback_t function prototype please refer to CFS - A certifiable file system for PikeOS document, chapter 3.
7.4 CFS Tools
makefs_cfs Helper Application
Together with CFS a host tool for creating a CFS file system image is provided. This tool can create a CFS image of desired geometry and populate it with files. Please note, that CFS library itself supports per file access rights management. On contrary PikeOS Volume Providers supports only per volume access rights. This tools allows creating CFS image with per file based access rights. The user should have in mind when creating image that will be used by the CFS Volume Provider. The CFS volume provider uses the User ID and Group ID from it’s configuration. If these User ID and Group ID are not sufficient for reading resp. writing the file all VP clients will have limited access to this file regardless of their access rights. For detailed description and usage of makefs_cfs tool please refer to CFS - A certifiable file system for PikeOS document, chapter 6.
dumpfs_cfs Helper Application
Together with CFS a host tool for examining a CFS file system image is provided. This tool can be used for interactive browsing through the content of CFS image downloaded from the target system. For detailed description and usage of this tool please refer to CFS - A certifiable file system for PikeOS document, chapter 7.
7.5 CFS Volume Provider Limitations
• Locking granularity and concurrent access
Locking is implemented using a mutex for each volume. That means that all accesses on one and the same
volume are serialized.
• CFS library limitations
For Limitations of CFS library refer to CFS - A certifiable file system for PikeOS document, chapter 8.
7.5.1 Compliance to ARINC653
The following points have to be taken into account when using a CFS volume provider as backend for the apex file system.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Copyright and Licensing 85
• Access rights not guaranteed to be applied on volume level.
By using the makefs_cfs tool it is possible to restrict access to single files or directories of a volume. This
contradicts to the requirement that access rights are always applied on volume level.
• Naming conventions.
Although the ARINC standard suggests that file names should be treated case insensitive and should
consist of a well defined set of characters CFS treats names case sensitive and does not throw and error if
characters like e.g. % are used.
• REMOVE_DIRECTORY() does not necessarily free memory visible at interface level.
CFS has separate block pools for data and meta data (inodes). At interface level there is only the number
of free data blocks visible in the volume status structure. Therefore removing of e.g. an empty directory
does not lead to a change of the visible free space at interface level.
• Entry kind in READ_DIRECTORY().
The kind of an entry retrieved by the function READ_DIRECTORY() cannot be returned by CFS.
• Stale file descriptors.
CFS does not handle stale file descriptors. Deleting or renaming of an open file (regardless by whom) will
take effect when all references to the file are closed (by closing all descriptors). Subsequent reads or write
to a deleted file are working as long as the descriptor is open.
• Differently or not reported error conditions.
Due to the slightly different semantics of ARINC in comparison to POSIX some specific error conditions are
reported by a different error code or are even not known by CFS (like stale file descriptors)
MAKE_DIRECTORY() cannot return EISIDR. If the path passed to MAKE_DIRECTORY already exists
EEXIST is returned regardless of the type of the existing entry.
READ_FILE() does not indicate EOVERFLOW when reading from a position beyond the size of the
file. The function cfs_lseek() allows the file offset to be set beyond the end of existing data in the file.
If data is later written at this point, subsequent reads in the gap between the previous end of data and
the newly written data return bytes with value 0 until data is written into the gap.
7.6 Copyright and Licensing
The implementation of CFS library 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.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
86 CFS Volume Provider
-
- 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.
8 FAT Volume Provider
The File Allocation Table (FAT) is a widely used file system that is simple and robust. The FAT Volume Provider uses FAT implementation based on code from http://elm-chan.org/fsw/ff/00index_e.html.
8.1 Binaries Available in PikeOS
FAT Volume Provider is available as a binary application fused together with device driver.
FAT Volume Provider with extblk-proxy
In this binary application the FAT Volume Provider is fused together with external block driver proxy.
8.2 Volume Configuration
The volume component defines a particular volume served by a certain volume provider. In case of FAT it’s divided into two parts.
FAT specific configuration
This part provides parameters required by the FAT implementation.
Block Size Logical block size of the FAT image
Format Enabled If there is no file system detected during mount operation, new empty file system will be created on the device.
Use preload During the initialization phase of the volume, overwrite the storage device with a file system image.
Preload Image File that will be copied to the storage device at volume initialization if preloading enabled.
Generic volume configuration
These items define how the volume provider should handle the device.
Volume name PikeOS prefix that will be used by clients to access the volume.
External device Check this if the volume provider is fused the way that it uses external device (e.g. together with extblk-proxy module). If set True this will enable a dependency on an external device.
Internal device This a string identification of the storage device in case when the Volume Provider is fused with a device driver that needs to distinguish multiple storage devices it provides.
Volume Worker Priority PikeOS priority of the volume worker thread
Maximum Atomic Size Maximum atomic transaction size in bytes
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
88 FAT Volume Provider
8.3 FAT Volume Provider Limitations
• Locking granularity and concurrent access
Locking is implemented using a mutex for each volume. That means that all accesses on one and the same
volume are serialized.
• Limited amount of mounted volumes
The FAT implementation has a compile time defined amount of maximum volumes currently this limit is set
to maximum of 32 volumes.
• Incompatible error handling
The FAT implementation has error handling that is not 100% compatible with the PikeOS error handling.
Most of the FAT errors are translated to P4_E_INVAL.
• Only 512 bytes large block size supported
At the moment only 512 bytes block size is supported by the volume provider.
• Long File Name (LFN) support always used
The LFN support can’t be disabled.
• No concurrent write / read access on single files. No renaming or unlinking of open files.
A single file cannot be opened both for reading and writing at the same time. Furthermore files can only be
opened for writing once at a time. When a file has an open file descriptor every open for writing, rename or
unlink operation will return P4_E_BUSY.
8.4 Copyright and Licensing
The code of FAT implementation is developed under BSD-style license and except from header included in the source files of it’s code, there are no other constraints regarding licensing regarding code. The LFN (long file name) feature on the FAT file system is a patent of Microsoft Corporation. The FAT implemen- tation can switch the LFN feature off by configuration option but it’s currently not supported by the FAT Volume Provider. When LFN feature is enabled on the commercial products, depending on the final destination a license from Microsoft may be required.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
9 YAFFS Volume Provider
YAFFS (Yet Another Flash File System), provided by Aleph One Limited, is an open-source file system specifically designed for embedded use with NAND and NOR Flash. The YAFFS Volume Provider uses YAFFS code from Aleph One. And provides PikeOS file system API on top of it.
9.1 Binaries Available in PikeOS
YAFFS Volume Provider is available as a binary application fused together with device driver.
YAFFS Volume Provider with extmtd-proxy
In this binary application the CFS Volume Provider is fused together with external block driver proxy. This binary is a part of volume providers demos for Native PikeOS and POSIX applications.
9.2 Volume Configuration
The volume component defines a particular volume provided by a certain volume provider. In case of YAFFS it’s divided into two parts.
YAFFS specific configuration
This part statically configures YAFFS implementation behavior. It defines FLASH geometry and features that YAFFS will use. (The Volume Provider checks this against flash geometry provided by the driver and reports an error if the device doesn’t fit this). There are two special configurations sets, one with preconfigured YAFFS1 layout volume and another one with preconfigured YAFFS2 layout volume. These two configurations have same items and following descriptions applies on both.
Total Bytes Per Chunk Data bytes per chunk (Spare Bytes not included).
Spare Bytes Per Chunk Size of the spare area, i.e. the number of OOB bytes per chunk.
Chunks Per Block Number of chunks in each erase block on the physical device, must be at least 2
Start Block Block number (not address in bytes) of the first block
End Block Block number (not address in bytes) of the last block must be at least startBlock + nReserved- Blocks + 2
Reserved Blocks Number of erasable blocks reserved for garbage collection and to cover for block failures. Minimum is 2, but 5 or so is better. If using a medium that is not expected to fail (e.g. RAM) then 2 can be used.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
90 YAFFS Volume Provider
Caches Number of entries in the YAFFS cache. Zero disables caching. A value of 10 to 20 is recommended for most systems.
Use Nand ECC This is a flag that tells YAFFS whether it should be doing ECC calculations or if it should be left to the driver.
No Tags ECC Do, or do not ECC on packed tags.
Is Yaffs2 Zero means YAFFS1 format will be used. One means YAFFS2 format will be used.
Format Enabled If the first mount attempt fails, format device and try to mount it again.
Force Format Always format device during the first mount.
Generic volume configuration
These items define how the volume provider should handle the device.
Volume name PikeOS prefix that will be used by clients to access the volume.
Use ramdisk This option will prepare a SHM based RAM disk for the device driver that is linked inside the volume provider.
Ramdisk size RAM disk size in bytes.
External device Check this if the volume provider is fused the way that it uses external device (e.g. together with mtdblk-proxy module). If set True this will enable a dependency on external device.
Internal device This a string identification of the storage device in case when the Volume Provider is fused with a device driver that needs to distinguish multiple storage devices it provides.
Volume Worker Priority PikeOS priority of the volume worker thread
Maximum Atomic Size Maximum atomic transaction size in bytes
9.3 YAFFS Volume Provider Limitations
• No tool for File System creation
Empty YAFFS file system is a freshly erased FLASH thus no formatting tool is needed. Preloading of
populated filesystem image is a complex task that differs depending on target system thus no generic tool
for creating a file system image populated by files is not provided.
• Big lock for whole YAFFS volume provider
The YAFFS implementation used requires a big lock. This means that in case one YAFFS volume provider
provides more volumes, client accessing one volume will affect another client accessing another volume.
• Maximum number of simultaneously open files The maximum number of simultaneously open files is
statically defined in the YAFFS implementation. It is set to value of 100. For lower values configuration
applies. If larger value set for a client in configuration it will be limited by this value.
• Maximum path and file length The maximum path and file length are statically defined in the YAFFS
implementation. The maximum path length is set to 255. The maximum file length is set to 255. The
YAFFS Volume Provider calls will return P4_E_NAME if this value is exceeded.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Copyright and Licensing 91
9.4 Copyright and Licensing
YAFFS implementation is licensed under GNU General Public License, version 2. There is an option to buy a license from Aleph One Limited, that does not have the GNU GPLv2 obligations. It is not recommended to mix GPLv2 licensed YAFFS volume provider parts with parts under different license because they would then inherit the GPL license.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
10 Limitations
The following limitations apply to volume providers:
• Time stamping is not supported. Information like the creation time or modification time of e.g. a file is not available for users accessing a volume provider.
• The root directory of a volume always serves as its mount point. Using a sub directory of a volume as mount point is not supported.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.