Added applayering but did not finish it.

3 files changed, 288 insertions, 1 deletions

diff --git a/doc/filesystem/Makefile b/doc/filesystem/Makefile
index 79c4967f3a..c2dfb0ce3a 100644
--- a/doc/filesystem/Makefile
+++ b/doc/filesystem/Makefile
@@ -21,7 +21,7 @@ dirs:
 
 COMMON_FILES=../common/cpright.texi ../common/setup.texi
 
-GENERATED_FILES=basefs.texi
+GENERATED_FILES=basefs.texi applayering.texi
 
 FILES= $(PROJECT).texi \
   preface.texi $(GENERATED_FILES)
@@ -56,6 +56,11 @@ basefs.texi: basefs.t Makefile
 	   -u "Top" \
 	   -n "" ${*}.t
 
+applayering.texi: applayering.t Makefile
+	$(BMENU) -p "" \
+	   -u "Top" \
+	   -n "" ${*}.t
+
 html: dirs $(FILES)
 	-mkdir -p $(WWW_INSTALL)/$(PROJECT)
 	# rm -f $(WWW_INSTALL)/$(PROJECT)/networkflow.jpg
diff --git a/doc/filesystem/applayering.t b/doc/filesystem/applayering.t
new file mode 100644
index 0000000000..510eb8a048
--- /dev/null
+++ b/doc/filesystem/applayering.t
@@ -0,0 +1,280 @@
+@c
+
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+
+@chapter Applications and Functional Layering
+
+@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).
+
+
+@example
+Figure 6
+@end example
+
+@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.
+
+@end enumerate
+
+
+@example
+Figure 7
+@end example
+
+
+
+
+
+@example
+Figure 8
+@end example
+
+
+
+
+
+
+@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:
+
+@enumerate
+@item access()
+@item chdir()
+@item chmod()
+@item chown()
+@item close()
+@item closedir()
+@item fchmod()
+@item fcntl()
+@item fdatasync()
+@item fpathconf()
+@item fstat()
+@item fsync()
+@item ftruncate()
+@item link()
+@item lseek()
+@item mkdir()
+@item mknod()
+@item mount()
+@item open()
+@item opendir()
+@item pathconf()
+@item read()
+@item readdir()
+@item rewinddir()
+@item rmdir()
+@item rmnod()
+@item scandir()
+@item seekdir()
+@item stat()
+@item telldir()
+@item umask()
+@item unlink()
+@item unmount()
+@item utime()
+@item write()
+@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
+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/
+@};
+
+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
+
+? 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
+@{
+    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 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.
+
+
diff --git a/doc/filesystem/filesystem.texi b/doc/filesystem/filesystem.texi
index 05fd99d993..267789b714 100644
--- a/doc/filesystem/filesystem.texi
+++ b/doc/filesystem/filesystem.texi
@@ -64,6 +64,7 @@ END-INFO-DIR-ENTRY
 
 @include preface.texi
 @include basefs.texi
+@include applayering.texi
 @ifinfo
 @node Top, Preface, (dir), (dir)
 @top filesystem
@@ -73,6 +74,7 @@ This is the online version of the RTEMS Filesystem Design Guide.
 @menu
 * Preface::
 * Base File System::
+* Applications and Functional Layering::
 * Command and Variable Index::
 * Concept Index::
 @end menu