Changeset 0fa66f2a in rtems

Timestamp:

10/08/99 18:11:31 (23 years ago)

Author:

Joel Sherrill <joel.sherrill@…>

Branches:

4.10, 4.11, 4.8, 4.9, 5, master

Children:

9bc1e52a

Parents:

6408000

Message:

Finished initial conversion to texinfo.

File:

• doc/filesystem/applayering.t (modified) (6 diffs)

doc/filesystem/applayering.t

@@ -1 +1 @@
 @c
-
 @c  COPYRIGHT (c) 1988-1998.
 @c  On-Line Applications Research Corporation (OAR).
@@ -13 +12 @@
 @section General
 
-The RTEMS file system framework was intended to be compliant with the POSIX 
-Files and Directories interface standard. The following file system characteristics 
-resulted in a functional switching layer (See figures 6 and 7).
+The RTEMS file system framework was intended to be compliant with the
+POSIX Files and Directories interface standard. The following file system
+characteristics resulted in a functional switching layer (See figures 6
+and 7).
 
 
@@ -24 +24 @@
 @enumerate
 
-@item Application programs are presented with a standard set of POSIX compliant 
-functions that allow them to interface with the files, devices and directories in the 
-file system. The interfaces to these routines do not reflect the type of subordinate 
-file system implementation in which the file will be found. 
-
-@item The file system framework developed under RTEMS allows for mounting file 
-systems of different types under the base file system.( Figure 3 ) 
-
-@item The mechanics of locating file information may be quite different between file 
-system types.
-
-@item The process of locating a file may require crossing file system boundaries. 
-
-@item The transitions between file systems and the processing required to access 
-information in different file systems is not visible at the level of the POSIX 
-function call.
-
-@item The POSIX interface standard provides file access by character pathname to the 
-file in some functions and through an integer file descriptor (Figure 8) in other 
-functions. 
-
-@item The nature of the integer file descriptor and its associated processing is operating 
-system and file system specific.
-
-@item Directory and device information must be processed with some of the same 
-routines that apply to files. 
-
-@item The form and content of directory and device information differs greatly from that 
-of a regular file. 
-
-@item Files, directories and devices represent elements (nodes) of a tree hierarchy. 
-
-@item The rules for processing each of the node types that exist under the file system are 
-node specific but are still not reflected in the POSIX interface routines.
+@item Application programs are presented with a standard set of POSIX
+compliant functions that allow them to interface with the files, devices
+and directories in the file system. The interfaces to these routines do
+not reflect the type of subordinate file system implementation in which
+the file will be found.
+
+@item The file system framework developed under RTEMS allows for mounting
+file systems of different types under the base file system.( Figure 3 )
+
+@item The mechanics of locating file information may be quite different
+between file system types.
+
+@item The process of locating a file may require crossing file system
+boundaries.
+
+@item The transitions between file systems and the processing required to
+access information in different file systems is not visible at the level
+of the POSIX function call.
+
+@item The POSIX interface standard provides file access by character
+pathname to the file in some functions and through an integer file
+descriptor (Figure 8) in other functions.
+
+@item The nature of the integer file descriptor and its associated
+processing is operating system and file system specific.
+
+@item Directory and device information must be processed with some of the
+same routines that apply to files.
+
+@item The form and content of directory and device information differs
+greatly from that of a regular file.
+
+@item Files, directories and devices represent elements (nodes) of a tree
+hierarchy.
+
+@item The rules for processing each of the node types that exist under the
+file system are node specific but are still not reflected in the POSIX
+interface routines.
 
 @end enumerate
@@ -78 +82 @@
 
 
-
-@section  Mapping of Generic System Calls to File System Specific OP Table or Handler Functions
-
-@subsection Generic routines (open (), read (), write (), close (), . )
-
-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 file system. To the application program, these functions allow access 
-to information in any mounted file system without explicit knowledge of the file 
-system type or the file system mount configuration. The following are functions that 
-are provided to the application:
+@section Mapping of Generic System Calls to File System 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 file system. To the
+application program, these functions allow access to information in any
+mounted file system without explicit knowledge of the file system type or
+the file system mount configuration. The following are functions that are
+provided to the application:
 
 @enumerate
@@ -128 +134 @@
 @end enumerate
 
