548 KiB
| title | source | category | pages | extracted |
|---|---|---|---|---|
| Pssw Reference Manual | docs/development/pssw-reference-manual.pdf | development | 282 | 2026-07-06T23:05:35.339949 |
Pssw Reference Manual
Extracted from
docs/development/pssw-reference-manual.pdf(282 pages). Figures, diagrams, and tables may not render accurately in plain text.
UniversalisOS System Software Reference Manual
Am Pfaffenstein 14, D-55270 Klein-Winternheim
Notice: The contents of this document are proprietary to Portugal Futurista GmbH and shall not be disclosed, disseminated, copied, or used except for purposes expressly authorized in writing by Portugal Futurista GmbH. UniversalisOS System Software Reference Manual UniversalisOS D5.0, Document Version D5.0-304
c 2005 – 2019 Portugal Futurista GmbH
Portugal Futurista GmbH Email: office@portugalfuturista.org Am Pfaffenstein 14 55270 Klein-Winternheim, Germany http://www.portugalfuturista.org
All rights reserved. UniversalisOS is a trademark of Portugal Futurista GmbH. The designations used to identify other software or hardware products in this publication may be trademarks of their manufacturers or sellers. Contents
1 The PSSW API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1.1 Terms and Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1.1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1.1.2 Invalid Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1.2 Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1.3 Global Types and Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 1.4 PSSW API Library Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 1.4.1 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 1.4.1.1 vm_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 1.5 Console I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 1.5.1 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 1.5.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.5.2.1 vm_cprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.5.2.2 vm_cputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.6 Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.6.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.6.1.1 struct vm_mem_stat_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.6.2 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.6.3 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 1.6.3.1 vm_mem_lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 1.6.3.2 vm_mem_pool_alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 1.6.3.3 vm_mem_stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 1.7 File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 1.7.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 1.7.1.1 struct vm_file_desc_ext_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 1.7.1.2 struct vm_file_desc_private_t . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 1.7.1.3 struct vm_file_desc_int_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 1.7.1.4 struct vm_file_desc_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 1.7.1.5 struct vm_file_stat_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 1.7.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 1.7.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 1.7.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 1.7.4.1 vm_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 1.7.4.2 vm_open_at . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 1.7.4.3 vm_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 1.7.4.4 vm_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 1.7.4.5 vm_read_at . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 1.7.4.6 vm_write_at . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 1.7.4.7 vm_discard_at . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 1.7.4.8 vm_fstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 1.7.4.9 vm_stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 1.7.4.10 vm_lseek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
4 CONTENTS
1.7.4.11 vm_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
1.7.4.12 vm_map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
1.7.4.13 vm_ioctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
1.7.4.14 vm_test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
1.7.4.15 vm_fsync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
1.7.4.16 vm_map_to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
1.8 Extended File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
1.8.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
1.8.1.1 struct vm_dir_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
1.8.2 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
1.8.3 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
1.8.3.1 vm_unlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
1.8.3.2 vm_rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
1.8.3.3 vm_statvfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
1.8.3.4 vm_ftruncate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
1.8.3.5 vm_dir_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
1.8.3.6 vm_dir_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
1.8.3.7 vm_dir_read_at . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
1.8.3.8 vm_dir_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
1.8.3.9 vm_dir_sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
1.8.3.10 vm_dir_rewind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
1.8.3.11 vm_mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
1.8.3.12 vm_umount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
1.9 Communication Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
1.9.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
1.9.1.1 struct vm_port_desc_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
1.9.1.2 struct vm_qport_stat_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
1.9.1.3 struct vm_sport_stat_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
1.9.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
1.9.3 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
1.9.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
1.9.4.1 vm_qport_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
1.9.4.2 vm_qport_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
1.9.4.3 vm_qport_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
1.9.4.4 vm_qport_pstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
1.9.4.5 vm_qport_psync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
1.9.4.6 vm_qport_stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
1.9.4.7 vm_qport_iterate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
1.9.4.8 vm_qport_control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
1.9.4.9 vm_qport_test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
1.9.4.10 vm_qport_read_routed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
1.9.4.11 vm_qport_write_routed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
1.9.4.12 vm_qport_clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
1.9.4.13 vm_qport_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
1.9.4.14 vm_sport_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
1.9.4.15 vm_sport_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
1.9.4.16 vm_sport_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
1.9.4.17 vm_sport_set_refresh_rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
CONTENTS 5
1.9.4.18 vm_sport_pstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
1.9.4.19 vm_sport_psync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
1.9.4.20 vm_sport_stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
1.9.4.21 vm_sport_iterate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
1.9.4.22 vm_sport_control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
1.9.4.23 vm_sport_test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
1.9.4.24 vm_sport_clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
1.9.4.25 vm_sport_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
1.10 Partition Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 1.10.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 1.10.1.1 struct vm_partition_stat_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 1.10.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 1.10.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 1.10.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 1.10.4.1 vm_part_set_mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 1.10.4.2 vm_reboot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 1.10.4.3 vm_shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 1.10.4.4 vm_part_pstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 1.10.4.5 vm_part_stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 1.11 Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 1.11.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 1.11.1.1 struct vm_procinfo_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 1.11.1.2 struct vm_proc_memseg_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 1.11.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 1.11.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 1.11.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 1.11.4.1 vm_cmd_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 1.11.4.2 vm_procinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 1.11.4.3 vm_proc_mem_iterate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 1.12 Health Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 1.13 Time Partition Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 1.13.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 1.13.1.1 struct vm_tsched_stat_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 1.13.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 1.13.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 1.13.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 1.13.4.1 vm_tsched_lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 1.13.4.2 vm_tsched_stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 1.13.4.3 vm_tsched_change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 1.14 System Extensions API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 1.14.1 Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 1.14.2 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 1.14.2.1 struct vm_se_if_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 1.14.2.2 struct vm_se_shm_iterate_t . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 1.14.3 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 1.14.4 Function Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 1.14.4.1 vm_se_part_change_cb_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 1.14.5 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
6 CONTENTS
1.14.6 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
1.14.6.1 vm_alloc_virt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
1.14.6.2 vm_malloc_aligned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
1.14.6.3 vm_malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
1.14.6.4 vm_calloc_aligned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
1.14.6.5 vm_calloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
1.14.6.6 vm_thread_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
1.14.6.7 vm_crit_enter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
1.14.6.8 vm_crit_leave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
1.14.6.9 vm_add_romimage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
1.14.6.10 vm_monitor_hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
1.14.6.11 vm_register_part_change_cb . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
1.14.6.12 vm_get_acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
1.14.6.13 vm_shm_iter_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
1.14.6.14 vm_shm_iter_take . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
1.14.6.15 vm_thread_get_priv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
1.15 File Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
1.15.1 Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
1.15.2 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
1.15.2.1 struct vm_se_fp_statics_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
1.15.2.2 struct vm_se_fp_if_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
1.15.3 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
1.15.4 Function Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
1.15.4.1 vm_se_fp_open_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
1.15.4.2 vm_se_fp_close_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
1.15.4.3 vm_se_fp_read_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
1.15.4.4 vm_se_fp_write_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
1.15.4.5 vm_se_fp_ioctl_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
1.15.4.6 vm_se_fp_fstat_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
1.15.4.7 vm_se_fp_map_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
1.15.4.8 vm_se_fp_prop_read_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
1.15.4.9 vm_se_fp_prop_write_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
1.15.4.10 vm_se_fp_prop_map_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
1.15.4.11 vm_se_fp_install_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
1.15.4.12 vm_se_fp_module_shutdown_t . . . . . . . . . . . . . . . . . . . . . . . . . . 162
1.15.4.13 vm_se_fp_partition_shutdown_t . . . . . . . . . . . . . . . . . . . . . . . . . 163
1.15.5 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
1.15.5.1 vm_fp_provider_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
1.15.5.2 vm_fp_get_domain_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
1.16 The Property File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
1.16.1 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
1.16.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
1.16.2.1 vm_prop_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
1.16.2.2 vm_prop_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
1.16.2.3 vm_prop_mem_map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
1.16.2.4 vm_prop_ioport_map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
1.16.2.5 vm_prop_int_grant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
1.16.2.6 vm_prop_dev_grant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
CONTENTS 7
1.17 Target Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 1.17.1 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 1.17.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 1.17.2.1 vm_target_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 1.18 External File Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 1.18.1 Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 1.18.2 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 1.18.2.1 struct vm_fp_listen_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 1.18.2.2 struct vm_fp_cmsg_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 1.18.2.3 struct vm_fp_rmsg_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 1.18.2.4 struct vm_fp_msg_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 1.18.3 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 1.18.4 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 1.18.5 Function Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 1.18.5.1 vm_fp_open_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 1.18.5.2 vm_fp_close_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 1.18.5.3 vm_fp_read_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 1.18.5.4 vm_fp_write_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 1.18.5.5 vm_fp_map_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 1.18.5.6 vm_fp_fstat_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 1.18.5.7 vm_fp_ioctl_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 1.18.6 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 1.18.6.1 vm_fp_msg_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 1.18.6.2 vm_fp_msg_wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 1.18.6.3 vm_fp_msg_dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 1.18.6.4 vm_fp_listen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 1.18.6.5 vm_fp_register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 1.19 Volume Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 1.19.1 Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 1.19.2 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 1.19.2.1 struct vm_vp_handlers_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 1.19.2.2 struct vm_vp_listen_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 1.19.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 1.19.4 Function Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 1.19.4.1 vm_vp_unlink_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 1.19.4.2 vm_vp_rename_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 1.19.4.3 vm_vp_statvfs_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 1.19.4.4 vm_vp_close_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 1.19.4.5 vm_vp_fsync_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 1.19.4.6 vm_vp_ftruncate_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 1.19.4.7 vm_vp_dir_create_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 1.19.4.8 vm_vp_dir_open_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 1.19.4.9 vm_vp_dir_read_at_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 1.19.4.10 vm_vp_dir_close_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 1.19.4.11 vm_vp_dir_sync_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 1.19.5 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 1.19.5.1 vm_vp_register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 1.19.5.2 vm_vp_listen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
8 CONTENTS
1.20 Request Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
1.21 Healthmonitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
1.21.1 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
2 The Virtual Machine Initialization Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 2.1 Common Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 2.1.1 stdBool64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 2.1.2 stdUnsignedShort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 2.1.3 stdUnsignedInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 2.1.4 stdUnsignedIntNoMinus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 2.1.5 stdUnsignedLong . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 2.1.6 stdUnsignedLongNoMinus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 2.1.7 stdUnsignedWord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 2.1.8 stdUnsignedWordNoMinus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 2.1.9 stdWord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 2.1.10 stdIPv4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 2.1.11 stdMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 2.1.12 partID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 2.1.13 partID0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 2.1.14 priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 2.1.15 version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 2.1.16 name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 2.1.17 name0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 2.1.18 path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 2.1.19 acl_path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 2.2 The VMIT Root Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 2.3 The Partition Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 2.3.1 The Memory Requirement Configuration Element . . . . . . . . . . . . . . . . . . . . . . 259 2.3.1.1 The Memory Type VM_MEM_TYPE_RAM . . . . . . . . . . . . . . . . . . . . . 260 2.3.1.2 The Memory Type VM_MEM_TYPE_ROM . . . . . . . . . . . . . . . . . . . . . 260 2.3.1.3 The Memory Type VM_MEM_TYPE_IO_MEM . . . . . . . . . . . . . . . . . . . 261 2.3.1.4 The Memory Type VM_MEM_TYPE_IO_PORT (x86 only) . . . . . . . . . . . . . 261 2.3.1.5 The Memory Type VM_MEM_TYPE_KMEM . . . . . . . . . . . . . . . . . . . . . 261 2.3.2 The Queuing Port Configuration Element . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 2.3.3 The Sampling Port Configuration Element . . . . . . . . . . . . . . . . . . . . . . . . . . 262 2.3.4 The File Access Configuration Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 2.3.5 The Process Configuration Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 2.3.5.1 The Process Map Configuration Element . . . . . . . . . . . . . . . . . . . . . 264 2.3.5.2 The Process File Configuration Element . . . . . . . . . . . . . . . . . . . . . 264 2.3.6 The Health Monitor Partition Configuration Element . . . . . . . . . . . . . . . . . . . . . 266 2.3.6.1 The Element "Default" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 2.3.6.2 The Element "If" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 2.3.6.3 The Element "Then" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 2.3.6.4 The Element "Domain" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 2.3.6.5 The Element "Switch" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 2.4 The Channel Configuration Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 2.5 The Shared Memory Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
CONTENTS 9
2.6 The Time Partition Configuration Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 2.6.1 The Window Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 2.6.1.1 Time Partition Periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 2.7 The Health Monitor Multi Partition Configuration Element . . . . . . . . . . . . . . . . . . . . . . 273 2.7.1 The Element "Default" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 2.7.2 The Element "If" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 2.7.3 The Element "Then" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 2.7.4 The Element "Domain" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 2.7.5 The Element "Switch" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 2.8 The Health Monitor Module Configuration Element . . . . . . . . . . . . . . . . . . . . . . . . . . 275 2.8.1 The Element "Default" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 2.8.2 The Element "If" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 2.8.3 The Element "Then" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 2.8.4 The Element "Domain" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 2.8.5 The Element "Switch" . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 2.9 System Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 3 Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 3.1 Individual Partition Abilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 4 PSSW Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
1 The PSSW API
1.1 Terms and Definitions
1.1.1 Terminology
The following terminology definitions apply to this reference manual:
undefined is used to describe behavior or state not defined in this specification that results from invalid usage or input state. Programs should not rely on undefined behavior or input state. Programs triggering undefined behavior or state should be considered invalid, because for everything that is used, a valid program must ensure that usage and input state are valid. The effect of undefined behavior or state may be global to the program, i.e., triggering it may disrupt the program’s functionality as a whole, including seemingly unrelated behavior or state.
unspecified is used to describe behavior or state not defined in this specification that results from valid usage and input state. Programs should not rely on unspecified behavior or state.
implementation-defined is used to describe behavior or state not defined in this specification, where some refining specification may have a definition of behavior or state. Programs may only rely on implementation-defined behavior or state in the context of the refining specifica- tion. A refining specification may be related to the exact underlying hardware, architecture manual, or specific configuration.
1.1.2 Invalid Pointers
For this document, any API involving pointers will, by default, have undefined behavior if any of the input pointers in invalid. NULL is also considered invalid. If NULL is allowed, the corresponding API description will state so explicitly. Note that in some cases, invalid pointers may very well be handled gracefully and cause a proper error code, e.g. if the kernel code protects itself against crashes due to invalid user pointers passed in. But still, this specification will normally not be explicit about when exactly an invalid pointer is an exceptional well-defined use case.
1.2 Header File
The PSSW API with all functions and definitions is imported into a C file by using the following header file include statement: #include <vm.h>
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Global Types and Constants 11
1.3 Global Types and Constants
This section describes data types and constants used within the PSSW API.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
12 The PSSW API
1.4 PSSW API Library Initialization
Before any function of the PSSW API can be used, the library has to be initialized. This is performed by the vm_init() (see section 1.4.1.1) call.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
PSSW API Library Initialization 13
1.4.1 Functions
1.4.1.1 vm_init
Initialize PSSW services.
Synopsis:
void vm_init(void)
Description: This function must be called once in each process that wants to use any of the PSSW services. It will verify that the PSSW API version used by the calling application matches the version of the PSSW module. If not, this function will not return, but raise a health monitor event P4_HM_DOMAIN_PART/P4_HM_TYPE_P4_E/P4_E_STATE on the partition level. If the health monitor is configured to ignore this, vm_init() (see section 1.4.1.1) will change the calling partition’s mode to IDLE regardless. Use of the PSSW-API by child tasks is not supported. A call to this service by a process’ child task is discouraged. It does not have an effect.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
14 The PSSW API
1.5 Console I/O
Console I/O functionality is intended for emergency and boot messages.
1.5.1 Defines
VM_CPRINTF_STRLEN
Description:
Maximum number of characters printable with one vm_cprintf() (see section 1.5.2.1) or vm_cputs() (see
section 1.5.2.2) call, including the terminating NUL character
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Console I/O 15
1.5.2 Functions
1.5.2.1 vm_cprintf
Print a formatted string on the UniversalisOS console.
Synopsis:
P4_e_t vm_cprintf(const char *fmt, ...)
Parameters: fmt IN: Format string followed by variable parameter list to be printed.
Description: This function behaves much like the well known C-function printf() but it only supports a small subset of the conversion specifiers and length modifiers described in ISO C99. Especially, floating point conversion is not supported. For details on the format string and argument passing consult the associated literature. The following conversion specifiers are supported:
• c The int argument is converted to an unsigned char, and the resulting character is written.
• s The const char * argument is expected to be a pointer to a null-terminated string.
• d, i The int argument is converted to signed decimal notation.
• u The unsigned int argument is converted to unsigned decimal.
• o The unsigned int argument is converted to unsigned octal.
• x, X The unsigned int argument is converted to unsigned hexadecimal. The lowercase letters "abcdef" are
used for ’x’ conversions, whereas the uppercase letters "ABCDEF" are used for ’X’ conversions.
• p, P The void * argument is converted to an unsigned hexadecimal as if by "%#x" and "%#X" respectively.
• % Print a "%" character. No argument is converted.
A minimum field width and precision is supported. Both may take the form of an asterisk (’*’) or a decimal digit string. In the case of an asterisk an argument of type int supplies the field width or precision. The flags ’+’ and for sign extension, ’#’ for an alternate form, ’-’ for left justification, and ’0’ for zero padding are supported. The length modifiers ’l’ for a long argument and ’ll’ for a long long argument are supported. If the resulting string would exceed VM_CPRINTF_STRLEN bytes (including the terminating ’NUL’ character), it will be truncated to VM_CPRINTF_STRLEN - 1 character and the NUL character will be appended. The I/O device used for character output depends on the platform and the value of the property specifying the system console. For more information how to select the system console, please refer to the corresponding UniversalisOS platform manual.
Warning: Be aware, that a pending console operation will block concurrent console operations from any partition.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
16 The PSSW API
This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success P4_E_NOTIMPL if the feature "console output" is disabled in the PSSW component. This is the case for the PSSW version targeting DO178-B software level A objectives. P4_E_TIMEOUT If the console file provider system extension can currently not handle the request and wants to unblock the client to reissue the request at a later point in time. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: The console is used to output kernel messages, too. Characters printed by vm_cprintf() (see section 1.5.2.1) can get intermixed with kernel messages.
Note: The vm_cprintf() (see section 1.5.2.1) function is not optimized for performance but intended to be used for printing emergency messages.
Warning: If the calling thread has been deleted, has been moved to a different time partition, has been exchanged its register context or has been subject to another system call which canceled the IPC operation while being blocked in a preceding service call, then the service does not return execution to the calling thread until the thread would have been woken up if the IPC would not have been canceled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Console I/O 17
1.5.2.2 vm_cputs
Print a string on the UniversalisOS console.
Synopsis:
P4_e_t vm_cputs(const char *str)
Parameters: str IN: String to be written to console.
Description: This function prints a string to the UniversalisOS console. Unlike the similar named C-function puts() this functions does not append a line-feed character to the output. If the string exceeds VM_CPRINTF_STRLEN bytes (including the terminating ’NUL’ character), only VM_CPRINTF_STRLEN - 1 characters will be printed. The I/O device used for character output depends on the platform and the value of the property specifying the system console. For more information how to select the system console, please refer to the corresponding UniversalisOS platform manual.
Warning: Be aware, that a pending console operation will block concurrent console operations from any partition. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success P4_E_NOTIMPL if the feature "console output" is disabled in the PSSW component. This is the case for the PSSW version targeting DO178-B software level A objectives. P4_E_TIMEOUT If the console file provider system extension can currently not handle the request and wants to unblock the client to reissue the request at a later point in time. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: The console is used to output kernel messages, too. Characters printed by vm_cputs() (see section 1.5.2.2) can get intermixed with kernel messages.
Note: The vm_cputs() (see section 1.5.2.2) function is not optimized for performance but intended to be used for printing emergency messages.
Warning: If the calling thread has been deleted, has been moved to a different time partition, has been exchanged its register context or has been subject to another system call which canceled the IPC operation while being blocked
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
18 The PSSW API
in a preceding service call, then the service does not return execution to the calling thread until the thread would have been woken up if the IPC would not have been canceled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Memory Management 19
1.6 Memory Management
This section describes functions to allocate memory and to retrieve status information from memory pools.
1.6.1 Structure Definitions
1.6.1.1 struct vm_mem_stat_t
Memory object status
Synopsis: struct vm_mem_stat_t { P4_uint32_t otype; vm_memory_access_mode_t access; vm_memory_cache_mode_t cache; P4_bool_t is_pool; P4_size_t size; P4_size_t free; P4_phys_addr_t paddress; P4_address_t palign; char name[VM_NAME_LEN]; };
Structure Element Description: otype Type of the memory object access Memory access permissions cache Caching strategy is_pool Flag indicating whether the memory object is a memory pool object or not size Size (in bytes) of the memory pool free Number of free bytes free. This value only has a meaningful value for memory pools, i.e., if is_pool is not FALSE. paddress Physical address of the memory object palign Physical alignment of the memory object name Name of the memory object
1.6.2 Data Type Definitions
vm_mem_desc_t Memory descriptor
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
20 The PSSW API
1.6.3 Functions
1.6.3.1 vm_mem_lookup
Retrieve the memory descriptor for a given name.
Synopsis:
P4_e_t vm_mem_lookup(vm_part_id_t part_id, const char *name, vm_mem_desc_t *mh_p)
Parameters: part_id IN: Partition ID VM_RESPART_MYSELF may be used to refer to the caller’s partition. name IN: Name of the memory pool as given in the VMIT mh_p OUT: Memory pool descriptor.
Description: A successful call to this function returns the memory descriptor corresponding to the name given by name in the resource partition identified by part_id. The memory descriptor returned by this function into *mh_p can be used as a handle to vm_mem_stat() (see section 1.6.3.3). Memory descriptors are local to each partition, so only a pair of partition id and memory descriptor uniquely identifies a memory requirement in the system. The descriptor can be also used in calls to vm_mem_pool_alloc() (see section 1.6.3.2) if the memory requirement is specified in the VMIT with the flag IsPool set to true. For looking up memory requirements in other partitions than the caller’s, the caller partition must have the VM_AB_MONITOR ability. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If mh_p is NULL, this function has undefined behavior. If this function returns anything but P4_E_OK, the contents of mh_p are unspecified.
Returns: P4_E_OK upon success P4_E_INVAL if name is not a valid PSSW name or if part_id refers to an invalid partition. P4_E_NOABILITY if the calling partition does not the ability VM_AB_MONITOR and part_id refers to another partition than the caller’s partition P4_E_NOENT if no memory pool with the given name exists in the given partition. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
See also:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Memory Management 21
vm_init() (see section 1.4.1.1), vm_mem_pool_alloc() (see section 1.6.3.2), and vm_mem_stat() (see section 1.6.3.3)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
22 The PSSW API
1.6.3.2 vm_mem_pool_alloc
Allocate memory from a partition’s memory pool.
Synopsis:
P4_e_t vm_mem_pool_alloc(vm_mem_desc_t mh, P4_size_t size, P4_address_t vaddr)
Parameters: mh IN: Memory pool descriptor size IN: Number of bytes to allocate, where size must be a multiple of P4_PAGESIZE vaddr IN: Virtual address where the memory shall be mapped to
Description: A successful call to this function allocates size bytes from the memory pool given by mh and maps it to the virtual address given by vaddr in the caller’s address space. If the memory pool contains physically contiguous memory, the allocated memory is also contiguous. Two con- secutive calls however are not guaranteed to return physically adjoining segments. This function can only be used to reference memory pools in the caller’s resource partition, therefore, the function has no parameter for a partition ID. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success P4_E_INVAL is returned if - size if zero. - either size or vaddr is not a multiple of P4_PAGESIZE - parts of the virtual address space in the range [vaddr : vaddr + size - 1] are outside of the valid user address space. It is also returned if mh does not refer to a memory pool of the caller’s resource partition. P4_E_OVERMAP if parts of the virtual address space in the range [vaddr : vaddr
• size - 1] are already mapped
P4_E_OOMEM if there are less than size bytes left in the pool.
P4_E_NOKMEM if the calling partition has not enough kernel pages left to install the mapping.
P4_E_ABORT if the call was aborted.
P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
See also: vm_init() (see section 1.4.1.1), vm_mem_lookup() (see section 1.6.3.1), vm_mem_stat() (see section 1.6.3.3)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Memory Management 23
1.6.3.3 vm_mem_stat
Retrieve status information about a memory object.
Synopsis:
P4_e_t vm_mem_stat(vm_part_id_t part_id, vm_mem_desc_t mh, vm_mem_stat_t *pstat)
Parameters: part_id IN: Partition ID VM_RESPART_MYSELF may be used to refer to the caller’s partition. mh IN: Memory pool descriptor pstat OUT: Memory pool status
Description: A successful call to this function returns the status of the memory requirement given by mh of the partition given by part_id in the data structure referenced by status. Refer to the description of the data structure vm_mem_stat_t for a detailed description of the memory status. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If pstat is NULL, this function has undefined behavior. If this function returns anything but P4_E_OK, the contents of pstat are unspecified.
Returns: P4_E_OK upon success P4_E_NOABILITY if the calling partition does not the ability VM_AB_MONITOR and part_id refers to another partition than the caller’s partition P4_E_INVAL if mh does not refer to a valid memory object of the partition part_id or if part_id refers to an invalid partition P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
See also: vm_init() (see section 1.4.1.1), vm_mem_pool_alloc() (see section 1.6.3.2), vm_mem_lookup() (see section 1.6.3.1), and vm_mem_stat_t
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
24 The PSSW API
1.7 File System
This section describes basic functions to access the UniversalisOS virtual file system layer.
1.7.1 Structure Definitions
1.7.1.1 struct vm_file_desc_ext_t
Application level file descriptor structure. Read and partly modified by external file provider implementations.
Synopsis:
struct vm_file_desc_ext_t { P4_uint32_t handle; P4_uint32_t type; P4_uint32_t size; P4_uid_t client; P4_uid_t read; P4_uid_t write; P4_uid_t ioctl; P4_uid_t fstat; P4_uid_t map; P4_uid_t open; P4_uid_t close; P4_uid_t dir; P4_uint32_t vflags; P4_uint8_t part_id; };
Structure Element Description: handle File handle. Fully maintained by the file provider. type File type. Not interpreted by the PSSW itself. Maintained by the file provider. Indicates file access semantics to the client. size Maximum transfer size. External file providers should set this to either the established mapping size for read/write callbacks, or for message oriented devices set it to the desired message size. receive mapping windows have to be sufficiently large to cover the maximum transfer size plus any alignment of user buffers within a memory page. client Client UID to uniquely identify the requesting thread. Set by the external file provider framework for file descriptors passed to the open entry point. read The file provider’s read daemon. Set by the external file provider’s open entry point to the UID of the thread which shall handle read requests to this file descriptor. write The file provider’s write daemon. Set by the external file provider’s open entry point to the UID of the thread which shall handle write requests to this file descriptor. ioctl The file provider’s ioctl daemon. Set by the external file provider’s open entry point to the UID of the thread which shall handle ioctl requests to this file descriptor. fstat The file provider’s fstat daemon. Set by the external file provider’s open entry point to the UID of the thread which shall handle fstat requests to this file descriptor.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 25
map The file provider’s map daemon. Set by the external file provider’s open entry point to the UID of the
thread which shall handle map requests to this file descriptor.
open The file provider’s open daemon. Set by a volume provider’s mount entry point to the UID of the thread which shall handle open requests on files. close The file provider’s close daemon. Set by a volume provider’s mount entry point to the UID of the thread which shall handle close requests on files. dir The file provider’s directory handling daemon. Set by a volume provider’s mount entry point to the UID of the thread which shall handle mkdir, rmdir and open, read, close requests on directories. vflags File protection flags as defined in VMIT. Set by the file provider framework for file descriptors passed to the open entry point. part_id Numerical client partition identifier. Set by the external file provider framework for file descriptors passed to the open entry point.
1.7.1.2 struct vm_file_desc_private_t
Type to encapsulate private data with proper alignment
Synopsis: struct vm_file_desc_private_t { P4_uint64_t fp_private[(VM_FILE_PRIVATE_DATA_SIZE+7)/8]; };
Structure Element Description: fp_private
1.7.1.3 struct vm_file_desc_int_t
PSSW level file descriptor structure. File descriptor per open instance of a file. Used to interface System Extension File Providers. Instances of this data objects are always exclusive to the calling thread and thus are never subject to concurrency.
Synopsis: struct vm_file_desc_int_t { P4_uint32_t oflags; P4_uint32_t vflags; P4_uint32_t fflags; P4_off_t size; P4_off_t pos; P4_file_type_t type; void * fp_handle; vm_file_desc_private_t _priv; };
Structure Element Description: oflags File open flags vflags File open flags allowed by the VMIT configuration fflags File open flags allowed by the file provider
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
26 The PSSW API
size Current File Size
pos Current file position
type File type
fp_handle Handle to the file provider
_priv Private data maintained by the file provider. Use vm_se_get_priv() to access this.
1.7.1.4 struct vm_file_desc_t
File descriptor handle for UniversalisOS managed files
Note: Use the descriptor as an opaque handle, do not rely on the actual content, structure, or type.
1.7.1.5 struct vm_file_stat_t
File status
See also: See vm_open() (see section 1.7.4.1) for a description of the file protection flags.
Synopsis:
struct vm_file_stat_t { P4_off_t size; P4_file_type_t type; P4_uint32_t fflags; P4_uint32_t vflags; P4_size_t blksize; P4_size_t blkunit; P4_uint32_t cond; P4_uint32_t device; P4_uint32_t inode; P4_uint32_t num_changes; P4_uint32_t num_write_errors; P4_uint32_t queue_length; P4_uint32_t read_avail_count; P4_uint32_t write_avail_count; };
Structure Element Description: size File size, given in units of blkunit. If blkunit is 1, then this is in bytes. The file size is only defined for regular files and properties. For device drivers, depending on driver, the file size may be ignored. type File type fflags File protection flags assigned by the provider. This information may only be different when queries via vm_stat() (see section 1.7.4.9) and vm_fstat() (see section 1.7.4.8), because the provider configuration may be both configured and be driver internal. The actual type of this is vm_file_access_mode_t. These are the bits as returned from the provider, which may allow more or less that what is set up in the VMIT.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 27
vflags File protection flags assigned by VMIT. This member remains uninitialized if a System Extension retrieves a file’s status. This may be a restriction of the port configuration and the provider’s gate configuration, depending on the driver. So this will be the effective permissions checked in vm_open() (see section 1.7.4.1). The actual type of this is vm_file_access_mode_t. Any bits defined in the VMIT may appear here. For files of volume providers this value is set to the maximum possible set of permissions (VM_O_PERM_MASK). blksize Maximum number of bytes transferred in an I/O operation. Device drivers report their maximum supported packet size in blksize. blkunit Block unit that vm_lseek() (see section 1.7.4.10) and vm_read_at() (see section 1.7.4.5)/vm_write_at() use, in bytes. cond Extended status conditions of the file. See VM_STATUS_* in the vm_status_cond_t type, explained in kernelref.pdf. device ID of device used for storing files on volume inode Inode number of the file on volume num_changes Number of changes. This field is maintained by the provider and is usually only used by volume providers. num_write_errors Number of write errors This field is maintained by the provider and is usually only used by volume providers. queue_length Length of the queue, if any. If a provider uses in internal queue, it may choose to report the length of the queue back to the application via this entry. If a driver does report the value back to user space, the default set by the framework is 1. read_avail_count Number of messages available before blocking in read. If a provider uses in internal queue and knows how many messages can be read without blocking, it may choose to report this to the application via this entry. If a driver does report the value back to user space, the default set by the framework is 0. write_avail_count Number of messages available before blocking in write. If a provider uses in internal queue and knows how many messages can be read without blocking, it may choose to report this to the application via this entry. If a driver does report the value back to user space, the default set by the framework is 0.
1.7.2 Defines
VM_FILE_PRIVATE_DATA_SIZE
Description:
Size of the file provider private data area within the PSSW level file descriptor. Given in bytes.
VM_MAX_NUM_FILE_PROVIDER
Description:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
28 The PSSW API
Maximum number of external file providers allowed in a configuration
VM_PATH_DELIM
Description:
Hierarchical file providers may use this as a path delimiter
VM_FP_DELIM
Description:
To separate the file provider and file name parts
VM_FD_IS_KDEV (descr)
Description:
Check whether a descriptor is a kernel level device driver.
1.7.3 Data Type Definitions
vm_file_ioctl_t The vm_file_ioctl_t data type encapsulates an ioctl command specified by an unique identifier
and the overall sizes of the input and output parameters transferred along with the command.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 29
1.7.4 Functions
1.7.4.1 vm_open
Open a file managed by a UniversalisOS file provider.
Synopsis:
P4_e_t vm_open(const char *name, vm_file_access_mode_t oflags, vm_file_desc_t *fd)
Parameters: name IN: File or pathname to open. Pathnames can have up to P4_MAX_EXT_PATHNAME_LEN characters (including the terminating zero). Note: Most providers (except volume providers) do only support up to VM_MAX_PATHNAME_LEN long pathnames. oflags IN: The parameter oflags is a logical combination of zero or more of the following constants:
• VM_O_RD for opening file name for reading,
• VM_O_WR for opening file name for writing,
• VM_O_RD_WR (equal to VM_O_RD | VM_O_WR) for opening file name
• for reading and writing,
• VM_O_EXEC for opening file name to be executed,
• VM_O_RD_WR_EXEC (equal to VM_O_RD | VM_O_WR | VM_O_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.
• VM_O_EXCL if used with VM_O_CREAT the call fails if the file already exists, no effect otherwise
• VM_O_WRLOCK for requesting exclusive write access to the file.
• VM_O_NONBLOCK for requesting non-blocking file operations. Drivers need support for this to
work.
fd OUT: Upon success, the requested file descriptor is saved in fd. In case of error, the content of fd is
unspecified.
Description: The vm_open() (see section 1.7.4.1) call is used to create a new file descriptor for a file or device specified by a pathname. Upon success the function returns 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 if vm_lseek() (see section 1.7.4.10) is supported by the underlying file system. If the file system supports it, this function can also be used to create files. To allow creation of a file that does not exist, the flag VM_O_CREAT should be passed. VM_O_CREAT can be combined with VM_O_EXCL to make vm_open() (see section 1.7.4.1) fail for existing files. Passing VM_O_EXCL without passing VM_O_CREAT leads to unspecified behavior. If the file system supports it, this function can also be used to return file descriptors which can be used exclu- sively for writing into a file. For this purpose VM_O_WRLOCK is used. After successfully opening a file with VM_O_WRLOCK all subsequent opens (for writing) to that file fail. Opening with VM_O_WRLOCK will also fail if any writers on that file already exist. The lock is released when the file descriptor is closed using vm_close()
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
30 The PSSW API
(see section 1.7.4.11). If the file system does not support exclusive writing opening with VM_O_WRLOCK might succeed without locking the file for writing. Note that unlinking or renaming of a locked file might still be possible. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If the function returns anything but P4_E_OK, the contents of fd are unspecified, including the possibility of being overwritten in unspecified ways. Invoking this function on a descriptor that is already in use may cause the descriptor to be overwritten in unspec- ified ways, regardless of whether the new request succeeds or fails. This means that as soon as this function is entered, the passed descriptor must be considered uninitialized until this function returns successfully. This function is not thread safe, i.e., no other operations may be ongoing in other threads on the same descriptor, because there is no protection against data races on the descriptor. Further, the initialization of the descriptor performed by this function is not atomic. Note that except for vm_open() (see section 1.7.4.1), all functions taking a vm_file_desc_t* have undefined behavior before the file descriptor is initialized using vm_open() (see section 1.7.4.1), and also after the descriptor is finalized using vm_close() (see section 1.7.4.11).
Returns: P4_E_OK upon success P4_E_PERM if the caller does not have oflags access rights to file name. if the caller tries to open a file on a volume provider which is not yet mounted. if VM_O_WRLOCK was used and the file has already been opened for writing. if writing was requested and the file has already been opened using another descriptor in conjunction with VM_O_WRLOCK. Note: for opening files in directories of a gate provider, VM_E_EXEC permissions are required, or else P4_E_PERM will be returned. Also note that a gate with an empty name "" will be interpreted as the root di- rectory, so any file name for which no explicit other gate is found will cause the root directory to be indexed. P4_E_NOTIMPL if the file system is not capable to access file name with the access rights oflags. P4_E_NAME if name is too long for the underlying provider. P4_E_NOENT if a file with the name name does not exist. P4_E_INVAL if a parameter is invalid. P4_E_OOFILE if no free file descriptor can be allocated from the partitions file descriptor pool. P4_E_MISMATCH if name is an existing directory. P4_E_LIMIT if there is not enough space available on the volume. P4_E_EXIST if VM_O_CREAT and VM_O_EXCL was used and name is an existing file. P4_E_RESTRICTED if VM_O_WR is given in oflags but the file system is write protected. This may be the case if it was not mounted for writing or it resides on a read-only storage device. P4_E_IO if the storage device containing the file reports a failure. P4_E_NOCONTAINER if a component of the path prefix, except for the last component, of name is not a volume or directory. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled. P4_E_TIMEOUT if VM_O_NONBLOCK was used, the driver needs to block, and the driver supports VM_O_NONBLOCK. If the call applies to an external file provider, additional error codes may be returned. Please refer to the docu- mentation of the according file provider.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 31
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
See also: vm_close() (see section 1.7.4.11)
Note: The flag VM_O_NONBLOCK is used to select non blocking operations on files. If supported by the underly- ing provider functions which do not support to specify a timeout (like vm_read() (see section 1.7.4.3)) will use P4_TIMEOUT_NULL internally in order to not block. If those functions are called from System Extensions inside partition daemon threads on files managed by kernel level device drivers, it is recommended to use VM_O_NON- BLOCK in the prior vm_open() (see section 1.7.4.1). Partition daemon threads must not block in order to not disturb scheduling. Please also note that vm_open() (see section 1.7.4.1) itself may block. Thus it is also discouraged to call vm_open() (see section 1.7.4.1) on kernel level device drivers from within partition daemon threads.
See also: Documentation of the underlying file provider
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
32 The PSSW API
1.7.4.2 vm_open_at
Open a file relative a directory.
Synopsis:
P4_e_t vm_open_at(vm_file_desc_t *parent, const char *name, P4_uint32_t oflags, vm_file_desc_t *child)
Parameters: parent INOUT: Directory where to open the file. name IN: The name of the file to open. The length of the string including the terminating NUL character must not exceed P4_MAX_EXT_PATHNAME_LEN bytes. oflags IN: Open flags just like in vm_open() (see section 1.7.4.1) child OUT: The new file descriptor.
Description: This is basically like vm_open() (see section 1.7.4.1), but allows specification of a file descriptor pointing to a directory relative to which the open request should be done. Note that there is no ’.’ and particularly no ’..’, so you cannot go upward in the directory hierarchy. This is important for access permission checking. If the function returns anything but P4_E_OK, the contents of child are unspecified, including the possibility of being overwritten in unspecified ways. This function has undefined behavior unless parent is an open file descriptor. The exact implementation of how a path is interpreted is in the hands of the file provider that gets the request, but UniversalisOS describes the following standard behavior: the path separator is ’/’. Multiple slashes are interpreted just like a single separator. Initial and final ’/’ characters are ignored. Passing name="" duplicates the parent file descriptor.
Returns: P4_E_OK in case of success. P4_E_INVAL if parent is not a valid file descriptor. if a parameter is invalid. Note that uninitialized descriptors cannot reliably be identified as invalid. Additionally, this returns the same error codes as vm_open() (see section 1.7.4.1).
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 33
1.7.4.3 vm_read
Read from a file managed by a UniversalisOS file provider.
Synopsis:
P4_e_t vm_read(vm_file_desc_t *fd, void *buff, P4_size_t buff_size, P4_size_t *read_size)
Parameters: fd IN: File descriptor for reading buff OUT: Pointer to the receive buffer. It must have at least a size of buff_size bytes. buff_size IN: Number of bytes to read read_size OUT: The number of bytes actually read is stored in read_size.
Description: vm_read() (see section 1.7.4.3) tries to read buff_size bytes from the file given by the descriptor fd and stores the result in buff. Concurrent read operations are processed sequentially in priority order of the callers for requests to external file providers and system extensions. For gate providers, the order is FIFO by default but can be switched to priority by passing the VM_O_PRIO open flag to vm_open() (see section 1.7.4.1). This flag is a hint to the gate provider, and ultimately, the order is determined by the gate provider. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. The time of the update of the file position is unspecified, i.e., it is not thread safe to run sequences of vm_lseek() (see section 1.7.4.10) followed by vm_read() (see section 1.7.4.3) concurrently. vm_read_at() (see section 1.7.4.5) can be used for this, because it is stateless wrt. the file position. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of read_size are unspecified, including the possibility of being overwritten in unspecified ways. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of buff are unspecified, including the possibility of being overwritten in unspecified ways.
Returns: P4_E_OK upon success P4_E_PERM if the file fd was not opened for reading. P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_SIZE if size is invalid P4_E_OVERFLOW arithmetic overflow of the seek position, which mean that the position is outside of what the file system can handle. P4_E_PAGEFAULT the buff is not fully mapped or not fully writable. P4_E_INVAL if buff is not fully located in the user accessable virtual memory space. P4_E_INVAL if the seek position is beyond the end of the file or device and this cannot be handled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
34 The PSSW API
P4_E_INVAL e.g. if fd is not a valid file descriptor. if a parameter is invalid. Note that uninitialized descriptors
cannot reliably be identified as invalid.
P4_E_OOMEM if system resources have been exhausted.
P4_E_TRUNC if the responsible provider works message oriented, the user buffer was too small to carry all
data of a packet. In this case buff and read_size contain valid data.
P4_E_TIMEOUT if the file was opened with a VM_O_NONBLOCK flag, and the driver supports non-blocking
operation, and if there is no data to be transferred, then instead of blocking for data, P4_E_TIMEOUT
will be returned.
P4_E_IO if the storage device containing the file reports a failure. *
P4_E_LIMIT if there was packet loss since the last reading of a message, i.e., the queue was full, but more
messages arrived and could not be stored. Devices that implement handshaking between reader and
writer will not ever produce this message, because the writer will block until the queue becomes free for
another message. However, devices that cannot stop messages from coming in may signal this (e.g.,
network devices).
P4_E_TRUNC if the message was received from hardware without knowing its exact size, but it turned out the
message was too large for the given buffer, i.e., there was data loss in the attempt to copy the message
into the user buffer. This will only happen for devices that have no knowledge of the size of the message
in the queue prior to copying it to the user. Devices that know that the message is too large will instead
return P4_E_SIZE.
P4_E_ABORT if the call was aborted.
P4_E_CANCEL if the call was canceled.
If the call applies to an external file provider, additional error codes may be returned. Please refer to the docu- mentation of the according file provider.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: Depending on the actual file provider attached to fd it is possible that this call blocks until the request is satisfied. There is no means to change this behavior.
Note: When invoked from a System Extension, read_size may be NULL. When invoked from a resource partition, read_size must not be NULL.
Note: Due to internal limitations of the underlying file provider attached to fd a call to vm_read may transfer fewer bytes than requested and even fewer bytes than available. In other words, vm_read(fd, buf, 4096, NULL) may transfer less than 4096 bytes, even if 4096 bytes or more are available in the file referenced by fd. Thus, you should always supply read_size and compare the number of bytes actually read to the number of bytes requested.
See also: Documentation of the underlying file provider
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 35
1.7.4.4 vm_write
Write to a file managed by a UniversalisOS file provider.
Synopsis:
P4_e_t vm_write(vm_file_desc_t *fd, const void *buff, P4_size_t buff_size, P4_size_t *written_size)
Parameters: fd IN: File descriptor for writing buff IN: Pointer to the transmit buffer. buff_size IN: Number of bytes to write written_size OUT: The number of bytes actually written is stored in written_size.
Description: vm_write() (see section 1.7.4.4) tries to write buff_size bytes to the file given by the descriptor fd from the buffer starting at buff. The order of the requests is handled in the same way as for vm_read() (see section 1.7.4.3). Upon success the file position is advanced accordingly if random access is supported. Depending on the underlying file system it is not guaranteed that calling vm_read() (see section 1.7.4.3) after vm_write() (see section 1.7.4.4) with the proper file position returns the new data. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. The time of the update of the file position is unspecified, i.e., it is not thread safe to run sequences of vm_lseek() (see section 1.7.4.10) followed by vm_write() (see section 1.7.4.4) concurrently. vm_write_at() (see section 1.7.4.6) can be used for this, because it is stateless wrt. the file position. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of written_size are unspecified, including the possibility of being overwritten in unspecified ways.
Returns: P4_E_OK upon success 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_NOTIMPL if the responsible provider does not support this operation. P4_E_SIZE if size is invalid P4_E_OVERFLOW arithmetic overflow of the seek position, which mean that the position is outside of what the file system can handle. P4_E_PAGEFAULT if buff is not entirely mapped. P4_E_INVAL if an invalid buff_size == 0 was given or the buffer is not fully located in the user accessable virtual memory range. P4_E_INVAL if the seek position is beyond the end of the file or device and this cannot be handled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
36 The PSSW API
P4_E_INVAL if a parameter is invalid, e.g., if the file descriptor is invalid. Note that uninitialized descriptors
cannot be reliably identified as invalid.
P4_E_OOMEM if the buffer could not be mapped due to a lack of system resources.
P4_E_TRUNC if the responsible provider works message oriented, the user buffer was too large to be written
in a single call. written_size will contain valid data in this case.
P4_E_TIMEOUT if the file was opened with a VM_O_NONBLOCK flag, and the driver supports non-blocking
operation, and if there is no data to be transferred, then instead of blocking for data, P4_E_TIMEOUT
will be returned.
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_ABORT if the call was aborted.
P4_E_CANCEL if the call was canceled.
If the call applies to an external file provider, additional error codes may be returned. Please refer to the docu- mentation of the according file provider.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: Depending on the actual file system attached to fd it is possible that this call blocks until the request is satisfied. There is no means to change this behavior.
Note: When invoked from a System Extension, written_size may be NULL. When invoked from a resource partition, written_size must not be NULL.
See also: Documentation of the underlying file provider
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 37
1.7.4.5 vm_read_at
Read with offset from a file managed by a UniversalisOS file provider.
Synopsis:
P4_e_t vm_read_at(vm_file_desc_t *fd, void *buff, P4_size_t buff_size, P4_off_t offset, P4_size_t *read_size)
Parameters: fd IN: File descriptor for reading. buff IN: Pointer to the receive buffer. It must have at least a size of buff_size bytes. buff_size IN: Number of bytes to read. offset IN: Offset from which to read. See vm_lseek() (see section 1.7.4.10) for an description of offset values. read_size OUT: The number of bytes actually read is stored in read_size.
Description: vm_read_at() (see section 1.7.4.5) works like vm_read() (see section 1.7.4.3), but allows specification of offset from which to read. In contrast to vm_read() (see section 1.7.4.3), vm_read_at() (see section 1.7.4.5) does not alter the logical file position. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of read_size are unspecified, including the possibility of being overwritten in unspecified ways. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of buff are unspecified, including the possibility of being overwritten in unspecified ways. If the service is used to read a directory entry of a directory file in the property file system the resulting string located in buff is guaranteed to be NUL-terminated if buff_size is greater than 0. If buff_size is greater than 0 and too small to hold the name of the directory entry including the NUL-termination the name is truncated and NUL-terminated after buff_size - 1 characters and the service returns P4_E_TRUNC.
Returns: See vm_lseek() (see section 1.7.4.10) and vm_read() (see section 1.7.4.3) for a list of return codes.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
38 The PSSW API
1.7.4.6 vm_write_at
Write with offset to a file managed by a UniversalisOS file provider.
Synopsis:
P4_e_t vm_write_at(vm_file_desc_t *fd, const void *buff, P4_size_t buff_size, P4_off_t offset, P4_size_t *written_size)
Parameters: fd IN: File descriptor for writing. buff IN: Pointer to the transmit buffer. buff_size IN: Number of bytes to write. offset IN: Offset from which to write. See vm_lseek() (see section 1.7.4.10) for an description of offset values. written_size OUT: The number of bytes actually written is stored in written_size.
Description: vm_write_at() (see section 1.7.4.6) works like vm_write() (see section 1.7.4.4), but allows specification of offset at which to write. In contrast to vm_write() (see section 1.7.4.4), vm_write_at() (see section 1.7.4.6) does not alter the logical file position. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of written_size are unspecified, including the possibility of being overwritten in unspecified ways.
Returns: See vm_lseek() (see section 1.7.4.10) and vm_write() (see section 1.7.4.4) for a list of return codes.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 39
1.7.4.7 vm_discard_at
Discard content in a UniversalisOS file provider.
Synopsis:
P4_e_t vm_discard_at(vm_file_desc_t *fd, P4_off_t discard_sz, P4_off_t offset, P4_off_t *discarded_sz)
Parameters: fd IN: File descriptor for discarding. discard_sz IN: Number of bytes to discard. To discard everything, pass P4_OFF_MAX. Some providers might not be able to selectively discard data. These providers will return P4_E_INVAL if anything but P4_OFF_MAX is passed to this function. offset IN: File position to start the discarding process. discarded_sz OUT: The number of bytes actually discarded is stored in written_size. Some providers may not be able to exactly define how much data was discarded. Such providers may return P4_OFF_MAX to indicate that everything was cleared.
Description: This function may have different meanings depending on the underlying file provider. The two possible function- alities are: (1) consuming content that will not be returned by vm_read() (see section 1.7.4.3) anymore, with- out actually reading and thus transferring content, and (2) resetting to a state just after vm_open() (see section 1.7.4.1). (2) might do more than (1), e.g. in a sampling port, vm_read() (see section 1.7.4.3) cannot reset a port to containing no data at all, while this function can. Depending on the underlying file provider, this may be a read or a write operation, e.g. for a queuing port, it is assumed to be a read operation that consumes everything, while for a sampling port, it is a write operation that resets the port to a state otherwise not accessible. There are functions vm_qport_clear() (see section 1.9.4.12) and vm_sport_clear() (see section 1.9.4.24) in the port provider API that correspond to this function’s functionality. Some drivers may support selective discarding, e.g. an SSD driver may implement discarding a single block of the underlying device. Therefore, this function takes a file position and the size of bytes to be discarded can be specified. To discard everything, pass ~0UL for the size parameter. The file position returned is the position behind the last discarded byte in the file. A full discard of the whole content will thus reset the file position to the beginning of the file. This function uses an additional ’t’ in its name compared to other functions like vm_read() (see section 1.7.4.3) to indicate that the API of passing the offset is read/write, i.e., a pointer to the offset is passed. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of discarded_sz are unspecified, including the possibility of being overwritten in unspecified ways.
Returns:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
40 The PSSW API
P4_E_OK upon success
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_NOTIMPL if the responsible provider does not support this operation.
P4_E_SIZE if discard_sz is invalid
P4_E_OVERFLOW if the seek position causes an arithmetic overflow
P4_E_INVAL if the seek position is beyond the end of the file or device and this cannot be handled.
P4_E_INVAL if a parameter is invalid, e.g., if fd is not a valid file descriptor. Note that uninitialized descriptors
cannot reliably be identified as invalid.
P4_E_TIMEOUT if the file was opened with a VM_O_NONBLOCK flag, and the driver supports non-blocking
operation, and if there is no data to be transferred, then instead of blocking for data, P4_E_TIMEOUT
will be returned.
P4_E_IO if the storage device containing the file reports a failure.
P4_E_ABORT if the call was aborted.
P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task, otherwise the result is undefined.
Note: Depending on the actual file system attached to fd it is possible that this call blocks until the request is satisfied. There is no means to change this behavior.
See also: Documentation of the underlying file provider
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 41
1.7.4.8 vm_fstat
Return status information of an open file managed by a UniversalisOS file provider.
Synopsis:
P4_e_t vm_fstat(vm_file_desc_t *fd, vm_file_stat_t *stat)
Parameters: fd IN: File descriptor stat OUT: Upon success, the structure elements at status are filled in. In case of error, the content is unspecified.
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. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. If the function returns anything but P4_E_OK, the contents of status are unspecified, including the possibility of being overwritten in unspecified ways.
Returns: P4_E_OK upon success P4_E_NOTIMPL if the responsible provider does not support this operation P4_E_INVAL if a parameter is invalid, e.g., if fd is not a valid file descriptor. Note that uninitialized descriptors cannot reliably be identified as invalid. P4_E_IO if the storage device containing the file reports a failure. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled. If the call applies to an external file provider, additional error codes may be returned. Please refer to the docu- mentation of the according file provider.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
See also: vm_stat() (see section 1.7.4.9)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
42 The PSSW API
1.7.4.9 vm_stat
Return status information of a file managed by a UniversalisOS file provider given the file name.
Synopsis:
P4_e_t vm_stat(const char *name, vm_file_stat_t *stat)
Parameters: name IN: File or pathname. Pathnames can have up to P4_MAX_EXT_PATHNAME_LEN characters (in- cluding the terminating zero). Note: Most providers (except volume providers) do only support up to VM_MAX_PATHNAME_LEN long pathnames. stat OUT: Upon success, the structure elements at status are filled in. In case of error, the content is unspecified.
Description: Provide several information about the current status of file given by name. See the description of vm_file_stat_t for the list of properties available. During the execution of this call one file descriptor is allocated, and freed before the call returns. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If the function returns anything but P4_E_OK, the contents of status are unspecified, including the possibility of being overwritten in unspecified ways.
Returns: P4_E_OK upon success P4_E_PERM if the caller does not have the stat permission to access file name. Note: check vm_open() (see section 1.7.4.1) for a more detailed description of this error code. P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_NAME if name is too long for the underlying provider. P4_E_NOENT if file name does not exist. P4_E_INVAL if a parameter is invalid P4_E_OOFILE if system resources have been exhausted, e.g. there is no free file descriptor. P4_E_IO if the storage device containing the file reports a failure. P4_E_NOCONTAINER a component of the path prefix of name is not a volume or directory. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled. If the call applies to an external file provider, additional error codes may be returned. Please refer to the docu- mentation of the according file provider.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: If the call applies to an external file provider, this request is routed to the provider in the same way as a vm_open() (see section 1.7.4.1) call. It is not completely handled by the PSSW.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 43
See also: vm_fstat() (see section 1.7.4.8)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
44 The PSSW API
1.7.4.10 vm_lseek
Change file pointer position in a file managed by a UniversalisOS file provider.
Synopsis:
P4_e_t vm_lseek(vm_file_desc_t *fd, P4_off_t offset, P4_origin_t origin, P4_off_t *new_offset)
Parameters: fd IN: File descriptor offset IN: Offset to change file position, can be negative. This counts blkunits (
See also:
vm_file_stat_t). If blkunit is 1, this is in bytes.
origin IN: How to interpret offset, see detailed description below
new_offset OUT: Upon success, the new file position is returned in new_offset. In case of error, this value is
unspecified. Like offset, this is in units of vm_file_stat_t:blkunit.
Description: The vm_lseek() (see section 1.7.4.10) function repositions the offset of the file descriptor fd 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.
The unit of a seek command depends on the file provider. For normal file semantics, this is in bytes, which is indicated by a block unit of 1 (see vm_file_stat_t:blkunit). Other values of blkunit indicate that the provider is package based and can seek only to full packets with a (maximum) size of blkuint each. Some system extensions may interpret this specially, e.g., like the property file system that disallows seek, but interprets the offset in read_at() is an index of an entry of a directory. Note that to be consistent with existing APIs, block drivers typically still use a byte count for positioning. Strictly speaking, the blkunit is a hint only drivers may interpret seek amounts as they see fit. However, if they implement file or packet based semantics for seeking, drivers should stick to the description above, because that is the expected behavior. The offset can also be negative, allowing to position relative to the current position in both directions. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. If the function returns anything but P4_E_OK, the contents of new_filepos are unspecified, including the possibility of being overwritten in unspecified ways.
Returns: P4_E_OK upon success
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 45
P4_E_PERM if fd has not been opened with read or write permission. P4_E_NOTIMPL if the responsible provider does not support this operation, e.g., if the file does not support the notion of a file position. P4_E_OVERFLOW if seeking to the the new file position caused an integer overflow in the ’P4_off_t’ type or resulted in a negative value. P4_E_INVAL if offset is out of range, or the resulting file position will be negative. P4_E_INVAL if a parameter is invalid, e.g., if fd is not a valid file descriptor. Note that uninitialized descriptors cannot reliably be identified as invalid. P4_E_IO if the underlying file system reports an I/O error when trying to complete outstanding file operations. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled. If the call applies to an external file provider, additional error codes may be returned. Please refer to the docu- mentation of the according file provider.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: Depending on the underlying file system, it might not be possible to extend a file’s size by using vm_lseek() (see section 1.7.4.10) to position over the current file size. An error code P4_E_INVAL will be returned in this case.
See also: Documentation of the underlying file provider
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
46 The PSSW API
1.7.4.11 vm_close
Close a file managed by a UniversalisOS file provider.
Synopsis:
P4_e_t vm_close(vm_file_desc_t *fd)
Parameters: fd IN: File descriptor
Description: This function closes an open file descriptor fd, so that it no longer refers to any file and may be reused. After closing a file descriptor, it must no longer be used to access a file. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. The contents of fd will be unspecified in case this function returns P4_E_OK. In case of an error, the contents of fd will remain unchanged, because the error may indicate a temporary failure so that the closing could be repeated later.
Returns: P4_E_OK upon success P4_E_INVAL if a parameter is invalid, e.g., if fd is not a valid file descriptor, or is in in use or in the process of being closed by another thread. Note that uninitialized descriptors cannot reliably be identified as invalid. P4_E_INVAL if the descriptor is in use by another thread. This may happen for some driver frameworks, e.g. KDEV, but not for others, e.g. ExtFP, based on the capabilities of the respective framework to trigger termination of concurrent requests. P4_E_IO if the underlying file system reports an I/O error when trying to complete outstanding file operations. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled. If an external file provider is to be closed, additional error codes may be returned. Please refer to the documenta- tion of the according file provider.
Note: Depending on the underlying file system, closing the file descriptor might force writing cached data into a file, which is an operation that might fail. The only place to get aware of this error is the vm_close() (see section 1.7.4.11) call.
Note: Depending on the underlying file system this call might block until a pending operation finishes. Thus it is discouraged to call vm_close() (see section 1.7.4.11) on kernel level device drivers from within partition daemon threads (in a System Extension).
Note:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 47
Close should not depend on the setting of the VM_O_NONBLOCK setting, but must, if necessary, block instead of failing. Otherwise, partition reboot would be broken because the partition reboot cannot handle failures (including deferrals) in close.
See also: vm_open() (see section 1.7.4.1)
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
48 The PSSW API
1.7.4.12 vm_map
Map or remap (parts of) a file managed by a UniversalisOS file provider into caller’s address space.
Synopsis:
P4_e_t vm_map(vm_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 start)
Parameters: fd IN: File descriptor of a file opened with VM_O_MAP permissions. 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.
Additionally, the VM_MEM_ACCESS_EXCL bit may be used to prohibit overmapping, i.e., it has the
opposite meaning of P4_M_REPLACE as documented e.g. for p4_mem_create().
The interpretation of this parameter depends on the underlying file provider. A file mapped write-only
may still be read without causing an exception. Also, some file providers may ignore the VM_MEM_AC-
CESS_EXCL bit.
flags IN: Map flags. This parameter is ignored.
start IN: Virtual address in caller’s address space where to map the file.
Description: The vm_map() (see section 1.7.4.12) function tries to map size bytes starting at offset offset from the 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. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor.
Returns: P4_E_OK upon success P4_E_PERM if the partition does not have prot access rights to file fd. P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_SIZE if size is invalid
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 49
P4_E_OVERFLOW if offset causes an arithmetic overflow P4_E_INVAL if the file is not suited for memory mapping P4_E_INVAL if a parameter is invalid, e.g., if fd is not a valid file descriptor. Note that uninitialized descriptors cannot reliably be identified as invalid. P4_E_TIMEOUT if the file was opened with a VM_O_NONBLOCK flag, and the driver supports non- blocking operation, and if the operation would need to block to be performed, then instead of blocking, P4_E_TIMEOUT will be returned. P4_E_NOKMEM if the file could not be mapped completely because of an insufficient. amount of free kernel memory. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Note: If the call applies to an external file provider, this request is routed to the provider in the same way as a vm_open() (see section 1.7.4.1) call. It is not completely handled by the PSSW.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: There is no function in this API to remove a mapping.
See also: UniversalisOS Kernel Reference Manual for more information on memory mapping
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
50 The PSSW API
1.7.4.13 vm_ioctl
Provider specific control function.
Synopsis:
P4_e_t vm_ioctl(vm_file_desc_t *fd, vm_file_ioctl_t cmd, void *data)
Parameters: fd IN: File descriptor of an open file cmd Command data Command specific data
Description: This function offers a general purpose interface to file providers. Each provider is free to support vm_ioctl() (see section 1.7.4.13) 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. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. The behavior of this function in case data is NULL is implementation-defined, i.e., it depends on the underlying driver how the function will behave. The contents of the memory pointed to by data after the call to this function is implementation-defined, i.e., it depends on the underlying driver how data is handled, and in which cases the data contents are specified or unspecified.
Returns: P4_E_OK upon success P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_INVAL if a parameter in invalid, e.g., if fd is invalid. Note that uninitialized descriptors cannot reliably be identified as invalid. P4_E_TIMEOUT if the file was opened with a VM_O_NONBLOCK flag, and the driver supports non- blocking operation, and if the operation would need to block to be performed, then instead of blocking, P4_E_TIMEOUT will be returned. P4_E_IO if the storage device containing the file reports a failure. If an external file provider is opened, additional error codes may be returned. Please refer to the documentation of the according file provider. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 51
1.7.4.14 vm_test
Control the driver’s test mode.
Synopsis:
P4_e_t vm_test(vm_file_desc_t *fd, vm_test_mode_t tm, P4_uint32_t cmd)
Parameters: fd IN: File descriptor of an open file tm IN: which test mode to select cmd IN: arbitrary command for the provider
Description: This function can be used to access the driver’s test features. The exact functionality is up to the driver, this is a generic API passing down commands to the driver to activate/deactivate synchronous or asynchronous tests. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor.
Returns: P4_E_OK upon success P4_E_PERM the driver does not grant access permissions to testing on the given descriptor. P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_INVAL if a parameter is invalid, e.g., if fd does not belong to an open file. Note that uninitialized descriptors cannot reliably be identified as invalid. P4_E_TIMEOUT if the file was opened with a VM_O_NONBLOCK flag, and the driver supports non- blocking operation, and if the operation would need to block to be performed, then instead of blocking, P4_E_TIMEOUT will be returned. P4_E_IO if the storage device containing the file reports a failure. The driver may return more errors if needed. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: Please also see the documentation for vm_test_mode_t.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
52 The PSSW API
1.7.4.15 vm_fsync
Sync the file state to the storage device.
Synopsis:
P4_e_t vm_fsync(vm_file_desc_t *fd)
Parameters: fd IN: File descriptor.
Description: The function writes all modified data and meta data of the file to storage device. The call blocks until the device reports that the transfer was completed. Due to the synchronous behavior of certain file systems (like CFS) it may also be that vm_fsync() (see section 1.7.4.15) is actually implemented as an empty function call and all data can be considered persistently written to storage on the return of other file system functions. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. This function ignores the VM_O_NONBLOCK flag and will always run with by default with an infinite timeout.
Returns: P4_E_OK upon success P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_INVAL if a parameter is invalid, e.g. if fd is not a valid file descriptor. Note that uninitialized descriptors cannot reliably be identified as invalid. P4_E_IO if the storage device containing the file reports failure. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Note: If the call applies to a volume provider, additional error codes may be returned. Please refer to the documentation of the corresponding volume provider.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File System 53
1.7.4.16 vm_map_to
Map or remap (parts of) a file managed by a UniversalisOS file provider into another address space.
Synopsis:
P4_e_t vm_map_to(vm_file_desc_t *fd, P4_task_t task, P4_off_t offset, P4_size_t size, vm_memory_access_mode_t prot, P4_uint32_t flags, P4_address_t start)
Parameters: fd IN: File descriptor. task IN: Task in which the mapping should be installed. 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 flags IN: Map flags. This parameter is ignored. start IN: Virtual address in caller’s address space where to map the file.
Description: The vm_map_to() (see section 1.7.4.16) function tries to map size bytes starting at offset offset from the file given by fd into the given task 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.
Returns: P4_E_OK upon success P4_E_INVAL if the file is not suited for memory mapping, or at least one of the parameters offset, size, start or prot is invalid. P4_E_BADTASK if the task task is not a primary application task, i.e. a direct child task of the SSW task. P4_E_NOKMEM if the file could not be mapped completely. P4_E_NOTIMPL if the responsible provider does not support this operation.
Note: This call is only available to system extensions. There is no function in this API to remove a mapping.
See also: UniversalisOS Kernel Reference Manual for more information on memory mapping
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
54 The PSSW API
1.8 Extended File System
This section describes extended functionality to of the UniversalisOS virtual file system layer. This includes creation, deletion, rename of files as well as directory operations.
1.8.1 Structure Definitions
1.8.1.1 struct vm_dir_t
Synopsis: struct vm_dir_t { P4_uint32_t sig; vm_directory_handle_t handle; P4_bool_t is_kdev; P4_uid_t read; P4_uid_t write; P4_uid_t close; };
Structure Element Description: sig Structure signature to protect against misuse. handle Directory handle. Fully maintained by the volume provider. is_kdev Volume provider type. KDEV vs. User Level read The file provider’s read daemon. Set by the volume provider’s dir_open entry point to the UID of the thread which shall handle read requests to this file descriptor. write The file provider’s write daemon. Set by the volume provider’s dir_open entry point to the UID of the thread which shall handle write requests to this file descriptor. close The file provider’s close daemon. Set by a volume provider’s mount entry point to the UID of the thread which shall handle close requests on files.
1.8.2 Data Type Definitions
vm_directory_handle_t Handle of an opened directory associated to a file descriptor.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Extended File System 55
1.8.3 Functions
1.8.3.1 vm_unlink
Delete the path and possibly the file or the directory it refers to.
Synopsis:
P4_e_t vm_unlink(const char *path, P4_unlink_flags_t flags)
Parameters: path IN: Path to the file which will be deleted. flags IN: flags
Description: Delete the path from the file system. If the path 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. Depending on the file system it is possible that during the execution of this call one file descriptor is allocated, and freed before the call returns. 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. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success 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_NOTIMPL if the responsible provider does not support this operation. This could also occur if e.g. path refers to a directory. P4_E_NAME if path is too long for the underlying provider. P4_E_NOENT if file path does not exist. P4_E_INVAL if a parameter is invalid P4_E_IO if the storage device containing path reports failure. P4_E_NOCONTAINER if a component of the path prefix of path is not a volume or directory. 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_OOFILE if no free file descriptor can be allocated (if needed for this call) P4_E_STATE if path is a directory and it is not empty. P4_E_RESTRICTED if path refers to a file on a read-only filesystem. P4_E_ABORT if the call was aborted.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
56 The PSSW API
P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: If the call applies to a volume provider, additional error codes may be returned. Please refer to the documentation of the corresponding volume provider.
Note: If the call applies to a volume provider, this request is routed to the provider in the same way as a vm_open() (see section 1.7.4.1) call. It is not completely handled by the PSSW.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Extended File System 57
1.8.3.2 vm_rename
Change the name or location of a file or directory.
Synopsis:
P4_e_t vm_rename(const char *old_path, const char *new_path, P4_rename_flags_t flags)
Parameters: old_path IN: The path to the file that will be renamed. new_path IN: The path the file will be renamed to. flags IN: flags
Description: Rename a file or directory and move it between directories if required. Open file or directory descriptors may be unaffected as well (depending on the file system). The semantics of this call depends on the flags parameter. If P4_RENAME_NO_DIR is set in flags, the function renames no directories, which corresponds to file renaming according to the ARINC 653 RENAME_FILE() service. Likewise, the flag P4_RENAME_DIR_ONLY is used to indicate that only directories are to be renamed, according to RENAME_DIRECTORY(). The two flags cannot sensibly be used at the same time, and drivers may react by rejecting both file and directory rename requests. If P4_RENAME_NO_REPLACE is specified, the function will fail if the new name already exists in the file system, i.e., it will not replace the existing file by the renamed one. Depending on the file system, it is possible that for performing the operation, a file descriptor is internally allocated, and freed before the call returns. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success P4_E_PERM if permission is denied for one of the directories in the path prefix in old_path or new_path. P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_NAME if path is too long for the underlying provider. P4_E_NOENT if old_path does not exist. P4_E_INVAL if new_path is a subdirectory of old_path P4_E_INVAL if a parameter is invalid P4_E_INVAL if both P4_RENAME_NO_NIR and P4_RENAME_DIR_ONLY is set in flags P4_E_LIMIT if 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 if 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_OOFILE if no free file descriptor can be allocated (if needed for this call)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
58 The PSSW API
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 old_path refers to a file or directory on a read-only file system.
P4_E_ABORT if the call was aborted.
P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: If the call applies to a volume provider, additional error codes may be returned. Please refer to the documentation of the corresponding volume provider.
Note: If the call applies to a volume provider, this request is routed to the provider in the same way as a vm_open() (see section 1.7.4.1) call. It is not completely handled by the PSSW.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Extended File System 59
1.8.3.3 vm_statvfs
Get file system statistics.
Synopsis:
P4_e_t vm_statvfs(const char *path, P4_statvfs_t *buf)
Parameters: 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.
Description: This function retrieves information about the filesystem. This can be e.g. the available space on the storage medium. Depending on the file system it is possible that during the execution of this call one file descriptor is allocated, and freed before the call returns. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If this function returns anything but P4_E_OK, the contents of buf are unspecified.
Returns: P4_E_OK upon success P4_E_PERM if permission is denied for one of the directories in the path prefix in old_path or new_path. P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_NAME if path is too long for the underlying provider. P4_E_NOENT if file name does not exist. P4_E_INVAL if name is not a valid file name P4_E_INVAL if a parameter is invalid P4_E_OOFILE if no free file descriptor can be allocated (if needed for this call) 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_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: If the call applies to a volume provider, this request is routed to the provider in the same way as a vm_open() (see section 1.7.4.1) call. It is not completely handled by the PSSW.
Note: If the call applies to a volume provider, additional error codes may be returned. Please refer to the documentation of the corresponding volume provider.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
60 The PSSW API
1.8.3.4 vm_ftruncate
Truncate file to a specific length.
Synopsis:
P4_e_t vm_ftruncate(vm_file_desc_t *fd, P4_off_t length, P4_truncate_flags_t flags)
Parameters: fd IN: File descriptor. length IN: The size in bytes the file will be set to. flags IN: Flags for the operation (P4_TRUNCATE_*).
Description: This function changes the size of the regular file represented by the fd file descriptor to the size of new_size in bytes. This function sets the file position in fd to behind the new end of the file if and only if the flag P4_TRUN- CATE_SET_FPOS is passed. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor.
Returns: P4_E_OK upon success P4_E_PERM if the file not open for writing. P4_E_NOTIMPL if the responsible provider does not support this operation, or of the driver does not support lseek (i.e., has no support for the notion of a file position). P4_E_INVAL if a parameter is invalid, e.g., if fd is not a valid file descriptor P4_E_LIMIT if there is not enough space on the device to extend the file. P4_E_IO if the storage device containing the file reports failure. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Note: If the call applies to a volume provider, additional error codes may be returned. Please refer to the documentation of the corresponding volume provider.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Extended File System 61
1.8.3.5 vm_dir_create
Create an empty directory with name path.
Synopsis:
P4_e_t vm_dir_create(const char *path)
Parameters: path IN: Path name to the directory that will be created.
Description: The vm_dir_create() (see section 1.8.3.5) call is used to create new directory. The directory will be empty. Depending on the file system it is possible that during the execution of this call one file descriptor is allocated, and freed before the call returns. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success P4_E_PERM Permission is denied for one of the directories in the path prefix in path or the write permission is denied to the parent directory of path. P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_NAME if path is too long for the underlying provider. P4_E_INVAL if a parameter is invalid P4_E_LIMIT There is not enough space on the device to store the new directory. P4_E_OOFILE if no free file descriptor can be allocated from the partitions file descriptor pool. P4_E_IO if the storage device containing path reports failure. P4_E_NOCONTAINER if a component of the path prefix of path is not a volume or directory. P4_E_EXIST if path is an existing file. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Note: If the call applies to a volume provider, additional error codes may be returned. Please refer to the documentation of the corresponding volume provider.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
See also: vm_unlink() (see section 1.8.3.1)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
62 The PSSW API
1.8.3.6 vm_dir_open
Open a directory.
Synopsis:
P4_e_t vm_dir_open(const char *path, vm_dir_t *dir)
Parameters: path IN: Path of the directory being opened. dir OUT: The directory stream.
Description: This function opens a directory stream corresponding to the directory path. The file position is set to the beginning of the file. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If the function returns anything but P4_E_OK, the contents of dir are unspecified, including the possibility of being overwritten in unspecified ways.
Returns: P4_E_OK upon success P4_E_PERM if the caller does not have enough access rights to open directory path. P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_NAME if path is too long for the underlying provider. P4_E_NOENT if a file with the name path does not exist. P4_E_INVAL if a parameter is invalid P4_E_NOCONTAINER if path is not a directory or a component of the path prefix of path is not a volume or directory. P4_E_OOFILE if no free directory descriptor can be allocated from the partitions directory descriptor pool. P4_E_IO if the storage device containing path reports failure. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Note: If the call applies to a volume provider, additional error codes may be returned. Please refer to the documentation of the corresponding volume provider.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
See also: vm_dir_close() (see section 1.8.3.8)
Note:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Extended File System 63
There is no flag to select non blocking operations on directories. Depending on the underlying file system each directory operation might block for an infinite time.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
64 The PSSW API
1.8.3.7 vm_dir_read_at
Read a directory.
Synopsis:
P4_e_t vm_dir_read_at(vm_dir_t *dir, P4_off_t *pos, P4_dirent_t *dirent)
Parameters: dir IN: The open directory pos INOUT: 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() (see section 1.8.3.7) or zero can be provided in this parameter. dirent OUT: The buffer that will be filled with the retrieved directory entry.
Description: The call reads a directory entry structure from the directory file at the given position pos. If the end of the directory was reached the name item of the dirent parameter contains empty string. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless dir is an open directory descriptor. The contents of dir will be unspecified in case this function returns P4_E_OK. In case of an error, the contents of dir will remain unchanged, because the error may indicate a temporary failure so that the closing could be repeated later. If the function returns anything but P4_E_OK, the contents of dirent are unspecified, including the possibility of being overwritten in unspecified ways.
Returns: P4_E_OK upon success P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_INVAL if a parameter is invalid, e.g., if dir is not a valid open directory. P4_E_IO if the storage device containing the directory reports failure. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Note: If the call applies to a volume provider, additional error codes may be returned. Please refer to the documentation of the corresponding volume provider.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Extended File System 65
Depending on the actual provider attached to dir it is possible that this call blocks until the request is satisfied. There is no means to change this behavior.
See also: Documentation of the underlying file provider
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
66 The PSSW API
1.8.3.8 vm_dir_close
Close a directory.
Synopsis:
P4_e_t vm_dir_close(vm_dir_t *dir)
Parameters: dir IN: open directory
Description: This function closes an open directory dir This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless dir is an open directory descriptor.
Returns: P4_E_OK upon success P4_E_INVAL if a parameter is invalid, e.g., 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. P4_E_IO if the storage device containing the directory reports failure. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Note: If the call applies to a volume provider, additional error codes may be returned. Please refer to the documentation of the corresponding volume provider.
Note: Depending on the underlying file system this call might block until a pending operation finishes.
See also: vm_dir_open() (see section 1.8.3.6)
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Extended File System 67
1.8.3.9 vm_dir_sync
Sync a directory.
Synopsis:
P4_e_t vm_dir_sync(vm_dir_t *dir)
Parameters: dir IN: open directory
Description: This function syncs an open directory dir. It is an addition to the function fsync() which syncs all data and metadata of an open file to the storage medium. Depending on the underlying file system it may be also possible to open a directory via vm_open() (see section 1.7.4.1) and call vm_fsync() (see section 1.7.4.15) on the descriptor to achieve the same behavior as required for vm_dir_sync() (see section 1.8.3.9). However ARINC forbids opening a directory via the file open function. For that reason vm_dir_sync() (see section 1.8.3.9) was introduced although it may be unsupported by certain file systems. Due to the synchronous behavior of certain file systems (like CFS) it may also be that called vm_dir_sync() (see section 1.8.3.9) is actually implemented as an empty function call and all data can be considered persistently written to storage on the return of other file system functions. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless dir is an open directory descriptor.
Returns: P4_E_OK upon success P4_E_INVAL if a parameter is invalid, e.g., 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. P4_E_IO if the storage device containing the directory reports failure. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Note: If the call applies to a volume provider, additional error codes may be returned. Please refer to the documentation of the corresponding volume provider.
See also: vm_dir_open() (see section 1.8.3.6)vm_fsync() (see section 1.7.4.15)
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
68 The PSSW API
1.8.3.10 vm_dir_rewind
Rewind the directory position.
Synopsis:
P4_e_t vm_dir_rewind(vm_dir_t *dir, P4_off_t *dir_pos)
Parameters: dir IN: open directory dir_pos OUT: directory position
Description: This function can be used to atomically reset the directory position in dir_pos used for directory reading with vm_dir_read_at() (see section 1.8.3.7) on dir. If dir is a directory of an external volume provider the operation is not atomic, e.g. it might be interrupted by other file system service calls, as the operation is fully done by the libvm in the callers address space without involving any system calls. Thus, it is also not possible for the service to detect invalid or stale directory handles in this case. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless dir is an open directory descriptor.
Returns: P4_E_OK upon success P4_E_INVAL if a parameter is invalid, e.g., if dir is not a valid open directory.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Extended File System 69
1.8.3.11 vm_mount
Mount File System Volume.
Synopsis:
P4_e_t vm_mount(const char *prefix, P4_uint32_t mflags)
Parameters: prefix IN: Prefix representing the volume. mflags IN: Mount flags.
Description: The call mounts the file system represented by given by prefix according the configuration from the property file system. For mflags a subset of the flags available for vm_open() (see section 1.7.4.1) can be used. Specifically VM_O_RD and VM_O_WR (as well as VM_O_RD_WR) are relevant for this function. For volumes UniversalisOS distinguishes between read and write access. The possibility to create new files (by using VM_O_CREAT) is also given if write permission is granted. Furthermore all functions which possibly change file system (meta)data (like vm_unlink() (see section 1.8.3.1), vm_rename() (see section 1.8.3.2), ...) are only available if write permission is given. Volume providers do not restrict the traversion of a file system tree to callers with the VM_O_EXEC permission. Furthermore mapping of files might be unavailable (which is the common case for e.g. CFS volume providers). This function is also implemented for non-volume providers (e.g. external file providers or KDEV drivers). For these providers P4_E_OK is returned without the invocation of any driver entry point. This enables applications to be written in a portable way, independent from the underlying provider type. A file access entry with the VM_O_MOUNT access right has to be given for the path "<provider_prefix>:" for the caller’s resource partition. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success P4_E_PERM if the calling thread has insufficient rights to mount the volume. Either VM_O_MOUNT is not given in the access rights of the calling thread’s resource partition for the volume prefix or mflags include ungranted (not given in the access rights list of the resource partition) access flags. if the volume provider doesn’t have access to the configured device. P4_E_NOENT if the volume prefix does not exist. if the configured device does not exist (e.g. if removable media is not present). 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). if the configured device name is invalid. if the device reports characteristics (like block sizes) which are not compatible with the volume configuration. P4_E_IO if the storage device containing the volume represented with prefix reports failure. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled. P4_E_OOMEM if the volume could not be mounted due to insufficient memory.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
70 The PSSW API
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: Depending on the actual file provider attached to the prefix it is possible that this call blocks until the request is satisfied. There is no means to change this behavior. Calling vm_mount() (see section 1.8.3.11) more than once on same volume prefix (from the same resource partition) is possible and will also result the call returning P4_E_OK.
See also: Documentation of the underlying file provider
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Extended File System 71
1.8.3.12 vm_umount
Unmount File System Volume.
Synopsis:
P4_e_t vm_umount(const char *prefix)
Parameters: prefix IN: Prefix representing the volume.
Description: The call unmounts the file system represented by prefix. During this operation all open files on the volume are closed and file/directory descriptors are freed. This function is also implemented for non-volume providers (e.g. external file providers or KDEV drivers). For these providers P4_E_OK is returned without the invocation of any driver entry point. This enables applications to be written in a portable way, independent from the underlying provider type. However, the provider must have been mounted using vm_mount() (see section 1.8.3.11) before. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success P4_E_PERM the volume prefix is not stored in the process’ mount table, e.g. vm_mount() (see section 1.8.3.11) has not been called before. P4_E_NOENT if the volume prefix does not exist. P4_E_INVAL if a parameter is invalid P4_E_IO if the storage device containing the volume represented with prefix reports failure. P4_E_STATE if there are open files left on the volume. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task. vm_mount() (see section 1.8.3.11) must have been called for the volume.
Note: Depending on the actual file provider attached to the prefix it is possible that this call blocks until the request is satisfied. There is no means to change this behavior.
See also: Documentation of the underlying file provider
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
72 The PSSW API
1.9 Communication Ports
UniversalisOS communication ports (PCPs) are designed to allow communication between different partitions. The API provides a message based read/write interface. Each port provides unidirectional data flow.
1.9.1 Structure Definitions
1.9.1.1 struct vm_port_desc_t
Opaque port descriptor for vm interface. Users should make no assumptions on the internal structure of this struct. It is opaque.
Synopsis: struct vm_port_desc_t { P4_uint32_t sig; P4_uint32_t id; P4_uint64_t refresh_rate; P4_size_t xfer_size; P4_bool_t is_sap; };
Structure Element Description: sig Struct signature to catch misuse id Identifier refresh_rate Period of sampling port, for validity computation xfer_size Maximum transfer size is_sap Whether the port is an SAP port
1.9.1.2 struct vm_qport_stat_t
Status information about a queuing port
Synopsis: struct vm_qport_stat_t { P4_uint32_t max_nb_messages; P4_size_t max_msg_size; unsigned vflags; vm_port_direction_t direction; P4_uint32_t oflags; char name[VM_NAME_LEN]; P4_uint32_t nb_messages; P4_uint32_t nb_waiters; P4_uint32_t cond; };
Structure Element Description: max_nb_messages Maximum number of messages which can be queued by the port. max_msg_size Maximum size of a single message to be transferred by the channel of this port.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 73
vflags Permissions as given in the VMIT. direction Port direction: either VM_PORT_SOURCE or VM_PORT_DESTINATION.
See also:
vm_port_direction_t.
oflags Port direction and flags used in open. This also contains the VM_O_NONBLOCK and VM_O_PRIORITY bits, if they were used during vm_qport_open() (see section 1.9.4.1).
See also:
vm_port_direction_t, vm_file_access_mode_t
name Identifier of the port. This is not available when the port is mapped to a gate provider once the port is opened (in vm_qport_pstat() (see section 1.9.4.4)), because the underlying gate provider does not know the name of a gate just from the descriptor. Only vm_qport_stat() (see section 1.9.4.6) and vm_qport_iterate() (see section 1.9.4.7) are guaranteed to return a non-empty string. nb_messages The number of messages or empty slots in the port. For a destination port, the maximum number of messages which can be read from the port until it is empty, implying no new messages to be written to the peer-port in the meantime. For a source port, the maximum number of messages which can be written to the port until it is full, implying no messages to be read from the peer-port in the meantime.
Note:
If the port is connected to a gate provider, only vm_qport_pstat() (see section 1.9.4.4) will return the
correct value. For gate providers, vm_qport_stat() (see section 1.9.4.6) and vm_qport_iterate() (see
section 1.9.4.7) will always return 0 here, because these function have no information about the internal
dynamic state of a port. This only become available once the port is opened.
nb_waiters Number of waiters on this port.
Note:
For gate providers, this is only available from vm_qport_pstat() (see section 1.9.4.4), but not from
vm_qport_stat() (see section 1.9.4.6) or vm_qport_iterate() (see section 1.9.4.7), because dynamic
information only becomes available once a port is opened.
cond Extended status conditions of the file. See VM_STATUS_* in the vm_status_cond_t type, explained in kernelref.pdf.
Note:
For gate providers, this is only available from vm_qport_pstat() (see section 1.9.4.4), but not from
vm_qport_stat() (see section 1.9.4.6) or vm_qport_iterate() (see section 1.9.4.7), because dynamic
information only becomes available once a port is opened.
1.9.1.3 struct vm_sport_stat_t
Status information about a sampling port
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
74 The PSSW API
Synopsis:
struct vm_sport_stat_t { P4_size_t max_msg_size; unsigned vflags; vm_port_direction_t direction; P4_uint64_t refresh_period; char name[VM_NAME_LEN]; vm_sport_msg_validity_t last_msg_validity; P4_uint64_t last_msg_age; P4_uint32_t cond; };
Structure Element Description: max_msg_size Maximum size of a single message to be transferred by the channel of this port. vflags Permissions as given in the VMIT. direction Port direction
See also:
vm_port_direction_t
refresh_period Age limit for valid messages (in ns).
In vm_sport_stat() (see section 1.9.4.20) and vm_sport_iterate() (see section 1.9.4.21), this is the con-
figured default refresh period, while in vm_sport_pstat() (see section 1.9.4.18), this is the currently set
refresh period, that is possibly different because it can be dynamically reset using vm_sport_set_re-
fresh_rate().
name Identifier of the port.
This is not available when the port is mapped to a gate provider once the port is opened (in
vm_sport_pstat() (see section 1.9.4.18)), because the underlying gate provider does not know the name
of a gate just from the descriptor. Only vm_sport_stat() (see section 1.9.4.20) and vm_sport_iterate()
(see section 1.9.4.21) are guaranteed to return a non-empty string.
last_msg_validity Validity status of the current message in the port.
Note:
This entry has no meaning for a source port and will always be set to VM_SPORT_NOT_APPLICABLE.
Note:
For gate providers, this is only available from vm_sport_pstat() (see section 1.9.4.18), but not from
vm_sport_stat() (see section 1.9.4.20) or vm_sport_iterate() (see section 1.9.4.21), because dynamic
information only becomes available once a port is opened.
last_msg_age Message age. From this, the validity is derived.
Because validity has no meaning to source ports, thing may always be set to 0 on source ports.
Note:
For gate providers, this is only available from vm_sport_pstat() (see section 1.9.4.18), but not from
vm_sport_stat() (see section 1.9.4.20) or vm_sport_iterate() (see section 1.9.4.21), because dynamic
information only becomes available once a port is opened.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 75
cond Extended status condition, see VM_STATUS_*. Note that some conditions might never occur for sam- pling ports.
Note:
For gate providers, this is only available from vm_sport_pstat() (see section 1.9.4.18), but not from
vm_sport_stat() (see section 1.9.4.20) or vm_sport_iterate() (see section 1.9.4.21), because dynamic
information only becomes available once a port is opened.
1.9.2 Defines
VM_QPORT_IS_SAP (pd)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
76 The PSSW API
1.9.3 Enumerations
Enumeration type vm_sport_msg_validity_t
Last message validity type. Used in the vm_sport_stat structure to indicate the validity of the last message of a destination port.
Name Description VM_SPORT_EMPTY No message has been transmitted to the port.
VM_SPORT_VALID The last message that was read from the port was valid.
VM_SPORT_INVALID The last message that was read from the port was invalid or the port has not been read since the last partition (re)start.
VM_SPORT_NOT_APPLICABLE The validity info is not meaningful since the stat operation was performed on an unconnected port or a source port.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 77
1.9.4 Functions
1.9.4.1 vm_qport_open
Open a queuing port.
Synopsis:
P4_e_t vm_qport_open(const char *name, P4_uint32_t flags, vm_port_desc_t *pd)
Parameters: name IN: Port name as configured in the VMIT. flags IN: Port direction can be one of the constants:
• VM_PORT_SOURCE for a source port,
• VM_PORT_DESTINATION for a destination port.
Additionally, to select a blocking discipline based on thread priority, VM_O_PRIORITY can be specified
as an additional bit. If this bit is not set, FIFO order is used instead of priority by default.
pd OUT: Upon success, the requested port descriptor is saved in pd. In case of error, the content of pd is
unspecified.
Description: This function opens the queuing port specified by the port name. Upon success the function returns a handle to the port which is used during subsequent calls to port communication services to identify the port. The port must exist (a queuing port with the given name must be configured in the VMIT) and the port direction must match the direction requested by the parameter flags. Note that the port direction corresponds with open flags: VM_PORT_SOURCE is an alias for VM_O_WR and VM_PORT_DESTINATION is an alias for VM_O_RD. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If the function returns anything but P4_E_OK, the contents of pd are unspecified, including the possibility of being overwritten in unspecified ways. Invoking this function on a descriptor that is already in use may cause the descriptor to be overwritten in unspec- ified ways, regardless of whether the new request succeeds or fails. This means that as soon as this function is entered, the passed descriptor must be considered uninitialized until this function returns successfully. This function is not thread safe, i.e., no other operations may be ongoing in other threads on the same descriptor, because there is no protection against data races on the descriptor. Further, the initialization of the descriptor performed by this function is not atomic. Note that except for vm_qport_open() (see section 1.9.4.1), all functions taking a vm_port_desc_t* have undefined behavior before the port descriptor is initialized using vm_qport_open() (see section 1.9.4.1), and also after the descriptor is finalized using vm_qport_close() (see section 1.9.4.13). Mixing ports opened with vm_qport_open() (see section 1.9.4.1) and vm_sport_open() (see section 1.9.4.14) also results in undefined behavior.
Returns: P4_E_OK upon success. This is also return if there is no connection to another port, so that the requester cannot see whether the other end of the channel actually exists.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
78 The PSSW API
P4_E_PERM if the parameter direction does not match the port’s direction, or both VM_O_RD and
VM_O_WR bits are set, i.e., ports must be unidirectional.
P4_E_NAME if name is too long for the underlying provider.
P4_E_NOENT if no port with the given name exists in the partition’s queuing port list
P4_E_INVAL if a parameter is invalid
P4_E_OOFILE if opening a kernel driver gate fails to allocate a new kernel file descriptor. System extensions
do not need to allocate a descriptor, so this error only occurs when accessing gate providers.
P4_E_ABORT if the call was aborted.
P4_E_CANCEL if the call was canceled.
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
See also: vm_qport_read() (see section 1.9.4.2), vm_qport_write() (see section 1.9.4.3), vm_qport_read_routed() (see sec- tion 1.9.4.10), vm_qport_pstat() (see section 1.9.4.4), vm_qport_stat() (see section 1.9.4.6), vm_qport_iterate() (see section 1.9.4.7), vm_qport_write_routed() (see section 1.9.4.11), vm_qport_clear() (see section 1.9.4.12), vm_qport_close() (see section 1.9.4.13).
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 79
1.9.4.2 vm_qport_read
Read a message from a queuing port.
Synopsis:
P4_e_t vm_qport_read(vm_port_desc_t *pd, void *buff, P4_size_t buff_size, P4_timeout_t timeout, P4_size_t *msg_size)
Parameters: pd IN: Descriptor of the destination port returned by vm_qport_open() (see section 1.9.4.1) buff OUT: The receive buffer buff_size IN: Size of the receive buffer given in bytes. buff_size must be greater than or equal to the maximum message size configured for the port. timeout IN: Absolute or relative Kernel-API timeout value of the operation or P4_TIMEOUT_NULL for non blocking operation, or P4_TIMEOUT_INFINITE for infinite blocking. msg_size OUT: Size of the received message in bytes. In case of error, the value msg_size is unspecified.
Description: This function reads a single message from the queuing port given by the port descriptor pd into the buffer given by buff. Upon success, the message is removed from the port, copied into the buffer and the actual message size is returned in msg_size. If a blocking write operation is pending on the opposite port of the connected channel, the corresponding thread will be unblocked. If the message queue is empty, vm_qport_read() (see section 1.9.4.2)
• waits for an incoming message until timeout expires, • waits infinitely for an incoming message if timeout == P4_TIMEOUT_INFINITE, or • returns immediately with an error when used in non blocking operation mode (timeout == P4_TIME- OUT_NULL).
The size of the caller’s memory buffer must be greater than or equal to the largest message size configured for the port pd. The function will never copy parts of a message into the buffer. If the buffer size is smaller than the maximum queue message size the call will fail even if the actual message would fit into the user buffer. In case of concurrent read operations, the requests are queued in FIFO order. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of msg_size are unspecified, including the possibility of being overwritten in unspecified ways. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of buff are unspecified, including the possibility of being overwritten in unspecified ways.
Returns:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
80 The PSSW API
P4_E_OK upon success
P4_E_PERM if pd does not refer to a destination port
P4_E_NOTIMPL if the requested operation is not available for the port referred to by pd.
P4_E_SIZE if buff_size is smaller than the configured maximum message size of the port
P4_E_BADTIMEOUT the timeout is invalid
P4_E_PAGEFAULT the buff is not fully mapped or not fully writable.
P4_E_INVAL if a parameter is invalid, e.g., if pd is not a valid port descriptor or if buff is not fully located in
the user accessable virtual memory space.
P4_E_TIMEOUT if timeout greater than zero was given and no message was received within the time interval
P4_E_TIMEOUT if timeout == P4_TIMEOUT_NULL was given and the message queue is empty
P4_E_LIMIT if there was packet loss since the last reading of a message, i.e., the queue was full, but more
messages arrived and could not be stored. Devices that implement handshaking between reader and
writer will not ever produce this message, because the writer will block until the queue becomes free for
another message. However, devices that cannot stop messages from coming in may signal this (e.g.,
network devices).
P4_E_TRUNC if the message was received from hardware without knowing its exact size, but it turned out the
message was too large for the given buffer, i.e., there was data loss in the attempt to copy the message
into the user buffer. This will only happen for devices that have no knowledge of the size of the message
in the queue prior to copying it to the user. Devices that know that the message is too large will instead
return P4_E_SIZE.
P4_E_ABORT if the call was aborted.
P4_E_CANCEL if the call was canceled.
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
See also: vm_qport_open() (see section 1.9.4.1), vm_qport_write() (see section 1.9.4.3), vm_qport_pstat() (see section 1.9.4.4), vm_qport_stat() (see section 1.9.4.6), and vm_qport_iterate() (see section 1.9.4.7)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 81
1.9.4.3 vm_qport_write
Write a message to a queuing port.
Synopsis:
P4_e_t vm_qport_write(vm_port_desc_t *pd, const void *buff, P4_size_t msg_size, P4_timeout_t timeout)
Parameters: pd IN: Descriptor of the source port returned by vm_qport_open() (see section 1.9.4.1) buff IN: Pointer to the message buffer msg_size IN: Size of the message buff given in bytes. msg_size must be less than or equal to the maximum message size. timeout IN: Absolute or relative Kernel-API timeout value of the operation or P4_TIMEOUT_NULL for non blocking operation, or P4_TIMEOUT_INFINITE for infinite blocking.
Description: This function writes a single message from the message buffer given by buff to the queuing port given by the port descriptor pd. The size of the message is given by msg_size. Upon success, the message is written to the port queue. If a blocking read operation is pending on the opposite port of the connected channel, the corresponding thread will be unblocked. If the message queue is full, vm_qport_write() (see section 1.9.4.3)
• waits for a free message buffer until timeout expires, • waits infinitely for a free message buffer if timeout == P4_TIMEOUT_INFINITE, or • returns immediately with an error when used in non blocking operation mode (timeout == P4_TIME- OUT_NULL).
The message size msg_size must be less than or equal to the maximum message size configured for the given port. This function never copies parts of a message, either the whole message is written to the port queue or the call fails returning an error code. In case of concurrent write operations, the requests are queued in FIFO order. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor.
Returns: P4_E_OK upon success P4_E_PERM if the port referred to by pd is not a source port P4_E_NOTIMPL if the requested operation is not available for the port referred to by pd. P4_E_SIZE if msg_size is larger than the configured message size of the port
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
82 The PSSW API
P4_E_TRUNC if not all of msg_size bytes could be transferred by the driver. Note that this function has no
means of returning the actual number of bytes transferred, so in returns this error code instead. This
error case indicates that the underlying driver is not fully compliant with port semantics.
P4_E_BADTIMEOUT the timeout is invalid
P4_E_PAGEFAULT the buff is not fully mapped.
P4_E_INVAL if a parameter is invalid, e.g., if pd is not a valid port descriptor or if buff is not fully located in
the user accessable memory space.
P4_E_TIMEOUT if timeout greater than zero was given and no message was written within the time interval
P4_E_TIMEOUT if timeout == P4_TIMEOUT_NULL was given and the message queue is full
P4_E_ABORT if the call was aborted.
P4_E_CANCEL if the call was canceled.
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
See also: vm_qport_open() (see section 1.9.4.1), vm_qport_read() (see section 1.9.4.2), vm_qport_pstat() (see section 1.9.4.4), vm_qport_stat() (see section 1.9.4.6), and vm_qport_iterate() (see section 1.9.4.7)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 83
1.9.4.4 vm_qport_pstat
Return the status of a queuing port identified by the port descriptor.
Synopsis:
P4_e_t vm_qport_pstat(vm_port_desc_t *pd, vm_qport_stat_t *stat)
Parameters: pd IN: Port descriptor, returned by a call to vm_qport_open() (see section 1.9.4.1) stat OUT: Upon success, the port status is returned in the structure referenced by status, in case of error, the content of this structure remains unchanged.
Description: This function provides several information about the current status of a queuing port given by the port descriptor pd. For a detailed description about the port status information, refer to the documentation of the data type vm_qport_stat_str. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor. If the function returns anything but P4_E_OK, the contents of status are unspecified, including the possibility of being overwritten in unspecified ways. Further note that gate providers cannot return the port name in this function, because it is not available in the kernel. Only vm_sport_stat() (see section 1.9.4.20) and vm_sport_iterate() (see section 1.9.4.21) will return the name of ports of gate providers. If the port is open without VM_O_RD or VM_O_WR permissions, or with VM_O_RD_WR permissions, then vm_pstat returns the number of messages that can be read, i.e., the number of messages in the queue, i.e., the same value as if the port had been opened in VM_O_RD direction. Only if it was opened with exactly VM_O_WR permissions, it will return the number of messages that can be written.
Returns: P4_E_OK upon success P4_E_NOTIMPL if the requested operation is not available for the port port. P4_E_INVAL if a parameter is invalid, e.g., if pd is not a valid port descriptor P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Note: The port descriptor pd must refer to a port which has been opened by a call to vm_qport_open() (see section 1.9.4.1).
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
See also:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
84 The PSSW API
vm_qport_open() (see section 1.9.4.1), vm_qport_read() (see section 1.9.4.2), vm_qport_write() (see section 1.9.4.3), vm_qport_stat() (see section 1.9.4.6), and vm_qport_iterate() (see section 1.9.4.7)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 85
1.9.4.5 vm_qport_psync
Sync data with external hardware.
Synopsis:
P4_e_t vm_qport_psync(vm_port_desc_t *pd)
Parameters: pd IN: Port descriptor, returned by a call to vm_qport_open() (see section 1.9.4.1)
Description: This may be available in some drivers. It may be used to flush ports to hardware and block until software buffers have all been transferred to the hardware. Or it may also be used to read buffers from hardware. Depending on the underlying driver, this call may do different things, so the driver documentation will describe what is implemented. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
86 The PSSW API
1.9.4.6 vm_qport_stat
Return the status of a queuing port identified by the port name.
Synopsis:
P4_e_t vm_qport_stat(const char *name, vm_qport_stat_t *stat)
Parameters: name IN: Port name as configured in the VMIT. stat OUT: Upon success, the port status is returned in the structure referenced by status, in case of error, the content of this structure remains unchanged.
Description: This function provides several information about the current status of a queuing port given by the port name. For a detailed description about the port status information, refer to the documentation of the data type vm_qport_stat_t. Whether a queuing port is an SAP port can be queried without using pstat by applying VM_QPORT_IS_SAP() to the port descriptor pointer. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If the function returns anything but P4_E_OK, the contents of status are unspecified, including the possibility of being overwritten in unspecified ways.
Returns: P4_E_OK upon success P4_E_NOTIMPL if the requested operation is not available for the port specified by name. P4_E_NAME if name is too long for the underlying provider. P4_E_NOENT if name does not reference a valid port P4_E_INVAL if a parameter is invalid P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
Note: This call may be applied to a port which has not yet been opened, however some of the port’s status informa- tion is only meaningful for an open port. In particular, for ports on gate providers, the number of messages can only be queried using vm_qport_pstat() (see section 1.9.4.4), not vm_qport_stat() (see section 1.9.4.6) nor vm_qport_iterate() (see section 1.9.4.7). In the same way, the number of waiters on gates is only available from vm_qport_pstat() (see section 1.9.4.4).
See also: vm_qport_open() (see section 1.9.4.1), vm_qport_read() (see section 1.9.4.2), vm_qport_write() (see section 1.9.4.3), vm_qport_pstat() (see section 1.9.4.4), and vm_qport_iterate() (see section 1.9.4.7)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 87
1.9.4.7 vm_qport_iterate
Return the status of a queuing port identified by the port number.
Synopsis:
P4_e_t vm_qport_iterate(P4_uint32_t pnr, vm_qport_stat_t *stat)
Parameters: pnr IN: Port number stat OUT: Upon success, the port status is returned in the structure referenced by status, in case of error, the content of this structure remains unchanged.
Description: This function returns the status of a queuing port given by the port number. It is used to iterate through the current partition’s port list. Iteration should start with the parameter pnr set to 0; the end of the partition’s port list is reached when the call returns with the error code P4_E_NOENT. For a detailed description about the port status information, refer to the documentation of the data type vm_qport_stat_str.
... pnr = 0; do { rc = vm_qport_iterate(pnr++, &stat); ... } while (rc == P4_E_OK);
This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If the function returns anything but P4_E_OK, the contents of status are unspecified, including the possibility of being overwritten in unspecified ways.
Returns: P4_E_OK upon success P4_E_NOTIMPL if the requested operation is not available for the port specified by pnr. P4_E_NOENT if the end of the port list has be reached P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Note: For ports at gate providers, this function cannot return complete status information. First of all, the state will always be reported as VM_PORT_CREATE, because the gate providers are descriptor based, and the gates are always created at boot time. Further, the number of messages is reported as 0 for these drivers, just like in vm_qport_stat() (see section 1.9.4.6), because gate providers can only provide full status information after a descriptor is available, for invoking the driver, i.e., using vm_qport_pstat() (see section 1.9.4.4). In the same way, the number of waiters on gates is only available from vm_qport_pstat() (see section 1.9.4.4).
Pre-Conditions:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
88 The PSSW API
The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
See also: vm_qport_open() (see section 1.9.4.1), vm_qport_read() (see section 1.9.4.2), vm_qport_write() (see section 1.9.4.3), vm_qport_pstat() (see section 1.9.4.4), and vm_qport_stat() (see section 1.9.4.6)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 89
1.9.4.8 vm_qport_control
Send port control command to a port provider.
Synopsis:
P4_e_t vm_qport_control(vm_port_desc_t *pd, P4_uint32_t cmd, void *data)
Parameters: pd IN: port descriptor cmd IN: command identifier data IN:[OUT] command specific data
Description: This function is similar to the vm_ioctl() (see section 1.7.4.13) command, but specific for queuing port providers. cmd specifies a command identifier which is defined with one of the VM_IOC_* calls. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor. The behavior of this function in case data is NULL is implementation-defined, i.e., it depends on the underlying driver how the function will behave. The contents of the memory pointed to by data after the call to this function is implementation-defined, i.e., it depends on the underlying driver how data is handled, and in which cases the data contents are specified or unspecified.
Returns: P4_E_OK upon success P4_E_NOTIMPL if the port does not provide the corresponding service P4_E_INVAL if a parameter is invalid, e.g., if pd is not a valid port descriptor P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
See also: vm_ioctl() (see section 1.7.4.13)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
90 The PSSW API
1.9.4.9 vm_qport_test
Control the driver’s test mode.
Synopsis:
P4_e_t vm_qport_test(vm_port_desc_t *pd, vm_test_mode_t tm, P4_uint32_t cmd)
Parameters: pd IN: port descriptor tm IN: which test mode to select cmd IN: arbitrary command for the provider
Description: This function can be used to access the driver’s test features. The exact functionality is up to the driver, this is a generic API passing down commands to the driver to activate/deactivate synchronous or asynchronous tests. Please also see the documentation for vm_test_mode_t. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 91
1.9.4.10 vm_qport_read_routed
Extended qport read for SAP ports.
Synopsis:
P4_e_t vm_qport_read_routed(vm_port_desc_t *pd, void *buff, P4_size_t buff_size, vm_sockaddr_storage_t *route, P4_size_t route_sz, P4_timeout_t timeout, P4_size_t *msg_size)
Parameters: pd IN: The port descriptor of the SAP (queuing) port buff OUT: The buffer for receiving the message buff_size IN: The size of the buffer in bytes. route OUT: Addresses of remote and local devices of the received message. This is an array of size 1 or 2 of vm_sockaddr_storage_t records. route_size indicates the size of the array in bytes, and, thus, implicitly indicates whether the array has 1 or 2 entries. The remote address of the device the message was received from is in array index [0]. The address of the local device the message was received on is in array index [1]. The function will fill in the route with data the driver stores. Which address family the driver uses is up to the driver. Drivers may have configuration settings for this or may take information from a previous write_routed(), or may be fixed to one address family this depends on the driver. Note that the declared type ’vm_sockaddr_t’ is not necessarily the valid parameter type. It is possible to pass a smaller types and set route_sz accordingly. The parameter type makes it easy to pass in an array of two vm_sockaddr_storage_t without casting.
See also:
drv_sockaddr_t, drv_sockaddr_ip4_t, drv_sockaddr_ip6_t, drv_sockaddr_storage_t.
route_sz IN: The size of the space reserved for route. If this is larger than sizeof(vm_sockaddr_storage_t), then there are two entries in the route array, otherwise there is one. This may be smaller than a vm_sockaddr_storage_t. It just needs to contain all relevant data in the amount of bytes defined. When passing just one address, route_sz may thus be equal to the size of that entry. timeout IN: Timeout: how long to possibly wait to be able to read data msg_size OUT: The amount of transferred data in bytes.
Description: This is similar to vm_qport_read() (see section 1.9.4.2), but can specify addresses of different end points to be used for sender and/or receiver. I.e., it allows the caller to receive both the address of the local interface and of the remote interface where the message originated. Routed operations are useful for implementing network oriented channels where the communicating ends have addresses, e.g. IP addresses. Consequently, vm_sockaddr_t and vm_sockaddr_storage_t closely follows the
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
92 The PSSW API
POSIX API wrt. specification of addresses, with a protocol and an address family. In the context of ports in UniversalisOS, the functions are used to access SAP ports. Note that in contrast to A653, the SAP drivers are stateless, so user space has to take care to transfer the addresses, otherwise, the driver will always use the default. State is moved to user space in order to make multi- threading less error-prone. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of msg_size are unspecified, including the possibility of being overwritten in unspecified ways. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of buff are unspecified, including the possibility of being overwritten in unspecified ways.
Returns: P4_E_OK if reading was successful. P4_E_PERM if the port is not open for reading. P4_E_NOTIMPL if this operation is not supported by the underlying driver. P4_E_SIZE if the buffer size is invalid, i.e., too small to accommodate a message of the maximum configured size for this port. P4_E_BADTIMEOUT if the timeout parameter is not a valid timeout P4_E_RESTRICTED if a local address is passed (i.e., route_size is greater than sizeof(drv_sockaddr_stor- age_t)), but the driver does not allow specifying a local address. P4_E_INVAL if a parameter is invalid, e.g., if the descriptor is not a valid port descriptor P4_E_TIMEOUT if timeout is equal to P4_TIMEOUT_NULL and the output queue is full. P4_E_TIMEOUT if timeout is not equal to P4_TIMEOUT_NULL, the output queue is full, and the time speci- fied by timeout has passed. P4_E_PAGEFAULT if any of the referenced pointers causes a memory access fault when read or written by the driver. P4_E_TIMEOUT if the operation was canceled in such a way that retrying might be successful. P4_E_BUSY if the operation is currently not possible, e.g. because the port is currently not available and it is not possible or makes no sense to block until it becomes available. E.g. this happens when the port descriptor is currently being closed. P4_E_IO if the underlying hardware detected a non-recoverable fault P4_E_LIMIT if there was packet loss since the last reading of a message, i.e., the queue was full, but more messages arrived and could not be stored. Devices that implement handshaking between reader and writer will not ever produce this message, because the writer will block until the queue becomes free for another message. However, devices that cannot stop messages from coming in may signal this (e.g., network devices). P4_E_TRUNC if the message was received from hardware without knowing its exact size, but it turned out the message was too large for the given buffer, i.e., there was data loss in the attempt to copy the message into the user buffer. This will only happen for devices that have no knowledge of the size of the message in the queue prior to copying it to the user. Devices that know that the message is too large will instead return P4_E_SIZE. P4_E_ABORT if the operation was aborted in such a way that simply retrying has no chance to success. P4_E_CANCEL if the call was canceled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 93
1.9.4.11 vm_qport_write_routed
Extended qport write for SAP ports.
Synopsis:
P4_e_t vm_qport_write_routed(vm_port_desc_t *pd, const void *buff, P4_size_t msg_size, const vm_sockaddr_storage_t *route, P4_size_t route_sz, P4_timeout_t timeout)
Parameters: pd IN: The port descriptor of the SAP (queuing) port buff IN: The buffer containing the message to be sent msg_size IN: The size of the message in the buffer to be sent in bytes route IN: The target and possibly source addresses. The addresses are passed exactly like in vm_qport_read_routed() (see section 1.9.4.10), i.e., this is a pointer to an array of vm_sockaddr_storage_t of 1 or 2 entries. Array index [0] is the remote address (the destination address) and index [1] is the local address (the source address). For sending, the addresses must be filled in by the caller. route_sz gives the size of the array in bytes and implicitly defines the number of addresses: 1 or 2. The length and family must be set so that the length is long enough to represent an address of the given type. Either entry can be VM_AF_NULL to indicate that for the corresponding device, no address or the default should be used. However, if the remote address is not specified, the driver is likely to reject the request if it has no default destination address. Similarly, if there is no default local address, or the driver is set to only allow two-address requests, the driver may reject the request. This function call is stateless wrt. the addresses: neither the port descriptor nor the driver store the remote address or change the default local address. Such state must be kept in application space. This is a deliberate design decision in order to allow for clean multi-threading of applications without race conditions. This function guarantees that the addresses passed as parameters will be used for exactly the message transferred in this call. Note that the declared type ’vm_sockaddr_t’ is not necessarily the exact parameter type that is passed. It is possible to pass a smaller type and set route_sz accordingly. The parameter type makes it easy to pass in an array of two vm_sockaddr_storage_t without casting.
See also:
drv_sockaddr_t, drv_sockaddr_ip4_t, drv_sockaddr_ip6_t, drv_sockaddr_storage_t.
route_sz IN: The size of the space reserved for route. If this is larger than sizeof(vm_sockaddr_storage_t), then there are two entries in the route array, otherwise there is one. route_sz may be smaller than 2sizeof(vm_sockaddr_storage_t) (for two address) or smaller than 1sizeof(vm_sockaddr_storage_t) (for one address), if the last address in the array needs less memory
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
94 The PSSW API
than a full vm_sockaddr_storage_t. E.g., when passing a single vm_sockaddr_ip4_t, route_sz may be
sizeof(vm_sockaddr_ip4_t).
timeout IN: Timeout: how long to possibly wait to be able to send data in bytes
Description: This can receive addresses of sender and/or receiver. I.e., this is similar to vm_qport_write() (see section 1.9.4.3), but allows the caller to set both the address of the local interface and of the remote interface where the message is routed. Routed operations are useful for implementing network oriented channels where the communicating ends have addresses, e.g. IP addresses. Consequently, vm_sockaddr_t and vm_sockaddr_storage_t closely follows the POSIX API wrt. specification of addresses, with a protocol and an address family. In the context of ports in UniversalisOS, the functions are used to access SAP ports. SAP drivers are strongly encouraged to be stateless wrt. the addresses, i.e., they should not remember an address passed in this call except for handling the request itself, i.e., a vm_qport_write_routed() (see section 1.9.4.11) should not set a default remote or local address for subsequent writes. Drivers may maintain a fixed default address set by global configuration, but to ease multi-threaded implementa- tion, they should require that each write request overrides that default individually if necessary. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor.
Returns: P4_E_OK if the message was successfully enqueued for sending. P4_E_PERM if the port is not open for writing. P4_E_NOTIMPL if this operation is not supported by the underlying driver. P4_E_SIZE if the buffer size is invalid, i.e., larger than a message of the maximum configured size for this port. P4_E_BADTIMEOUT if the timeout value is invalid P4_E_INVAL if a parameter is invalid, e.g., if the descriptor is invalid P4_E_RESTRICTED if a local address is passed (i.e., route_size is greater than sizeof(drv_sockaddr_stor- age_t)), but the driver does not allow specifying the local address. P4_E_TIMEOUT if timeout is equal to P4_TIMEOUT_NULL and the output queue is full. P4_E_TIMEOUT if timeout is not equal to P4_TIMEOUT_NULL, the output queue is full, and the time speci- fied by timeout has passed. P4_E_PAGEFAULT if any of the referenced pointers causes a memory access fault when read or written by the driver or the framework. P4_E_TRUNC if the underlying driver could only write part of the message. In this case, the port is connected to a non-compliant queuing port driver. A compliant driver would guarantee to either fully send the message or not to send it at all. P4_E_TIMEOUT if the operation was canceled in such a way that retrying might be successful. P4_E_BUSY if the operation is currently not possible, e.g. because the port is currently not available and it is not possible or makes no sense to block until it becomes available. E.g. this happens when the port descriptor is currently being closed. P4_E_IO if the underlying hardware detected a non-recoverable fault P4_E_ABORT if the operation was aborted in such a way that simply retrying has no chance to success.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 95
P4_E_CANCEL if the call was canceled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
96 The PSSW API
1.9.4.12 vm_qport_clear
Clear a queuing port, discard all messages.
Synopsis:
P4_e_t vm_qport_clear(vm_port_desc_t *pd)
Parameters: pd The port descriptor of the port to be cleared
Description: Clearing a queuing port means to consume all message without processing them, i.e., by discarding the mes- sages. This operation is typically only allowed by the reader of a queuing port. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor.
Returns: P4_E_OK if the port content was cleared. P4_E_PERM if the port is forbidden to be cleared from this side of the channel. P4_E_NOTIMPL if the underlying port does not support to be cleared. The framework does not make an attempt to simulate clearing by consuming message until the port is empty, because this may lead to infinite loops when the port is filled simultaneously, plus it might take a very long time, since such a loop is O(queue_length), while the specific clear operation is typically O(1). P4_E_INVAL if a parameter is invalid, e.g., if the port descriptor is invalid P4_E_BUSY if the port is currently busy, e.g., because it is being closed in another thread, too. P4_E_IO if the underlying hardware had a fault. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 97
1.9.4.13 vm_qport_close
Close a queuing port.
Synopsis:
P4_e_t vm_qport_close(vm_port_desc_t *pd)
Parameters: pd The port descriptor of the port to be closed
Description: Closing a port is the opposite of opening it. This will deallocate possible system resources used for the descriptor. After that, the port descriptor will not be usable anymore for operations on the port, but to use it again, the port has to be re-opened. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor. The contents of pd will be unspecified in case this function returns P4_E_OK. In case of an error, the contents of pd will remain unchanged, because the error may indicate a temporary failure so that the closing could be repeated later.
Returns: P4_E_OK if the port could be closed. P4_E_INVAL if a parameter is invalid, e.g., if the port descriptor is invalid, or is in use or in the process of being closed by another thread. P4_E_BUSY if the port is currently busy, e.g., because it is being closed in another thread, too. P4_E_IO if the underlying hardware had a fault. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
98 The PSSW API
1.9.4.14 vm_sport_open
Open a sampling port.
Synopsis:
P4_e_t vm_sport_open(const char *name, P4_uint32_t flags, vm_port_desc_t *pd)
Parameters: name IN: Port name as configured in the VMIT flags IN: Port direction can be one of the constants:
• VM_PORT_SOURCE for a source port,
• VM_PORT_DESTINATION for a destination port.
pd OUT: Upon success, the requested port descriptor is saved in pd. In case of error, the content of pd is
unspecified.
Description: This function behaves exactly like vm_qport_open() (see section 1.9.4.1) except that it can only be applied to sampling ports instead of queuing ports. For a detailed description, including the return values, refer to the documentation of vm_qport_open() (see section 1.9.4.1). If the function returns anything but P4_E_OK, the contents of pd are unspecified, including the possibility of being overwritten in unspecified ways. Invoking this function on a descriptor that is already in use may cause the descriptor to be overwritten in unspec- ified ways, regardless of whether the new request succeeds or fails. This means that as soon as this function is entered, the passed descriptor must be considered uninitialized until this function returns successfully. This function is not thread safe, i.e., no other operations may be ongoing in other threads on the same descriptor, because there is no protection against data races on the descriptor. Further, the initialization of the descriptor performed by this function is not atomic. Note that except for vm_sport_open() (see section 1.9.4.14), all functions taking a vm_port_desc_t* have un- defined behavior before the port descriptor is initialized using vm_sport_open() (see section 1.9.4.14), and also after the descriptor is finalized using vm_sport_close() (see section 1.9.4.25). Mixing ports opened with vm_sport_open() (see section 1.9.4.14) and vm_qport_open() (see section 1.9.4.1) also results in undefined be- havior. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
See also: vm_sport_read() (see section 1.9.4.15), vm_sport_write() (see section 1.9.4.16), vm_sport_pstat() (see section 1.9.4.18), vm_sport_stat() (see section 1.9.4.20), vm_sport_iterate() (see section 1.9.4.21), vm_sport_clear() (see section 1.9.4.24), vm_sport_close() (see section 1.9.4.25).
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 99
1.9.4.15 vm_sport_read
Read a message from a sampling port.
Synopsis:
P4_e_t vm_sport_read(vm_port_desc_t *pd, void *buff, P4_size_t buff_size, P4_size_t *msg_size, vm_sport_msg_validity_t *validity)
Parameters: pd IN: Descriptor of the destination port returned by vm_sport_open() (see section 1.9.4.14) buff OUT: Pointer to the receive buffer buff_size IN: Size of buffer buff given in bytes. buff_size must be greater than or equal to the maximum message size configured for the port. msg_size OUT: Upon success, msg_size will contain the received message size in bytes. In case of error, the value msg_size is unspecified. validity OUT: returns the validity of the received message.
Description: This function reads the current message from the sampling port given by the port descriptor pd into the buffer given by buff. Upon success (P4_E_OK), the variable referenced by validity has been written and should be checked by the caller to get information about the state of the message buffer. validity can assume the following values:
• VM_SPORT_INVALID the message was copied but it is invalid with respect to the ports refresh period. • VM_SPORT_VALID the message was copied and it is valid with respect to the ports refresh period. • VM_SPORT_EMPTY no message has yet been transferred to the port, and no message has been copied to the buff.
If a message was copied to buff, its size is returned in msg_size. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of msg_size are unspecified, including the possibility of being overwritten in unspecified ways. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of validity are unspecified, including the possibility of being overwritten in unspecified ways. If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of buff are unspecified, including the possibility of being overwritten in unspecified ways.
Returns: P4_E_OK upon success P4_E_PERM if the port referred to by pd is not a destination port
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
100 The PSSW API
P4_E_NOTIMPL if the requested operation is not available for the port referred to by pd. P4_E_SIZE if buff_size is smaller than the configured maximum message size of the port P4_E_PAGEFAULT the buff is not fully mapped or not fully writable P4_E_INVAL if a parameter is invalid, e.g., if pd is not a valid port descriptor or if buff is not fully located in the user accessable virtual memory space. P4_E_TRUNC if the message was received from hardware without knowing its exact size, but it turned out the message was too large for the given buffer, i.e., there was data loss in the attempt to copy the message into the user buffer. This will only happen for devices that have no knowledge of the size of the message in the queue prior to copying it to the user. Devices that know that the message is too large will instead return P4_E_SIZE. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
Note: A vm_sport_read() (see section 1.9.4.15) operation does not consume the message, it can be re-read until it is overwritten by a new message.
See also: vm_sport_open() (see section 1.9.4.14), vm_sport_write() (see section 1.9.4.16), vm_sport_pstat() (see section 1.9.4.18), vm_sport_stat() (see section 1.9.4.20), and vm_sport_iterate() (see section 1.9.4.21)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 101
1.9.4.16 vm_sport_write
Write a message to a sampling port.
Synopsis:
P4_e_t vm_sport_write(vm_port_desc_t *pd, const void *buff, P4_size_t msg_size)
Parameters: pd IN: Descriptor of the source port returned by vm_sport_open() (see section 1.9.4.14) buff IN: Pointer to the message buffer to write msg_size IN: Size of the message buff given in bytes. msg_size must be less than or equal to the maximum message size.
Description: This function is used to replace the current message of the sampling port given by the port descriptor pd with the message given by buff Upon success, msg_size bytes of the message buffer are written to the port. The message size may not exceed the maximum message size configured for the port. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor.
Returns: P4_E_OK upon success P4_E_PERM if the port referred to by pd is not a source port P4_E_NOTIMPL if the requested operation is not available for the port referred to by pd. P4_E_SIZE if msg_size is larger than the configured maximum message size of the port P4_E_TRUNC if not all of msg_size bytes could be transferred by the driver. Note that this function has no means of returning the actual number of bytes transferred, so in returns this error code instead. This error case indicates that the underlying driver is not fully compliant with port semantics. P4_E_PAGEFAULT the buff is not fully mapped. P4_E_INVAL if a parameter is invalid, e.g., if pd is not a valid port descriptor or if buff is not fully located in the user accessable virtual memory space. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
See also: vm_sport_open() (see section 1.9.4.14), vm_sport_read() (see section 1.9.4.15), vm_sport_pstat() (see section 1.9.4.18), vm_sport_stat() (see section 1.9.4.20), and vm_sport_iterate() (see section 1.9.4.21)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
102 The PSSW API
1.9.4.17 vm_sport_set_refresh_rate
Reset the current refresh rate used for the port.
Synopsis:
static __forceinline void vm_sport_set_refresh_rate(vm_port_desc_t *pd, P4_uint64_t new_refresh_rate)
Parameters: pd IN: Port descriptor for which to change the refresh rate. new_refresh_rate IN: The new refresh rate to be used for the port.
Description: When a sampling port is opened, the refresh rate will be set to zero. This function changes that refresh rate. The current refresh rate is used for judgment of validity in vm_sport_read() (see section 1.9.4.15) and vm_sport_stat() (see section 1.9.4.20). Note that after closing a port or in a partition reboot, the current refresh rate will be forgotten, and after the next open, the port’s refresh rate is set to zero again. Also note that refresh rates are only used for destination ports. For source ports, the default refresh rate may have a meaning to the driver, but the UniversalisOS system and libraries do not use it. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor.
Returns: Nothing
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 103
1.9.4.18 vm_sport_pstat
Return the status of a sampling port identified by the port name.
Synopsis:
P4_e_t vm_sport_pstat(vm_port_desc_t *pd, vm_sport_stat_t *stat)
Parameters: pd IN: Port descriptor, returned by a call to vm_sport_open() (see section 1.9.4.14) stat OUT: Upon success, the port status is returned in the structure referenced by status, in case of error, the content of this structure remains unchanged.
See also:
vm_sport_stat_str
Description: This function behaves exactly like vm_qport_pstat() (see section 1.9.4.4) except that it can only be applied to sampling ports instead of queuing ports. For a detailed description, including the return values, refer to the documentation of vm_qport_pstat() (see section 1.9.4.4). Note that the returned refresh rate is the current refresh rate for the given port descriptor. After opening a sampling port, this is the port’s default refresh rate, which can be reset using vm_sport_set_refresh_rate(). The returned validity is based on the current refresh rate. This is different from vm_sport_stat() (see section 1.9.4.20), which always uses the port’s default refresh rate. Further note that gate providers cannot return the port name in this function, because it is not available in the kernel. Only vm_sport_stat() (see section 1.9.4.20) and vm_sport_iterate() (see section 1.9.4.21) will return the name of ports of gate providers. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor. If the function returns anything but P4_E_OK, the contents of status are unspecified, including the possibility of being overwritten in unspecified ways.
Note: The port descriptor pd must refer to a port which has been opened by a call to vm_qport_open() (see section 1.9.4.1).
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
See also: vm_sport_open() (see section 1.9.4.14), vm_sport_read() (see section 1.9.4.15), vm_sport_write() (see section 1.9.4.16), vm_sport_stat() (see section 1.9.4.20), and vm_sport_iterate() (see section 1.9.4.21)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
104 The PSSW API
1.9.4.19 vm_sport_psync
Send a sync request to the given descriptor.
Synopsis:
P4_e_t vm_sport_psync(vm_port_desc_t *pd)
Parameters: pd IN: Port descriptor, returned by a call to vm_qport_open() (see section 1.9.4.1)
Description: Depending on the underlying driver, this call may do different things. The general idea is to flush data from memory onto an external device. The exact semantics must be checked for each driver. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 105
1.9.4.20 vm_sport_stat
Return the status of a sampling port identified by the port name.
Synopsis:
P4_e_t vm_sport_stat(const char *name, vm_sport_stat_t *stat)
Parameters: name IN: Port name as configured in the VMIT. stat OUT: Upon success, the port status is returned in the structure referenced by status, in case of error, the content of this structure remains unchanged.
See also:
vm_sport_stat_str
Description: This function behaves exactly like vm_qport_stat() (see section 1.9.4.6) except that it can only be applied to sampling ports instead of queuing ports. For a detailed description, including the return values, refer to the documentation of vm_qport_stat() (see section 1.9.4.6). Note that the returned refresh rate is the port default refresh rate, and the returned validity is based on that default refresh rate. This is different from vm_sport_pstat() (see section 1.9.4.18), which uses the currently active refresh rate for the port descriptor, set using vm_sport_set_refresh_rate(). Also note that the validity of a source port cannot be checked with this function. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If the function returns anything but P4_E_OK, the contents of status are unspecified, including the possibility of being overwritten in unspecified ways.
Note: This call may be applied to a port which has not yet been opened, however some of the port’s status information is only meaningful for open ports. In particular, gate providers can only report the age of the message in vm_sport_pstat() (see section 1.9.4.18), but not in vm_sport_stat() (see section 1.9.4.20) nor in vm_sport_iterate() (see section 1.9.4.21), because they require an open descriptor to invoke the driver to return this information.
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
See also: vm_qport_open() (see section 1.9.4.1), vm_qport_read() (see section 1.9.4.2), vm_qport_write() (see section 1.9.4.3), vm_qport_stat() (see section 1.9.4.6), and vm_qport_iterate() (see section 1.9.4.7)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
106 The PSSW API
1.9.4.21 vm_sport_iterate
Return status of a sampling port identified by the port number.
Synopsis:
P4_e_t vm_sport_iterate(P4_uint32_t pnr, vm_sport_stat_t *stat)
Parameters: pnr IN: Port number stat OUT: Upon success, the port status is returned in the structure referenced by status, in case of error, the content of this structure remains unchanged.
See also:
vm_sport_stat_str
Description: This function behaves exactly like vm_qport_iterate() (see section 1.9.4.7) except that it can only be applied to sampling ports instead of queuing ports. For a detailed description, including the return values, refer to the documentation of vm_qport_iterate() (see section 1.9.4.7). This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If the function returns anything but P4_E_OK, the contents of status are unspecified, including the possibility of being overwritten in unspecified ways.
Note: This call may be applied to a port which has not yet been opened, however some of the port’s status information is only meaningful for open ports.
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
See also: vm_qport_open() (see section 1.9.4.1), vm_qport_read() (see section 1.9.4.2), vm_qport_write() (see section 1.9.4.3), vm_qport_stat() (see section 1.9.4.6), and vm_qport_iterate() (see section 1.9.4.7)
Note: For ports at gate providers, this function cannot return complete status information. First of all, the state will always be reported as VM_PORT_CREATE, because the gate providers are descriptor based, and the gates are always created at boot time. Further, the number of messages is reported as 0 for these drivers, just like in vm_sport_stat() (see section 1.9.4.20), because gate providers can only provide full status information after a descriptor is available, for invoking the driver, i.e., using vm_sport_pstat() (see section 1.9.4.18).
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 107
1.9.4.22 vm_sport_control
Send port control command to a port provider.
Synopsis:
P4_e_t vm_sport_control(vm_port_desc_t *pd, P4_uint32_t cmd, void *data)
Parameters: pd IN: port descriptor cmd IN: command identifier data INOUT: command specific data
Description: This function is similar to the vm_ioctl() (see section 1.7.4.13) command, but specific for sampling port providers. cmd specifies a command identifier which is defined with one of the VM_IOC_* calls. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor. The behavior of this function in case data is NULL is implementation-defined, i.e., it depends on the underlying driver how the function will behave. The contents of the memory pointed to by data after the call to this function is implementation-defined, i.e., it depends on the underlying driver how data is handled, and in which cases the data contents are specified or unspecified.
Returns: P4_E_OK upon success P4_E_NOTIMPL if the port does not provide the corresponding service P4_E_INVAL if a parameter is invalid, e.g., if pd is not a valid port descriptor P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
See also: vm_ioctl() (see section 1.7.4.13)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
108 The PSSW API
1.9.4.23 vm_sport_test
Control the driver’s test mode.
Synopsis:
P4_e_t vm_sport_test(vm_port_desc_t *pd, vm_test_mode_t tm, P4_uint32_t cmd)
Parameters: pd IN: port descriptor tm IN: which test mode to select cmd IN: arbitrary command for the provider
Description: This function can be used to access the driver’s test features. The exact functionality is up to the driver, this is a generic API passing down commands to the driver to activate/deactivate synchronous or asynchronous tests. Please also see the documentation for vm_test_mode_t. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Communication Ports 109
1.9.4.24 vm_sport_clear
Clear as sampling port, reset it to empty state.
Synopsis:
P4_e_t vm_sport_clear(vm_port_desc_t *pd)
Parameters: pd The port descriptor of the port to be cleared
Description: Clearing a sampling port means to reset the state to empty just like it was at system boot time. This operation is typically only allowed by the writer of a sampling port. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor.
Returns: P4_E_OK if the port content was cleared. P4_E_PERM if the port is forbidden to be cleared from this side of the channel. P4_E_NOTIMPL if the underlying port does not support to be cleared. P4_E_INVAL if a parameter is invalid, e.g., if the port descriptor is invalid. P4_E_BUSY if the port is currently busy, e.g., because it is being closed in another thread, too. P4_E_IO if the underlying hardware had a fault. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
110 The PSSW API
1.9.4.25 vm_sport_close
Close a sampling port.
Synopsis:
P4_e_t vm_sport_close(vm_port_desc_t *pd)
Parameters: pd The port descriptor of the port to be closed
Description: Closing a port is the opposite of opening it. This will deallocate possible system resources used for the descriptor. After that, the port descriptor will not be usable anymore for operations on the port, but to use it again, the port has to be re-opened. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless pd is an open port descriptor. The contents of pd will be unspecified in case this function returns P4_E_OK. In case of an error, the contents of pd will remain unchanged, because the error may indicate a temporary failure so that the closing could be repeated later.
Returns: P4_E_OK if the port could be closed. P4_E_INVAL if a parameter is invalid, e.g., if the port descriptor is invalid, or is in use or in the process of being closed by another thread. P4_E_BUSY if the port is currently busy, e.g., because it is being closed in another thread, too. P4_E_IO if the underlying hardware had a fault. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Partition Management 111
1.10 Partition Management
Functions of the partition management group are intended to retrieve information about the partitions’ status and allow the shutdown or restart of a given partition.
1.10.1 Structure Definitions
1.10.1.1 struct vm_partition_stat_t
Data structure describing status of a partition
Synopsis: struct vm_partition_stat_t { char name[VM_NAME_LEN]; vm_part_id_t id; vm_part_operating_mode_t operating_mode; P4_uint32_t op_mode_flags; vm_ability_t abilities; P4_prio_t max_prio; P4_task_t first_child_task_num; P4_task_t last_child_task_num; unsigned int open_files; unsigned int max_open_files; P4_uint32_t period; P4_uint32_t duration; P4_uint32_t cookie; P4_uint32_t timepart; P4_cpumask_t cpu_mask; P4_cpumask_t tp_cpu_mask; };
Structure Element Description: name Partition name id ID of the partition as defined in VMIT operating_mode Partition Operating Mode op_mode_flags Contains information about the startup condition of the partition abilities Partition abilities max_prio Maximum priority first_child_task_num Task ID of the first child task last_child_task_num Task ID of the last child task open_files Number of file descriptors currently in use. The number reported only considers the number of open files in system extensions and ExtFPs, but not in KDEV drivers. Further, this entry is not considered particularly useful to applications, which can count better by themselves what exactly they want to know. For these reasons, this entry is deprecated and should not be used. max_open_files Maximum number of available file descriptors (MaxFDCount) period Period of associated time partition. If 0, this partition is aperiodic duration Duration of associated time partition. If 0, this partition is aperiodic cookie Cookie set by vm_part_set_mode() (see section 1.10.4.1)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
112 The PSSW API
timepart Time partition ID cpu_mask CPU mask of the partition. This corresponds to the CPU mask configured for the partition masked with the CPU mask of its time partition. The CPU mask of the time partition is defined by the scheduling table (by the ’CpuMask’ attribute of the window tables containing windows of that time partition). tp_cpu_mask CPU mask of the time partition assigned to the partition
1.10.2 Defines
VM_RESPART_MYSELF
Description:
Symbol to refer to the resource partition of the calling task. May be used as a synonym for the
index of the caller’s resource partition in vm_part_set_mode() (see section 1.10.4.1), vm_part_pstat()
(see section 1.10.4.4), vm_procinfo() (see section 1.11.4.2), vm_shutdown() (see section 1.10.4.3) and
vm_mem_stat() (see section 1.6.3.3).
VM_PART_MIN_MCP
Description:
Absolute minimum value of the maximum controlled priority attribute to be assigned to a resource
partition.
VM_PART_MAX_MCP
Description:
Absolute maximum value of the maximum controlled priority attribute to be assigned to a resource
partition.
VM_PART_FLAG_START_COND_RESTART
Description:
Partition restart start condition flag. 0: Partition was started after a module start. 1: Partition was
restarted during module run-time.
VM_PART_FLAG_START_COND_HM
Description:
HM-caused start condition flag.
This bit, if set, indicates that the start condition was caused by health monitoring subsystem.
This bit is mutually exclusive with VM_PART_FLAG_START_COND_SYSTEM and
VM_PART_FLAG_START_COND_SCHED.
VM_PART_FLAG_START_COND_SYSTEM
Description:
System event caused start condition flag.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Partition Management 113
This bit, if set, indicates that the partition mode change was triggered by another partition or system
extension.
This bit is mutually exclusive with VM_PART_FLAG_START_COND_HM and
VM_PART_FLAG_START_COND_SCHED.
VM_PART_FLAG_START_COND_SCHED
Description:
Schedule change caused start condition flag.
This bit, if set, indicates that the partition mode change was triggered by a schedule change action.
This bit is mutually exclusive with VM_PART_FLAG_START_COND_HM and
VM_PART_FLAG_START_COND_SYSTEM.
1.10.3 Data Type Definitions
vm_part_id_t Numerical resource partition identifier to refer to a resource partition by the identifier it has been assigned in the VMIT configuration.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
114 The PSSW API
1.10.4 Functions
1.10.4.1 vm_part_set_mode
Set the mode of a partition.
Synopsis:
P4_e_t vm_part_set_mode(vm_part_id_t id, vm_part_operating_mode_t operating_mode, P4_uint32_t cookie, P4_bool_t change_mode, P4_bool_t change_cookie)
Parameters: id IN: Partition ID. The special value VM_RESPART_MYSELF is used to address the caller’s partition. The numbering of id starts from one. operating_mode IN: operating mode to be set cookie IN: user cookie to be saved and kept during a partition reboot change_mode IN: Defines whether or not the targeted partition’s operating mode is to be changed. change_cookie IN: Defines whether or not the targeted partition’s cookie is to be changed.
Description: Initiate the transition of the operating mode of the resource partition identified by id from its current operating mode to the one specified by operating_mode. Valid operating modes are those defined by the enumeration vm_part_operating_mode_t. The operating mode of a resource partition is reflected by its status which is retrieved via the service vm_part_stat() (see section 1.10.4.5) and vm_part_pstat() (see section 1.10.4.4). If operating_mode is VM_PART_MODE_IDLE, the targeted partition will be halted. All processes are able to change the operating mode of their own partition. The symbol VM_RESPART_MYSELF may be used as a synonym for the caller’s resource partition identifier. Only processes in partitions with the ability VM_AB_PART_SET_MODE are permitted to change operating modes of other partitions. The following operating mode transitions are considered invalid:
• VM_PART_MODE_IDLE -> VM_PART_MODE_IDLE
• VM_PART_MODE_IDLE -> VM_PART_MODE_NORMAL
• VM_PART_MODE_COLD_START -> VM_PART_MODE_WARM_START
• VM_PART_MODE_NORMAL -> VM_PART_MODE_NORMAL
Setting VM_PART_MODE_NORMAL for other partitions that one’s own is considered an invalid mode switch. Specific operating mode transitions cause the targeted partition to perform an asynchronous partition reboot. The new operating mode is not reflected until the reboot is performed. These are:
• VM_PART_MODE_COLD_START -> VM_PART_MODE_COLD_START
• VM_PART_MODE_WARM_START -> VM_PART_MODE_COLD_START
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Partition Management 115
• VM_PART_MODE_NORMAL -> VM_PART_MODE_COLD_START • VM_PART_MODE_WARM_START -> VM_PART_MODE_WARM_START • VM_PART_MODE_NORMAL -> VM_PART_MODE_WARM_START
If requesting an operating mode change while another one is still pending, the change only succeeds if the new operating mode has a higher priority than the pending one. Otherwise the function will return an error. This takes pending requests from all other sources beside this service into account, like Health Monitoring and requests from System Extensions. The priority levels of operating modes are (lowest to highest):
• VM_PART_MODE_NORMAL • VM_PART_MODE_WARM_START • VM_PART_MODE_COLD_START • VM_PART_MODE_IDLE
Open files are closed before rebooting. Memory pools are reset. If operating_mode is VM_PART_MODE_IDLE, the partition will be halted. The parameter cookie allows specification of a value which will be saved for the resource partition if set_cookie is TRUE. The cookie’s value will be kept through partition reboots and can be read using the services vm_part_stat() (see section 1.10.4.5) or vm_part_pstat() (see section 1.10.4.4). Note that setting the cookie takes immediate effect, i.e., during shutdown for a new mode, the new cookie is already in effect. Setting the cookie is not atomically linked to setting the mode. Even in some error cases, the cookie will have been updated. See the error codes to see the relationship of cookie update and mode change. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success. P4_E_NOABILITY if the caller does not have the ability VM_AB_PART_SET_MODE. The cookie has not been set. P4_E_INVAL if id is not a valid partition ID. The cookie has not been set. P4_E_INVAL if the requested mode value is not a valid vm_part_operating_mode_t. The cookie has not been set. P4_E_INVAL if the requested mode cannot be requested by the requester, regardless of the current operating mode (e.g., NORMAL mode can only be requested by a partition itself, not from another partition). The cookie has not been set. P4_E_MISMATCH if the requested mode transition is not considered valid, i.e., from the current mode, a transition to the requested mode is not possible. (E.g. trying to switch from COLD_START to WARM_START or from IDLE to IDLE.) The cookie, if given, has been set. P4_E_STATE The operating mode change was requested before the target partition was able to handle a pending request and the new request was of lower priority than the pending one. The cookie, if given, has been set. P4_E_EXIST When redundantly switching from NORMAL to NORMAL mode. The cookie, if given, has been set.
Pre-Conditions:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
116 The PSSW API
vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: There is no mechanism for a partition to get informed when being rebooted, e.g. to perform critical cleanup tasks.
See also: vm_part_stat() (see section 1.10.4.5), vm_part_pstat() (see section 1.10.4.4)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Partition Management 117
1.10.4.2 vm_reboot
Reboot a partition.
Synopsis:
P4_e_t vm_reboot(vm_part_id_t id)
Parameters: id IN: Partition ID. The special value VM_RESPART_MYSELF is used to address the caller’s partition. The numbering of id starts from one.
Description: Restart the partition given by id into VM_PART_MODE_COLD_START mode. UniversalisOS ensures that the partition restarts in exactly the same environment as booted for the first time. All resources as preassigned in the VMIT are freed and available again to the partition upon startup. Permission restrictions apply, if a non negative number is given for id. A partition always has the per- mission to reboot itself. In order to reboot another partition the calling partition must have the ability VM_AB_PART_SET_MODE. Open files are closed before rebooting. Memory pools are reset. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success. P4_E_NOABILITY if the caller does not have the ability VM_AB_PART_SET_MODE. P4_E_INVAL if id is not a valid partition ID. P4_E_STATE The operating mode change was requested before the target partition was able to handle a pending request and the new request was of lower priority than the pending one.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: There is no mechanism for a partition to get informed when being rebooted, e.g. to perform critical cleanup tasks.
See also: vm_part_set_mode() (see section 1.10.4.1)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
118 The PSSW API
1.10.4.3 vm_shutdown
Shutdown a partition.
Synopsis:
P4_e_t vm_shutdown(vm_part_id_t id)
Parameters: id IN: Partition ID. The special value VM_RESPART_MYSELF is used to address the caller’s partition. The numbering of id starts from one.
Description: Shutdown partition given by id into VM_PART_MODE_IDLE mode. UniversalisOS ensures that all resources, preassigned through the VMIT are freed and would be available again at restart. Permission restrictions apply, if a non negative number is given for id. A partition always has the permis- sion to shutdown itself. In order to shutdown another partition the calling partition must have the ability VM_AB_PART_SET_MODE. Open files are closed prior to shutdown. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success. P4_E_NOABILITY if the caller does not have the ability VM_AB_PART_SET_MODE. P4_E_INVAL if id is not a valid partition ID. P4_E_MISMATCH if the requested mode transition is not considered valid, i.e., from the current mode, a transition to the requested mode is not possible. (E.g. trying to switch from IDLE to IDLE.) P4_E_STATE The operating mode change was requested before the target partition was able to handle a pending request and the new request was of lower priority than the pending one.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: There is no mechanism for a partition to get informed when being rebooted, e.g. to perform critical cleanup tasks.
See also: vm_part_set_mode() (see section 1.10.4.1)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Partition Management 119
1.10.4.4 vm_part_pstat
Return status information of a partition identified by id.
Synopsis:
P4_e_t vm_part_pstat(vm_part_id_t id, vm_partition_stat_t *status)
Parameters: id IN: Partition ID. The special value VM_RESPART_MYSELF is used to address the caller’s partition. The numbering of id starts from one. status OUT: Upon success, the structure elements at status are filled in. In case of error, the content is undefined.
Description: This function provides several information about the current status of the partition given by id. See the description of vm_partition_stat_t for the list of properties available. Permission restrictions apply, if a non negative number is given for id. A partition always has the permission to call vm_part_pstat() (see section 1.10.4.4) for itself. In order to retrieve the status of another partition the calling partition must have the ability VM_AB_MONITOR. If called from a system extension, then id must not be VM_RESPART_MYSELF. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If status is NULL, this function has undefined behavior. If this function returns anything but P4_E_OK, the contents of status are unspecified.
Returns: P4_E_OK upon success P4_E_INVAL if id is not a valid partition ID, or if id is VM_RESPART_MYSELF and the function is invoked from a system extension. P4_E_NOABILITY if the caller does not have the ability to execute the call. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
Note: Since the partition IDs are ascending numbers, this function can be used to iterate through all existing partitions.
See also: vm_part_stat() (see section 1.10.4.5) and vm_partition_stat_t
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
120 The PSSW API
1.10.4.5 vm_part_stat
Return status information of a partition identified by name.
Synopsis:
P4_e_t vm_part_stat(const char *name, vm_partition_stat_t *status)
Parameters: name IN: Partition name status OUT: Upon success, the structure elements at status are filled in. In case of error, the content is undefined.
Description: This function provides several information about the current status of the partition given by name. See the description of vm_partition_stat_t for the list of properties available. A partition always has the permission to call vm_part_stat() (see section 1.10.4.5) for itself. In order to retrieve the status of another partition the calling partition must have the ability VM_AB_MONITOR. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If status is NULL, this function has undefined behavior. If this function returns anything but P4_E_OK, the contents of status are unspecified.
Returns: P4_E_OK upon success P4_E_INVAL if name is not a valid partition name. P4_E_NOABILITY if the caller does not have the ability to access information of partition name. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
See also: vm_part_pstat() (see section 1.10.4.4) and vm_partition_stat_t
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Process Management 121
1.11 Process Management
This section describes functions to retrieve information on processes and get the command line of the calling process.
1.11.1 Structure Definitions
1.11.1.1 struct vm_procinfo_t
Data structure providing information about a process
See also: vm_procinfo() (see section 1.11.4.2)
Synopsis: struct vm_procinfo_t { P4_task_t first_child_task_num; P4_task_t last_child_task_num; P4_task_t proc_task_num; P4_prio_t mcp; P4_size_t cmd_line_len; char appname[VM_NAME_LEN]; };
Structure Element Description: first_child_task_num Task identifier of the first child last_child_task_num Task identifier of the last child proc_task_num Identifier of the process’ task mcp Maximum controlled priority of the process cmd_line_len Length of the command line string (excluding terminating zero) appname Name of the application
1.11.1.2 struct vm_proc_memseg_t
A memory segment mapped for a process
Note: Use VM_MEMSEG_...() extractor macros.
Synopsis: struct vm_proc_memseg_t { P4_address_t virtbase; P4_phys_addr_t physbase; P4_size_t size; char req_name[VM_NAME_LEN]; };
Structure Element Description:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
122 The PSSW API
virtbase Virtual memory address, lower bits carry attribute information physbase Physical memory address, lower bits carry type information size Size of memory segment, in bytes req_name Name of the memory requirement from which the mapping was established
1.11.2 Defines
VM_PROC_MYSELF
Description:
Symbol to refer to the calling process.
This may be used as a synonym for the process iteration number of the calling process in calls to
vm_procinfo() (see section 1.11.4.2).
VM_MEMSEG_ISCONTIG (x)
Description:
Test if a memory segment is mapped to a physically contiguous resource.
Parameters:
x Virtual memory entry found in the memory segment table.
Returns:
1 if the memory is contiguous, 0 otherwise.
VM_MEMSEG_CACHE (x)
Description:
Retrieve the cache attributes of a memory segment.
Parameters:
x Virtual memory entry found in the memory segment table.
Returns:
Value defined in enumeration vmitMemoryCacheMode_t.
VM_MEMSEG_ACCESS (x)
Description:
Test access permissions of a memory segment.
Parameters:
x Virtual memory entry found in the memory segment table.
Returns:
Value defined in enumeration vmitMemoryAccessMode_t.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Process Management 123
VM_MEMSEG_ADDR (x)
Description:
Extract the virtual memory address part of an entry in the memory segment table
Parameters:
x Virtual memory entry found in the memory segment table.
Returns:
Virtual memory address.
VM_MEMSEG_PHYS_ADDR (x)
Description:
Extract the physical memory address part of an entry in the memory segment table
Parameters:
x Physical memory entry found in the memory segment table.
Returns:
Physical memory address.
VM_MEMSEG_MEMTYPE (x)
Description:
Extract the memory type part of a process memory segment
Parameters:
x Physical base address of a process memory segment
Returns:
An object of the type vm_memory_type_t.
1.11.3 Data Type Definitions
vm_proc_id_t Process identifier
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
124 The PSSW API
1.11.4 Functions
1.11.4.1 vm_cmd_line
Retrieve the command line string of the calling process.
Synopsis:
P4_e_t vm_cmd_line(char *buff, P4_size_t buff_size)
Parameters: buff OUT: Upon a successful call buff holds the command line string. buff_size IN: Size of the buffer buff
Description: A call to this function returns the command line string of the calling process in a buffer referenced by buff. If the command line string is longer than buff_size bytes (including the terminating NUL character), only buff_size - 1 bytes are copied and the NUL character is appended. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If this function returns anything but P4_E_OK, the contents of cmd are unspecified.
Returns: P4_E_OK upon success P4_E_INVAL if buff_size is zero. P4_E_TRUNC if the command line string has been truncated to buff_size - 1 bytes. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Note: vm_procinfo() (see section 1.11.4.2) can be used to get the length of the command line string. A buffer of the length returned plus one must be provided to be sure the string fits into memory.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Process Management 125
1.11.4.2 vm_procinfo
Retrieve process information.
Synopsis:
P4_e_t vm_procinfo(vm_part_id_t part_id, vm_proc_id_t proc_id, vm_procinfo_t *info)
Parameters: part_id IN: Partition ID as assigned in the VMIT. The special value VM_RESPART_MYSELF is used to address the caller’s partition. proc_id IN: Process iteration number, or VM_PROC_MYSELF to get information about the caller’s process. info OUT: Upon success, process information is returned in info.
Description: This function retrieves information about all processes or about the caller’s process only. If proc_id is VM_PROC_MYSELF and part_id is VM_RESPART_MYSELF, information about the caller’s process is returned. Iteration through the processes of a given partition part_id starts from proc_id = 0. Iteration is complete if P4_E_NOENT is returned. The calling partition needs the ability VM_AB_MONITOR to retrieve information about a process of another partition. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If info is NULL, this function has undefined behavior. If this function returns anything but P4_E_OK, the contents of info are unspecified.
Returns: P4_E_OK upon success P4_E_NOENT if no process with the given part_id and proc_id is configured. P4_E_INVAL if VM_PROC_MYSELF was given for proc_id but part_id was not the caller’s resource partition. P4_E_NOABILITY if the caller does not have the ability to access information of the requested process. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
See also: vm_part_pstat() (see section 1.10.4.4), vm_part_stat() (see section 1.10.4.5)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
126 The PSSW API
1.11.4.3 vm_proc_mem_iterate
Return the properties of a process’s memory segment.
Synopsis:
P4_e_t vm_proc_mem_iterate(P4_uint32_t id, vm_proc_memseg_t *info)
Parameters: id IN: Memory requirement ID info OUT: Memory pool status
Description: This function returns the properties of a process’s memory segment. The segment is specified by its index. This function can be used to iterate through the current process’s list of memory segments. Iteration should start with the parameter id set to 0; the end of the memory segment is reached when the call returns the error code P4_E_NOENT. vm_proc_memseg_t memseg; for(id = 0; vm_proc_mem_iterate(id, &memseg) == P4_E_OK; id++) { ... }
This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If info is NULL, this function has undefined behavior. If this function returns anything but P4_E_OK, the contents of info are unspecified.
Returns: P4_E_OK upon success P4_E_NOENT if the end of the memory requirement list has be reached P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: The system software library must have been initialized by a call to vm_init() (see section 1.4.1.1).
See also: vm_mem_stat() (see section 1.6.3.3), vm_mem_lookup() (see section 1.6.3.1)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Health Monitoring 127
1.12 Health Monitoring
The UniversalisOS health monitoring system is designed to detect errors at system runtime and allows execution of recovery actions as configured by the system integrator. It is mainly inspired by the ARINC 653 standard. For more information see UniversalisOS Kernel Reference Manual, section 1.37, page 449 and UniversalisOS User Manual.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
128 The PSSW API
1.13 Time Partition Management
This section describes functions to switch time partition schemes.
1.13.1 Structure Definitions
1.13.1.1 struct vm_tsched_stat_t
Data structure providing information about the time partition schedule. The current_sched_id, next_sched_id, cur- rent_sched_name, and next_sched_name members of this structure are global to the system. The last_change, major_time_framecpu_mask, and sync_cpu members are local to a synchronized set of CPUs. @ see vm_time_sched_stat().
Synopsis: struct vm_tsched_stat_t { P4_time_t last_change; P4_time_t major_time_frame; P4_cpumask_t cpu_mask; P4_cpuid_t sync_cpu; vm_tsched_id_t current_sched_id; vm_tsched_id_t next_sched_id; char current_sched_name[VM_NAME_LEN]; char next_sched_name[VM_NAME_LEN]; };
Structure Element Description: last_change Time of the last schedule change on the given CPU major_time_frame Major Time Frame of the window table assigned to the given CPU cpu_mask CPUs to which the window table is assigned sync_cpu CPU to which the time partition schedule on all CPUs in cpu_mask is synchronized current_sched_id ID of the current time partition schedule next_sched_id ID of the next time partition schedule current_sched_name Name of the current time partition schedule next_sched_name Name of the next time partition schedule
1.13.2 Defines
VM_TSCHED_CHANGE_SYNC_MAJOR
Description:
Flag to sync time partition switching at major time frame.
1.13.3 Data Type Definitions
vm_tsched_id_t Time partition schedule identifier
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Time Partition Management 129
1.13.4 Functions
1.13.4.1 vm_tsched_lookup
Lookup the scheduling scheme id by name.
Synopsis:
P4_e_t vm_tsched_lookup(const char *name, vm_tsched_id_t *id)
Parameters: name IN: Name of new scheduling scheme id OUT: ID of the scheduling scheme name
Description: This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If id is NULL, this function has undefined behavior. If this function returns anything but P4_E_OK, the contents of id are unspecified.
Returns: P4_E_OK upon success P4_E_NOENT if name is not a scheduling scheme defined in the VMIT. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
130 The PSSW API
1.13.4.2 vm_tsched_stat
Retrieve the time partition scheduling status for a CPU.
Synopsis:
P4_e_t vm_tsched_stat(P4_cpuid_t cpuid, vm_tsched_stat_t *stat)
Parameters: cpuid IN: CPU id for the time partition scheduling status. P4_CPU_MYSELF for the caller’s CPU stat OUT: Time partition scheduling status structure
Description: The retrieved status contains global information about the current and the next scheduling scheme applicable to all CPUs with active time partitioning. If not scheme change is requested, the current and the next scheme are the same. Beside the global information, the status contains information of one window table within the current scheme. The window table is the one in the current scheme that contains cpuid in its CPU mask. If the caller has not the ability to manipulate time partition scheduling, the CPU mask of the window table is ANDed with the CPU mask of the caller’s partition and in the Sync CPU information is set to P4_NUM_CPU.
See also: vm_tsched_stat_t This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. If stat is NULL, this function has undefined behavior. If this function returns anything but P4_E_OK, the contents of stat are unspecified.
Returns: P4_E_OK upon success P4_E_STATE if on CPU cpuid time partition scheduling is not activated. P4_E_NOABILITY if the calling partition does not have the ability VM_AB_TIMEPART_SETUP and cpuid is not in its CPU mask. P4_E_INVAL if cpuid is invalid. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Time Partition Management 131
1.13.4.3 vm_tsched_change
Change the time partitioning scheme to the specified one.
Synopsis:
P4_e_t vm_tsched_change(vm_tsched_id_t id, P4_uint32_t sync)
Parameters: id IN: ID of new scheduling scheme to switch to. sync IN: Synchronization flag for the scheduling change. If this is VM_TSCHED_CHANGE_SYNC_MAJOR, then P4_TIMEPART_SWITCH_MAJOR will be used, otherwise P4_TIMEPART_SWITCH_IMMEDIATE.
Description: Request to switch to scheduling scheme id. The time partition scheme is identified using an id as returned by vm_tsched_lookup. No dynamic change or creation of the scheme is possible. If the flag VM_TSCHED_CHANGE_SYNC_MAJOR is not set in sync, the change is executed immediately (at the next system tick). If the flag VM_TSCHED_CHANGE_SYNC_MAJOR is set in sync, the change to the next scheme is synchronized to the next Major Time Frame. The time partition switch synchronization point is either the next system tick or the major time frame expiration. All subsequent schedule switch requests that occur before the synchronization point lead to the PSSW spinning until the pending switch is completed. During this time application code on the same core in the resource partition of the caller will not be able to execute. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success P4_E_NOENT if id does not identify a scheduling scheme defined in the VMIT. P4_E_NOABILITY if the calling partition does not have the ability. VM_AB_TIMEPART_SETUP. P4_E_STATE if VM_TSCHED_CHANGE_SYNC_MAJOR is set in sync but time partitioning is currently not active. P4_E_CONFIG if VM_TSCHED_CHANGE_SYNC_MAJOR is set in sync but strong time partition synchro- nization is not enabled via the kernel configuration parameter tps_strong_sync. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled. P4_E_INVAL if the kernel does not allow switching because the input parameters are invalid. Please refer to the kernel reference manual and the function p4_timepart_switch() for details about this error case.
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
132 The PSSW API
1.14 System Extensions API
The concept of System Extensions provide a way to enhance certain aspects of the PSSW and its API. This section details the definitions and datatypes which are common to all System Extension classes. To develop a module for a specific extension class please see the corresponding chapter. The API available to System Extensions contains a subset of the PSSW API available to applications as well as additional service calls. The following PSSW service calls are available for use by System Extensions:
• vm_cprintf() (see section 1.5.2.1)
• vm_cputs() (see section 1.5.2.2)
• vm_open() (see section 1.7.4.1)
• vm_read() (see section 1.7.4.3)
• vm_read_at() (see section 1.7.4.5)
• vm_write() (see section 1.7.4.4)
• vm_write_at() (see section 1.7.4.6)
• vm_fstat() (see section 1.7.4.8)
• vm_stat() (see section 1.7.4.9)
• vm_lseek() (see section 1.7.4.10)
• vm_close() (see section 1.7.4.11)
• vm_map() (see section 1.7.4.12)
• vm_map_to() (see section 1.7.4.16)
• vm_ioctl() (see section 1.7.4.13)
• vm_prop_read() (see section 1.16.2.1)
• vm_prop_write() (see section 1.16.2.2)
• vm_prop_mem_map() (see section 1.16.2.3)
• vm_prop_ioport_map() (see section 1.16.2.4)
• vm_prop_int_grant() (see section 1.16.2.5)
• vm_prop_dev_grant() (see section 1.16.2.6)
• vm_part_pstat() (see section 1.10.4.4)
The additional service calls are described in this section.
1.14.1 Header File
Include this header file additionally for system extensions functionality: #include <vm_se.h>
1.14.2 Structure Definitions
1.14.2.1 struct vm_se_if_t
System extension interface descriptor. This is the minimum information a system extension must provide to its manager framework. The individual extension classes (VM_SE_CLASS_*) define additional descriptor fields which are specific to the corresponding class, such as function callbacks.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
System Extensions API 133
An object of this type should not be defined directly. Instead, it is used as member in API structures, where it should be initialized by means of the macro VM_SE_DESCRIPTOR() (see section 1.14.3).
Synopsis: struct vm_se_if_t { P4_uint32_t version; char driver_name[VM_NAME_LEN+1]; };
Structure Element Description: version Port provider interface version number. Set to VM_SE_IF_VERSION. driver_name Extension name. A string which identifies the system extension in the system.
1.14.2.2 struct vm_se_shm_iterate_t
Data structure for iteration over configured shared memory requirements by system extensions.
Synopsis: struct vm_se_shm_iterate_t { void * iter; const char * name; P4_address_t vaddr; P4_phys_addr_t paddr; P4_address_t palign; P4_uint32_t type; P4_uint32_t access_mode; P4_uint32_t cache_mode; P4_uint32_t mem_region_partition; P4_uint32_t mem_region_id; P4_uint32_t contiguous; P4_size_t size; P4_size_t zero_count; };
Structure Element Description: iter PSSW internal iterator name Name of the shared memory requirement vaddr The virtual address of the memory requirement in the virtual address space of the System Software. paddr The physical address the memory requirement has been mapped to. palign The alignment of the memory requirement. This value is unspecified if the absolute physical address was given in the VMIT, i.e., the value read back here may be different from the VMIT specification, because the memory subsystem ignored it. type The type of the memory requirement. access_mode The Permissions of the memory requirement. cache_mode Cache mode mem_region_partition Memory region partition mem_region_id Memory region ID
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
134 The PSSW API
contiguous Flag whether the memory is contiguous size The size of the memory requirement. zero_count Number of Bytes zeroed by the PSSW at module init
1.14.3 Defines
__vm_init
VM_GLOBAL
Description:
Constant signifying global memory for a partition ID.
VM_DECLARE_SE (desc) Declare a system extension. Description: This macro publishes a system extension. A special section in the ELF binary passes the information to the PSSW system extension loader.
Parameters:
desc Pointer to the system extension descriptor.
VM_SE_HOOK_PART_TABLE Index of hooks to PSSW internals.
VM_SE_IF_VERSION
Description:
Version number of system extension API.
VM_SE_PRIO_NUM
Description:
Number of priority levels that can be used with vm_thread_create() (see section 1.14.6.6).
VM_SE_DESCRIPTOR (klass, name) Initialize a common system extension descriptor. Description: This macro is used to initialize a vm_se_if_t data object for a system extension with classname.
Parameters:
class System extension class.
name Pointer to the name to register the System Extension with.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
System Extensions API 135
1.14.4 Function Type Definitions
1.14.4.1 vm_se_part_change_cb_t
Synopsis:
typedef void vm_se_part_change_cb_t(vm_part_id_t part_id, vm_part_operating_mode_t mode, P4_bool_t is_startup)
Description: Handler for partition state change callbacks.
Parameters: part_id IN: Numeric partition ID. mode IN: Partition state. On partition startup, this value reflects the new partition state. On partition shutdown, this reflects the planend new partition state, but we cannot guaranteed that this will really happen that way: at shutdown, we cannot give the new mode exactly, but only a current prognosis, because it might change after invoking this callback by a stricter decision, because the shutdown is not atomic (e.g., is is possible that this is called with COLD_START, but we go down to IDLE).
Parameters: is_startup IN: Startup status, true on partition startup, false on shutdown. If NORMAL mode is entered from WARM_START or COLD_START, this will be FALSE.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
136 The PSSW API
1.14.5 Enumerations
Enumeration type vm_se_prio_t
Coarse grained priority levels for system extension threads. Defines a set of five priority levels. Used as an argument for vm_thread_create() (see section 1.14.6.6).
Name Description VM_SE_PRIO_LOWEST Priority value for lowest priority system extension thread.
VM_SE_PRIO_LOW Priority value for low priority system extension thread.
VM_SE_PRIO_MEDIUM Priority value for medium priority system extension thread.
VM_SE_PRIO_HIGH Priority value for high priority system extension thread.
VM_SE_PRIO_HIGHEST Priority value for highest priority system extension thread.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
System Extensions API 137
1.14.6 Functions
1.14.6.1 vm_alloc_virt
Allocate virtual memory.
Synopsis:
P4_address_t vm_alloc_virt(P4_size_t size, P4_phys_addr_t ref_addr, P4_uint32_t part_id)
Parameters: size IN: Size of virtual memory to allocate in bytes. ref_addr IN: Physical reference address. This should be the physical address that is to be mapped into the virtual memory. This is needed for some architectures to return correctly aligned virtual addresses. If you know that you don’t care, use ~(P4_phys_addr_t)0. part_id IN: The resource partition ID to allocate virtual memory from. Use VM_GLOBAL to allocate from the global pool of virtual memory.
Description: Tries to allocate an page-aligned unmapped virtual memory area of the specified size, rounded up to a multiple of the page size. On success, a pointer to the allocated memory region is returned in mem. PSSW’s memory, including the virtual memory, is partitioned, so a partition ID is passed to determine which partition to allocate it from.
Note: The virtual memory allocated with this service can be used with the p4_mem_create() system call.
Returns: A virtual address !=0 on success. 0 if there is no memory left.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
138 The PSSW API
1.14.6.2 vm_malloc_aligned
Allocate an array of elements from RAM conforming to the specified alignment constraint.
Synopsis:
static __forceinline __vm_init void* vm_malloc_aligned(P4_size_t elem_cnt, P4_size_t elem_sz, P4_address_t alignment, unsigned part)
Parameters: elem_cnt IN: The number of elements to allocate. If you need only one element, you may pass 1. A value of 0 is OK. elem_sz IN: The size of a single element in the array. A value of 0 is OK, but would indicate that what was passed was not the result of a sizeof(), because objects cannot have size 0 in C. alignment IN: Alignment constraint in bytes. This must be a power of two. part IN: Partition ID of the resource partition to allocate the RAM from. Use VM_GLOBAL to select the global memory pool.
Description: The memory is taken from the UniversalisOS System Software’s internal memory. Once allocated it cannot be released. On success, the service returns a pointer to the allocated memory area and NULL in case of an error. This service may only be used in the installation entry points of system extensions and in the configuration entry point of port provider system extensions. The memory is taken from one of the different pools that exist, which are organized per partition. The partition argument selects which pool to allocate from. This function protects against integer overflows when multiplying elem_cnt and elem_sz. To be efficient, the second argument to this function should be constant. I.e., if you allocate a single area, pass ’1’ as second argument, not as first.
Note: The content of the allocated memory is undefined, i.e., it will not be zeroed.
Returns: The base address of the allocated memory, or NULL if no memory could be allocated. NULL is also return in case of an integer overflow when multiplying elem_cnt with elem_sz. Note that this returns a valid pointer if count*size1 is 0. NULL is only returned in case of an error (out of memory or integer overflow in multiplication).
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
System Extensions API 139
1.14.6.3 vm_malloc
Synopsis:
static __forceinline __vm_init void* vm_malloc(P4_size_t elem_cnt, P4_size_t elem_sz, unsigned part)
Parameters: elem_cnt IN: The number of elements to allocate. If you need only one element, you may pass 1. A value of 0 is OK. elem_sz IN: The size of a single element in the array. A value of 0 is OK, but would indicate that what was passed was not the result of a sizeof(), because objects cannot have size 0 in C. part IN: The partition number of the partition to allocate memory from. VM_GLOBAL signifies the global memory pool not associated with any resource partition.
Description: Allocate memory with the default alignment. Exactly equal to vm_malloc_aligned, except that the alignment is automatically selected by the framework. The alignment is large enough for any machine data type of the architecture. This function is a convenience function for the most common cases where the caller does not require a specific alignment, but where the default is OK. Like vm_malloc_aligned(), this protects against integer overflows when multiplying elem_cnt and elem_sz.
Returns: The base address of the allocated memory, or NULL if no memory could be allocated. NULL is also return in case of an integer overflow when multiplying elem_cnt with elem_sz.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
140 The PSSW API
1.14.6.4 vm_calloc_aligned
Allocate an array of zeroed elements from RAM conforming to the specified alignment constraint.
Synopsis:
static __forceinline __vm_init void* vm_calloc_aligned(P4_size_t elem_cnt, P4_size_t elem_sz, P4_address_t alignment, unsigned part)
Parameters: elem_cnt IN: The number of elements to allocate. If you need only one element, you may pass 1. A value of 0 is OK. elem_sz IN: The size of a single element in the array. A value of 0 is OK, but would indicate that what was passed was not the result of a sizeof(), because objects cannot have size 0 in C. alignment IN: Alignment constraint in bytes. This must be a power of two. part IN: Partition ID of the resource partition to allocate the RAM from. Use VM_GLOBAL to select the global memory pool.
Description: This is just like vm_malloc_aligned but guarantees zeroed memory.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
System Extensions API 141
1.14.6.5 vm_calloc
Synopsis:
static __forceinline __vm_init void* vm_calloc(P4_size_t elem_cnt, P4_size_t elem_sz, unsigned part)
Parameters: elem_cnt IN: The number of elements to allocate. If you need only one element, you may pass 1. A value of 0 is OK. elem_sz IN: The size of a single element in the array. A value of 0 is OK, but would indicate that what was passed was not the result of a sizeof(), because objects cannot have size 0 in C. part IN: The partition number of the partition to allocate memory from. VM_GLOBAL signifies the global memory pool not associated with any resource partition.
Description: Allocate zeroed memory with the default alignment. This is just like vm_malloc but guarantees zeroed memory.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
142 The PSSW API
1.14.6.6 vm_thread_create
Create a new system extension thread.
Synopsis:
P4_e_t vm_thread_create(P4_thr_t *tid, const char *name, vm_se_prio_t prio_level, void(*entry)(void *), P4_size_t stacksize, void *user)
Parameters: tid OUT: handle of the new thread name IN: name of new thread prio_level IN: priority level of the new thread entry IN: pointer to a function to be executed by the new thread stacksize IN: size, in bytes, of stack to be allocated for the new thread user IN: user argument passed to the thread function func
Description: Create a new system extension thread. The new thread is created in stopped mode and should be released by calling p4_thread_resume().
Note: Once created, a thread can never be deleted. Threads can only be created during the initialization phase, and not at runtime. Threads have to be created directly in the context of the installation or configuration entry point of system exten- sions. Threads should not be created by other threads. If one of the arguments entry or user is invalid, the behavior is undefined. To start a thread, use p4_thread_resume(). To stop it, use p4_thread_stop().
Returns: P4_E_OK Upon success P4_E_LIMIT If the thread could not be allocated Other error codes are like those of p4_thread_create().
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
System Extensions API 143
1.14.6.7 vm_crit_enter
Enter a critical section.
Synopsis:
void vm_crit_enter(P4_prio_t *prio)
Parameters: prio OUT: pointer to the current thread state
Description: A call to this function disables all thread and time partition switching. Code enclosed by vm_crit_enter() (see section 1.14.6.7) and vm_crit_leave() (see section 1.14.6.8) should be as brief as possible and always have constant, deterministic execution time. The current system state will be stored in state. The critical section must be left by a call to vm_crit_leave() (see section 1.14.6.8) with the same argument state.
Note: This call is only available for system extensions.
Note: If calls to vm_crit_enter() (see section 1.14.6.7)/vm_crit_leave() are nested, a unique "state" data object must be used at each nesting level. The behavior is undefined if a unique "state" object is not used at each nesting level.
See also: vm_crit_leave() (see section 1.14.6.8)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
144 The PSSW API
1.14.6.8 vm_crit_leave
Leave a critical section.
Synopsis:
void vm_crit_leave(P4_prio_t *prio)
Parameters: prio IN: pointer to previous system state
Description: Return from a critical section. The value pointed to by state must be the one previously returned by vm_crit_enter() (see section 1.14.6.7).
Note: This call is only available for system extensions.
Note: If calls to vm_crit_enter() (see section 1.14.6.7)/vm_crit_leave() are nested, a unique "state" data object must be used at each nesting level. The behavior is undefined if a unique "state" object is not used at each nesting level.
See also: vm_crit_enter() (see section 1.14.6.7)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
System Extensions API 145
1.14.6.9 vm_add_romimage
Deploy a mapped ROM image to add the contents of its file system to the extensible ROM file system (xrfs). The files are addressed via the directory specified with the call. For instance, if a ROM image containing a file f is registered with the directory p, a call to vm_open() may address the file via xrfs:p/f.
Synopsis:
P4_e_t vm_add_romimage(const void *start, const char *sub_prefix)
Parameters: start IN: virtual address of a ROM image to be added sub_prefix IN: name of the directory to be used to address the added ROM Image
Description: A call to this function will deploy the ROM image mapped to address start to the extensible ROM file system. A maximum of 16 ROM images may be registered during runtime.
Returns: P4_E_OK Upon success. P4_E_INVAL If the memory at the given virtual address does not contain a valid ROM image. P4_E_INVAL If the given directory contains the path delimiter. P4_E_INVAL If the given directory has already been registered. P4_E_OOMEM If the maximum number of ROM images has already been registered.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
146 The PSSW API
1.14.6.10 vm_monitor_hook
Monitoring Hook into the PSSW for System Extensions. This service returns pointers to various internal data structures. The caller has to include private headers of the PSSW component in order to be able to parse those data structures.
Synopsis:
void* vm_monitor_hook(unsigned int type)
Parameters: type IN: ID of requested data structure. This is one of the VM_SE_HOOK_* constants.
Returns: Pointer to requested data structure or NULL if type does not refer to a known data structure.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
System Extensions API 147
1.14.6.11 vm_register_part_change_cb
Register a callback handler for partition startup and shutdown. The PSSW registers the handler cb as callback for partition mode change. The PSSW will call this handler at partition startup, shutdown, and transition to mode VM_PART_MODE_NORMAL from the partition daemon’s context.
Synopsis:
P4_e_t vm_register_part_change_cb(vm_se_part_change_cb_t *cb)
Parameters: cb Callback to be registered.
Description: At startup, the callback will be passed the new mode. At shutdown, it will be passed the planned new mode. Not that the new mode might become stricter until the shutdown is complete, so this is not guaranteed to be the new mode, but just the current plan at the time of shutting down the partition.
Returns: P4_E_OK Upon success.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
148 The PSSW API
1.14.6.12 vm_get_acl
Iterate all file access configuration entries of a partition.
Synopsis:
P4_e_t vm_get_acl(unsigned int part_id, unsigned int idx, char *name, P4_size_t name_sz, vm_file_access_mode_t *access_mode)
Parameters: part_id IN: Specifies the ID of the partition to query. idx IN: An integer to be iterated from 0 contiguously upwards by the caller. The first value must be 0, the second 1, etc., until this function return P4_E_NOENT. name OUT: Access control path name string, including the final ’*’ for wildcard matches. This is a copy of what was found in the VMIT. name_sz IN: Is the size of the allocated array ’name’. If there is not enough space to store the whole string. If There is not enough space for the whole path as given in the VMIT, this function will return P4_E_TRUNC, otherwise P4_E_OK. For full paths, this should be VM_MAX_PATHNAME_LEN. For provider names, VM_NAME_LEN will suffice. access_mode OUT: VMIT file access flags indicating provider type.
Description: The behavior of this function is undefined if part_id == 0. The behavior of this function is undefined if name_sz == 0.
Returns: P4_E_OK if an entry was found, name was stored without truncation, and access_mode was set. P4_E_TRUNC if an entry was found, name was stored but truncated, and access_mode was set. P4_E_NOENT if no such entry was found. P4_E_INVAL if the partition was not found in the system.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
System Extensions API 149
1.14.6.13 vm_shm_iter_init
Iterate shared memory requirements.
Synopsis:
void vm_shm_iter_init(vm_se_shm_iterate_t *it)
Parameters: it IN: pointer to the iteration structure which is initialized.
Description: Called once to start iteration by initializing the iterator. The internal iterator is modified to point to the first memory requirement (if existent).
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
150 The PSSW API
1.14.6.14 vm_shm_iter_take
Iterate shared memory requirements.
Synopsis:
P4_bool_t vm_shm_iter_take(vm_se_shm_iterate_t *it)
Parameters: it IN: pointer to the iteration structure which is filled.
Description: Can be called in loop until FALSE is returned to iterate all configured shared memory requirements. The Payload data of the iteration structure (e.g. name, vaddr, paddr, ...) is set for the current memory requirement. Furthermore the internal iterator is modified to point to the next requirement (if existent). If the alignment is ignored by the memory subsystem, e.g. because a physical address was explicitly given, then the exact value for the alignment returned by this function is unspecified.
Returns: TRUE if entry was returned. FALSE if no entry could be returned (e.g. at the end of the iteration).
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
System Extensions API 151
1.14.6.15 vm_thread_get_priv
Get the pointer to the TLS area reserved for SE drivers.
Synopsis:
void* vm_thread_get_priv(P4_size_t size)
Parameters: size The size of the area the driver wants to use.
Description: There are some severe limitations for drivers to use thread local storage (TLS) in SEs:
• TLS is not persistent across service calls, because TLS is shared among all drivers.
• TLS is not persistent across nested SE calls, because TLS is shared among all drivers.
• Because of the above limitations, the TLS area may be overwritten by arbitrary data before entering a driver
callback, in order to detect misuse.
• A driver must not rely on a particular value or initialization of the TLS when entered.
Also note that in threads created using vm_thread_create() (see section 1.14.6.6), drivers own the TLS priv pointer of those threads: these threads are not shared with other drivers, so here, the TLS is persistent in the expected way. The API follows that of other getter functions for private areas. The space reserved in TLS is just one pointer, i.e., sizeof(void*). This function will assert() that size is maximally equal to sizeof(void*). // set up TLS data (a single pointer) my_tls_data_t **tls = vm_thread_get_priv(sizeof(*tls)); *tls = &my_tls_data;
Returns: A pointer to the private TLS area reserved for drivers.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
152 The PSSW API
1.15 File Providers
File providers are a class of system extensions which are offering a file interface to the application. The system extension can then be accessed using the usual file system functions of the PSSW.
1.15.1 Header File
Include this header file additionally for file provider functionality: #include <vm_se_fp.h>
1.15.2 Structure Definitions
1.15.2.1 struct vm_se_fp_statics_t
Data type for File Provider static storage. A pointer to an object of this type is passed to any of the a file provider’s callback functions.
Synopsis: struct vm_se_fp_statics_t { void * mgr; void * user; };
Structure Element Description: mgr This pointer is private to the system extension manager and must not be touched by the provider. user The user pointer is private to the file provider and opaque to the system extension manager. It should be initialized in the provider’s install entry point. Typically it points to provider specific global data, pointers to hardware resources, etc.
1.15.2.2 struct vm_se_fp_if_t
The File Provider Interface is used by a provider to publish its function callbacks to the controlling extension manager.
Synopsis: struct vm_se_fp_if_t { vm_se_if_t extension; vm_se_fp_install_t * install; vm_se_fp_open_t * open; vm_se_fp_close_t * close; vm_se_fp_read_t * read; vm_se_fp_write_t * write; vm_se_fp_ioctl_t * ioctl; vm_se_fp_fstat_t * fstat; vm_se_fp_map_t * map; vm_se_fp_prop_read_t * prop_read; vm_se_fp_prop_write_t * prop_write; vm_se_fp_prop_map_t * prop_map;
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File Providers 153
vm_se_fp_module_shutdown_t * module_shutdown;
vm_se_fp_partition_shutdown_t * partition_shutdown;
};
Structure Element Description: extension Common system extension interface descriptor install Provider install entry point. open Provider open entry point. close Provider close entry point. read Provider read entry point. write Provider write entry point. ioctl Provider ioctl entry point. fstat Provider fstat entry point. map Provider map entry point. prop_read Provider property read entry point. prop_write Provider property write entry point. prop_map Provider property map entry point. module_shutdown Provider module shutdown entry point. partition_shutdown Provider partition shutdown entry point.
1.15.3 Defines
vm_se_get_priv (fd, size)
1.15.4 Function Type Definitions
1.15.4.1 vm_se_fp_open_t
File Provider open file entry point.
Synopsis:
typedef P4_e_t vm_se_fp_open_t(void *private, P4_uid_t client, const char *path, P4_uint32_t oflags, P4_bool_t stat_rq, vm_file_desc_int_t *fd, vm_file_stat_t *stat)
Description: This entry point is mandatory to be implemented by File Provider System Extensions. This entry point is called if a client thread calls the API service vm_open() (see section 1.7.4.1) or vm_stat() (see section 1.7.4.9) on the System Extension File Provider’s file system. Internally the PSSW already creates its own file handle, which is
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
154 The PSSW API
passed to this function as fd. To store private data in the file handle, the file descriptor provides a private storage area named fp_private of size VM_FILE_PRIVATE_DATA_SIZE. This file descriptor and its private data are valid until the file is closed. Access to fp_private should be via vm_se_get_priv(). This function must not block.
Note: This entry point is mandatory for a file provider implementation.
Parameters: private IN: The private data of the File Provider as registered during installation. client IN: Client UID. path IN: The file pathname to open without the File Provider prefix. oflags IN: File access flags specified by the caller. stat_rq Can be ignored, it is always FALSE. fd IN: File descriptor to be completed by the File Provider. stat Can be ignored, it is always NULL.
Returns: P4_E_OK on success P4_E_NOTIMPL if the requested open mode is not supported or status retrieval is requested and not sup- ported. P4_E_BUSY if the File Provider System Extension is currently busy. P4_E_IO if the File Provider System Extension detects an miscellaneous I/O error. P4_E_TIMEOUT if the File Provider System Extension can currently not handle the request and wants to unblock the client to reissue the request at a later point in time. P4_E_NOENT if the specified file does not exist in the File Provider System Extension’s file system. P4_E_OOFILE if no free descriptor objects can be allocated from the File Provider System Extension’s descriptor pool.
1.15.4.2 vm_se_fp_close_t
File Provider close file entry point.
Synopsis:
typedef void vm_se_fp_close_t(void *private, P4_uid_t client, vm_file_desc_int_t *fd)
Description: This entry point is called if a client thread calls the API service vm_close() (see section 1.7.4.11) on the System Extension File Provider’s file system.
Note: This entry point is mandatory for a file provider implementation.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File Providers 155
Parameters: private IN: The private data of the File Provider as registered during installation. client IN: Client UID fd IN: File descriptor identifying the file to close.
Returns: nothing.
1.15.4.3 vm_se_fp_read_t
File Provider read from file entry point.
Synopsis:
typedef P4_e_t vm_se_fp_read_t(void *private, P4_uid_t client, vm_file_desc_int_t *fd, void *buff, P4_size_t buff_size, P4_origin_t origin, P4_off_t offset, P4_size_t *read_size_p, P4_off_t *new_pos_p)
Description: This entry point is optional to be implemented by File Provider System Extensions. This entry point is called if a client thread calls the API service vm_read() (see section 1.7.4.3), vm_lseek() (see section 1.7.4.10) or vm_read_at() (see section 1.7.4.5) on the System Extension File Provider’s file system. This function must not block.
Parameters: private The private data of the File Provider as registered during installation. client Client UID fd File descriptor identifying the file to read from. buff The read buffer. buff_size Size of the read buffer in bytes. origin Specifies how to interpret the offset parameter and which operations to perform. offset File offset to read from. Relative to either the current offset, the start or the end of the file as specified by origin. read_size_p Actual number of bytes read to be set by the File Provider. new_pos_p Updated logical file position to be set by the File Provider.
Returns: P4_E_OK on success P4_E_IO if the File Provider System Extension detects an miscellaneous I/O error.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
156 The PSSW API
P4_E_TIMEOUT if the File Provider System Extension can currently not handle the request and wants to
unblock the client to reissue the request at a later point in time.
P4_E_NOTIMPL if the requested operation is not supported.
P4_E_INVAL if some parameter is found to be invalid.
P4_E_TRUNC if the File Provider System Extension could not perform the requested operation or only a part
of it.
1.15.4.4 vm_se_fp_write_t
File Provider write to file entry point.
Synopsis:
typedef P4_e_t vm_se_fp_write_t(void *private, P4_uid_t client, vm_file_desc_int_t *fd, const void *buff, P4_size_t buff_size, P4_origin_t origin, P4_off_t offset, P4_size_t *written_size_p, P4_off_t *new_pos_p)
Description: This entry point is optional to be implemented by File Provider System Extensions. This entry point is called if a client thread calls the API service vm_write() (see section 1.7.4.4) or or vm_write_at() (see section 1.7.4.6) on the System Extension File Provider’s file system. This function must not block.
Parameters: private The private data of the File Provider as registered during installation. client Client UID. fd File descriptor identifying the file to write to. buff The write buffer. buff_size Size of the write buffer in bytes. origin Specifies how to interpret the offset parameter and which operations to perform. offset File offset to write to. Relative to either the current offset, the start or the end of the file as specified by origin. written_size_p Actual number of bytes written to be set by the File Provider. new_pos_p Updated logical file position to be set by the File Provider.
Returns: P4_E_OK on success P4_E_IO if the File Provider System Extension detects an miscellaneous I/O error. P4_E_TIMEOUT if the File Provider System Extension can currently not handle the request and wants to unblock the client to reissue the request at a later point in time.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File Providers 157
P4_E_NOTIMPL if the requested operation is not supported. P4_E_INVAL if some parameter is recognized to be invalid. P4_E_TRUNC if the File Provider System Extension could not perform the requested operation or only a part of it.
1.15.4.5 vm_se_fp_ioctl_t
File Provider I/O control entry point.
Synopsis:
typedef P4_e_t vm_se_fp_ioctl_t(void *private, P4_uid_t client, vm_file_desc_int_t *fd, P4_uint32_t cmd, void *data)
Description: This entry point is invoked if a client thread calls vm_ioctl() (see section 1.7.4.13) on a file descriptor identifying a file provided by the File Provider. This entry point is optional to be implemented by File Provider System Extensions. The command has to be defined with one of the following macros: • VM_IOC • VM_IOC_IN • VM_IOC_OUT • VM_IOC_INOUT
This function must not block.
Parameters: private The private data of the File Provider as registered during installation. client Client UID. fd File descriptor identifying the file to write to. cmd Command identifier. data Buffer used to transfer transfer command specific parameters.
Returns: P4_E_OK on success P4_E_TIMEOUT if the File Provider System Extension can currently not handle the request and wants to unblock the client to reissue the request at a later point in time. P4_E_IO if the File Provider System Extension detects an miscellaneous I/O error. P4_E_INVAL if some parameter is recognized to be invalid. P4_E_PERM if the File Provider System Extension does not permit the requesting client to perform the operation on the specified file. P4_E_NOTIMPL if the File Provider System Extension does not support the requested operation on the specified file.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
158 The PSSW API
1.15.4.6 vm_se_fp_fstat_t
File Provider File Status Retrieval entry point.
Synopsis:
typedef P4_e_t vm_se_fp_fstat_t(void *private, P4_uid_t client, vm_file_desc_int_t *fd, vm_file_stat_t *stat)
Description: This entry point is invoked if a client thread calls vm_fstat() (see section 1.7.4.8) on a file descriptor identifying a file provided by the File Provider. This entry point is optional to be implemented by File Provider System Extensions.
Parameters: private The private data of the File Provider as registered during installation. client Client UID. fd File descriptor identifying the file to retrieve the status of. stat File status to be set by the File Provider.
Returns: P4_E_OK on success. P4_E_IO if the File Provider System Extension detects an miscellaneous I/O error. P4_E_TIMEOUT if the File Provider System Extension can currently not handle the request and wants to unblock the client to reissue the request at a later point in time. P4_E_NOTIMPL if the requested operation is not supported.
1.15.4.7 vm_se_fp_map_t
File Provider Map entry point.
Synopsis:
typedef P4_e_t vm_se_fp_map_t(void *private, P4_uid_t client, vm_file_desc_int_t *fd, P4_task_t tid, P4_off_t offset, P4_size_t size, vm_memory_access_mode_t prot, P4_uint32_t flags, P4_address_t start)
Description: This entry point is invoked if a client thread calls vm_map() (see section 1.7.4.12) or vm_map_to() (see section 1.7.4.16) on a file descriptor identifying a file provided by the File Provider. This entry point is optional to be implemented by File Provider System Extensions.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File Providers 159
Parameters: private The private data of the File Provider as registered during installation. client Client UID. fd File descriptor identifying the file to map from. tid Destination task identifier. offset Offset within the file fd to map from. size Number of bytes to map. prot Memory access mode for the mapping. flags File open flags. Unused. start Start address for the mapping within the virtual address space of tid
Returns: P4_E_OK on success P4_E_IO if the File Provider System Extension detects an miscellaneous I/O error. P4_E_TIMEOUT if the File Provider System Extension can currently not handle the request and wants to unblock the client to reissue the request at a later point in time. P4_E_INVAL if some parameter is recognized to be invalid. P4_E_NOKMEM if the resource partition of tid has insufficient kernel memory to fully establish the mapping.
1.15.4.8 vm_se_fp_prop_read_t
File Provider property read entry point.
Synopsis:
typedef P4_e_t vm_se_fp_prop_read_t(void *private, P4_uid_t client, vm_file_desc_int_t *fd, const char *relpath, P4_prop_type_t type, P4_size_t size, void *read_buff, P4_size_t *read_size_p, P4_prop_type_t *read_type_p)
Description: This entry point is invoked if a client thread calls vm_prop_read() (see section 1.16.2.1) on a file descriptor identifying a file provided by the File Provider. This entry point is optional to be implemented by File Provider System Extensions.
Parameters: private The private data of the File Provider as registered during installation. client Client UID. fd File descriptor which, together with relpath, addresses the node to retrieve the property of. relpath Path of the element to read. Relative to the opened path. type Expected type of the element to read.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
160 The PSSW API
size Maximum size in bytes of the element to read.
read_buff Read buffer. read_size_p Number of bytes actually read. read_type_p Actual type of the read element.
Returns: P4_E_OK on success P4_E_TIMEOUT if the File Provider System Extension can currently not handle the request and wants to unblock the client to reissue the request at a later point in time. P4_E_IO if the File Provider System Extension detects an miscellaneous I/O error. P4_E_INVAL if some parameter is recognized to be invalid. P4_E_NOENT if the specified property does not exist in the File Provider System Extension’s file system. P4_E_NOTIMPL if the requested operation is not supported.
1.15.4.9 vm_se_fp_prop_write_t
File Provider property write entry point.
Synopsis:
typedef P4_e_t vm_se_fp_prop_write_t(void *private, P4_uid_t client, vm_file_desc_int_t *fd, const char *relpath, P4_prop_type_t type, P4_size_t size, const void *write_buff, P4_size_t *written_size_p)
Description: This entry point is invoked if a client thread calls vm_prop_write() (see section 1.16.2.2) on a file descriptor identifying a file provided by the File Provider. This entry point is optional to be implemented by File Provider System Extensions.
Parameters: private The private data of the File Provider as registered during installation. client Client UID. fd File descriptor which, together with relpath, addresses the node to write the property of. relpath Path of the element to write. Relative to the opened path. type Type of the element to write. size Size in bytes of the element to write. write_buff Write buffer. written_size_p Number of bytes actually written.
Returns: P4_E_OK on success
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File Providers 161
P4_E_IO if the File Provider System Extension detects an miscellaneous I/O error. P4_E_INVAL if some parameter is recognized to be invalid. P4_E_NOENT if the specified property does not exist in the File Provider System Extension’s file system. P4_E_NOTIMPL if the requested operation is not supported.
1.15.4.10 vm_se_fp_prop_map_t
File Provider property map entry point.
Synopsis:
typedef P4_e_t vm_se_fp_prop_map_t(void *private, P4_uid_t client, vm_file_desc_int_t *fd, const char *relpath, P4_prop_type_t type, P4_task_t task, P4_address_t addr, P4_size_t size, P4_address_t *mapped_addr_p, P4_size_t *mapped_size_p)
Description: This entry point is invoked if a client thread calls vm_prop_map() on a file descriptor identifying a file provided by the File Provider. This entry point is optional to be implemented by File Provider System Extensions.
Parameters: private The private data of the File Provider as registered during installation. client Client UID. fd File descriptor which, together with relpath, addresses the property node to map. relpath Path of the element to map. Relative to the opened path. type Expected type of the element to map. task Destination task identifier for the mapping. addr Address to establish the mapping at in the destination tasks’s virtual address space. size Requested size of the mapping. mapped_addr_p The actual address the mapping has been established at in the destination task’s address space. mapped_size_p Actual size of the established mapping.
Returns: P4_E_OK on success P4_E_IO if the File Provider System Extension detects an miscellaneous I/O error. P4_E_INVAL if some parameter is recognized to be invalid. P4_E_NOENT if the specified property does not exist in the File Provider System Extension’s file system. P4_E_NOTIMPL if the requested operation is not supported. P4_E_NOKMEM if the resource partition of task has insufficient kernel memory to fully establish the mapping.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
162 The PSSW API
1.15.4.11 vm_se_fp_install_t
File Provider Installation Entry Point.
Synopsis:
typedef P4_e_t vm_se_fp_install_t(vm_se_fp_statics_t *s, const char *version_string)
Description: This entry point is mandatory to be implemented by File Provider System Extensions. This is the first entry point of a File Provider System Extension to be called.
Note: There is no file provider deinstall entry point.
Parameters: s The File Provider static data. version_string A string containing the (expected) system extension version information as specified by the VMIT. This information is not interpreted by the PSSW. Provider which are not subject to VMIT configu- ration are passing an empty string.
Returns: P4_E_OK on success. If the return code of a File Provider System Extension installation callback differs from P4_E_OK, the PSSW injects the module level error.
1.15.4.12 vm_se_fp_module_shutdown_t
File provider module shutdown entry point.
Synopsis:
typedef void vm_se_fp_module_shutdown_t(vm_se_fp_statics_t *s)
Description: This entry point is invoked if the system is performing a module shutdown in order for the File Provider to perform necessary cleanup operations on its hardware device(s). This entry point is optional to be implemented by File Providers. This entry point is called if the target module is about to shut down.
Parameters: s The File Provider static data.
Returns: nothing
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File Providers 163
1.15.4.13 vm_se_fp_partition_shutdown_t
File Provider partition shutdown entry point.
Synopsis:
typedef void vm_se_fp_partition_shutdown_t(vm_se_fp_statics_t *s, vm_part_id_t partition_id)
Description: This entry point is invoked if the system is performing a partition shutdown in order for the File Provider to perform necessary cleanup operations on its hardware device(s). This entry point is optional to be implemented by File Providers. This entry point is called if a resource partition is about to shut down.
Parameters: s The File Provider static data. partition_id The resource partition identifier of the partition which is shutting down as assigned by the VMIT configuration.
Returns: nothing
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
164 The PSSW API
1.15.5 Functions
1.15.5.1 vm_fp_provider_name
Query the provider name of this file provider.
Synopsis:
const char* vm_fp_provider_name(const vm_se_fp_statics_t *s)
Parameters: s IN: provider’s statics pointer
Returns: The name of the provider as configured in the VMIT.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
File Providers 165
1.15.5.2 vm_fp_get_domain_id
Query the HM domain ID of this file provider.
Synopsis:
P4_uint32_t vm_fp_get_domain_id(const vm_se_fp_statics_t *s)
Parameters: s IN: provider’s statics pointer
Returns: The HM domain as configured in the VMIT.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
166 The PSSW API
1.16 The Property File System
The property file system is intended to present configuration options of a running UniversalisOS system in a file system. The configuration options are grouped in a hierarchical tree structure. Each node (for which read, write or map access is granted) can be opened at runtime by means of vm_open() (see section 1.7.4.1) and read/mapped or even changed. The structure of the file sytem and the nodes’ default values are defined at compile time in XML files and composed to the system’s image by the configconv tool.
1.16.1 Defines
VM_PROP_READ_UINT32 (fd, node, buff)
Description:
Read a property of the type P4_PROP_T_UINT32
Parameters:
fd File descriptor
node Path relative to fd
buff Pointer to a P4_uint32_t data object
See also:
vm_prop_read() (see section 1.16.2.1)
VM_PROP_READ_UINT64 (fd, node, buff)
Description:
Read a property of the type P4_PROP_T_UINT64
Parameters:
fd File descriptor
node Path relative to fd
buff Pointer to a P4_uint64_t data object
See also:
vm_prop_read() (see section 1.16.2.1)
VM_PROP_READ_ADDR (fd, node, buff)
Description:
Read a property of the type P4_PROP_T_ADDR
Parameters:
fd File descriptor
node Path relative to fd
buff Pointer to a P4_phys_addr_t data object
See also:
vm_prop_read() (see section 1.16.2.1)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Property File System 167
VM_PROP_READ_SIZE (fd, node, buff)
Description:
Read a property of the type P4_PROP_T_SIZE
Parameters:
fd File descriptor
node Path relative to fd
buff Pointer to a P4_size_t data object
See also:
vm_prop_read() (see section 1.16.2.1)
VM_PROP_READ_BOOL (fd, node, buff)
Description:
Read a property of the type P4_PROP_T_BOOL
Parameters:
fd File descriptor
node Path relative to fd
buff Pointer to a P4_uint32_t data object
See also:
vm_prop_read() (see section 1.16.2.1)
VM_PROP_READ_STRING (fd, node, size, buff, readsize)
Description:
Read a property of the type P4_PROP_T_STRING
Parameters:
fd File descriptor
node Path relative to fd
size size of the character array
buff Pointer to a character array large enough to hold the addressed property’s content, with a
maximum of P4_PROP_MAX_DATA_LENGTH characters. This includes the termination NUL
character.
readsize The actual number of bytes read is returned in this pointer.
See also:
vm_prop_read() (see section 1.16.2.1)
VM_PROP_READ_BIN (fd, node, size, buff, readsize)
Description:
Read a property of the type P4_PROP_T_BIN
Parameters:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
168 The PSSW API
fd File descriptor
node Path relative to fd
size size of the character array
buff Pointer to a character array large enough to hold the addressed property’s content with a
maximum of P4_PROP_MAX_DATA_LENGTH bytes.
readsize The actual number of bytes read is returned in this pointer.
See also:
vm_prop_read() (see section 1.16.2.1)
VM_PROP_READ_CONFIG (fd, node, size, buff, readsize)
Description:
Read a property of the type P4_PROP_T_CONFIG
Parameters:
fd File descriptor
node Path relative to fd
size size of the character array
buff Pointer to a character array large enough to hold the addressed property’s content.
readsize The actual number of bytes read is returned in this pointer.
See also:
vm_prop_read() (see section 1.16.2.1)
VM_PROP_READ_MEMMAP (fd, node, buff)
Description:
Read a property of the type P4_PROP_T_MEMMAP
Parameters:
fd File descriptor
node Path relative to fd
buff Pointer to a data structure of the type P4_prop_memmap_t
See also:
vm_prop_read() (see section 1.16.2.1)
VM_PROP_READ_PORTMAP (fd, node, buff)
Description:
Read a property of the type P4_PROP_T_PORTMAP
Parameters:
fd File descriptor
node Path relative to fd
buff Pointer to a data structure of the type P4_prop_portmap_t
See also:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Property File System 169
vm_prop_read() (see section 1.16.2.1)
VM_PROP_READ_INTERRUPT (fd, node, buff)
Description:
Read a property of the type P4_PROP_T_INTERRUPT
Parameters:
fd File descriptor
node Path relative to fd
buff Pointer to a data structure of the type P4_uint32_t
See also:
vm_prop_read() (see section 1.16.2.1)
VM_PROP_READ_DEVICE (fd, node, buff)
Description:
Read a property of the type P4_PROP_T_DEVICE
Parameters:
fd File descriptor
node Path relative to fd
buff Pointer to a data structure of the type P4_uint32_t
See also:
vm_prop_read() (see section 1.16.2.1)
VM_PROP_READ_MAC (fd, node, buff)
Description:
Read a property of the type P4_PROP_T_MAC
Parameters:
fd File descriptor
node Path relative to fd
buff Pointer to a data structure of the type P4_uint8_t[6]
See also:
vm_prop_read() (see section 1.16.2.1)
VM_PROP_READ_IPV4 (fd, node, buff)
Description:
Read a property of the type P4_PROP_T_IPV4
Parameters:
fd File descriptor
node Path relative to fd
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
170 The PSSW API
buff Pointer to a data structure of the type P4_uint8_t[4]
See also:
vm_prop_read() (see section 1.16.2.1)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Property File System 171
1.16.2 Functions
1.16.2.1 vm_prop_read
Read a property node.
Synopsis:
P4_e_t vm_prop_read(vm_file_desc_t *fd, const char *node, P4_prop_type_t type, P4_size_t size, void *buff, P4_prop_type_t *read_type, P4_size_t *read_size)
Parameters: fd IN: File descriptor of a property node prior opened for read access. node IN: Relative node name. If node is the NULL pointer, the read target is the property node given by fd. type IN: Requested type of the property node. If P4_PROP_T_ANY is given, the property node may be of any type. size IN: Maximum number of data bytes to be read. For P4_uint32_t, P4_size_t, P4_phys_addr_t, P4_uint64_t, P4_prop_memmap_t, P4_prop_portmap_t data, it is required that the size is exactly equal to the data buffer for safety reasons, and in order to catch accidental type mismatches. Otherwise, P4_E_INVAL will be returned. buff IN: Reference to the read buffer. The user buffer shall be
• a P4_uint32_t variable for types P4_PROP_T_BOOL, P4_PROP_T_UINT32, P4_PROP_T_IN-
TERRUPT, or P4_PROP_T_DEVICE,
• a P4_size_t variable for types P4_PROP_T_SIZE or P4_PROP_T_DIR.
• a P4_uint64_t variable for type P4_PROP_T_UINT64,
• a P4_phys_addr_t variable for type P4_PROP_T_ADDR,
• a P4_prop_memmap_t data structure variable for type P4_PROP_T_MEMMAP,
• a P4_prop_portmap_t data structure variable for type P4_PROP_T_PORTMAP,
• a character buffer of size up to P4_PROP_MAX_DATA_LENGTH for the property
types P4_PROP_T_ANY, P4_PROP_T_STRING, P4_PROP_T_BIN, P4_PROP_T_CONFIG or
P4_PROP_T_COMMENT.
read_type OUT: If not the NULL pointer, the actual type of the property node is returned in this parameter. read_size OUT: If not the NULL pointer, the actual number of read bytes is returned in the parameter.
Description: This function reads the property node specified by the file descriptor fd and the relative node node. If node is the NULL pointer, the read target is the property node referenced by the file descriptor fd. If node specifies a valid sub-node of the property given by fd, this will be the read target. If the requested property node has the type attribute P4_PROP_T_LINK, the read target will be the link target. If the parameter type is P4_PROP_T_ANY, the read target may be of any type, otherwise it must have the specified type attribute.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
172 The PSSW API
A successful call to vm_prop_read() (see section 1.16.2.1) copies the data section of the property node into the user buffer given by buff. The parameter size specifies the maximum number of bytes which should be read, the actual number of bytes read is returned in *read_size. If the property data section is larger than size bytes, size bytes will be read but an error code indicates that the data section was truncated. If size is zero, no data will be read and no error code will indicate an truncation. This can be used to just determine the type of the node. If the property has the type P4_PROP_T_DIR, the number of child nodes of the directory is copied to *buff. In order to read the name of a child node, it is possible to call vm_read_at() (see section 1.7.4.5) on an opened file descriptor that refers to a P4_PROP_T_DIR node. The file position then specifies the index of the child node in the directory. The actual property type is returned in read_type, if the referenced property node has the type P4_PROP_T_LINK, the type of the link target is returned. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. The following is an overview showing how buffer size, read_size, actual property size, and the result interact, provided no other errors occurred (*read_size is only assigned if it is non-NULL).
if buffer size == property size: P4_E_OK, *read_size == buffer size
if buffer size < property size: if buffer size == 0 P4_E_OK, *read_size == buffer size else P4_E_TRUNC, *read_size == buffer size
if buffer size > property size: if type == P4_PROP_T_STRING || type == P4_PROP_T_COMMENT || read_size != NULL: P4_E_OK, *read_size == property_size else P4_E_SIZE
In case of P4_E_OK, P4_E_TRUNC, or P4_E_SIZE, the function ensures that the data (as far as available) and the type have been transferred, i.e., *buff and *read_type are valid in these cases. In other cases, the operation was not completed and the contents of buff, read_type are unspecified.
Returns: P4_E_OK upon success P4_E_INVAL if fd does not refer to an open property node, or if node is not a valid node name, or if type specifies an invalid property node type, or if type is not P4_PROP_T_LINK and the referenced property node does not have the type type. if size exceeds P4_PROP_MAX_DATA_LENGTH
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Property File System 173
P4_E_SIZE if read_size is NULL, and size is greater than the the size of the property data. This error is not generated for types P4_PROP_T_STRING or P4_PROP_T_COMMENT, because it the buffer will be NUL-terminated and thus there is an end marker. P4_E_TRUNC if the property data is larger than size bytes and size is not zero. Note: This error is also generated for P4_PROP_T_STRING and P4_PROP_T_COMMENT (in contrast to P4_E_SIZE). P4_E_NOTIMPL if the responsible file provider does not support the property read operation. P4_E_PERM if fd was not opened for read access. P4_E_NOENT if node does not reference a sub-node of fd. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
See also: vm_open() (see section 1.7.4.1), vm_read() (see section 1.7.4.3), vm_lseek() (see section 1.7.4.10), vm_read_at() (see section 1.7.4.5), vm_prop_write() (see section 1.16.2.2), vm_prop_mem_map() (see sec- tion 1.16.2.3), vm_prop_ioport_map() (see section 1.16.2.4), vm_prop_int_grant() (see section 1.16.2.5), and vm_prop_dev_grant() (see section 1.16.2.6)
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
174 The PSSW API
1.16.2.2 vm_prop_write
Write the data section of a property node.
Synopsis:
P4_e_t vm_prop_write(vm_file_desc_t *fd, const char *node, P4_prop_type_t type, P4_size_t size, const void *buff, P4_size_t *written_size)
Parameters: fd IN: File descriptor of a property node opened for write access. node IN: Relative node name. If node is the NULL pointer, the write target is the property given by fd. type IN: Requested type of the property node. size IN: Number of bytes to write buff IN: Reference to the user data buffer. written_size OUT: If not the NULL pointer, the actual number of bytes written is returned in this parameter.
Description: This function overwrites the data section of an existing property node. The property node is specified by the file descriptor fd and the relative node node. This function is not implemented by the built-in file providers. If node is the NULL pointer, the write target is the property node referenced by the file descriptor fd. If node specifies a valid sub-node of the property given by fd, this will be the write target. If the requested property node has the type attribute P4_PROP_T_LINK, the write target will be the link target. The parameter type must match the actual type of the node or, if the actual node type is P4_PROP_T_LINK, type must match the type of the link target. The function vm_prop_write() (see section 1.16.2.2) can only be applied on write targets of the following types:
• P4_PROP_T_BOOL
• P4_PROP_T_UINT32
• P4_PROP_T_UINT64
• P4_PROP_T_ADDR
• P4_PROP_T_SIZE
• P4_PROP_T_BIN
• P4_PROP_T_CONFIG
• P4_PROP_T_MEMMAP
• P4_PROP_T_PORTMAP
• P4_PROP_T_INTERRUPT
• P4_PROP_T_DEVICE
The parameter size specifies the number of bytes which shall be written. The value of size must match the size of the property’s data section. This is also true for the data type P4_PROP_T_BIN. The actual number of bytes written is returned in written_size.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Property File System 175
Please refer to vm_prop_read() (see section 1.16.2.1) for a list of property types and their corresponding sizes. The buffer given by buff holds the data to be written. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. If this function returns anything but P4_E_OK, the contents of written_size are unspecified.
Returns: P4_E_OK upon success P4_E_INVAL if fd does not refer to an open property node, or if node is not a valid node name, or if type specify a valid node type, or if type does not match the type the referenced property node, or if size does not match the size of the property node’s data section. P4_E_NOTIMPL if the responsible file provider does not support the property write operation. P4_E_PERM if fd was not opened for write access. P4_E_NOENT if node does not reference a sub-node of fd. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
See also: vm_open() (see section 1.7.4.1), vm_prop_read() (see section 1.16.2.1), and vm_prop_mem_map() (see sec- tion 1.16.2.3), vm_prop_ioport_map() (see section 1.16.2.4), vm_prop_int_grant() (see section 1.16.2.5), and vm_prop_dev_grant() (see section 1.16.2.6)
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
176 The PSSW API
1.16.2.3 vm_prop_mem_map
Map the memory mapped I/O resource identified by a property node into the caller’s task.
Synopsis:
P4_e_t vm_prop_mem_map(vm_file_desc_t *fd, const char *node, P4_size_t max_size, P4_address_t vbase, P4_address_t *mapped_addr, P4_size_t *mapped_size)
Parameters: fd IN: File descriptor of a property node opened for map access node IN: Relative node name of the property node to map. If node is the NULL pointer, the map target is the property node given by fd. max_size IN: max_size specifies the maximum size of area where the caller accepts the mapping of the requested resource. To make sure that the resource can be mapped, the caller should specify a size which is at least P4_PAGESIZE bytes larger than the actual size
• physical offset (poffset) of the resource to be mapped.
If max_size is ~0UL, the caller indicates that a mapping of any size will be accepted. In this case
an error may be raised if the resulting mapping exceeds the caller’s virtual address space.
The value of max_size must be ~0UL or a multiple of P4_PAGESIZE.
vbase IN: vbase specifies the virtual base address where the resource shall be mapped. The actual mapping starts at the sum of vbase and the property attribute poffset. mapped_addr OUT: If mapped_addr is not the NULL pointer, the virtual address of the mapped resource is returned in *mapped_addr. It is the sum of vbase and the poffset attribute of the property. mapped_size OUT: If mapped_size is not the NULL pointer, the actual size of the mapped resource is returned in *mapped_size.
Description: This function grants access to a memory mapped I/O segment represented by the property node specified by the file descriptor fd and the relative node node. If node is the NULL pointer, the map target is the property node referenced by the file descriptor fd. If node specifies a valid sub-node of the property given by fd, this will be the map target. If the requested property node has the type attribute P4_PROP_T_LINK, the map target will be the link target. The function vm_prop_mem_map() (see section 1.16.2.3) can only be applied on P4_PROP_T_MEMMAP target nodes to establish a virtual mapping to the physical or I/O memory segment represented by the property. The caller specifies the virtual segment where the mapping may be installed by the start address vbase and the size max_size. The actual start address of the resource is vbase + poffset and the end address is vbase + poffset + psize. PHYS |--------|--------|--------|... page boundaries pbase | |********| ------- physical resource
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Property File System 177
|<---------->|<------>| poffset psize
VIRT |--------|--------|--------|... page boundaries vbase | max_size |<------------------------>| -- area where mappings will be accepted |xxxxxxxxxxxxxxxxx| -- mapped area (entire pages) |********| ------- mapped resource |<------>| | | | +------------ *mapped_size = psize +----------------- *mapped_addr = vbase + poffset
The resulting mapping will have read and write permission and it will be mapped uncached. Any existing mapping in the caller’s address space will be replaced.
The parameter max_size specifies the maximum size of the area where mappings are accepted and vbase specifies the virtual address of the mapping in the caller’s address space. Both vbase and max_size must be a multiple of P4_PAGESIZE. The physical address and the actual size of the mapping are returned in mapped_addr and mapped_size. Observe that there is no way to undo a mapping that was established by this function. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. If this function returns anything but P4_E_OK, the contents of mapped_addr are unspecified. If this function returns anything but P4_E_OK, the contents of mapped_size are unspecified.
Returns: P4_E_OK upon success P4_E_INVAL if fd does not refer to an open property entry, or if node is not a valid node name, or if the addressed property node does not represent a mappable object, or if max_size is smaller than the range spanned by the property’s poffset + psize attributes, or if the physical memory range requested through the property is invalid (e.g. due to an addressing overflow). if vbase is not page-aligned. if max_size is not a multiple of the page size. if the memory area to establish the mapping at is not entirely located within the valid user address space (from P4_MEM_USR_BASE to P4_MEM_USR_END) P4_E_NOTIMPL if the responsible file provider does not support the property map operation for the targeted file. P4_E_PERM if fd was not opened for map access. P4_E_NOENT if node does not references a sub-node of fd. P4_E_NOKMEM if the calling resource partition has insufficient free kernel memory to fully establish the requested mapping.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
178 The PSSW API
P4_E_CONFIG If the requested physical memory region can’t be addressed (is outside the physical address space or is in the user address space) or If the memory area specified by the property is invalid. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
See also: vm_open() (see section 1.7.4.1), vm_prop_read() (see section 1.16.2.1), vm_prop_write() (see section 1.16.2.2), vm_prop_ioport_map() (see section 1.16.2.4), vm_prop_int_grant() (see section 1.16.2.5), and vm_prop_dev_grant() (see section 1.16.2.6)
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Property File System 179
1.16.2.4 vm_prop_ioport_map
Map the port mapped I/O resource identified by a property node into the caller’s task.
Synopsis:
P4_e_t vm_prop_ioport_map(vm_file_desc_t *fd, const char *node, P4_address_t *mapped_addr, P4_size_t *mapped_size)
Parameters: fd IN: File descriptor of a property node opened for map access node IN: Relative node name of the property node to map. If node is the NULL pointer, the map target is the property node given by fd. mapped_addr OUT: If mapped_addr is not the NULL pointer, the starting port of the mapped resource is returned in *mapped_addr. mapped_size OUT: If mapped_size is not the NULL pointer, the actual size of the port mapped resource is returned in *mapped_size.
Description: This function grants access to a port mapped I/O resource represented by the property node specified by the file descriptor fd and the relative node node. If node is the NULL pointer, the map target is the property node referenced by the file descriptor fd. If node specifies a valid sub-node of the property given by fd, this will be the map target. If the requested property node has the type attribute P4_PROP_T_LINK, the map target will be the link target. The function vm_prop_ioport_map() (see section 1.16.2.4) can only be applied on target nodes of type P4_PROP_T_PORTMAP to gain access to a range of I/O ports. The address and the actual size of the mapping are returned in mapped_addr and mapped_size. Observe that there is no way to undo a mapping that was established by this function. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. If this function returns anything but P4_E_OK, the contents of mapped_addr are unspecified. If this function returns anything but P4_E_OK, the contents of mapped_size are unspecified.
Returns: P4_E_OK upon success P4_E_INVAL if fd does not refer to an open property entry, or if node is not a valid node name, or if the addressed property node does not represent a mappable object, or if the physical memory range requested through the property is invalid (e.g. due to an addressing overflow). P4_E_NOTIMPL if the responsible file provider does not support the property map operation for the targeted file.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
180 The PSSW API
P4_E_CONFIG if the targeted property node is not properly configured (e.g. if the range of I/O port address described by it exceeds the valid range of I/O port addresses. P4_E_PERM if fd was not opened for map access. P4_E_NOENT if node does not references a sub-node of fd. P4_E_NOKMEM if the calling resource partition has insufficient kernel memory left to create the requested mapping. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
See also: vm_open() (see section 1.7.4.1), vm_prop_read() (see section 1.16.2.1), and vm_prop_write() (see sec- tion 1.16.2.2)vm_prop_mem_map() (see section 1.16.2.3), vm_prop_int_grant() (see section 1.16.2.5), and vm_prop_dev_grant() (see section 1.16.2.6)
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Property File System 181
1.16.2.5 vm_prop_int_grant
Grant access to the interrupt resource identified by a property node into the caller’s task.
Synopsis:
P4_e_t vm_prop_int_grant(vm_file_desc_t *fd, const char *node, P4_intid_t *irq)
Parameters: fd IN: File descriptor of a property node opened for map access node IN: Relative node name of the targeted property node. If node is the NULL pointer, the map target is the property node given by fd. irq OUT: If irq is not the NULL pointer, the actual ID of the granted interrupt is returned in *irq.
Description: This function grants access to an interrupt resource represented by the property node specified by the file descrip- tor fd and the relative node node. If node is the NULL pointer, the map target is the property node referenced by the file descriptor fd. If node specifies a valid sub-node of the property given by fd, this will be the map target. If the requested property node has the type attribute P4_PROP_T_LINK, the map target will be the link target. The function vm_prop_int_grant() (see section 1.16.2.5) can only be applied on target nodes of type P4_PROP_T_INTERRUPT. The ID of the interrupt is returned in irq. Observe that there is no way to undo the granted access that was established by this function. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. If this function returns anything but P4_E_OK, the contents of irq are unspecified.
Returns: P4_E_OK upon success P4_E_INVAL if fd does not refer to an open property entry, or if node is not a valid node name, or if the addressed property node does not represent a mappable object, or if the interrupt ID requested through the property is invalid. P4_E_NOTIMPL if the responsible file provider does not support the property map operation for the targeted file (e.g. the targeted property file does not have the type P4_PROP_T_INTERRUPT). P4_E_PERM if fd was not opened for map access. P4_E_NOENT if node does not references a sub-node of fd. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
See also:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
182 The PSSW API
vm_open() (see section 1.7.4.1), vm_prop_read() (see section 1.16.2.1), and vm_prop_write() (see sec- tion 1.16.2.2)vm_prop_mem_map() (see section 1.16.2.3), vm_prop_ioport_map() (see section 1.16.2.4) and vm_prop_dev_grant() (see section 1.16.2.6)
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Property File System 183
1.16.2.6 vm_prop_dev_grant
Grant access to the kernel level device resource identified by a property node into the caller’s task.
Synopsis:
P4_e_t vm_prop_dev_grant(vm_file_desc_t *fd, const char *node, P4_devid_t *dev)
Parameters: fd IN: File descriptor of a property node opened for map access node IN: Relative node name of the targeted property node. If node is the NULL pointer, the map target is the property node given by fd. dev OUT: If dev is not the NULL pointer, the actual ID of the granted kernel level device is returned in *dev.
Description: This function grants access to a kernel level device resource represented by the property node specified by the file descriptor fd and the relative node node. If node is the NULL pointer, the map target is the property node referenced by the file descriptor fd. If node specifies a valid sub-node of the property given by fd, this will be the map target. If the requested property node has the type attribute P4_PROP_T_LINK, the map target will be the link target. The function vm_prop_dev_grant() (see section 1.16.2.6) can only be applied on target nodes of type P4_PROP_T_DEVICE. The ID of the kernel level device is returned in dev. Observe that there is no way to undo the granted access that was established by this function. This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked. This function has undefined behavior unless fd is an open file descriptor. If this function returns anything but P4_E_OK, the contents of dev are unspecified.
Returns: P4_E_OK upon success P4_E_INVAL if fd does not refer to an open property entry, or if node is not a valid node name, or if the addressed property node does not represent a mappable object, or if the device ID requested through the property is invalid. P4_E_NOTIMPL if the responsible file provider does not support the property map operation for the targeted file. P4_E_CONFIG if the device ID in the addressed property entry is not supported by the PSP. P4_E_PERM if fd was not opened for map access. P4_E_NOENT if node does not references a sub-node of fd. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
184 The PSSW API
See also: vm_open() (see section 1.7.4.1), vm_prop_read() (see section 1.16.2.1), and vm_prop_write() (see sec- tion 1.16.2.2)vm_prop_mem_map() (see section 1.16.2.3), vm_prop_ioport_map() (see section 1.16.2.4) and vm_prop_int_grant() (see section 1.16.2.5)
Pre-Conditions: vm_init() (see section 1.4.1.1) must have been called at least once by the caller’s task. This function is deprecated since UniversalisOS 5.0 and may be removed in the future.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Target Control 185
1.17 Target Control
This section describes data types and functions to shutdown and restart the system.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
186 The PSSW API
1.17.1 Enumerations
Enumeration type vm_reboot_mode_t
Target reboot/halt/power off modes. Used as an argument for the vm_target_reset() (see section 1.17.2.1) func- tion.
Name Description VM_TARGET_REBOOT Reboot the target
VM_TARGET_HALT Halt the target
VM_TARGET_POWER_OFF Power off the target
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Target Control 187
1.17.2 Functions
1.17.2.1 vm_target_reset
Reset or halt the target.
Synopsis:
P4_e_t vm_target_reset(vm_reboot_mode_t mode)
Parameters: mode IN: Mode which specifies whether to reboot or halt the target
See also:
vm_reboot_mode_t (see section 1.17.1)
Description: This function has undefined behavior before vm_init() (see section 1.4.1.1) is invoked.
Returns: P4_E_OK upon success P4_E_NOABILITY if the calling partition does not have the ability VM_AB_PSP_RESET. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
188 The PSSW API
1.18 External File Providers
External File Providers are user level processes providing a file system to other processes.
1.18.1 Header File
Include this header file additionally for external file provider functionality: #include <vm_fp.h>
1.18.2 Structure Definitions
1.18.2.1 struct vm_fp_listen_t
External file provider descriptor passed to vm_fp_listen() (see section 1.18.6.4). Before passing an instance of this data type to vm_fp_listen() (see section 1.18.6.4), a file provider server thread initializes the members with references to its entry point implementations. The member handle is to be set to the value returned by the call to vm_fp_register() (see section 1.18.6.5).
Synopsis: struct vm_fp_listen_t { P4_uid_t listen_uid; P4_uint32_t handle; P4_address_t map_addr; P4_size_t map_size; vm_fp_open_t * open; vm_fp_close_t * close; vm_fp_read_t * read; vm_fp_write_t * write; vm_fp_map_t * map; vm_fp_fstat_t * fstat; vm_fp_ioctl_t * ioctl; };
Structure Element Description: listen_uid UID to listen to. Not to be altered by the file provider itself. handle Handle to identify the file provider as returned by vm_fp_register() (see section 1.18.6.5). map_addr Virtual base address to receive user buffers via the IPC mapping mechanism. Has to be initialized for each thread which provide read and/or write entry points. The value must be a multiple of P4_PAGE- SIZE. If the vm_fp_listen_t structure is used embedded into the vm_vp_listen_t structure by a volume provider this field should also be set for worker threads handling requests different from mount() and umount(), as mapping is also used for transfering paths in e.g. vm_open() (see section 1.7.4.1). map_size Size of mapping area provided for incoming IPC mappings open Open entry point. Mandatory to be implemented. close Close entry point. Mandatory to be implemented. read Read entry point. Optional to be implemented. write Write entry point. Optional to be implemented. map Map entry point. Optional to be implemented.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
External File Providers 189
fstat Status retrieval entry point. Optional to be implemented.
ioctl I/O control entry point. Optional to be implemented.
1.18.2.2 struct vm_fp_cmsg_t
Helper type to add alignment in a way clang understands it and so no-one accidentally accesses the array
Synopsis: struct vm_fp_cmsg_t { P4_uint64_t data[(VM_MAX_C_MSG_SIZE+7)/8]; };
Structure Element Description: data
1.18.2.3 struct vm_fp_rmsg_t
Helper type to add alignment in a way clang understands it and so no-one accidentally accesses the array
Synopsis: struct vm_fp_rmsg_t { P4_uint64_t data[(VM_MAX_R_MSG_SIZE+7)/8]; };
Structure Element Description: data
1.18.2.4 struct vm_fp_msg_t
External file provider IPC message structure. The structure of an external file provider message. It represents messages sent and received by the external file provider to the calling client thread or partition daemon thread. Except for the member handler, its contents should not be altered by the file provider itself. The services vm_fp_msg_init() (see section 1.18.6.1), vm_fp_msg_wait() (see section 1.18.6.2) and vm_fp_msg_dispatch() (see section 1.18.6.3) are provided to deal with this data structure.
Synopsis: struct vm_fp_msg_t { P4_message_t ipc_cmsg; P4_message_t ipc_rmsg; P4_uint32_t ipc_state; P4_cc_t ipc_cc; vm_fp_cmsg_t cmsg; vm_fp_rmsg_t rmsg; P4_size_t cmap; P4_uid_t client; P4_size_t cmsg_size;
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
190 The PSSW API
P4_size_t rmsg_size;
P4_size_t cmap_size;
vm_fp_listen_t handler;
};
Structure Element Description: ipc_cmsg P4 IPC message descriptor of the received message. ipc_rmsg P4 IPC message descriptor of the response message. ipc_state Additional P4 IPC status ipc_cc Full P4 IPC completion code cmsg Calling message buffer rmsg Response message buffer cmap Offset of the received mapping client UID of the calling thread cmsg_size Size of the calling message in bytes rmsg_size Size of the response message in bytes cmap_size Size of the received mapping in bytes handler KDEV handle as returned by vm_fp_register() (see section 1.18.6.5)
1.18.3 Defines
VM_SEEK
Description:
Bitmask to be applied to the origin parameter of the read and write entry points of File Providers to
identify a seek request issued to a File Provider.
VM_TRANSFER
Description:
Bitmask to be applied to the origin parameter of the read and write entry points of File Providers to
identify a data transfer request issued to a File Provider.
VM_SEEK_MASK
Description:
Bitmask to be applied to the origin parameter of the read and write entry points of File Providers to ex-
tract the actual origin of the seek request (one of P4_SEEK_SET, P4_SEEK_CUR or P4_SEEK_END).
VM_FP_HAS_READ_PERM (oflags)
In a file provider system extension or an external file provider, check if the file open mode oflags covers
read permission.
Parameters:
oflags The file open mode to test
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
External File Providers 191
Returns:
0 If oflags does not include read permission
VM_FP_HAS_WRITE_PERM (oflags) In a file provider system extension or an external file provider, check if the file open mode oflags covers write permission.
Parameters:
oflags The file open mode to test
Returns:
0 If oflags does not include write permission
VM_FP_HAS_EXEC_PERM (oflags) In a file provider system extension or an external file provider, check if the file open mode oflags covers execution permission.
Parameters:
oflags The file open mode to test
Returns:
0 If oflags does not include execution permission
VM_FP_HAS_MAP_PERM (oflags) In a file provider system extension or an external file provider, check if the file open mode oflags covers map permission.
Parameters:
oflags The file open mode to test
Returns:
0 If oflags does not include map permission
VM_FP_HAS_FSPROV_PERM (oflags) In a file provider system extension or an external file provider, check if the file open mode oflags includes the special file access flag VM_O_FSPROV.
Parameters:
oflags The file open mode to test
Returns:
0 If oflags does not include the special flag VM_O_FSPROV
VM_MAX_C_MSG_SIZE
Description:
Maximum message buffer size for a file provider command message.
This is the maximum of the sizes of all IPC buffers that may be received by vm_fp_msg_wait() (see
section 1.18.6.2): sizeof(sswipc_extfp_s_all_t)
VM_MAX_R_MSG_SIZE
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
192 The PSSW API
Description:
Maximum message buffer size for a file provider return message.
This is the maximum of the sizes of all IPC buffer that may be send by vm_fp_msg_wait() (see section
1.18.6.2): sizeof(sswipc_extfp_r_all_t)
1.18.4 Data Type Definitions
vm_file_handle_t Handle of an opened file associated to a file descriptor.
1.18.5 Function Type Definitions
1.18.5.1 vm_fp_open_t
Prototype of the open entry point to be implemented by external file providers.
Synopsis:
typedef P4_e_t vm_fp_open_t(P4_uid_t client, const char *filename, P4_uint32_t oflags, vm_file_desc_ext_t *fd)
Description: An external file provider implements the open entry point in order to handle vm_open() (see section 1.7.4.1) requests to its file system. It may reject invalid requests with one of the described error codes. If an open request is detected to be valid, it is the responsibility of the implementation of this entry point to populate the given file descriptor fd. The member "handle" of the file descriptor has to be set to a unique value representing the instance of the open file. It is passed to the other file provider entry points if the client requests actual file operations using the file descriptor returned by vm_open() (see section 1.7.4.1).
Note: This entry point is mandatory to be implemented by external file providers.
Warning: It is prohibited to use the PSSW file system API targeting other External File Providers to implement the open entry point of an External File Provider. File system service calls would never return execution to the caller, since the IPC mask of the calling thread restricts the set of communication partners to the PSSW.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. filename Name of the file to open without the file provider prefix. oflags Requested file open mode. The requested mode has already been validated to be permitted to the caller. fd External file descriptor data structure representing the instance of the open file. The entry point im- plementation will populate this data structure. The members "client", "part_id" and "vflags" are already preset with valid values when the entry point is called.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
External File Providers 193
Returns: P4_E_OK On success. P4_E_BUSY If the hardware device is already used at arrival of the service request and can not be shared. P4_E_CONFIG If the file provider is not configured properly. P4_E_INVAL If any parameter is detected to be invalid. P4_E_NOENT If the file which is requested to be opened does not exist in the provided file system. P4_E_PERM If the client thread is not permitted to open the file in the requested mode. for the specified file for the caller. P4_E_IO If a hardware failure has been detected. P4_E_TIMEOUT If the request can temporarily not be handled and should be reissued. P4_E_NOTIMPL If the requested open mode is not supported for the targeted file. P4_E_OOFILE If no free descriptor objects can be allocated from the file provider descriptor pool.
1.18.5.2 vm_fp_close_t
Prototype of the close entry point to be implemented by external file providers.
Synopsis:
typedef void vm_fp_close_t(P4_uid_t client, vm_file_desc_ext_t *fd)
Description: An external file provider implements the close entry point in order to handle vm_close() (see section 1.7.4.11) requests to its file system. It may reject invalid requests with one of the described error codes. If a close request is detected to be valid, it is the responsibility of the implementation of this entry point to free resources possibly used by the open file instance which is represented by the given file descriptor fd. Pending requests on the open file are either to be aborted or to be completed before the actual close operation is performed.
Note: This entry point is mandatory to be implemented by external file providers.
Warning: It is prohibited to use the PSSW file system API targeting other External File Providers to implement the close entry point of an External File Provider. File system service calls would never return execution to the caller, since the IPC mask of the calling thread restricts the set of communication partners to the PSSW.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. fd External file descriptor data structure representing the instance of the open file as initialized by the open entry point of the file provider.
Returns: nothing.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
194 The PSSW API
1.18.5.3 vm_fp_read_t
Prototype of the read entry point to be implemented by external file providers.
Synopsis:
typedef P4_e_t vm_fp_read_t(P4_uid_t client, vm_file_handle_t handle, P4_off_t offset, P4_origin_t origin, P4_address_t buffer, P4_size_t buff_size, P4_size_t *read_size, P4_off_t *new_pos)
Description: An external file provider implements the read entry point in order to handle vm_read() (see section 1.7.4.3), vm_read_at() (see section 1.7.4.5) and vm_lseek() (see section 1.7.4.10) requests to its file system. It may reject invalid requests with one of the described error codes. If a valid read request is detected, it is the responsibility of the implementation of this entry point to copy up to buff_size bytes of data from the open file identified by handle to the given read buffer buffer and to save the actual number of bytes read in read_size. Depending on origin, the file provider has to alter the logical file position, perform a read operation or both. This is indicated by the flags VM_SEEK and/or VM_TRANSFER set within origin. If both operations are requested at once, the logical file position must not be altered permanently. If a seek operation is requested, the bitmasks VM_SEEK_MASK may be used to extract the actual seek origin from the origin parameter. A pure seek operation does not transfer any data.
Note: This entry point is optional to be implemented by external file providers.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. handle Handle identifying the open file as associated to the file descriptor during the file open sequence. offset Offset to seek to or to read from. To be interpreted in relation to origin. origin Origin of the seek request. This is also used to differ between the three types of requests this entry point is responsible for. buffer Read data buffer of the given size. buff_size The requested number of bytes to read. read_size Pointer to an object of the data type P4_size_t to save the actual number of bytes read in. new_pos Pointer to an object of the data type P4_off_t to save the updated file position in.
Returns: P4_E_OK On success. P4_E_PERM If the file has not been opened with read permission. P4_E_NOTIMPL If the requested operation is not supported on the specified file. P4_E_INVAL If a parameter is detected to be invalid.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
External File Providers 195
P4_E_IO If a hardware failure has been detected.
P4_E_TRUNC If the file provider supports partial read operations and the given buffer size is smaller than the
number of bytes read from the file.
P4_E_SIZE If the file provider does not support partial read operations and the given buffer size is smaller
than the number of bytes to be read from the file.
P4_E_TIMEOUT If the request can temporarily not be handled and should be reissued.
1.18.5.4 vm_fp_write_t
Prototype of the write entry point to be implemented by external file providers.
Synopsis:
typedef P4_e_t vm_fp_write_t(P4_uid_t client, vm_file_handle_t handle, P4_off_t offset, P4_origin_t origin, P4_address_t buffer, P4_size_t buff_size, P4_size_t *written_size)
Description: An external file provider implements the write entry point in order to handle vm_write() (see section 1.7.4.4) and vm_write_at() (see section 1.7.4.6) requests to its file system. It may reject invalid requests with one of the described error codes. If a write request is detected to be valid, it is the responsibility of the implementation of this entry point to copy up to buff_size bytes of data from the given write buffer buffer to the open file identified by handle and to save the actual number of bytes written in written_size. Depending on origin, the file provider has to perform a sequential write operation or a combined seek and write operation. This is indicated by the flags VM_SEEK and VM_TRANSFER of the parameter origin. If the combined seek and write operation is requested, the logical file position must not be altered permanently. The parameter offset is only of interest for the combined request. In this case, it contains the absolute offset within the file to write to.
Note: This entry point is optional to be implemented by external file providers.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. handle Handle identifying the open file as associated to the file descriptor during the file open sequence. offset Offset to seek to or to read from. origin Origin of the vm_write_at() (see section 1.7.4.6) request. This is used to differ between the two types of requests this entry point is responsible for. buffer Write data buffer of the given size. buff_size The requested number of bytes to write. written_size Pointer to an object of the data type P4_size_t to save the actual number of bytes written in.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
196 The PSSW API
Returns: P4_E_OK On success. P4_E_PERM If the file has not been opened with write permission. P4_E_NOTIMPL If the requested operation is not supported on the specified file. P4_E_INVAL If a parameter is detected to be invalid. P4_E_IO If a hardware failure has been detected. P4_E_TRUNC If the file provider supports partial write operations and the given buffer size is smaller than the number of bytes written to the file. P4_E_SIZE If the file provider does not support partial write operations and the given buffer size if smaller than the number of bytes to be written to the file. P4_E_TIMEOUT If the request can temporarily not be handled and should be reissued.
1.18.5.5 vm_fp_map_t
Prototype of the map entry point to be implemented by external file providers.
Synopsis:
typedef P4_e_t vm_fp_map_t(P4_uid_t client, vm_file_handle_t handle, P4_off_t offset, P4_size_t size, P4_uint32_t prot, P4_uint32_t flags, P4_address_t *map_base, P4_size_t *map_size, vm_memory_access_mode_t *map_access, unsigned *map_cache)
Description: An external file provider implements the map entry point in order to handle vm_map() (see section 1.7.4.12) requests to its file system. It may reject invalid requests with one of the described error codes. The given access mode prot is to be validated against the file open mode of fd. For valid requests, the entry point stores the base address of the map window in map_base, its size in map_size and the access and cache modes in map_access and map_cache respectively. The external file provider framework will establish the mapping in the client task’s address space. Map addresses and sizes have to be page aligned.
Note: This entry point is optional to be implemented by external file providers.
Warning: If the map entry point implementation returns invalid values in map_access or map_cache or inappropriate 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.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
External File Providers 197
handle Handle identifying the open file as associated to the file descriptor during the file open sequence. offset File offset to map from. size Requested size of the mapping. prot Requested memory access mode to establish the mapping with. flags A combination of flags specified by the caller to be interpreted by the file provider. map_base Virtual address in the file provider’s task to map from. To be set by the file provider entry point. map_size Size of the mapping transferred to the client. To be set by the file provider entry point. map_access Access mode to qualify the returned mapping for. A driver must assign to *map_access to set either read-only, write-only, or read-write access. map_cache Cache mode to qualify the returned mapping for. This is either an explicit value of type vm_mem- ory_cache_mode_t, or VM_MEM_CACHE_INHERIT to use the cache attributes of the original mapping at map_base. The default, if a driver does not assigne a value to *map_cache, is VM_MEM_CACHE_IN- HERIT. Note that a file provider might not even have the VM_AB_CACHE_CHANGE ability. In this case, setting *map_cache will result in the resulti IPC causing an error so that the client will not receive an an- swer to the request. External file providers should, therefore, either be aware of their abilities or use the default of not assigning to *map_cache.
Returns: P4_E_OK On success. P4_E_PERM If the file has not been opened with map permission or if the file has not been opened with sufficient permission to qualify the mapping as requested. P4_E_NOTIMPL If the requested operation is not supported on the specified file. P4_E_INVAL If a parameter is detected to be invalid. P4_E_IO If a hardware failure has been detected. P4_E_BUSY If the request can not be fulfilled because of insufficient resources used by other clients. P4_E_TIMEOUT If the request can temporarily not be handled and should be reissued.
1.18.5.6 vm_fp_fstat_t
Prototype of the file status retrieval entry point to be implemented by external file providers.
Synopsis:
typedef P4_e_t vm_fp_fstat_t(P4_uid_t client, vm_file_handle_t handle, vm_file_stat_t *statbuf)
Description: An external file provider implements the status retrieval entry point in order to handle vm_stat() (see section 1.7.4.9) requests to its file system. It may reject invalid requests with one of the described error codes. For valid requests, the implementation of this entry point populates the statbuf data structure with the status information of the file identified by handle.
Note: This entry point is optional to be implemented by external file providers.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
198 The PSSW API
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. handle Handle identifying the open file as associated to the file descriptor during the file open sequence. statbuf Status structure to be filled with the status information of the specified file.
Returns: P4_E_OK On success. P4_E_PERM If the caller is not permitted to retrieve the file status. P4_E_NOTIMPL If the requested operation is not supported on the specified file. P4_E_INVAL If a parameter is detected to be invalid. P4_E_IO If a hardware failure has been detected. P4_E_TIMEOUT If the request can temporarily not be handled and should be reissued.
1.18.5.7 vm_fp_ioctl_t
Prototype of the I/O control entry point to be implemented by external file providers.
Synopsis:
typedef P4_e_t vm_fp_ioctl_t(P4_uid_t client, vm_file_handle_t handle, P4_uint32_t iocmd, P4_address_t data_in, P4_address_t data_out)
Description: An external file provider implements the I/O control entry point in order to handle vm_ioctl() (see section 1.7.4.13) requests to its file system. It may reject invalid requests with one of the described error codes. The actual I/O control commands iocmd and the data buffer structures are defined and documented by the file provider. Input and output data buffer addresses are given as data_in and data_out. The maximum size of each data buffer is defined by the constant VM_IOC_MAX_PARAM_SIZE.
Note: This entry point is optional to be implemented by external file providers.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. handle Handle identifying the open file as associated to the file descriptor during the file open sequence. iocmd The I/O control command identifier specified by the client. data_in The I/O control command buffer sent by the client. data_out The I/O control response buffer to be filled by the file provider.
Returns: P4_E_OK On success. P4_E_PERM If the file has not been opened with appropriate permission. P4_E_NOTIMPL If the requested operation is not supported on the specified file.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
External File Providers 199
P4_E_INVAL If a parameter is detected to be invalid. P4_E_IO If a hardware failure has been detected. P4_E_TIMEOUT If the request can temporarily not be handled and should be reissued.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
200 The PSSW API
1.18.6 Functions
1.18.6.1 vm_fp_msg_init
Initialize an external file provider’s message structure to prepare it for subsequent calls to vm_fp_msg_wait() and vm_fp_msg_dispatch().
Synopsis:
void vm_fp_msg_init(vm_fp_msg_t *msg)
Parameters: msg A reference to the message descriptor to initialize.
Description: This function initializes msg. Please note, that the member "handler" has to be filled out before this function is called. A message has not to be reinitialized before it is passed to vm_fp_msg_wait() (see section 1.18.6.2). If the member "handler" of the given message descriptor specifies a value different from NULL for the open, close or stat entry point, other entry point references have to be set to NULL. Otherwise, a health monitoring error will be raised by the external file provider framework. If error processing does not halt file provider execution, the resource partition will be shut down.
Note: If the function fails, execution will not be returned to the calling thread. In product version without external file provider support, this service is not available.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
External File Providers 201
1.18.6.2 vm_fp_msg_wait
Listen for service requests.
Synopsis:
P4_e_t vm_fp_msg_wait(vm_fp_msg_t *msg)
Parameters: msg The message representing the response to the previously handled request and in which a new request is to be received.
Description: This service sends the response message represented by msg to the thread it has been received from and afterwards waits for a service request msg to arrive at the calling thread from either a client thread or the partition daemon of the file provider’s resource partition. Once a request has been received, the function returns in order for the caller to pass this message to vm_fp_msg_dispatch() (see section 1.18.6.3). In case an external file provider passes invalid provider handles or violates the communication protocol between PSSW and external file providers by sending invalid replies a health monitor event is injected by the PSSW for the providers resource partition.
Note: In product versions without external file provider support, this service is not available.
Returns: P4_E_OK On success. P4_E_INVAL If msg was corrupted or not correctly initialized by vm_fp_msg_init() (see section 1.18.6.1). P4_E_SIZE The sent or received message was corrupted and too large for the receive buffer of the counter- part, or the mapping area was too small for the request. P4_E_STATE If the communication partner is currently not available. This may be caused by a partition reboot. P4_E_NOKMEM There was not enough kernel memory to establish the mapping for the received buffer. Please note that additional error codes may be returned as the service returns the error code part of the IPC completion code. For detailed analysis of the error cause the caller could evaluate the ipc_cc field of msg.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
202 The PSSW API
1.18.6.3 vm_fp_msg_dispatch
Dispatch a service request to the appropriate entry point.
Synopsis:
P4_e_t vm_fp_msg_dispatch(vm_fp_msg_t *msg)
Parameters: msg The message to dispatch to the appropriate file provider entry point.
Description: This function forwards a service request msg received from a client thread or the partition daemon thread to one of the registered callback functions respecting the type of the requested service. The message may be received by the function vm_fp_msg_wait() (see section 1.18.6.2). If the to be dispatched message represents a vm_open() (see section 1.7.4.1), vm_close() (see section 1.7.4.11) or vm_stat() (see section 1.7.4.9) request and the member "handler" of the given message msg has the corresponding entry point set to NULL, the function will raise a Health Monitoring error. If error processing does not halt file provider execution, the resource partition will be shut down.
Note: In product version without external file provider support, this service is not available.
Returns: P4_E_OK On success. P4_E_NOTIMPL If an unknown service was requested or the requested service could not be determined because of a corrupted message.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
External File Providers 203
1.18.6.4 vm_fp_listen
Listen for service requests and handle them.
Synopsis:
P4_e_t vm_fp_listen(vm_fp_listen_t *fp)
Parameters: fp A reference to the external file provider’s descriptor.
Description: Calling this function enters an endless loop listening for service requests issued to the provider’s file system via IPC. Once a service request is received, the corresponding entry point is entered. References to the file provider’s entry points are contained in fp. This function is in fact a combination of the functions vm_fp_msg_init() (see section 1.18.6.1), vm_fp_msg_wait() (see section 1.18.6.2) and vm_fp_msg_dispatch() (see section 1.18.6.3) executed in an endless loop as long as no error occurs. Please refer to the descriptions of these function for further details.
Note: This function does only return in case of an error.
Returns: The error code of vm_fp_msg_wait() (see section 1.18.6.2) or vm_fp_msg_dispatch() (see section 1.18.6.3) (first error code is returned). Please refer to the documentation of these functions. For detailed error analysis both functions may need to be called separately.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
204 The PSSW API
1.18.6.5 vm_fp_register
Register a user level file provider.
Synopsis:
P4_e_t vm_fp_register(const char *name, P4_uint32_t *handle)
Parameters: name Name of the file system to register. handle Reference to the handle of the external file provider. This may be a reference to the member "handle" of the external file provider’s descriptor.
Description: This service registers a user level file provider at the PSSW. After a successful call to this function, service requests to the file system name will be routed to the caller of this function. On success handle is assigned a value uniquely identifying the file provider. The external file provider will copy this handle into its external file provider descriptor.
Note: In product version without external file provider support, this service is not functional.
Returns: P4_E_OK On success. P4_E_NOENT If external file providers are not supported by the system. This can happen if the kextfp KDEV driver is not fused with the kernel. P4_E_PERM If the given name is not configured as an external file provider prefix in the VMIT configuration, i.e. the calling resource partition has no permission to register as the specified file provider. If the integrator specified VM_O_VOLPROV instead of VM_O_FSPROV for the provider prefix in the VMIT configuration. P4_E_INVAL If an input parameter is invalid, e.g., the name is too long. P4_E_BUSY if the prefix was already registered by another file provider. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Volume Providers 205
1.19 Volume Providers
Volume Providers are user level processes providing an extended file system to other processes.
1.19.1 Header File
Include this header file additionally for volume provider functionality:
#include <vm_vp.h>
1.19.2 Structure Definitions
1.19.2.1 struct vm_vp_handlers_t
Synopsis:
struct vm_vp_handlers_t { vm_vp_unlink_t * unlink; vm_vp_rename_t * rename; vm_vp_fsync_t * fsync; vm_vp_ftruncate_t * ftruncate; vm_vp_close_t * close; vm_vp_dir_create_t * dir_create; vm_vp_dir_open_t * dir_open; vm_vp_dir_read_at_t * dir_read_at; vm_vp_dir_close_t * dir_close; vm_vp_dir_sync_t * dir_sync; vm_vp_mount_t * mount; vm_vp_umount_t * umount; vm_vp_statvfs_t * statvfs; };
Structure Element Description: unlink Unlink method, will be called when vm_unlink() (see section 1.8.3.1) was called from client application. rename Rename method, will be called when vm_rename() (see section 1.8.3.2) was called from client application. fsync Synchronize file data method, will be called when vm_fsync() (see section 1.7.4.15) was called from client application. ftruncate Truncate method, will be called when vm_ftruncate() (see section 1.8.3.4) was called from client application. close File close method, will be called when vm_close() (see section 1.7.4.11) was called from client applica- tion. dir_create Create directory method, will be called when vm_dir_create() (see section 1.8.3.5) was called from client application. dir_open Open directory method, will be called when vm_dir_open() (see section 1.8.3.6) was called from client application. dir_read_at Read directory method, will be called when vm_dir_read_at() (see section 1.8.3.7) was called from client application.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
206 The PSSW API
dir_close Close directory method, will be called when vm_dir_close() (see section 1.8.3.8) was called from client application. dir_sync Sync directory method, will be called when vm_dir_sync() (see section 1.8.3.9) was called from client application. mount Volume mount method, will be called when vm_mount() (see section 1.8.3.11) was called from client application. umount Volume unmount method, will be called when vm_umount() (see section 1.8.3.12) was called from client application. statvfs File system status method, will be called when vm_statvfs() (see section 1.8.3.3) was called from client application.
1.19.2.2 struct vm_vp_listen_t
Volume provider descriptor passed to vm_vp_listen() (see section 1.19.5.2). Before passing an instance of this data type to vm_vp_listen() (see section 1.19.5.2), a volume provider server thread initializes the members with references to its entry point implementations. The member fpl.handle is to be set to the value returned by the call to vm_vp_register() (see section 1.19.5.1). Furthermore the provider has to initialize pointers to two buffers where paths from the user are stored by the libvm (e.g. for vm_rename() (see section 1.8.3.2) both buffers are needed).
Synopsis: struct vm_vp_listen_t { vm_fp_listen_t fpl; vm_vp_handlers_t vph; char * path_buff1; char * path_buff2; };
Structure Element Description: fpl File provider listen structure and handlers shared with ExtFPs vph Volume provider specific handlers path_buff1 Pointer to first path buffer (of size P4_MAX_EXT_PATHNAME_LEN) path_buff2 Pointer to second path buffer (of size P4_MAX_EXT_PATHNAME_LEN)
1.19.3 Data Type Definitions
vm_vp_open_t File System library open method. The vm_open() (see section 1.7.4.1) call is used to convert a pathname into a file descriptor. Upon success the function returns 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:
client IN UniversalisOS Unique Identifier (UID) of the requesting thread.
name IN: File or pathname to open.
oflags IN: The parameter oflags is a logical combination of one or more of the following constants:
• VM_O_RD for opening file name for reading,
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Volume Providers 207
• 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 OUT: Upon success, the requested file descriptor is saved in fd. In case of error, the content
of fd is unspecified.
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_OOFILE if no free file descriptor can be allocated from the file descriptor pool.
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_EXCL 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.
vm_vp_read_t File System library read and read at position method. The vm_read_at() (see section 1.7.4.5) attempts to read up to buf_size bytes from file offset offset. In case of an read at request The function does not alter the logical file position.
Parameters:
client IN: UniversalisOS Unique Identifier (UID) of the requesting thread.
handle IN: Handle identifying the open file as associated to the file descriptor during the file open
sequence.
offset Offset to seek to or to read from. To be interpreted in relation to origin.
origin Origin of the seek request. This is also used to differ between the three types of requests
this entry point is responsible for.
buffer Read data buffer of the given size.
buff_size The requested number of bytes to read.
read_size Pointer to an object of the data type P4_size_t to save the actual number of bytes read
in.
new_pos Pointer to an object of the data type P4_off_t to save the updated file position 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_NOTIMPL if the responsible provider does not support this operation.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
208 The PSSW API
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.
vm_vp_write_t File System library write and write at position method. The vm_write_at() (see section 1.7.4.6) attempts to write up to buf_size bytes from file offset offset. In case of an write at request the function does not alter the logical file position.
Parameters:
client UniversalisOS Unique Identifier (UID) of the requesting thread.
handle IN: Handle identifying the open file as associated to the file descriptor during the file open
sequence.
offset Offset to seek to or to read from.
origin Origin of the vm_write_at() (see section 1.7.4.6) request. This is used to differ between the
two types of requests this entry point is responsible for.
buffer Write data buffer of the given size.
buff_size The requested number of bytes to write.
written_size Pointer to an object of the data type P4_size_t to save the actual number of bytes
written in.
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_NOTIMPL if the responsible provider does not support this operation.
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.
vm_vp_fstat_t File System library file status method. 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:
client UniversalisOS Unique Identifier (UID) of the requesting thread.
handle IN: Handle identifying the open file as associated to the file descriptor during the file open
sequence.
status OUT: Upon success, the structure elements at status are filled in. In case of error, the
content is unspecified.
Returns:
P4_E_OK upon success
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 a failure.
P4_E_STATE if the file handle is invalid due to unlinking or renaming.
vm_vp_map_t File System library file map method.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Volume Providers 209
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:
client UniversalisOS Unique Identifier (UID) of the requesting thread.
handle IN: Handle identifying the open file as associated to the file descriptor during the file open
sequence.
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 exe-
cution. 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: Map flags. This parameter is ignored.
start IN: Virtual address in caller’s address space where to map the file.
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.
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.
vm_vp_ioctl_t File System library I/O control method. This function offers a general purpose interface to file providers. Each provider is free to support vm_ioctl() (see section 1.7.4.13) 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:
client UniversalisOS Unique Identifier (UID) of the requesting thread.
handle IN: Handle identifying the open file as associated to the file descriptor during the file open
sequence.
cmd IN: Command to execute on the file
data IN: Command specific data
Returns:
P4_E_OK upon success
P4_E_NOTIMPL if the responsible provider does not support this operation.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
210 The PSSW API
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.
vm_vp_mount_t vm_vp_umount_t
1.19.4 Function Type Definitions
1.19.4.1 vm_vp_unlink_t
File System library unlink method.
Synopsis:
typedef P4_e_t vm_vp_unlink_t(P4_uid_t client, const char *path, P4_unlink_flags_t flags)
Description: 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: client UniversalisOS Unique Identifier (UID) of the requesting thread. 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.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Volume Providers 211
P4_E_NOTIMPL if this operation is not supported. 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 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.
1.19.4.2 vm_vp_rename_t
File System library rename method.
Synopsis:
typedef P4_e_t vm_vp_rename_t(P4_uid_t client, 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. The semantics of this call depends on the flags parameter. If P4_RENAME_NO_DIR is set in flags, the function renames no directories, which corresponds to file renaming according to the ARINC 653 RENAME_FILE() service. Likewise, the flag P4_RENAME_DIR_ONLY is used to indicate that only directories are to be renamed, according to RENAME_DIRECTORY(). The two flags cannot sensibly be used at the same time, and drivers may react by rejecting both file and directory rename requests. If P4_RENAME_NO_REPLACE is specified, the function will fail if the new name already exists in the file system, i.e., it will not replace the existing file by the renamed one. If no flags is specified, then the function may rename both files and directories and also overwrite existing files, which corresponds to the behaviour of the POSIX rename() service.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. 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.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
212 The PSSW API
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.
1.19.4.3 vm_vp_statvfs_t
File System library statvfs method.
Synopsis:
typedef P4_e_t vm_vp_statvfs_t(P4_uid_t client, const char *volume_path, P4_statvfs_t *buf)
Description: The function retrieves information about the filesystem. During the execution of this call one file descriptor is allocated, and freed before the call returns.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. volume_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_NOTIMPL if the responsible provider does not support this operation. 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.
1.19.4.4 vm_vp_close_t
File System library file close method.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Volume Providers 213
Synopsis:
typedef P4_e_t vm_vp_close_t(P4_uid_t client, vm_file_desc_ext_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: client UniversalisOS Unique Identifier (UID) of the requesting thread. fd IN: file descriptor identifying the open file as associated to the file descriptor during the file open sequence.
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.
1.19.4.5 vm_vp_fsync_t
File System library synchronize file data method.
Synopsis:
typedef P4_e_t vm_vp_fsync_t(P4_uid_t client, vm_file_handle_t handle)
Description: The function writes to storage device all modified data and of the file. The call blocks until the device reports that the transfer was completed.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. handle IN: Handle identifying the open file as associated to the file descriptor during the file open sequence.
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.
1.19.4.6 vm_vp_ftruncate_t
File System library file truncate method.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
214 The PSSW API
Synopsis:
typedef P4_e_t vm_vp_ftruncate_t(P4_uid_t client, vm_file_handle_t handle, P4_off_t new_size, P4_truncate_flags_t flags)
Description: Changing the size of the regular file represented by the fd file descriptor to the size of new_size in bytes.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. handle IN: Handle identifying the open file as associated to the file descriptor during the file open sequence. new_size IN: The size in bytes the file will be set to. flags IN: Flags for truncate operation (see P4_TRUNCATE_*).
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.
1.19.4.7 vm_vp_dir_create_t
File System library create directory method.
Synopsis:
typedef P4_e_t vm_vp_dir_create_t(P4_uid_t client, const char *path)
Description: The call is used to create new directory. The directory will be empty.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. 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.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Volume Providers 215
P4_E_NOTIMPL if the responsible provider does not support this operation. P4_E_INVAL if name 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.
1.19.4.8 vm_vp_dir_open_t
File System library open directory method.
Synopsis:
typedef P4_e_t vm_vp_dir_open_t(P4_uid_t client, const char *path, vm_dir_t *dir_desc)
Description: The call opens a directory stream corresponding to the directory path. The file position is set to the beginning of the file.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. path IN: Path of the directory being opened. dir_desc OUT: The directory descriptor.
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. P4_E_NOTIMPL if the responsible provider does not support this operation. 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_OOFILE if no free file descriptor can be allocated from the partitions file descriptor pool. P4_E_IO if the storage device containing path reports failure.
1.19.4.9 vm_vp_dir_read_at_t
File System library read directory method.
Synopsis:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
216 The PSSW API
typedef P4_e_t vm_vp_dir_read_at_t(P4_uid_t client, vm_directory_handle_t handle, P4_dirent_t *dirent, 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 dirent parameter contains empty string.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. handle IN: Handle identifying the open directory as associated to the directory descriptor during the directory open sequence. dirent OUT: The buffer that will be filled with the retrieved directory entry pos INOUT: 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() (see section 1.8.3.7) or zero can be provided in this parameter.
Returns: P4_E_OK upon success P4_E_TRUNC if the directory entry’s length exceeds size of dirent. The pos must be updated in this case too. P4_E_INVAL if dir is not a valid open directory. P4_E_OOMEM if system resources have been exhausted. P4_E_NOTIMPL if the underlying file system does not support this operation. P4_E_STATE if the directory handle is not valid anymore because of removing or or renaming.
1.19.4.10 vm_vp_dir_close_t
File System library close directory method.
Synopsis:
typedef P4_e_t vm_vp_dir_close_t(P4_uid_t client, vm_directory_handle_t handle)
Description: This function closes an open directory dir.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. handle IN: Handle identifying the open directory as associated to the directory descriptor during the directory open sequence.
Returns: P4_E_OK upon success
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Volume Providers 217
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. P4_E_NOTIMPL if the responsible provider does not support this operation.
1.19.4.11 vm_vp_dir_sync_t
File System library sync directory method.
Synopsis:
typedef P4_e_t vm_vp_dir_sync_t(P4_uid_t client, vm_directory_handle_t handle)
Description: This function synchronizes meta data of an open directory dir.
Parameters: client UniversalisOS Unique Identifier (UID) of the requesting thread. handle IN: Handle identifying the open directory as associated to the directory descriptor during the directory open sequence.
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.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
218 The PSSW API
1.19.5 Functions
1.19.5.1 vm_vp_register
Register a user level volume provider.
Synopsis:
P4_e_t vm_vp_register(const char *name, P4_uint32_t *handle)
Parameters: name Name of the file system to register. handle Reference to the handle of the external file provider. This may be a reference to the member "handle" of the external file provider’s descriptor.
Description: This service registers a user level volume provider at the PSSW. After a successful call to this function, service requests to the file system name will be routed to the caller of this function. On success handle is assigned a value uniquely identifying the file provider. The external file provider will copy this handle into its external file provider descriptor.
Note: In product version without external file provider support, this service is not functional.
Returns: P4_E_OK On success. P4_E_NOENT If external file providers are not supported by the system. This can happen if the kextfp KDEV driver is not fused with the kernel. P4_E_PERM If the given name is not configured as an external file provider prefix in the VMIT configuration, i.e. the calling resource partition has no permission to register as the specified file provider. If the integrator specified VM_O_FSPROV instead of VM_O_VOLPROV for the provider prefix in the VMIT configuration. P4_E_INVAL If an input parameter is invalid, e.g., the name is too long. P4_E_BUSY If the prefix was already registered by another volume provider. P4_E_ABORT if the call was aborted. P4_E_CANCEL if the call was canceled.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Volume Providers 219
1.19.5.2 vm_vp_listen
Listen for service requests and handle them.
Synopsis:
P4_e_t vm_vp_listen(vm_vp_listen_t *vp)
Parameters: vp A reference to the volume provider’s descriptor.
Description: Calling this function enters an endless loop listening for service requests issued to the provider’s workers via IPC. Once a service request is received, the corresponding entry point is entered. References to the volume provider’s entry points are contained in vp. According to the presence of vp->vph.mount and vp->vph.umount the working mode is selected:
- mount or umount is set In this case the service handles just mount and unmount requests.
- mount and umount are not set In this case service handles all other client requests. This function is executed as long as no error occurs.
Note: The IPC mask is overridden when mount and umount requests are handled.
Note: This function does only return in case of an error.
Returns: The error code of vm_fp_msg_wait() (see section 1.18.6.2) or vm_fp_msg_dispatch() (see section 1.18.6.3) (first error code is returned). Please refer to the documentation of these functions.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
220 The PSSW API
1.20 Request Service
The Request Service allows system extensions to implement blocking the requests in a uniform way. The interface also makes system extensions that use blocking stackable, i.e., one system extension may use another that blocks.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 221
1.21 Healthmonitoring
(C) Copyright Portugal Futurista.
1.21.1 Defines
VM_ERR_1
Description:
PSSW Error 1
msg:
Unable to map ROM to 0x
scope:
global
continuation:
fatal
VM_ERR_2
Description:
PSSW Error 2
msg:
Invalid number of partitions in VMIT: lu
description:
There are too many partition entries in the VMIT. The maximum number of partitions is 254.
scope:
global
continuation:
fatal
VM_ERR_3
Description:
PSSW Error 3
msg:
Partition ’s’:
Invalid partition ID: d
description:
The partition ID attribute at the given partition is out of range. The ID must be between 1 and 254.
scope:
global
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
222 The PSSW API
VM_ERR_4
Description:
PSSW Error 4
msg:
MaxPrio(=d) must not exceed d
scope:
partition
continuation:
fatal
VM_ERR_5
Description:
PSSW Error 5
msg:
MaxPrio(=d) must not be below d
scope:
partition
continuation:
fatal
VM_ERR_6
Description:
PSSW Error 6
msg:
Invalid operating mode d, expected IDLE(=d) or COLD_START(=d)
scope:
partition
continuation:
fatal
VM_ERR_7
Description:
PSSW Error 7
msg:
TimePartitionID=d out of range (0..d)
scope:
partition
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 223
VM_ERR_8
Description:
PSSW Error 8
msg:
PartitionIdentifier=d out of range (1..d)
scope:
partition
continuation:
fatal
VM_ERR_9
Description:
PSSW Error 9
msg:
Maximum number of tasks exceeded.
scope:
global
continuation:
fatal
VM_ERR_10
Description:
PSSW Error 10
msg:
Unable to map process to 0xlx, rc=s
scope:
partition
continuation:
fatal
VM_ERR_11
Description:
PSSW Error 11
msg:
Unable to create apploader mapping rc=s
scope:
partition
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
224 The PSSW API
VM_ERR_12
Description:
PSSW Error 12
msg:
Error creating partition daemon thread: s
scope:
partition
continuation:
fatal
VM_ERR_13
Description:
PSSW Error 13
msg:
CpuMask intersection is empty:
Partition has 0xlx, SchedulingTable restricts to 0xlx.
scope:
partition
continuation:
fatal
VM_ERR_14
Description:
PSSW Error 14
msg:
Error pinning partition to cpumask 0xllx: s
scope:
partition
continuation:
fatal
VM_ERR_15
Description:
PSSW Error 15
msg:
TP scheme ’s’ is not defined in module VMIT
scope:
partition
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 225
VM_ERR_16
Description:
PSSW Error 16
msg:
Overlapping CPU mask 0x
scope:
partition
continuation:
fatal
VM_ERR_17
Description:
PSSW Error 17
msg:
TP scheme ’s’: No window table found in global VMIT for CpuMask=0x
scope:
partition
continuation:
fatal
VM_ERR_18
Description:
PSSW Error 18
msg:
TP scheme ’s’: Time partition ID u is larger than configured maximum u
scope:
partition
continuation:
fatal
VM_ERR_19
Description:
PSSW Error 19
msg:
Non-contiguous TP scheme ’s’: start is u, expected u
scope:
partition
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
226 The PSSW API
VM_ERR_20
Description:
PSSW Error 20
msg:
In TP scheme ’s’: integer overflow: u+u
scope:
partition
continuation:
fatal
VM_ERR_21
Description:
PSSW Error 21
msg:
TP scheme ’s’: window table for CpuMask=0x
scope:
partition
continuation:
fatal
VM_ERR_22
Description:
PSSW Error 22
msg:
Sync CPU u not part of CPU mask 0x
scope:
partition
continuation:
fatal
VM_ERR_23
Description:
PSSW Error 23
msg:
Unable to create schedule change daemon for CPU u: s
scope:
global
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 227
VM_ERR_24
Description:
PSSW Error 24
msg:
TP0 window u must have: Flags="" Id="0" UserData="0"
scope:
partition
continuation:
fatal
VM_ERR_25
Description:
PSSW Error 25
msg:
TP schema ’s’: Inconsistent configuration of TP window at start=u.
scope:
partition
continuation:
fatal
VM_ERR_26
Description:
PSSW Error 26
msg:
TP schema ’s’: Start=u: Time partition is scheduled in multiple WindowTables
scope:
partition
continuation:
fatal
VM_ERR_27
Description:
PSSW Error 27
msg:
TP schema ’s’: Inconsistent configuration of TP window at start=u.
scope:
partition
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
228 The PSSW API
VM_ERR_28
Description:
PSSW Error 28
msg:
TP u period/duration mismatch: p=u,d=u vs. p=u,d=u.
scope:
global
continuation:
fatal
VM_ERR_29
Description:
PSSW Error 29
msg:
TP scheme ’s’: TP u: cpu mask 0x
scope:
global
continuation:
fatal
VM_ERR_30
Description:
PSSW Error 30
msg:
TP scheme ’s’: TP u: overlapping window: start=u, expected u.
scope:
global
continuation:
fatal
VM_ERR_31
Description:
PSSW Error 31
msg:
TP scheme ’s’: TP u: Duration <= SwitchOutDuration
scope:
global
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 229
VM_ERR_32
Description:
PSSW Error 32
msg:
TP scheme ’s’: TP u: window at start=u: illegal CPU allocation 0x
scope:
global
continuation:
fatal
VM_ERR_33
Description:
PSSW Error 33
msg:
TP scheme ’s’: TP u: illegal window or gap in assigned partitions
scope:
global
continuation:
fatal
VM_ERR_34
Description:
PSSW Error 34
msg:
Too many scheduling windows are used: max is u
scope:
global
continuation:
fatal
VM_ERR_35
Description:
PSSW Error 35
msg:
TP schema ’s’: overlapping windows in joined window table detected
scope:
global
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
230 The PSSW API
VM_ERR_36
Description:
PSSW Error 36
msg:
TP schema ’s’: non-existing CPUs in CpuMask: 0x
scope:
global
continuation:
fatal
VM_ERR_37
Description:
PSSW Error 37
msg:
TP schema ’s’: 0x
scope:
global
continuation:
fatal
VM_ERR_38
Description:
PSSW Error 38
msg:
TP schema ’s’: 0x
scope:
global
continuation:
fatal
VM_ERR_39
Description:
PSSW Error 39
msg:
Unable to load TP ktable, rc=s (d)
scope:
global
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 231
VM_ERR_40
Description:
PSSW Error 40
msg:
unable to open ’s’: s
scope:
partition
continuation:
recoverable
VM_ERR_41
Description:
PSSW Error 41
msg:
Page offset in ELF file is not equal to target address’s in ’s’
scope:
partition
continuation:
recoverable
VM_ERR_42
Description:
PSSW Error 42
msg:
ELF load ’s’: Cannot map file to execute in place: s
scope:
partition
continuation:
recoverable
VM_ERR_43
Description:
PSSW Error 43
msg:
ELF load ’s’: Cannot alloc 0xlx bytes from pool ’s’: s
scope:
partition
continuation:
recoverable
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
232 The PSSW API
VM_ERR_44
Description:
PSSW Error 44
msg:
ELF load ’s’: Cannot copy 0xzx bytes of data: s
scope:
partition
continuation:
recoverable
VM_ERR_45
Description:
PSSW Error 45
msg:
ELF load ’s’: Cannot clear 0xzx bytes of memory: s
scope:
partition
continuation:
recoverable
VM_ERR_46
Description:
PSSW Error 46
msg:
ELF load ’s’: could not read elf header of file: rc=s
scope:
partition
continuation:
recoverable
VM_ERR_47
Description:
PSSW Error 47
msg:
ELF load ’s’: wrong ELF signature
scope:
partition
continuation:
recoverable
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 233
VM_ERR_48
Description:
PSSW Error 48
msg:
ELF load ’s’: not a 64 bit executable
scope:
partition
continuation:
recoverable
VM_ERR_49
Description:
PSSW Error 49
msg:
ELF load ’s’: not a 32 bit executable
scope:
partition
continuation:
recoverable
VM_ERR_50
Description:
PSSW Error 50
msg:
ELF load ’s’: e_machine is invalid, expected MACHINE_STR
scope:
partition
continuation:
recoverable
VM_ERR_51
Description:
PSSW Error 51
msg:
ELF load ’s’: e_version is invalid, found 0xx
scope:
partition
continuation:
recoverable
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
234 The PSSW API
VM_ERR_52
Description:
PSSW Error 52
msg:
ELF load ’s’: not an ET_EXEC type binary, found 0xx
scope:
partition
continuation:
recoverable
VM_ERR_53
Description:
PSSW Error 53
msg:
ELF load ’s’: Error phoff too large in ELF file
scope:
partition
continuation:
recoverable
VM_ERR_54
Description:
PSSW Error 54
msg:
ELF load ’s’: Error reading program header of file: s
scope:
partition
continuation:
recoverable
VM_ERR_55
Description:
PSSW Error 55
msg:
Unable to register HM PAC bitmap
scope:
global
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 235
VM_ERR_56
Description:
PSSW Error 56
msg:
Unable to create HMPartActionD for CPU u
scope:
global
continuation:
fatal
VM_ERR_57
Description:
PSSW Error 57
msg:
Unable to create HMPartActionD for CPU u
scope:
global
continuation:
fatal
VM_ERR_58
Description:
PSSW Error 58
msg:
Unable to create HMPartActionD for CPU u
scope:
global
continuation:
fatal
VM_ERR_59
Description:
PSSW Error 59
msg:
Duplicate provider ’s’
scope:
global
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
236 The PSSW API
VM_ERR_60
Description:
PSSW Error 60
msg:
Duplicate gate ’s:s’, rpid=u
scope:
global
continuation:
fatal
VM_ERR_61
Description:
PSSW Error 61
msg:
KDEV version mismatch: s
scope:
global
continuation:
fatal
VM_ERR_62
Description:
PSSW Error 62
msg:
The libvm does not match PSSW version: app=0xx vs PSSW=0xx
scope:
partition
continuation:
recoverable
VM_ERR_63
Description:
PSSW Error 63
msg:
Partition u: VMIT: Too large: llu
scope:
global
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 237
VM_ERR_64
Description:
PSSW Error 64
msg:
VMIT is invalid.
scope:
global
continuation:
fatal
VM_ERR_65
Description:
PSSW Error 65
msg:
VMIT has bad structure CRC (wrong version?): 0x
scope:
global
continuation:
fatal
VM_ERR_66
Description:
PSSW Error 66
msg:
VMIT PartitionID is u, but expected u
scope:
global
continuation:
fatal
VM_ERR_67
Description:
PSSW Error 67
msg:
VMIT Version is u, but expected u
scope:
global
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
238 The PSSW API
VM_ERR_68
Description:
PSSW Error 68
msg:
Module global VMIT ’s’ not found.
scope:
global
continuation:
fatal
VM_ERR_69
Description:
PSSW Error 69
msg:
Partition: u
MemRegionPartion/MemRegionID are invalid
scope:
global
continuation:
fatal
VM_ERR_70
Description:
PSSW Error 70
msg:
Node ’prop:s’ has wrong type, expected prop_uint32
scope:
global
continuation:
fatal
VM_ERR_71
Description:
PSSW Error 71
msg:
Found duplicate shared memory entry s.
scope:
global
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 239
VM_ERR_72
Description:
PSSW Error 72
msg:
Shared memory configuration entry of invalid type u (only RAM and I/O memory is allowed).
scope:
global
continuation:
fatal
VM_ERR_73
Description:
PSSW Error 73
msg:
Provider ’s’ misses driver name
scope:
global
continuation:
fatal
VM_ERR_74
Description:
PSSW Error 74
msg:
System extensions ’s’ not linked with PSSW
scope:
global
continuation:
fatal
VM_ERR_75
Description:
PSSW Error 75
msg:
System extension ’s’ misses callbacks install, open, or close
scope:
global
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
240 The PSSW API
VM_ERR_76
Description:
PSSW Error 76
msg:
Install callback of file provider ’s’ returned s
scope:
global
continuation:
fatal
VM_ERR_77
Description:
PSSW Error 77
msg:
Duplicate file provider ’s’
scope:
global
continuation:
fatal
VM_ERR_78
Description:
PSSW Error 78
msg:
Unable to allocate+map partition u memory, rc=s
scope:
global
continuation:
fatal
VM_ERR_79
Description:
PSSW Error 79
msg:
No more virtual memory for partition u, wanted size=lu
scope:
global
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 241
VM_ERR_80
Description:
PSSW Error 80
msg:
Global ROM file system not found.s
scope:
global
continuation:
fatal
VM_ERR_81
Description:
PSSW Error 81
msg:
Bad path name ’s’ in file access record
scope:
partition
continuation:
fatal
VM_ERR_82
Description:
PSSW Error 82
msg:
Number of tasks exceeded, max=u.
scope:
partition
continuation:
fatal
VM_ERR_83
Description:
PSSW Error 83
msg:
Process ’s’:
Could not establish memory requirement ’s’.
scope:
partition
continuation:
recoverable
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
242 The PSSW API
VM_ERR_84
Description:
PSSW Error 84
msg:
Process ’s’:
Memory requirement ’s’ must not be a pool.
scope:
partition
continuation:
recoverable
VM_ERR_85
Description:
PSSW Error 85
msg:
Process ’s’: unable to create ioport: s
scope:
partition
continuation:
recoverable
VM_ERR_86
Description:
PSSW Error 86
msg:
Access mode for mapping of memory requirement ’s’ for process ’s’ exceeds permissions.
scope:
partition
continuation:
recoverable
VM_ERR_87
Description:
PSSW Error 87
msg:
Access mode for mapping of memory requirement ’s’ for process ’s’ exceeds permissions.
scope:
partition
continuation:
recoverable
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 243
VM_ERR_88
Description:
PSSW Error 88
msg:
Could not map memory requirement ’s’ for process ’s’: s
scope:
partition
continuation:
recoverable
VM_ERR_89
Description:
PSSW Error 89
msg:
MaxPrio(=d) of process ’s’ must be less than MaxPrio(=d) of partition.
scope:
partition
continuation:
recoverable
VM_ERR_90
Description:
PSSW Error 90
msg:
Process ’s’ has no entry point.
scope:
partition
continuation:
recoverable
VM_ERR_91
Description:
PSSW Error 91
msg:
Failed to create task for process ’s’: s
scope:
partition
continuation:
recoverable
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
244 The PSSW API
VM_ERR_92
Description:
PSSW Error 92
msg:
Error reading .text segment of task d ’s’: rc=s (0xx)
scope:
partition
continuation:
recoverable
VM_ERR_93
Description:
PSSW Error 93
msg:
Task d ’s’ lacks __p4_start() signature
scope:
partition
continuation:
recoverable
VM_ERR_94
Description:
PSSW Error 94
msg:
Error starting task d ’s’: rc=s (0xx)
scope:
partition
continuation:
recoverable
VM_ERR_95
Description:
PSSW Error 95
msg:
VM_MEM_TYPE_IO_PORT memory requirement ’s’ is not supported
scope:
partition
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 245
VM_ERR_96
Description:
PSSW Error 96
msg:
Size 0xlx of memory requirement ’s’ is not a multiple by page size 0xlx
scope:
partition
continuation:
fatal
VM_ERR_97
Description:
PSSW Error 97
msg:
Shared memory ’s’ cannot be used as a pool
scope:
partition
continuation:
fatal
VM_ERR_98
Description:
PSSW Error 98
msg:
Pool memory ’s’ must be either RAM, ROM, or IO_MEM.
scope:
partition
continuation:
fatal
VM_ERR_99
Description:
PSSW Error 99
msg:
Physical address 0xllx of memory requirement ’s’ is not a multiple of page size 0xlx
scope:
partition
continuation:
fatal
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
246 The PSSW API
VM_ERR_100
Description:
PSSW Error 100
msg:
Memory requirement ’s’ must have a physical address
scope:
partition
continuation:
fatal
VM_ERR_101
Description:
PSSW Error 101
msg:
Memory requirement ’s’ has type VM_MEM_TYPE_ROM, but is configured to be writeable
scope:
partition
continuation:
fatal
VM_ERR_102
Description:
PSSW Error 102
msg:
Memory requirement ’s’:
Unable to allocate lu bytes from mem region u, rc=s
scope:
partition
continuation:
fatal
VM_ERR_103
Description:
PSSW Error 103
msg:
Memory requirement ’s’:
Unable to map allocated memory: rc=s
scope:
partition
continuation:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 247
fatal
VM_ERR_104
Description:
PSSW Error 104
msg:
Memory requirement ’s’:
Unable to allocate lu bytes from mem region u, rc=s
scope:
partition
continuation:
fatal
VM_ERR_105
Description:
PSSW Error 105
msg:
Memory requirement ’s’:
Unable to map allocated memory: rc=s
scope:
partition
continuation:
fatal
VM_ERR_106
Description:
PSSW Error 106
msg:
Memory requirement ’s’:
Unable to allocate memory from memreg 0xx: rc=s
scope:
partition
continuation:
fatal
VM_ERR_107
Description:
PSSW Error 107
msg:
Memory requirement ’s’:
Unable to map allocated memory from memreg 0xx, rc=s
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
248 The PSSW API
scope:
partition
continuation:
fatal
VM_ERR_108
Description:
PSSW Error 108
msg:
ZeroCount is too large in memreq s
scope:
partition
continuation:
fatal
VM_ERR_109
Description:
PSSW Error 109
msg:
p4_mem_create() for zeroing failed: s: va=0xlx, pa=0xllx, s
scope:
partition
continuation:
fatal
VM_ERR_110
Description:
PSSW Error 110
msg:
Could not allocate and/or map memory requirement ’s’: s
scope:
partition
continuation:
fatal
VM_ERR_111
Description:
PSSW Error 111
msg:
TP schema ’s’: Window duration 0 is not allowed at start=u.
scope:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Healthmonitoring 249
partition
continuation:
fatal
VM_ERR_ID_ALL Iteration macro for PSSW error IDs This macro can be used to iterate all PSSW error IDs.
VM_ERR_ID_MAX
Description:
Maximum PSSW Error Identifier.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
2 The Virtual Machine Initialization Table
A UniversalisOS system is configured through a binary module called the Virtual Machine Initialization Table (VMIT). The VMIT must be part of the ROM File System and it must have the name ’VMIT’. For more information about the UniversalisOS ROM File System, refer to UniversalisOS User Manual. As part of the build process, the VMIT is generated from an XML file by a tool called universalisos-configconv, which is also used for driver configuration files. The XML file contains the configuration data in a human readable format, and it adheres to the definition in the corresponding XSD file. The VMIT can be generated and modified using the UniversalisOS integrated development tool chain. It should be edited only inside the CODEO development tool, because the configurator will overwrite manual changes made to the vmit4.xml file the next time the configuration files are exported. The following points should be noted when creating a system configuration XML file:
• The XML document prolog must contain the following XML declaration:
<?xml version="1.0" encoding="US-ASCII"?>
• Within the XML file, only characters from the US-ASCII character set are allowed. This also applies to
characters used in comment sections.
Note: This means that only the lower 128 characters of Unicode are supported (code points
U+0000...U+007F). Characters with accents or umlauts are not part of the US-ASCII character set.
• All XML element and attribute names are case-sensitive.
• All configuration data is stored in XML attribute nodes. Text nodes are not used in the XML file.
• The order in which attributes appear has no influence on the resulting binary module.
• Within list-type elements such as <PartitionTable>, the order of the list elements has an influence on
the order in which the elements are processed by the UniversalisOS system software at boot time. This may be
visible to the user, especially if a configuration error occurs due to limited system resources.
The following sections describe the various configuration elements used in an XML configuration file. In these sections, the term VMIT refers to the XML configuration file rather than the binary configuration module.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Common Data Types 251
2.1 Common Data Types
All configuration data is given in the following form:
AttributeName="data"
The following sections describe the data types commonly used for attribute values. Beside these common data types, there are special data types like enumeration types that are described at the documentation of the related attributes.
2.1.1 stdBool64
A 64-bit boolean type which has two values, either true or false. This type is case sensitive.
2.1.2 stdUnsignedShort
This is a decimal or hexadecimal unsigned integer with 16 bits width (octal or binary are not allowed). It corre- sponds to the XSD type ’unsignedShort’, but numbers may be specified in decimal or hexadecimal notation, so XSD has to handle this as string. It translates to the C type ’unsigned int’. The constraints for the decimal format of this type only roughly check that the value is OK. configconv has the correct check that this converts to ’unsigned long long’ correctly.
2.1.3 stdUnsignedInt
This is a decimal or hexadecimal unsigned integer with 32 bits width (octal or binary are not allowed). It corre- sponds to the XSD type ’unsignedInt’, but numbers may be specified in decimal or hexadecimal notation, so XSD has to handle this as string. It translates to the C type ’unsigned int’. The constraints for the decimal format of this type only roughly check that the value is OK. configconv has the correct check that this converts to ’unsigned long long’ correctly.
2.1.4 stdUnsignedIntNoMinus
Similar to stdUnsignedInt, but the special value -1 is not allowed.
2.1.5 stdUnsignedLong
This is a decimal or hexadecimal unsigned integer with 64 bits width (octal or binary are not allowed). It corre- sponds to the XSD type ’unsignedLong’, but numbers may be specified in decimal or hexadecimal notation, so XSD has to handle this as string. It translates to the C type ’unsigned long long’. The constraints for the decimal format of this type only roughly check that the value is OK. configconv has the correct check that this converts to ’unsigned long long’ correctly.
2.1.6 stdUnsignedLongNoMinus
Similar to stdUnsignedLong, but the special value -1 is not allowed.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
252 The Virtual Machine Initialization Table
2.1.7 stdUnsignedWord
This is a decimal or hexadecimal unsigned integer as wide as the target architecture pointer type. This integer type has no equivalent in standard XSD, where there is only ’unsignedInt’ with 32 bits, and ’unsigned- Long’ with 64 bits. This has the base type ’__unsignedWord’, which is special to configconv. It has 32 bits width for ILP32 platforms and 64 bits width for LP64 platform. It translates to the C type ’unsigned long’. The constraints for this type only roughly check that the value is OK. configconv has the full that this converts to ’unsigned long’ correctly.
2.1.8 stdUnsignedWordNoMinus
Similar to stdUnsignedWord, but the special value -1 is not allowed.
2.1.9 stdWord
This is a decimal or hexadecimal signed integer as wide as the target architecture pointer type. This integer type has no equivalent in standard XSD, where there is only ’int’ with 32 bits, and ’long’ with 64 bits. This has the internal type ’__word’, which is special to configconv. It has 32 bits width for ILP32 platforms and 64 bits width for LP64 platform. It translates to the C type ’long’. The constraints for this type only roughly check that the value is OK. configconv has the full check that this converts to ’long’ correctly.
2.1.10 stdIPv4
This is a dotted quad to store IPv4 addresses. This type has no equivalent in standard XSD, which will handle it as a string. It has the internal type ’__ipv4’, which is special to configconv. The resulting C type has 32 bits and is always stored in network byte order (big endian). The constraints for this type only roughly check that the value is OK, because checking decimal number by pattern matching is complicated. However, configconv has the full check that each byte converts to ’unsigned char’ correctly. The pattern here does check that no superfluous leading zeros are used for any integer in the quad.
2.1.11 stdMAC
This is a colon-separated six-byte string to store MAC addresses. This type has no equivalent in standard XSD, which will handle it as a string. It has the internal type ’__mac’, which is special to configconv. The resulting C type has 64 bits and is aligned to 8 bytes, and is always stored in network byte order. Since MAC addresses are only 48 bits, the lower 16 bits of the stored constant are 0. E.g. ff:ee:dd:cc:bb:aa will be stored as the big-endian 64-bit integer 0xffeeddccbbaa0000. The constraints for this type check that the value conforms to the standard hexadecimal notation of MAC ad- dresses. configconv also has a check that each byte converts to ’unsigned char’ correctly.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Common Data Types 253
2.1.12 partID
A partition ID, either for resource or time partitions. This is an unsigned byte that is restricted to the range 1..254. 0 is not allowed because it is reserved to signify global scope. 255 is not allowed because it is a wild card for ’any partition’ in UniversalisOS.
2.1.13 partID0
A partition ID, either for resource or time partitions, just like ’partID’, but partition number 0 is allowed.
2.1.14 priority
A thread priority. This is an unsigned byte restricted to the range 1..246. Other values in the 8bit unsigned range are reserved by UniversalisOS.
2.1.15 version
A version number. This is an arbitrary string with a length between 1 and 31 characters.
2.1.16 name
A name to identify an entity. This is an arbitrary string with a length between 1 and 31 characters.
2.1.17 name0
A name to identify an entity, which may also have length 0. Otherwise like ’name’.
2.1.18 path
A path in the UniversalisOS file system. This is an arbitrary string with a length between 1 and 255 characters. The provider part must not contain color nor slash. The provider part and the colon are mandatory. The path must not start with a slash. The asterisk is excluded completely because it has a special meaning in the acl_path type.
2.1.19 acl_path
An access control list path in the UniversalisOS file system. This is an arbitrary string with a length between 1 and 255 characters. Some restrictions apply to the format, expressed as pattern restrictions. Similar to a normal path, but the colon is optional and the path may be terminated by an optional asterisk.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
254 The Virtual Machine Initialization Table
2.2 The VMIT Root Element
Configuration
1
PartitionTable
...
1
ConnectionTable
...
1
SharedMemoryTable
...
1
ScheduleTable
...
1
MultiPartitionHMTable
...
1
ModuleHMTable
...
1
SystemExtensionTable
...
Figure 1: The Root Element
The element contains exactly one instance of the following elements:
PartitionTable The Partition Table contains the resource partition related configuration parameters. For each resource partition that shall be configured, it contains one element. It is not an error for the partition table to be empty. However, the resulting system will do nothing than executing the idle thread after the boot process has finished.
A detailed description of the partition configuration can be found in section 2.3, page 256.
ConnectionTable The Connection Table describes the configuration of the communication channels, each of which connects two Partition Communication Ports. For each channel that shall be configured, the Con- nection Table contains one element. The Connection Table can be empty.
A detailed description of the channel configuration can be found in section 2.4, page 268.
SharedMemoryTable The Shared Memory Table describes the shared memory resources that shall be created by the UniversalisOS System Software. For each shared memory object that shall be created, the Shared Memory Table contains one element. The Shared Memory Table can be empty.
A detailed description of the shared memory configuration can be found in section 2.5, page 270.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The VMIT Root Element 255
ScheduleTable The Schedule Table contains the configuration data for the Time Partition Scheduler. Multi- ple scheduling schemes are supported. For each scheduling scheme, the Schedule Table contains one element. If time partitioning is not used, the Schedule Table can be empty. A detailed description of the time partition configuration can be found in section 2.6, page 271.
MultiPartitionHMTable The Multi Partition Health Monitor Table is part of the PSSW health monitor module and consists of a matrix with the system state as index to the columns and the error identifier as index to the rows. The health monitor handles the error at the error level specified at the corresponding matrix element. The following error levels are defined:
• Module Error Level
• Partition Error Level
• Process Error Level
ModuleHMTable The Module Health Monitor Table is part of the PSSW health monitor module and consists of a matrix with the system state as index to the columns and the error identifier as index to the rows. The actions to be taken at module level are:
• Ignore the error and continue execution.
• Shutdown the module.
• Reset the module.
Note: The actions to be taken at partition error level are defined in the corresponding Partition Health
Monitor Table. There is a Partition Health Monitor Table for each partition. Errors at process level are
forwarded to a user defined error handler. Therefore, there is no process health monitor table.
SystemExtensionTable The System Extension Table contains the configuration data for system extensions. A detailed description of the system extensions configuration can be found in section 2.9, page 277.
The following scalar attributes are defined for the element:
Name Type / Constraints Description PartitionID partID0 The resource partition number to which this VMIT applies. The global VMIT uses 0, which is also the default.
Version VM_VMIT_VERSION_CURRENT This attribute specifies the version of the VMIT. It is not evaluated by the UniversalisOS system software.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
256 The Virtual Machine Initialization Table
2.3 The Partition Configuration
PartitionTable
0..N
Partition
1
MemoryRequirementTable
0..N
MemoryRequirement
1
FileAccessTable
0..N
FileAccess
1
QueuingPortTable
0..N
QueuingPort
1
SamplingPortTable
0..N
SamplingPort
1
ProcessTable
0..N
Process
1
MapTable
0..N
Map
1
FileTable
0..N
1 File
HMTable
...
Figure 2: The Partition Table
The element contains the partition configuration information for one partition. The partition config- uration contains a set of scalar attributes and exactly one instance of the following elements:
MemoryRequirementTable The Memory Requirement Table describes the physical memory-, I/O memory-, I/O port-, and kernel memory requirements of the partition. The Memory Requirement Table contains one element for each individual memory object. The table can be empty. However, it is hard to imagine the use for a resource partition that does not provide any memory resources.
Note that the property file system is the preferred method for assigning driver resources.
A detailed description of the memory requirement configuration can be found in section 2.3.1, page 259.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Partition Configuration 257
QueuingPortTable The Queuing Port Table describes the Partition Communication Ports (PCP) provided by the partition. The Queuing Port Table contains one element for each PCP that shall be configured for the partition. If the partition shall not provide any port, the table can be empty. A detailed description of the queuing port configuration can be found in section 2.3.2, page 262.
SamplingPortTable The Sampling Port Table describes the Partition Communication Ports (PCP) provided by the partition. The Sampling Port Table contains one element for each PCP that shall be configured for the partition. If the partition shall not provide any port, the table can be empty. A detailed description of the sampling port configuration can be found in section 2.3.3, page 262.
FileAccessTable The File Access Table describes the partition’s access permissions to objects (files, paths, devices or properties) in the UniversalisOS filesystem. The File Access Table contains of a set of elements that describe the access permissions for one or a group of objects. A detailed description of the file access configuration can be found in section 2.3.4, page 263.
ProcessTable The Process Table describes the configuration for the application processes that shall be started in the resource partition. The Process Table contains one element for each process that shall be started. The table can be empty, if no process shall be started. A detailed description of the process configuration can be found in section 2.3.5, page 263.
HMTable The Health Monitor Table is part of the PSSW health monitor module and consists of a matrix with the system state as index to the columns and the error identifier as index to the rows. If an error is classified to be handled at the error level Partition by the System Health Monitor Table (see above), the action to be taken is defined at the corresponding matrix element of the corresponding Health Monitor Table. The actions to be taken at partition level are:
• Ignore the error and continue execution.
• Set the partition mode to idle.
• Restart the partition in cold start mode.
• Restart the partition in warm start mode.
The following scalar attributes are defined for a partition:
Name Type / Constraints Description Name name, unique within the Identifier partID This attribute specifies a unique integer constant to identify a partition.
MaxChildTaskCount stdUnsignedIntNoMinus This attribute tells the UniversalisOS system software component how many UniversalisOS tasks shall be reserved for the partition. The number must be at least the number of processes configured in the process section (the Primary Processes) plus the sum of the child tasks configured for each of these processes. A configuration error will be raised during system initialization if there are not enough tasks available to satisfy the task requirements of all partitions.
MaxPrio priority This attribute defines the maximum possible UniversalisOS scheduling priority for any thread running in the partition. Service requests from an application (partition port communication, application loading, file transfer, etc.) will be performed by the UniversalisOS system software at priority MaxPrio and MaxPrio - 1. As a result an application processes may only be assigned a MaxPrio - 2.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
258 The Virtual Machine Initialization Table
Name Type / Constraints Description TimePartitionID partID0 This attribute specifies the ID of the time partition in which the partition shall be started. If 0 is specified, the resource partition will be assigned to the special time partition τ 0 . A configuration error will be raised if the value of the time partition ID exceeds the number of time partitions supported by the UniversalisOS kernel. Note that the number of supported time partitions can be specified by a UniversalisOS kernel parameter. The default number of supported time partitions is 8 (including time partition τ 0 ).
StartupMode one of: This attribute specifies the startup mode of the partition. VM_PART_MODE_IDLE If StartupMode is VM_PART_MODE_IDLE, the partition will be created, all resources will be allocated for the partition, but the application processes VM_PART_MODE_COLD_START will not be created. If StartupMode is VM_PART_MODE_COLD_START, the application pro- cesses will be created, the files specified in the process configuration sec- tion will be loaded into the address spaces of the application processes, and the processes will be started. If an application process throws an ex- ception in this partition mode, the PSSW health monitor will assume the system state VM_HM_ST_PART_INIT. The partition modes VM_PART_MODE_WARM_START and VM_PART_MODE_NORMAL cannot be enabled at partition boot time, i.e., these are invalid settings in the VMIT. These modes can only be entered by a partition at runtime by manually switching modes.
SchedChangeAction one of: The action to run when the time partition schedule is changed. VM_SCHED_CHANGE_ COLD_START VM_SCHED_CHANGE_ WARM_START VM_SCHED_CHANGE_IGNORE
MultiPartitionHMTableID stdUnsignedIntNoMinus The Id of the multi-partition health monitoring table that is used for this partition. That table is used to decide whether an event is module level or partition level.
Abilities empty or one or (space separated) The abilities of the partition. Please note that only the abilities: combination of: VM_AB_TIMEPART_CHANGE, VM_AB_MONITOR, VM_AB_PSP_CON- VM_AB_TIMEPART_SETUP SOLE, VM_AB_MEM_CREATE, VM_AB_HM_INJECT_OTHER, VM_AB_PSP_RESET VM_AB_TRACE, VM_AB_CACHE_CHANGE, VM_AB_ULOCK_SHARED VM_AB_PART_SET_MODE will be propagated to application tasks upon partition creation (i.e., only VM_AB_TIMEPART_CHANGE these abilities are propagated as equivalent P4_AB abilities available at VM_AB_MONITOR Kernel-level). VM_AB_PSP_CONSOLE VM_AB_MEM_CREATE VM_AB_HM_INJECT_OTHER VM_AB_TRACE VM_AB_CACHE_CHANGE VM_AB_ULOCK_SHARED
MaxFDCount stdUnsignedIntNoMinus Maximum number of file descriptors which can be obtained simultaneously in this partition. The maximum value is 65535. KDEV gate descriptors also consume one MaxFDCount each but their maximum number in the "global data" partition is 128.
CpuMask stdUnsignedWord Maximum set of CPUs the partition may run on. Each bit corresponds to a CPU, e.g., 0x3 specifies that the partition may run on CPUs 0 and 1. The actual list of CPUs is restricted further by the ScheduleTable, which al- locates time partitions to CPUs. Each resource partition has an associated time partition, and the resource partition’s CpuMask is restricted by its time partition’s CPU mask. A value of -1 means ’all CPUs in the system’. This is also used to restrict the Partition Daemon of the partition in the PSSW to a given set of CPUs.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Partition Configuration 259
2.3.1 The Memory Requirement Configuration Element
The element specifies a memory resource that shall be accessible by the partition. The following scalar attributes are defined for a memory resource:
Name Type / Constraints Description Name name, unique amongst all memory re- This attribute specifies the name to identify the memory resource. quirements int the partition
Type one of: This attribute specifies the memory type for the memory resource. The VM_MEM_TYPE_RAM different memory types are described in the following sections. VM_MEM_TYPE_IO_PORT VM_MEM_TYPE_IO_MEM VM_MEM_TYPE_ROM VM_MEM_TYPE_KMEM
Size stdUnsignedWordNoMinus This attribute specifies the size of the memory resource. It must be a multiple of P4_PAGESIZE, except for memory requirements of type VM_MEM_TYPE_IO_PORT, where the size can be given with byte- granularity.
PhysicalAddress stdUnsignedLong This attribute specifies the physical address of the start of the memory resource. The meaning of this attribute depends on the memory type and is described in the corresponding section for each memory type.
Alignment stdUnsignedWord This attribute specifies the physical alignment requirement for the memory resource. The meaning of this attribute depends on the memory type and is described in the corresponding section for each memory type.
Contiguous boolean This attribute specifies whether the memory resource shall be composed of physically contiguous pages. The meaning of this attribute depends on the memory type and is described in the corresponding section for each memory type.
AccessMode one or (space separated) combination This attribute specifies the permitted memory access. of: VM_MEM_ACCESS_RD VM_MEM_ACCESS_WR VM_MEM_ACCESS_EXEC
CacheMode one of: This entry specifies the cache attributes of the memory requirement. De- VM_MEM_CACHE_CB pending on the hardware some options may not be supported or have no VM_MEM_CACHE_WT effect. VM_MEM_CACHE_INHIBIT VM_MEM_CACHE_CB Cached write-back memory access VM_MEM_CACHE_WC VM_MEM_CACHE_WT Cached write-through memory access VM_MEM_CACHE_DEV VM_MEM_CACHE_INHIBIT Uncached strongly-ordered memory access VM_MEM_CACHE_WC Uncached write-combining memory access VM_MEM_CACHE_DEV ARM memory type device or uncached memory ac- cess
IsPool boolean A memory requirement declared to be a pool serves as a container pro- cesses and applications can allocate memory from. If the memory pool is referenced in a process file entry, memory for application loading is allo- cated from the pool. Memory of a pool is assigned to a process on demand.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
260 The Virtual Machine Initialization Table
Name Type / Constraints Description ZeroCount stdUnsignedWordNoMinus Number of bytes to zero from the beginning of this memory requirement. This will only be considered if the memory is mapped at init time, i.e., not when this is marked as pool. This must be less than or equal to Size, and it must not be larger than one page (typically 4096). Synchronization among partitions would, theoretically, be possible with a single initialized byte in the SHM. The configuration item for the size exists so that users can initialize larger structures conveniently, like cache lines containing a spin lock. In order to keep boot time low, and because it would require a technically more advanced mechanism, the size of clearing memory is limited to 1 page, which should be more than enough for any synchronization structure to be cleared. Note that for memory requirements of type VM_MEM_TYPE_IO_PORT, the attribute ZeroCount will be ignored.
MemRegionPartition stdUnsignedInt Partition of the memory region pool defined in RBX. If this has the default value, the partition is the current one, unless MemRegionID is also the default value, in which case the partition will be assumed to be 0.
MemRegionID stdUnsignedInt ID of the memory region pool defined in RBX. If this has the default value, the partition number is assumed to be the default one, too. Then, the global pool is used (partition=0, id=0).
2.3.1.1 The Memory Type VM_MEM_TYPE_RAM
A memory requirement of type VM_MEM_TYPE_RAM describes a memory resource consisting of Size / P4_PAGESIZE System RAM pages that shall be allocated and assigned to the partition. The memory resource is further specified by the following attributes:
PhysicalAddress specifies the starting physical address of the memory resource. Normally, this attribute is set to -1, meaning that no special physical address is required for the memory resource. If an address is specified, it must be a multiple of P4_PAGESIZE and it must reference physical memory. In this case, the memory allocator tries to allocate a physically contiguous memory segment of size Size starting at the address given by the PhysicalAddress attribute. If this is not possible, a configuration error will be raised by the PSSW. If a physical address is specified, the attributes Alignment and Contiguous are ignored.
Alignment specifies the alignment requirement for the memory resource. If there is no special alignment require- ment for the memory resource, this attribute is set to -1, otherwise the specified value must be a power of two and greater than or equal to P4_PAGESIZE. In this case, the memory allocator tries to allocate a physically contiguous memory segment of size Size with the given alignment. If this is not possible, a configuration error will be raised by the PSSW. If an alignment requirement is specified, the attribute Contiguous is ignored.
Contiguous indicates whether the memory resource shall be composed of physically contiguous memory pages. If this is required, Contiguous is set to true, otherwise to false. If contiguous memory is required, the memory allocator tries to allocate a physically contiguous memory segment of size Size. If this is not possible, a configuration error will be raised by the PSSW.
2.3.1.2 The Memory Type VM_MEM_TYPE_ROM
A memory requirement of type VM_MEM_TYPE_ROM specifies an area within a ROM segment, starting at the physical address given by the PhysicalAddress attribute and with the size given by Size, which shall be accessible by the partition.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Partition Configuration 261
The memory resource can be readable and executable for the partition and caching can be enabled. For memory resources of type VM_MEM_TYPE_ROM, the PhysicalAddress attribute must be a multiple of P4_PAGESIZE and it must point to a ROM address (latter can not be enforced during configuration).
Note: A boot image loaded into RAM is also considered ROM.
For this type of memory requirement, the Alignment and Contiguous attributes are ignored. If necessary, ROM pages can be assigned to more than one partition.
2.3.1.3 The Memory Type VM_MEM_TYPE_IO_MEM
A memory requirement of type VM_MEM_TYPE_IO_MEM specifies an area of memory mapped I/O address space that shall be accessible by the partition. The PhysicalAddress attribute points to the start of the requested I/O memory area. It must be a multiple of P4_PAGESIZE. It depends on the underlying hardware whether all physical addresses within the specified range are accessible. Note: The attributes AccessMode and CacheMode are considered, but in most cases it is desirable to set the access to read/write/execute (VM_MEM_ACCESS_RD_WR_EXEC) and to switch off the cache (VM_MEM_CACHE_INHIBIT).
For this type of memory requirement, the Alignment and Contiguous attributes are ignored. If necessary, I/O memory pages can be assigned to more than one partition, but of course no virtual mapping can be established.
2.3.1.4 The Memory Type VM_MEM_TYPE_IO_PORT (x86 only)
A memory requirement of type VM_MEM_TYPE_IO_PORT specifies an area of consecutive I/O ports that shall be accessible by the partition. The PhysicalAddress attribute points to the start of the requested I/O port range. For this type of mem- ory requirement, the size can be given with byte-granularity. The Alignment, Contiguous, AccessMode, CacheMode and ZeroCount attributes are ignored. If necessary, I/O memory ports can be assigned to more than one partition.
2.3.1.5 The Memory Type VM_MEM_TYPE_KMEM
A memory requirement of type VM_MEM_TYPE_KMEM tells the PSSW how much memory (given in bytes) shall be allocated for the partition’s kernel resources. The value must be a multiple of P4_PAGESIZE. This value usually depends on the target architecture. Please refer to the UniversalisOS Platform Manual of your board to calculate the kernel memory needed for the partition. Only one VM_MEM_TYPE_KMEM can be specified per partition. The PhysicalAddress, Alignment and Contiguous attributes are ignored. It is a configuration error to specify a MemRegionPartition different from the partition id when MemRegionID is also specified.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
262 The Virtual Machine Initialization Table
2.3.2 The Queuing Port Configuration Element
The element configures a Partition Communication Port (PCP). The port configuration element has the following attributes:
Name Type / Constraints Description Name name, unique amongst all queuing This attribute specifies the name used to identify the queuing port. ports of a partition
Type VM_PORT_QUEUING
Direction one of: This attribute specifies the direction of the port, from the point of view of VM_PORT_DESTINATION the channel connected to the port. VM_PORT_SOURCE Note: From the application point of view, data is written to a source port and can be read from a destination port.
MaxMessageSize stdUnsignedIntNoMinus This attribute specifies the maximum size (in bytes) of a message that can be transferred through the port.
MaxMessageCount stdUnsignedIntNoMinus This attribute specifies the maximum number of messages that can be queued by the port.
2.3.3 The Sampling Port Configuration Element
The element configures a Partition Communication Port (PCP). The port configuration element has the following attributes:
Name Type / Constraints Description Name name, unique amongst all sampling This attribute specifies the name used to identify the sampling port. ports of a partition
Type VM_PORT_SAMPLING
Direction one of: This attribute specifies the direction of the port, from the point of view of VM_PORT_DESTINATION the channel connected to the port. VM_PORT_SOURCE Note: From the application point of view, data is written to a source port and can be read from a destination port.
MaxMessageSize stdUnsignedIntNoMinus This attribute specifies the maximum size (in bytes) of a message that can be transferred through the port.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Partition Configuration 263
2.3.4 The File Access Configuration Element
The element configures the access permission for one or a group of objects in the UniversalisOS file system. When a user application attempts to open a file from the UniversalisOS file system, the PSSW compares the path given by the open call with the list of file access entries. If a matching entry is found, the system software allows access of that object with the permissions given by the file access entry. If more than one match is found, resulting permissions are the union of the individual permissions. The wildcard "*" can be used to accept any string suffix. This can even enable entire directory trees. The asterisk is only allowed as the last character in the entry.
Name Type / Constraints Description FileName acl_path This attribute specifies the filename (including the entire path) which shall be accessible by an application of the partition.
AccessMode one or (space separated) combination This attribute specifies the access rights of the file to be opened. of: VM_O_RD: Allow reading, e.g. vm_read(), vm_qport_read(), VM_O_RD vm_sport_read(), etc. This flag can be used in access control lists, VM_O_WR gate and port permissions, and vm_open(). VM_O_EXEC VM_O_WR: Allow writing, e.g. vm_write(), vm_qport_write(), VM_O_MAP vm_sport_write(), etc. This flag can be used in access control lists, VM_O_MOUNT gate and port permissions, and vm_open(). VM_O_FSPROV VM_O_EXEC: Allow the file/device to be opened for code execution mode, VM_O_VOLPROV so that it can be mapped with execution permissions using vm_map(). This is a file access right and can be used in vm_open(). VM_O_MAP: Allow memory mapping (parts of the) device, e.g. using vm_map(). VM_O_MOUNT: Access right to mount a volume via vm_mount(). Af- terwards, vm_open() access is possible. If this flag is present, then vm_mount() is allowed, otherwise, vm_open() is allowed. VM_O_FSPROV: Access right to be used in the file access list of a partition to identify a partition as the file system provider for the given path (which must be a device prefix). VM_O_VOLPROV: Access right to be used in the file access list of a parti- tion to identify a partition as the volume provider for the given path (which must be a volume prefix).
2.3.5 The Process Configuration Element
The element configures one application process of the partition. The process configuration contains a set of scalar attributes and exactly one instance of the following elements:
MapTable The Map Table contains the information of how to setup the initial address space of the application process. It contains a list of elements which describe the mapping of one virtual contiguous address segment. A detailed description of the element can be found in section 2.3.5.1, page 264.
FileTable The File Table contains the information, which files have to be copied or mapped by the application loader into the address space of the application process. Currently only ELF-Files can be loaded by the application loader. A detailed description of the element can be found in section 2.3.5.2, page 264.
The following scalar attributes are defined for the element
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
264 The Virtual Machine Initialization Table
Name Type / Constraints Description Name name This attribute specifies the name of the process
MaxPrio priority [0 .. Partition::MaxPrio - 2] This attribute specifies the Maximum Controlled Priority (MCP) for the ap- plication process. This is also the initial priority at which the initial thread of the application starts running. The MCP must be less or equal to the MCP of the partition minus two.
MaxChildTaskCount stdUnsignedIntNoMinus [0 .. Parti- This attribute specifies the number of tasks to be donated to the process. tion::MaxChildTaskCount - 2] The tasks’ states are inactive at process startup.
MaxThreadCount unsignedInt [1..4095] This attribute specifies the maximum number of UniversalisOS threads to be cre- ated within this process. At runtime the threads up-to MaxThreadCount-1 can be created.
CmdLine string This attribute allows specification of a command line which can be read by the function vm_cmd_line() from the according process.
2.3.5.1 The Process Map Configuration Element
The element specifies one virtual contiguous memory segment in the address space of the application process. It references one of the partition’s memory requirement entries and tells the system software, where this memory object shall appear in address space of the process. If required, one memory requirement may be referenced by more than one Map from the same or another process of the same partition. This allows, for example, to access an I/O page which contains the registers of different hardware devices from more than one server I/O process. Virtual memory areas of processes within the same partition must not overlap. The following scalar attributes are defined for the element
Name Type / Constraints Description MemoryRequirementName name, must reference a memory re- This attribute specifies the memory object that shall be mapped. The mem- quirement of the partition ory requirement must be in the Memory Requirement Table of the parti- tion, memory objects of other partitions cannot be mapped. The mem- ory object must be of the type VM_MEM_TYPE_RAM, VM_MEM_TYPE_ROM, VM_MEM_TYPE_IO_MEM, VM_MEM_TYPE_IO_PORT. VirtualAddress stdUnsignedWordNoMinus This attribute specifies the virtual address of the mapping. The address must be a multiple of P4_PAGESIZE. If the memory object to be mapped has the type VM_MEM_TYPE_IO_PORT, the virtual address must be set to the same value as the according physical address entry in the memory requirement. A configuration error will be raised during system startup, if overlapping virtual mappings are created, or if the mapping does not fit into the user accessible virtual address space.
AccessMode one or (space separated) combination This attribute specifies the permitted memory access of the mapping. It of: must not exceed the permission of the referenced memory object. VM_MEM_ACCESS_RD VM_MEM_ACCESS_WR VM_MEM_ACCESS_EXEC
2.3.5.2 The Process File Configuration Element
The element specifies one file that shall be loaded or copied into the address space of the application process. The file is specified by its full path name. Currently only files conforming to the ELF Binary Format can be loaded by the UniversalisOS system software. ELF files contain one or more program headers, which describe where the different sections (text, read only data, writable data) have to be loaded. It also specifies the program entry point (if it is an executable file), the virtual address and the size of the uninitialized data segment (BSS segment). Writable segments are always copied into
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Partition Configuration 265
the address space of the application process. The BSS segment 1 is created in the address space of the process and initialized with zeroes. A macro is available (P4_DECLARE_STACK()) for an application to declare the stack size it requires. This information is then embedded in the ELF file, and set up by the PSSW loader. The stack itself is included in a dedicated .stack segment and surrounded by unmapped guard pages. Two attributes determine how programs are loaded:
• UsePool If this boolean flag of the process file entry to use for loading the file is set to true, memory
required for the various sections is allocated on the demand (in multiples of pages) from the according pool.
Else the memory area is used completely as configured for loading the application. If not all segments could
be loaded completely (either because the pool or the memory area was too small) a configuration error is
raised during initialization.
• ExecInPlace If this boolean flag of the process file entry is set to true, read only sections of the ELF
binary are mapped instead of being copied to RAM. For other sections the rules described above apply.
The following scalar attributes are defined for the element :
Name Type / Constraints Description FileName path This attribute specifies the name of the file to be copied into the address space of the application process.
HasEntryPoint boolean This attribute specifies whether the file has an entry point and should be specified only once for each process if multiple files are given.
ExecInPlace boolean The text segment of the executable file is mapped into the process address space instead of allocating RAM and copying the segment.
UsePool boolean Use pool memory for all ELF segments of a file to be loaded. (Usually these are at least data, bss and text and probably more depending on the architecture.)
PoolName name0 If UsePool is true, a memory requirement of the current partition must be referenced, having the attribute IsPool set to true. If UsePool is false, PoolName must be left blank.
1 In fact there can be more than one uninitialized data segment
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
266 The Virtual Machine Initialization Table
2.3.6 The Health Monitor Partition Configuration Element
HMTable
1
0..N
DefaultSwitch Domain
0..N
1 1
Default If
Switch
0..N
1 1
Then Default If
1
Then
Figure 3: The Partition Health Monitor Configuration Table
If an error is injected into the Health Monitor that is accountable to a specific partition (partition scope) and the responsible defined the error to be handled on partition level, then the action to be taken is determined by means of the element of the partition that caused the error. Depending on the error level defined in this table, the error may be forwarded to a process level error handler. The element contains exactly one element of which contains one element of , and an arbitrary number of elements where each of them contains exactly one element of . The element also contains an arbitrary number of elements where each of them contains exactly one element of (which contains the same elements as the ).
2.3.6.1 The Element "Default"
The element has the following scalar attributes:
Name Type / Constraints Description Level P4_hm_level_t, one of: This attribute defines at which error level the error recovery should take P4_HM_LEVEL_MODULE place. P4_HM_LEVEL_PARTITION P4_HM_LEVEL_USER • The error affects the partition and the action defined in Action will be executed.
• The error affects the process that caused it only and will be for-
warded to a process level error handler.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Partition Configuration 267
Name Type / Constraints Description Action P4_hm_pac_t, one of: The partition action defined here is only executed if the error level is set to P4_HM_PAC_IDLE P4_HM_LEVEL_PARTITION. P4_HM_PAC_COLD_START If P4_HM_PAC_IGNORE is specified, the error will be ignored and the af- P4_HM_PAC_WARM_START fected application continues its execution. P4_HM_PAC_IGNORE Note: In many error cases (e.g. memory violation) this action will cause the error to be raised unavoidably again.
If P4_HM_PAC_IDLE is specified, the partition will be halted.
If P4_HM_PAC_WARM_START is specified, the partition will be restarted in
the operating mode warm start.
If P4_HM_PAC_COLD_START is specified, the partition will be restarted in
the operating mode cold start.
Code unsignedInt Each partition can define what this means, the system just passes it through.
Notify unsignedInt Platform Specific Notification Action made available to drivers and PSP.
2.3.6.2 The Element "If"
See section 2.7.2, page 274.
2.3.6.3 The Element "Then"
Same attributes as , see section 2.3.6.1, page 266.
2.3.6.4 The Element "Domain"
See section 2.7.4, page 274.
2.3.6.5 The Element "Switch"
Same structure as , i.e. one element of , and an arbitrary number of elements where each of them contains exactly one element of .
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
268 The Virtual Machine Initialization Table
2.4 The Channel Configuration Element
.
ConnectionTable
1
PartitionChannelTable
0..N
Channel
1
SourcePortRef
1
DestinationPortRef
1
GateChannelTable
0..N
Channel
1
PartitionPortRef
1
ProviderPortRef
Figure 4: The Channel Table
The Partition Channel Table configures the connection between Partition Communication Ports (PCPs). The channel table contains a list of elements , which configures one Partition Communication Channel (PCC). A channel has two end-points, one Source PCP and one Destination PCP. A channel may be used to connect two application ports with each other (ramports). In this case, the source- and destination port may belong to the same or different partitions. In a Gate Channel Table a channel may connect an application port to a gate provider acting as a port provider. In this case, one end point must belong to a partition and the other one to a gate provider. The Source PCP is configured by the element and the Destination PCP by the element . One queuing port can only belong to one channel. One destination sampling port can only belong to one channel, while a source sampling port can be referenced in an arbitrary number of channels.
Note: This allows configuration of one source sampling port connected to many sampling destination ports
(broadcast).
Two PCPs can only be connected by a channel, if the following conditions are met:
• Both PCPs, referenced by the channel configuration, do exist.
• The port type (queuing- or sampling port type) must be the same for the source and destination port.
• The port attribute Direction of the port referenced by the element <SourcePortRef> is
VM_PORT_SOURCE.
• The port attribute Direction of the port referenced by the element <DestinationPortRef> is
VM_PORT_DESTINATION.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Channel Configuration Element 269
• The maximum message size of the Source PCP must be equal to the size of the Destination PCP.
• Only one endpoint can be connected to a gate provider.
Additional conditions for a channel, connecting queuing ports:
• None of the PCPs referenced by the channel configuration is already referenced by another channel.
• The maximum number of messages of the Source PCP must be equal to the maximum numbers of messages of the Destination PCP.
The number of messages which will be buffered by the channel is the maximum of the values given by the attribute MaxMessageCount of both PCPs. The element has the following scalar attributes:
Name Type / Constraints Description PortName name, must reference a valid Source This attribute specifies the Source PCP. PCP in the partition’s port list
PartitionID stdUnsignedIntNoMinus This attribute specifies the ID of the respective partition.
The element has the following scalar attributes:
Name Type / Constraints Description PortName name, must reference a valid Destina- This attribute specifies the Destination PCP. tion PCP in the partition’s port list
PartitionID stdUnsignedIntNoMinus This attribute specifies the ID of the respective partition.
The element has the following scalar attributes:
Name Type / Constraints Description PortName name The partition port.
PartitionID stdUnsignedIntNoMinus This attribute specifies the ID of the respective partition.
The element has the following scalar attributes:
Name Type / Constraints Description PortName name0 The gate provider gate name.
ProviderName name This attribute specifies the name (the provider prefix) of the respective gate provider.
In addition to the elements describing the end-points of the channel, a channel has the following scalar attributes:
Name Type / Constraints Description PortType one of: This attribute determines, whether the channel connects sampling or queu- VM_PORT_SAMPLING ing ports respectively. VM_PORT_QUEUING
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
270 The Virtual Machine Initialization Table
2.5 The Shared Memory Configuration
SharedMemoryTable
0..N
MemoryRequirement
Figure 5: The Shared Memory Table
The Shared Memory Table given by the element describes a list of memory objects which shall be shared between partitions. Each shared memory object is described by an element . The contents of this element is described in section 2.3.1, page 259. The only memory type which is not allowed for a shared memory object is the type VM_MEM_TYPE_KMEM. A shared memory object appears in the UniversalisOS Shared Memory File System as a file with the name specified in the attribute Name of the corresponding element , e.g. if the name attribute of a memory requirement is SHM_1, the shared memory object can be accessed by the name shm:/SHM_1. Each shared memory requirement in the Shared Memory Table must have a unique name attribute.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Time Partition Configuration Element 271
2.6 The Time Partition Configuration Element
ScheduleTable
0..N
ScheduleScheme
1..N
WindowTable
0..N
Window
Figure 6: The Time Partition Configuration Table
Time partitioning is configured by the element . The structure of this element is shown in figure 6. The Schedule Table can be empty if only time partition τ 0 is used. Otherwise, it contains one or more elements . Note that the Kernel’s tps_strong_sync property may impact the behavior of time partitioning. Please refer to the UniversalisOS User Manual and the UniversalisOS Kernel Reference Manual for more details. The element specifies one scheduling scheme for the time partition scheduler. Each scheduling scheme must have a unique name within the Schedule Table as attribute:
Name Type / Constraints Description Name name, must be unique within the This attribute specifies the name of the scheduling scheme. Schedule Table
SyncCpu stdUnsignedIntNoMinus This attribute specifies the CPU to which to synchronize for this scheduling scheme.
If a scheduling scheme with the name SCHED_BOOT exists, the time partition scheduler will be started by the sys- tem software and the time partitions will be scheduled as described by this scheme. The UniversalisOS system software API provides a function to start time scheduling and to switch to another time scheduling scheme. However, only applications in a partition with the ability VM_AB_TIMEPART_SETUP have the necessary permission. A scheduling scheme consists of at least one element . The Window Table contains a list of elements , each of them describing one scheduling window, and it has the following attribute:
Name Type / Constraints Description CpuMask stdUnsignedWord This attribute specifies the CPUs for which this window table is valid. This means that an application executing in a normal partition P in a window W is allowed to execute on a CPU core if a) that CPU core is configured to partition P, and b) if that CPU core is configured, explicitly or by default, to the window table that window W belongs to.
2.6.1 The Window Element
The element describes one scheduling entity for the time partition scheduler. A scheduling Window is defined by the offset from the start of the Major Time Frame, the duration of the window, and the Id of the time partition which shall be active during this window. The major time frame starts at offset zero and includes all scheduling Windows. Scheduling Windows must not overlap and no gaps between scheduling windows are allowed. To define gaps in the Major Time frame, the integrator must set the time partition ID to 0 so that only time partition τ 0 is active.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
272 The Virtual Machine Initialization Table
The values for the offset and the duration of the Window are given in ticks. A tick is the resolution of the timer source driving the time partition scheduler. This value depends on the hardware platform. On some platforms it is configurable by a UniversalisOS Kernel property.
Name Type / Constraints Description Identifier stdUnsignedIntNoMinus This attribute specifies a unique Id for the window.
Start stdUnsignedIntNoMinus This attribute specifies the start of the window relative to the start of the Major Time Frame. The value is given in ticks.
Duration stdUnsignedIntNoMinus This attribute specifies the duration of the window. The value is given in ticks.
SwitchOutDuration stdUnsignedIntNoMinus This attribute specifies the duration of the window’s switch out phase as the end of the window. The value is given in ticks.
TimePartitionID partID0 This attribute specifies the ID of the time partition which shall be active during this window.
Flags combination of: This attribute specifies options for the scheduling window. VM_SCF_PERIOD VM_SCF_PERIOD marks this window to be the beginning of a period. The VM_SCF_FLUSH_TLB PSSW uses this information to determine and verify the time partition peri- VM_SCF_INVAL_ICACHE ods and durations. VM_SCF_FLUSH_DCACHE VM_SCF_FLUSH_TLB instructs the time partition switcher to flush the MMU translation look-aside buffer when switching to this slice to improve execution determinism. VM_SCF_INVAL_ICACHE instructs the time partition switcher to flush the CPU instruction cache when switching to this slice to improve execution determinism. VM_SCF_FLUSH_DCACHE instructs the time partition switcher to flush the CPU data cache when switching to this slice to improve execution deter- minism.
UserData stdUnsignedShort This attribute is a generic integer that is passed to drivers upon the time partition switch. It may encode additional information that the system inte- grator and the driver implementors agreed on. This value is not interpreted in any way by UniversalisOS, but only passed on as is in notifications.
2.6.1.1 Time Partition Periods
Within the major time frame, any time partition can be periodic. Periodic partitions are executed just like aperiodic ones; however, in a period partition the application can use the p4_sleep() µkernel service to synchronize with the beginning of the next period, and the vm_part_stat() and vm_part_pstat() service calls return the time partition period and duration of the currently active time partition. A time partition period must meet the following constraints:
• the major time frame is an integer multiple of the time partition period
• all periods of this time partition within the major time frame have the same duration
Time partition periods are set using the VM_SCF_PERIOD flag. At boot time, the PSSW will analyze, determine and verify the time partition periods and durations. Upon an error, a configuration error is thrown and the system will be halted.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Health Monitor Multi Partition Configuration Element 273
2.7 The Health Monitor Multi Partition Configuration Element
MultiPartitionHMTable
1..N
Table
1 0..N
DefaultSwitch Domain
0..N
1 1
Default If Switch
0..N
1
1
Then Default If
1
Then
Figure 7: The Multi Partition Health Monitor Configuration Table
If an error is injected into the Health Monitor that is accountable to a specific partition (partition scope), then the action to be taken is determined first by means of the element that is referred to by the configuration of the partition that caused the error. Depending on the error level defined in the table, further tables may be consulted. The structure of this element is shown in figure 7. The element contains at least one element . The element
Name Type / Constraints Description Name name, must be unique within the ele- The name is only of descriptive nature and is not referenced at another ment . point in the configuration.
Identifier stdUnsignedIntNoMinus Unique identifier of the table. This identifier may be referenced by multiple partitions. The PSSW Health Monitor will query the respective table when determining error levels and actions for errors that are injected in the scope of those partitions. The value ’0’ for Identifier is reserved for an internal default table.
The element
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
274 The Virtual Machine Initialization Table
2.7.1 The Element "Default"
The element has the following scalar attributes:
Name Type / Constraints Description Level P4_hm_level_t, one of: This attribute defines at which error level the error recovery should take P4_HM_LEVEL_MODULE place. P4_HM_LEVEL_PARTITION P4_HM_LEVEL_USER • The error affects the whole module and the action defined in Ac- tion will be executed.
• The error affects the partition that caused it only and the PSSW
Health Monitor will consult the PartitionHMTable (See 2.3.6) of the
faulted partition for further error processing.
Action P4_hm_mac_t, one of: The module action defined here is only executed if the error level is set to P4_HM_MAC_IGNORE P4_HM_LEVEL_MODULE. P4_HM_MAC_SHUTDOWN P4_HM_MAC_POWEROFF P4_HM_MAC_RESET
Notify unsignedInt Platform Specific Notification Action made available to drivers and PSP.
2.7.2 The Element "If"
The element controls if the given action will be executed. It has the following scalar attributes:
Name Type / Constraints Description Type P4_hm_type_t, one of: The type of the Value attribute. P4_HM_TYPE_UINT P4_HM_TYPE_P4_E P4_HM_TYPE_TRAP P4_HM_TYPE_PERSONALITY
Value stdUnsignedInt If this value and its type match, the given action will be executed.
2.7.3 The Element "Then"
Same attributes as , see section 2.7.1, page 274.
2.7.4 The Element "Domain"
The element has the following scalar attributes:
Name Type / Constraints Description Identifier unsignedInt This matches if the domain is equal to the identifier.
2.7.5 The Element "Switch"
Same structure as , i.e. one element of , and an arbitrary number of elements where each of them contains exactly one element of .
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
The Health Monitor Module Configuration Element 275
2.8 The Health Monitor Module Configuration Element
ModuleHMTable
1
0..N
DefaultSwitch Domain
0..N
1 1
Default If
Switch
0..N
1 1
Then Default If
1
Then
Figure 8: The Module Health Monitor Configuration Table
If an error is injected into the Health Monitor that is not accountable to a specific partition (partition scope), then the action to be taken is determined by means of the element . All errors that are injected in module scope are handled on module level. The structure of this element is shown in figure 8. The element contains exactly one element of which contains one element of , and an arbitrary number of elements where each of them contains exactly one element of . The element also contains an arbitrary number of elements where each of them contains exactly one element of (which contains the same elements as the ).
2.8.1 The Element "Default"
The element has the following scalar attributes:
Name Type / Constraints Description Action P4_hm_mac_t, one of: The module action defined here is only executed if the error level is set to P4_HM_MAC_IGNORE P4_HM_LEVEL_MODULE. P4_HM_MAC_SHUTDOWN P4_HM_MAC_POWEROFF P4_HM_MAC_RESET
Notify unsignedInt Platform Specific Notification Action made available to drivers and PSP.
2.8.2 The Element "If"
See section 2.7.2, page 274.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
276 The Virtual Machine Initialization Table
2.8.3 The Element "Then"
Same attributes as , see section 2.8.1, page 275.
2.8.4 The Element "Domain"
See section 2.7.4, page 274.
2.8.5 The Element "Switch"
Same structure as , i.e. one element of , and an arbitrary number of elements where each of them contains exactly one element of .
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
System Extensions 277
2.9 System Extensions
SystemExtensionTable
1
FileProviderTable
0..N
FileProvider
1
GateProviderTable
0..N
GateProvider
1
GateTable
0..N
Gate
Figure 9: The System Extension Configuration
System extensions are configured using the element. The structure of this element is shown in figure 9. The element contains a sub element , which contains an arbitrary number of elements and a sub element , which contains an arbitrary number of elements . The has the following attributes:
Name Type / Constraints Description Name name, must be a unique file provider This attribute specifies the file provider name space prefix. It must be name. unique within the system. For file providers, this is the name that appears in the path prefix.
Driver name0, must be existing SE file driver This is mandatory in the global configuration to identify the driver in the (not known in VMIT) system. All drivers have a name by which they identify themselves in a UniversalisOS system. This attribute refers to that name. See the driver manual to find the driver name. Drivers can be used multiple times to create multiple providers using a single driver, if the driver supports this. In a partition local configuration, the Driver name is ignored and is thus declared optional in XML.
Version version This attribute specifies the version of the system extension. It is not evalu- ated by the UniversalisOS system software. In a partition local configuration, this is ignored and may be left unset.
DomainID stdUnsignedIntNoMinus This is the error domain this provider will generate. This Id can be matched in the HM tables.
The has the following attributes:
Name Type / Constraints Description Name name, must be a unique gate provider This attribute specifies the gate provider name space prefix. It must be name. unique within the system. When gates are accessed using the file API (e.g. vm_open()), this is the prefix the path will have.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
278 The Virtual Machine Initialization Table
Name Type / Constraints Description Driver name0, must be existing kernel driver This is mandatory in the global configuration to identify the driver in the (not known in VMIT). system. All drivers have a name by which they identify themselves in a UniversalisOS system. This attribute refers to that name. See the driver manual to find the driver name. Drivers can be used multiple times to create multiple providers using a single driver, if the driver supports this. In a partition local configuration, the Driver name is ignored and is thus declared optional in XML.
Version stdUnsignedIntNoMinus This version is passed to the driver for checking in the p4_kdev_init_prov() call. In a partition local configuration, this is ignored and may be left unset.
DomainID stdUnsignedIntNoMinus This is the error domain this provider will generate. This Id can be matched in the HM tables.
The has the following attributes:
Name Type / Constraints Description Name name0, must be unique per gate Name to be used by the PSSW for this gate. It is used e.g. for vm_open() provider. to select the right gate. Note that for port gates, the name used by the partition port is relevant. I.e., for ports, the PSSW does not use this name. The name is also used as a reference in the VMIT in the ProviderPortRef to identify this gate. Gate names must be unique per gate provider, but need not be unique in the system. The empty string is a valid gate name. In fact, it is a useful gate name for the root node of file systems driver that uses ’enter’ callbacks to implement the directory hierarchy.
Cookie stdUnsignedLong, must be unique per Identification for a driver to associate a gate with its configuration record. provider. Drivers have no idea about names, so the cookie is the identifier for them. If the value -1 is used, the cookie value is enumerated automatically by the system. This must be unique per provider, but needs not be unique in the system. Drivers have complete freedom of the usage of the valid value range, there is no interpretation of the cookie values. However, if in doubt, do not invent complex random names, but start at 0 (or 1 if you prefer), it’s easier that way.
AccessMode vm_file_access_mode Maximum access mode for this gate. This is used together with the file access permissions to restrict access in vm_open(). It is also used to restrict access in vm_qport_open() and vm_sport_open(). For channels, it will be checked that the access permissions agree with those of the ports defined in the partition. Additional to this, drivers may have special internal contraints on opening a gate, so this entry is a restriction to what a gate provider implementation allows.
Note: The order of system extensions and gate providers within the element does not imply any ordering on the initialisation of the providers at run time.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
3 Privileges
The UniversalisOS kernel manages the privileges of application processes at task level. The possible privileges of a task are divided into:
• Abilities
• Communication rights
• Interrupt attachment rights
A task can only grant to its child task those privileges that the task itself owns. The PSSW is the parent of all application tasks, and is granted at boot time by the UniversalisOS kernel full privileges. The PSSW configures application’s privileges according to the information specified in the configuration. Please refer to the UniversalisOS User Manual and to the UniversalisOS Kernel Reference Manual for further information. Child tasks created by applications cannot communicate with the PSSW, i.e., they cannot use any vm_...() function. A set of abilities can be individually assigned to Partitions in the configuration. Some abilities (VM_AB_TRACE, VM_AB_CACHE_CHANGE, and VM_AB_ULOCK_SHARED) are granted to a new Partition by default while others have to be explicitly set for a partition in the VMIT configuration. Granting non-default abilities may enable a partition to affect other partitions as well as the entire system. Partitions with non-default abilities normally have a higher trust level than other partitions. Partitions are called System Partitions when they are configured with at least one of the non-default abilities. The PSSW, being the parent of all user applications, statically installs the UniversalisOS kernel abilities of all application processes according to resource partition abilities defined in the VMIT configuration. The full set of abilities of the system is represented by the type P4_ability_mask_t (P4_AB_* abilities, see the UniversalisOS Kernel Reference Manual). The full set of P4_AB abilities is granted by the Kernel to the PSSW at boot time. VM_AB_* abilities (represented by the type vm_ability_t) are different from the P4_AB abilities in that they can be specified in the VMIT configuration. Table 31 summarizes the set of VM_AB abilities that have corresponding P4_AB abilities. Some VM_AB abilities are also reserved for privileged entities that operate at PSSW level. Specifically, the abilities:
• VM_AB_PSP_RESET
• VM_AB_PART_SET_MODE
• VM_AB_TIMEPART_SETUP
are not propagated to the kernel upon task creation, and will not therefore be available in application processes despite the possibility of configure them in the VMIT. In addition to abilities, the PSSW executes services requested by the applications, e.g. rebooting of another partition or opening of a file. In this case, the PSSW dynamically verifies the abilities defined in the VMIT configuration (see section 2, page 250).
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
280 Privileges
VM_AB Ability P4_AB Ability
VM_AB_TIMEPART_CHANGE P4_AB_TIMEPART_CHANGE
VM_AB_MONITOR P4_AB_MONITOR
VM_AB_PSP_CONSOLE P4_AB_PSP_CONSOLE
VM_AB_MEM_CREATE P4_AB_MEM_CREATE
VM_AB_HM_INJECT_OTHER P4_AB_HM_INJECT_OTHER
VM_AB_TRACE P4_AB_TRACE
VM_AB_CACHE_CHANGE P4_AB_CACHE_CHANGE
VM_AB_ULOCK_SHARED P4_AB_ULOCK_SHARED
Table 31: VM_AB Abilities and their P4_AB Counterparts
Communication rights between two processes are granted only when one process acts as file provider and the other one opens a file supplied by the provider. The communication rights are granted for both processes after a successful call to the vm_open() service. Per default, no user process has the right to attach to an interrupt or a kernel level device. Such rights have to be granted by means of adequate property nodes targeted by the Property File System Services vm_prop_int_grant() and vm_prop_dev_grant() respectively.
3.1 Individual Partition Abilities
Critical UniversalisOS kernel abilities are reserved for the PSSW task (and for System Extensions, which operate at the same privilege level as the PSSW). These abilities include the permission of e.g., setting up, disabling, enabling time partitioning, managing KMEM memory, or triggering critical HM errors. Therefore, only the abilities VM_AB_TIMEPART_CHANGE, VM_AB_MONITOR, VM_AB_PSP_CONSOLE, VM_AB_MEM_CREATE, VM_AB_HM_INJECT_OTHER, VM_AB_TRACE, VM_AB_CACHE_CHANGE, VM_AB_ULOCK_SHARED are propagated to application tasks upon application task creation. The following services offered by the PSSW are restricted or not available for processes running within partitions without additional abilities:
• vm_part_set_mode():
A partition can only set the operating mode of other partitions if it has the ability
VM_AB_PART_SET_MODE. All partitions are allowed to set their own operating mode regardless
of their abilities.
• vm_reboot():
A partition can only reboot other partitions if it has the ability VM_AB_PART_SET_MODE. All partitions are
allowed to reboot themselves regardless of their abilities.
• vm_shutdown():
A partition can only shutdown other partitions if it has the ability VM_AB_PART_SET_MODE. All partitions
are allowed to shutdown themselves regardless of their abilities.
• vm_part_pstat():
A partition can only retrieve the status of other partitions if has the ability VM_AB_MONITOR. All partitions
are allowed to retrieve their own status regardless of their abilities.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Individual Partition Abilities 281
• vm_part_stat():
A partition can only retrieve the status of other partitions if it has the ability VM_AB_MONITOR. All partitions
are allowed to retrieve their own status regardless of their abilities.
• vm_tsched_stat(), vm_tsched_change():
Not available for partitions without the ability VM_AB_TIMEPART_SETUP.
• vm_target_reset():
Not available for partitions without the ability VM_AB_PSP_RESET.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
4 PSSW Parameters
PSSW parameters are stored in the ROMImage in the property file system. The following parameters are defined.
Path Type Default p4/kernel/log_level uint32 3 Verbosity level of PSSW console output. Please see the list of valid verbosity levels below.
Level Description
0 Turn logging off
1 Show fatal errors only
2 Show any errors
3 Show errors and warnings (default)
4 Show errors, warnings, and verbose information
5 Show errors, warnings, verbose information, and debug messages
The log_level also controls the verbosity level of the default PSSW logger for Health-Monitoring events. Partition-level health-monitoring events are displayed when log_level ≥ 1. A log_level ≥ 4 allows printing on the PSSW console HM events of level P4_HM_LEVEL_USER. These events are normally managed by userspace exception/health-monitoring handlers and are therefore not displayed by default.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.