6. Filesystem Implementation Requirements¶

6.3.1. Mapping of Generic System Calls to Filesystem Specific Functions¶

The list of generic system calls includes the routines open(), read(), write(), close(), etc..

The Files and Directories section of the POSIX Application Programs Interface specifies a set of functions with calling arguments that are used to gain access to the information in a filesystem. To the application program, these functions allow access to information in any mounted filesystem without explicit knowledge of the filesystem type or the filesystem mount configuration. The following are functions that are provided to the application:

1. access()
2. chdir()
3. chmod()
4. chown()
5. close()
6. closedir()
7. fchmod()
8. fcntl()
9. fdatasync()
10. fpathconf()
11. fstat()
12. fsync()
13. ftruncate()
14. link()
15. lseek()
16. mkdir()
17. mknod()
18. mount()
19. open()
20. opendir()
21. pathconf()
22. read()
23. readdir()
24. rewinddir()
25. rmdir()
26. rmnod()
27. scandir()
28. seekdir()
29. stat()
30. telldir()
31. umask()
32. unlink()
33. unmount()
34. utime()
35. write()

The filesystem’s type as well as the node type within the filesystem determine the nature of the processing that must be performed for each of the functions above. The RTEMS filesystem provides a framework that allows new filesystem to be developed and integrated without alteration to the basic framework.

To provide the functional switching that is required, each of the POSIX file and directory functions have been implemented as a shell function. The shell function adheres to the POSIX interface standard. Within this functional shell, filesystem and node type information is accessed which is then used to invoke the appropriate filesystem and node type specific routine to process the POSIX function call.

6.3.2. File/Device/Directory function access via file control block - rtems_libio_t structure¶

The POSIX open() function returns an integer file descriptor that is used as a reference to file control block information for a specific file. The file control block contains information that is used to locate node, file system, mount table and functional handler information. The diagram in Figure 8 depicts the relationship between and among the following components.

File Descriptor Table:

This is an internal RTEMS structure that tracks all currently defined file descriptors in the system. The index that is returned by the file open() operation references a slot in this table. The slot contains a pointer to the file descriptor table entry for this file. The rtems_libio_t structure represents the file control block.

Allocation of entry in the File Descriptor Table:

Access to the file descriptor table is controlled through a semaphore that is implemented using the rtems_libio_allocate() function. This routine will grab a semaphore and then scan the file control blocks to determine which slot is free for use. The first free slot is marked as used and the index to this slot is returned as the file descriptor for the open() request. After the alterations have been made to the file control block table, the semaphore is released to allow further operations on the table.

Maximum number of entries in the file descriptor table is configurable through the src/exec/sapi/headers/confdefs.h file. If the CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS constant is defined its value will represent the maximum number of file descriptors that are allowed. If CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS is not specified a default value of 20 will be used as the maximum number of file descriptors allowed.

File control block - rtems_libio_t structure:

struct rtems_libio_tt {
    rtems_driver_name_t              *driver;
    off_t                             size;
    off_t                             offset;
    unsigned32                        flags;
    rtems_filesystem_location_info_t  pathinfo;
    Objects_Id                        sem;
    unsigned32                        data0;
    void                              data1;
    void                              file_info;
    rtems_filesystem_file_handlers_r  handlers;
};

A file control block can exist for regular files, devices and directories. The following fields are important for regular file and directory access:

• Size - For a file this represents the number of bytes currently stored in a file. For a directory this field is not filled in.
• Offset - For a file this is the byte file position index relative to the start of the file. For a directory this is the byte offset into a sequence of dirent structures.
• Pathinfo - This is a structure that provides a pointer to node information, OPS table functions, Handler functions and the mount table entry associated with this node.
• file_info - A pointer to node information that is used by Handler functions
• handlers - A pointer to a table of handler functions that operate on a file, device or directory through a file descriptor index

6.3.3. File/Directory function access via rtems_filesystem_location_info_t structure¶

The rtems_filesystem_location_info_tt structure below provides sufficient information to process nodes under a mounted filesystem.

struct rtems_filesystem_location_info_tt {
    void                                     *node_access;
    rtems_filesystem_file_handlers_r         *handlers;
    rtems_filesystem_operations_table        *ops;
    rtems_filesystem_mount_table_entry_t     *mt_entry;
};

It contains a void pointer to filesystem specific nodal structure, pointers to the OPS table for the filesystem that contains the node, the node type specific handlers for the node and a reference pointer to the mount table entry associated with the filesystem containing the node

6.4.1. Filesystem Handler Table Functions¶

OPS table functions are defined in a rtems_filesystem_operations_table structure. It defines functions that are specific to a given filesystem. One table exists for each filesystem that is supported in the RTEMS configuration. The structure definition appears below and is followed by general developmental information on each of the functions contained in this function management structure.

typedef struct {
    rtems_filesystem_evalpath_t        evalpath;
    rtems_filesystem_evalmake_t        evalformake;
    rtems_filesystem_link_t            link;
    rtems_filesystem_unlink_t          unlink;
    rtems_filesystem_node_type_t       node_type;
    rtems_filesystem_mknod_t           mknod;
    rtems_filesystem_rmnod_t           rmnod;
    rtems_filesystem_chown_t           chown;
    rtems_filesystem_freenode_t        freenod;
    rtems_filesystem_mount_t           mount;
    rtems_filesystem_fsmount_me_t      fsmount_me;
    rtems_filesystem_unmount_t         unmount;
    rtems_filesystem_fsunmount_me_t    fsunmount_me;
    rtems_filesystem_utime_t           utime;
    rtems_filesystem_evaluate_link_t   eval_link;
    rtems_filesystem_symlink_t         symlink;
} rtems_filesystem_operations_table;

6.4.2. File Handler Table Functions¶

Handler table functions are defined in a rtems_filesystem_file_handlers_r structure. It defines functions that are specific to a node type in a given filesystem. One table exists for each of the filesystem’s node types. The structure definition appears below. It is followed by general developmental information on each of the functions associated with regular files contained in this function management structure.

typedef struct {
    rtems_filesystem_open_t           open;
    rtems_filesystem_close_t          close;
    rtems_filesystem_read_t           read;
    rtems_filesystem_write_t          write;
    rtems_filesystem_ioctl_t          ioctl;
    rtems_filesystem_lseek_t          lseek;
    rtems_filesystem_fstat_t          fstat;
    rtems_filesystem_fchmod_t         fchmod;
    rtems_filesystem_ftruncate_t      ftruncate;
    rtems_filesystem_fpathconf_t      fpathconf;
    rtems_filesystem_fsync_t          fsync;
    rtems_filesystem_fdatasync_t      fdatasync;
    rtems_filesystem_fcntl_t          fcntl;
} rtems_filesystem_file_handlers_r;