-The file system's type as well as the node type within the file system determine the 
-nature of the processing that must be performed for each of the functions above. The 
-RTEMS file system provides a framework that allows new file systems to be 
-developed and integrated without alteration to the basic framework.  
-
-? Use of function pointers for functional redirection
-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, file system and 
-node type information is accessed which is then used to invoke the appropriate file 
-system and node type specific routine to process the POSIX function call. 
-
-? 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.
-
-1. 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.
-2. 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.
-3. 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.
-4. File control block - rtems_libio_t structure
+The file system's type as well as the node type within the file system
+determine the nature of the processing that must be performed for each of
+the functions above. The RTEMS file system provides a framework that
+allows new file systems to be developed and integrated without alteration
+to the basic framework.
+
+@subsection Use of function pointers for functional redirection
+
+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, file system and node type information is accessed which
+is then used to invoke the appropriate file system and node type specific
+routine to process the POSIX function call.
+
+@subsection 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.
+
+@enumerate
+
+@item 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.
+
+@item 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.
+
+@item 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.
+
+@item File control block - rtems_libio_t structure
+
+@example
 struct rtems_libio_tt @{
-    rtems_driver_name_t            *driver;
-    off_t                                   size;      /* size of file */
-    off_t                                   offset;    /* current offset into file */
-    unsigned32                            flags;
-    rtems_filesystem_location_info_t    pathinfo;
-    Objects_Id                            sem;
-    unsigned32                            data0;   /* private to "driver" */
-    void                                   data1;     / . */
-    void                                   file_info; /used by file handlers/
-    rtems_filesystem_file_handlers_r   handlers; /type specific handlers/
+  rtems_driver_name_t               *driver;
+  off_t                              size;      /* size of file */
+  off_t                              offset;    /* current offset into file */
+  unsigned32                         flags;
+  rtems_filesystem_location_info_t   pathinfo;
+  Objects_Id                         sem;
+  unsigned32                         data0;     /* private to "driver" */
+  void                               data1;     / . */
+  void                               file_info; /used by file handlers/
+  rtems_filesystem_file_handlers_r   handlers;  /type specific 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 
+@end example
+
+A file control block can exist for regular files, devices and directories.
+The following fields are important for regular file and directory access:
+
+@itemize @bullet
+
+@item Size - For a file this represents the number of bytes currently
+stored in a file. For a directory this field is not filled in.
+
+@item 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.
+
+@item 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.
+
+@item 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
-
-? File/Directory function access via rtems_filesystem_location_info_t structure
-
-The rtems_filesystem_location_info_tt structure below provides sufficient 
+
+@item handlers - A pointer to a table of handler functions that operate on
+a file, device or directory through a file descriptor index
+
+@end itemize
+
+@end enumerate
+
+@subsection 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 file system.
 
-struct rtems_filesystem_location_info_tt
-@{
+@example
+struct rtems_filesystem_location_info_tt @{
     void                                         *node_access;
     rtems_filesystem_file_handlers_r         *handlers;
@@ -210 +241 @@
     rtems_filesystem_mount_table_entry_t     *mt_entry;
 @};
-
-It contains a void pointer to file system specific nodal structure, pointers to the 
-OPS table for the file system that contains the node, the node type specific 
-handlers for the node and a reference pointer to the mount table entry associated 
-with the file system containing the node
-
-? File System Functional Interface to Files and Directories
-? Access using relative or absolute path names to file
-? OP Table for File System - rtems_filesystem_operations_table
-1. evalpath ()
-2. evalformake ()
-3. link ()
-4. unlink ()
-5. node_type ()
-6. mknod ()
-7. rmnod ()
-8. chown ()
-9. freenod ()
-10. mount ()
-11. fsmount_me ()
-12. unmount ()
-13. fsunmount_me ()
-14. utime ()
-15. eval_link ()
-16. symlink ()
-17. readlink ()
-
-? Access using file handle
-? Handlers for file system node types ( regular file, directories, and devices ) - 
-rtems_filesystem_file_handlers_r
-1. open ()
-2. close ()
-3. read ()
-4. write ()
-5. ioctl ()
-6. lseek ()
-7. fstat ()
-8. fchmod ()
-9. ftruncate ()
-10. fpathconf ()
-11. fsync ()
-12. fdatasync ()
-
-
-
-? POSIX Directory Access Functions
-
-BSD/newlib has provided a set of POSIX directory access routines. These routines 
-allow directories to be open and the entries under the directory read. The getdents 
-routine allows for customization of the BSD routines to a particular file system 
-implementation. Some of the original BSD routines were modified, but maintain the 
-same calling interface as the original BSD/newlib routine.
-The following directory access routines are included in the BSD set:
-
-? opendir ()closedir ()
-? readdir () 
-? getdents ()
-? closedir () 
-? ***   rewinddir ()
-? scandir () (built on fstat () )
-? ***   seekdir () 
-? telldir ()
-
-*** Not the original BSD stuff
-
-
-Jennifer will fill this section in.
-
-
+@end example
+
+It contains a void pointer to file system specific nodal structure,
+pointers to the OPS table for the file system that contains the node, the
+node type specific handlers for the node and a reference pointer to the
+mount table entry associated with the file system containing the node
+
+@subsection File System Functional Interface to Files and Directories
+
+@itemize @bullet
+
+@item Access using relative or absolute path names to file
+
+@item OP Table for File System - rtems_filesystem_operations_table
+
+@enumerate
+@item evalpath()
+@item evalformake()
+@item link()
+@item unlink()
+@item node_type()
+@item mknod()
+@item rmnod()
+@item chown()
+@item freenod()
+@item mount()
+@item fsmount_me()
+@item unmount()
+@item fsunmount_me()
+@item utime()
+@item eval_link()
+@item symlink()
+@item readlink()
+@end enumerate
+
+@item Access using file handle
+
+@item Handlers for file system node types ( regular file, directories, and devices ) - rtems_filesystem_file_handlers_r
+
+@enumerate
+@item open()
+@item close()
+@item read()
+@item write()
+@item ioctl()
+@item lseek()
+@item fstat()
+@item fchmod()
+@item ftruncate()
+@item fpathconf()
+@item fsync()
+@item fdatasync()
+@end enumerate
+
+@end itemize
+
+@section POSIX Directory Access Functions
+
+BSD/newlib has provided a set of POSIX directory access routines. These
+routines allow directories to be open and the entries under the directory
+read. The getdents routine allows for customization of the BSD routines to
+a particular file system implementation. Some of the original BSD routines
+were modified, but maintain the same calling interface as the original
+BSD/newlib routine. The following directory access routines are included
+in the BSD set:
+
+@itemize @bullet
+@item opendir()
+@item closedir()
+@item readdir() 
+@item getdents()
+@item closedir() 
+@item rewinddir() (not BSD)
+@item scandir() (built on fstat() )
+@item seekdir()  (not BSD)
+@item telldir()
+@end itemize
+
+XXX Jennifer will fill this section in.
+
+