[6408000] | 1 | @c |
---|
| 2 | @c COPYRIGHT (c) 1988-1998. |
---|
| 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
| 5 | @c |
---|
| 6 | @c $Id$ |
---|
| 7 | @c |
---|
| 8 | |
---|
| 9 | |
---|
| 10 | @chapter Applications and Functional Layering |
---|
| 11 | |
---|
| 12 | @section General |
---|
| 13 | |
---|
[0fa66f2a] | 14 | The RTEMS file system framework was intended to be compliant with the |
---|
| 15 | POSIX Files and Directories interface standard. The following file system |
---|
| 16 | characteristics resulted in a functional switching layer (See figures 6 |
---|
| 17 | and 7). |
---|
[6408000] | 18 | |
---|
| 19 | |
---|
| 20 | @example |
---|
| 21 | Figure 6 |
---|
| 22 | @end example |
---|
| 23 | |
---|
| 24 | @enumerate |
---|
| 25 | |
---|
[0fa66f2a] | 26 | @item Application programs are presented with a standard set of POSIX |
---|
| 27 | compliant functions that allow them to interface with the files, devices |
---|
| 28 | and directories in the file system. The interfaces to these routines do |
---|
| 29 | not reflect the type of subordinate file system implementation in which |
---|
| 30 | the file will be found. |
---|
[6408000] | 31 | |
---|
[0fa66f2a] | 32 | @item The file system framework developed under RTEMS allows for mounting |
---|
| 33 | file systems of different types under the base file system.( Figure 3 ) |
---|
[6408000] | 34 | |
---|
[0fa66f2a] | 35 | @item The mechanics of locating file information may be quite different |
---|
| 36 | between file system types. |
---|
[6408000] | 37 | |
---|
[0fa66f2a] | 38 | @item The process of locating a file may require crossing file system |
---|
| 39 | boundaries. |
---|
[6408000] | 40 | |
---|
[0fa66f2a] | 41 | @item The transitions between file systems and the processing required to |
---|
| 42 | access information in different file systems is not visible at the level |
---|
| 43 | of the POSIX function call. |
---|
[6408000] | 44 | |
---|
[0fa66f2a] | 45 | @item The POSIX interface standard provides file access by character |
---|
| 46 | pathname to the file in some functions and through an integer file |
---|
| 47 | descriptor (Figure 8) in other functions. |
---|
[6408000] | 48 | |
---|
[0fa66f2a] | 49 | @item The nature of the integer file descriptor and its associated |
---|
| 50 | processing is operating system and file system specific. |
---|
[6408000] | 51 | |
---|
[0fa66f2a] | 52 | @item Directory and device information must be processed with some of the |
---|
| 53 | same routines that apply to files. |
---|
[6408000] | 54 | |
---|
[0fa66f2a] | 55 | @item The form and content of directory and device information differs |
---|
| 56 | greatly from that of a regular file. |
---|
[6408000] | 57 | |
---|
[0fa66f2a] | 58 | @item Files, directories and devices represent elements (nodes) of a tree |
---|
| 59 | hierarchy. |
---|
[6408000] | 60 | |
---|
[0fa66f2a] | 61 | @item The rules for processing each of the node types that exist under the |
---|
| 62 | file system are node specific but are still not reflected in the POSIX |
---|
| 63 | interface routines. |
---|
[6408000] | 64 | |
---|
| 65 | @end enumerate |
---|
| 66 | |
---|
| 67 | |
---|
| 68 | @example |
---|
| 69 | Figure 7 |
---|
| 70 | @end example |
---|
| 71 | |
---|
| 72 | |
---|
| 73 | |
---|
| 74 | |
---|
| 75 | |
---|
| 76 | @example |
---|
| 77 | Figure 8 |
---|
| 78 | @end example |
---|
| 79 | |
---|
| 80 | |
---|
| 81 | |
---|
| 82 | |
---|
| 83 | |
---|
[0fa66f2a] | 84 | @section Mapping of Generic System Calls to File System Specific Functions |
---|
[6408000] | 85 | |
---|
| 86 | |
---|
[0fa66f2a] | 87 | The list of generic system calls includes the routines open(), read(), |
---|
| 88 | write(), close(), etc.. |
---|
[6408000] | 89 | |
---|
[0fa66f2a] | 90 | The Files and Directories section of the POSIX Application Programs |
---|
| 91 | Interface specifies a set of functions with calling arguments that are |
---|
| 92 | used to gain access to the information in a file system. To the |
---|
| 93 | application program, these functions allow access to information in any |
---|
| 94 | mounted file system without explicit knowledge of the file system type or |
---|
| 95 | the file system mount configuration. The following are functions that are |
---|
| 96 | provided to the application: |
---|
[6408000] | 97 | |
---|
| 98 | @enumerate |
---|
| 99 | @item access() |
---|
| 100 | @item chdir() |
---|
| 101 | @item chmod() |
---|
| 102 | @item chown() |
---|
| 103 | @item close() |
---|
| 104 | @item closedir() |
---|
| 105 | @item fchmod() |
---|
| 106 | @item fcntl() |
---|
| 107 | @item fdatasync() |
---|
| 108 | @item fpathconf() |
---|
| 109 | @item fstat() |
---|
| 110 | @item fsync() |
---|
| 111 | @item ftruncate() |
---|
| 112 | @item link() |
---|
| 113 | @item lseek() |
---|
| 114 | @item mkdir() |
---|
| 115 | @item mknod() |
---|
| 116 | @item mount() |
---|
| 117 | @item open() |
---|
| 118 | @item opendir() |
---|
| 119 | @item pathconf() |
---|
| 120 | @item read() |
---|
| 121 | @item readdir() |
---|
| 122 | @item rewinddir() |
---|
| 123 | @item rmdir() |
---|
| 124 | @item rmnod() |
---|
| 125 | @item scandir() |
---|
| 126 | @item seekdir() |
---|
| 127 | @item stat() |
---|
| 128 | @item telldir() |
---|
| 129 | @item umask() |
---|
| 130 | @item unlink() |
---|
| 131 | @item unmount() |
---|
| 132 | @item utime() |
---|
| 133 | @item write() |
---|
| 134 | @end enumerate |
---|
| 135 | |
---|
[0fa66f2a] | 136 | The file system's type as well as the node type within the file system |
---|
| 137 | determine the nature of the processing that must be performed for each of |
---|
| 138 | the functions above. The RTEMS file system provides a framework that |
---|
| 139 | allows new file systems to be developed and integrated without alteration |
---|
| 140 | to the basic framework. |
---|
| 141 | |
---|
| 142 | @subsection Use of function pointers for functional redirection |
---|
| 143 | |
---|
| 144 | To provide the functional switching that is required, each of the POSIX |
---|
| 145 | file and directory functions have been implemented as a shell function. |
---|
| 146 | The shell function adheres to the POSIX interface standard. Within this |
---|
| 147 | functional shell, file system and node type information is accessed which |
---|
| 148 | is then used to invoke the appropriate file system and node type specific |
---|
| 149 | routine to process the POSIX function call. |
---|
| 150 | |
---|
| 151 | @subsection File/Device/Directory function access via file control block - rtems_libio_t structure |
---|
| 152 | |
---|
| 153 | The POSIX open() function returns an integer file descriptor that is used |
---|
| 154 | as a reference to file control block information for a specific file. The |
---|
| 155 | file control block contains information that is used to locate node, file |
---|
| 156 | system, mount table and functional handler information. The diagram in |
---|
| 157 | Figure 8 depicts the relationship between and among the following |
---|
| 158 | components. |
---|
| 159 | |
---|
| 160 | @enumerate |
---|
| 161 | |
---|
| 162 | @item File Descriptor Table |
---|
| 163 | |
---|
| 164 | This is an internal RTEMS structure that tracks all currently defined file |
---|
| 165 | descriptors in the system. The index that is returned by the file open() |
---|
| 166 | operation references a slot in this table. The slot contains a pointer to |
---|
| 167 | the file descriptor table entry for this file. The rtems_libio_t structure |
---|
| 168 | represents the file control block. |
---|
| 169 | |
---|
| 170 | @item Allocation of entry in the File Descriptor Table |
---|
| 171 | |
---|
| 172 | Access to the file descriptor table is controlled through a semaphore that |
---|
| 173 | is implemented using the rtems_libio_allocate() function. This routine |
---|
| 174 | will grab a semaphore and then scan the file control blocks to determine |
---|
| 175 | which slot is free for use. The first free slot is marked as used and the |
---|
| 176 | index to this slot is returned as the file descriptor for the open() |
---|
| 177 | request. After the alterations have been made to the file control block |
---|
| 178 | table, the semaphore is released to allow further operations on the table. |
---|
| 179 | |
---|
| 180 | @item Maximum number of entries in the file descriptor table is |
---|
| 181 | configurable through the src/exec/sapi/headers/confdefs.h file. If the |
---|
| 182 | CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS constant is defined its value |
---|
| 183 | will represent the maximum number of file descriptors that are allowed. |
---|
| 184 | If CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS is not specified a default |
---|
| 185 | value of 20 will be used as the maximum number of file descriptors |
---|
| 186 | allowed. |
---|
| 187 | |
---|
| 188 | @item File control block - rtems_libio_t structure |
---|
| 189 | |
---|
| 190 | @example |
---|
[6408000] | 191 | struct rtems_libio_tt @{ |
---|
[0fa66f2a] | 192 | rtems_driver_name_t *driver; |
---|
| 193 | off_t size; /* size of file */ |
---|
| 194 | off_t offset; /* current offset into file */ |
---|
| 195 | unsigned32 flags; |
---|
| 196 | rtems_filesystem_location_info_t pathinfo; |
---|
| 197 | Objects_Id sem; |
---|
| 198 | unsigned32 data0; /* private to "driver" */ |
---|
| 199 | void data1; / . */ |
---|
| 200 | void file_info; /used by file handlers/ |
---|
| 201 | rtems_filesystem_file_handlers_r handlers; /type specific handlers/ |
---|
[6408000] | 202 | @}; |
---|
[0fa66f2a] | 203 | @end example |
---|
| 204 | |
---|
| 205 | A file control block can exist for regular files, devices and directories. |
---|
| 206 | The following fields are important for regular file and directory access: |
---|
[6408000] | 207 | |
---|
[0fa66f2a] | 208 | @itemize @bullet |
---|
| 209 | |
---|
| 210 | @item Size - For a file this represents the number of bytes currently |
---|
| 211 | stored in a file. For a directory this field is not filled in. |
---|
| 212 | |
---|
| 213 | @item Offset - For a file this is the byte file position index relative to |
---|
| 214 | the start of the file. For a directory this is the byte offset into a |
---|
| 215 | sequence of dirent structures. |
---|
| 216 | |
---|
| 217 | @item Pathinfo - This is a structure that provides a pointer to node |
---|
| 218 | information, OPS table functions, Handler functions and the mount table |
---|
| 219 | entry associated with this node. |
---|
| 220 | |
---|
| 221 | @item file_info - A pointer to node information that is used by Handler |
---|
[6408000] | 222 | functions |
---|
| 223 | |
---|
[0fa66f2a] | 224 | @item handlers - A pointer to a table of handler functions that operate on |
---|
| 225 | a file, device or directory through a file descriptor index |
---|
| 226 | |
---|
| 227 | @end itemize |
---|
| 228 | |
---|
| 229 | @end enumerate |
---|
| 230 | |
---|
| 231 | @subsection File/Directory function access via rtems_filesystem_location_info_t structure |
---|
[6408000] | 232 | |
---|
[0fa66f2a] | 233 | The rtems_filesystem_location_info_tt structure below provides sufficient |
---|
[6408000] | 234 | information to process nodes under a mounted file system. |
---|
| 235 | |
---|
[0fa66f2a] | 236 | @example |
---|
| 237 | struct rtems_filesystem_location_info_tt @{ |
---|
[6408000] | 238 | void *node_access; |
---|
| 239 | rtems_filesystem_file_handlers_r *handlers; |
---|
| 240 | rtems_filesystem_operations_table *ops; |
---|
| 241 | rtems_filesystem_mount_table_entry_t *mt_entry; |
---|
| 242 | @}; |
---|
[0fa66f2a] | 243 | @end example |
---|
| 244 | |
---|
| 245 | It contains a void pointer to file system specific nodal structure, |
---|
| 246 | pointers to the OPS table for the file system that contains the node, the |
---|
| 247 | node type specific handlers for the node and a reference pointer to the |
---|
| 248 | mount table entry associated with the file system containing the node |
---|
| 249 | |
---|
| 250 | @subsection File System Functional Interface to Files and Directories |
---|
| 251 | |
---|
| 252 | @itemize @bullet |
---|
| 253 | |
---|
| 254 | @item Access using relative or absolute path names to file |
---|
| 255 | |
---|
| 256 | @item OP Table for File System - rtems_filesystem_operations_table |
---|
| 257 | |
---|
| 258 | @enumerate |
---|
| 259 | @item evalpath() |
---|
| 260 | @item evalformake() |
---|
| 261 | @item link() |
---|
| 262 | @item unlink() |
---|
| 263 | @item node_type() |
---|
| 264 | @item mknod() |
---|
| 265 | @item rmnod() |
---|
| 266 | @item chown() |
---|
| 267 | @item freenod() |
---|
| 268 | @item mount() |
---|
| 269 | @item fsmount_me() |
---|
| 270 | @item unmount() |
---|
| 271 | @item fsunmount_me() |
---|
| 272 | @item utime() |
---|
| 273 | @item eval_link() |
---|
| 274 | @item symlink() |
---|
| 275 | @item readlink() |
---|
| 276 | @end enumerate |
---|
| 277 | |
---|
| 278 | @item Access using file handle |
---|
| 279 | |
---|
| 280 | @item Handlers for file system node types ( regular file, directories, and devices ) - rtems_filesystem_file_handlers_r |
---|
| 281 | |
---|
| 282 | @enumerate |
---|
| 283 | @item open() |
---|
| 284 | @item close() |
---|
| 285 | @item read() |
---|
| 286 | @item write() |
---|
| 287 | @item ioctl() |
---|
| 288 | @item lseek() |
---|
| 289 | @item fstat() |
---|
| 290 | @item fchmod() |
---|
| 291 | @item ftruncate() |
---|
| 292 | @item fpathconf() |
---|
| 293 | @item fsync() |
---|
| 294 | @item fdatasync() |
---|
| 295 | @end enumerate |
---|
| 296 | |
---|
| 297 | @end itemize |
---|
| 298 | |
---|
| 299 | @section POSIX Directory Access Functions |
---|
| 300 | |
---|
| 301 | BSD/newlib has provided a set of POSIX directory access routines. These |
---|
| 302 | routines allow directories to be open and the entries under the directory |
---|
| 303 | read. The getdents routine allows for customization of the BSD routines to |
---|
| 304 | a particular file system implementation. Some of the original BSD routines |
---|
| 305 | were modified, but maintain the same calling interface as the original |
---|
| 306 | BSD/newlib routine. The following directory access routines are included |
---|
| 307 | in the BSD set: |
---|
| 308 | |
---|
| 309 | @itemize @bullet |
---|
| 310 | @item opendir() |
---|
| 311 | @item closedir() |
---|
| 312 | @item readdir() |
---|
| 313 | @item getdents() |
---|
| 314 | @item closedir() |
---|
| 315 | @item rewinddir() (not BSD) |
---|
| 316 | @item scandir() (built on fstat() ) |
---|
| 317 | @item seekdir() (not BSD) |
---|
| 318 | @item telldir() |
---|
| 319 | @end itemize |
---|
[6408000] | 320 | |
---|
[0fa66f2a] | 321 | XXX Jennifer will fill this section in. |
---|
[6408000] | 322 | |
---|
| 323 | |
---|