From 48a7fa31f918a6fc88719b3c9393a9ba2829f42a Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 15 Nov 2016 10:37:59 -0600 Subject: Remove texinfo format documentation. Replaced by Sphinx formatted documentation. closes #2812. --- doc/filesystem/Makefile.am | 65 -- doc/filesystem/filesystem.texi | 101 -- doc/filesystem/fsrequirements.t | 1180 ----------------------- doc/filesystem/imfs.t | 2035 --------------------------------------- doc/filesystem/init.t | 110 --- doc/filesystem/miniimfs.t | 13 - doc/filesystem/mounting.t | 168 ---- doc/filesystem/patheval.t | 106 -- doc/filesystem/preface.texi | 78 -- doc/filesystem/stamp-vti | 4 - doc/filesystem/syscalls.t | 1127 ---------------------- doc/filesystem/tftp.t | 11 - doc/filesystem/version.texi | 4 - 13 files changed, 5002 deletions(-) delete mode 100644 doc/filesystem/Makefile.am delete mode 100644 doc/filesystem/filesystem.texi delete mode 100644 doc/filesystem/fsrequirements.t delete mode 100644 doc/filesystem/imfs.t delete mode 100644 doc/filesystem/init.t delete mode 100644 doc/filesystem/miniimfs.t delete mode 100644 doc/filesystem/mounting.t delete mode 100644 doc/filesystem/patheval.t delete mode 100644 doc/filesystem/preface.texi delete mode 100644 doc/filesystem/stamp-vti delete mode 100644 doc/filesystem/syscalls.t delete mode 100644 doc/filesystem/tftp.t delete mode 100644 doc/filesystem/version.texi (limited to 'doc/filesystem') diff --git a/doc/filesystem/Makefile.am b/doc/filesystem/Makefile.am deleted file mode 100644 index cb7a60b232..0000000000 --- a/doc/filesystem/Makefile.am +++ /dev/null @@ -1,65 +0,0 @@ -# -# COPYRIGHT (c) 1988-2002. -# On-Line Applications Research Corporation (OAR). -# All rights reserved. - -PROJECT = filesystem - -include $(top_srcdir)/project.am -include $(top_srcdir)/main.am - -BMENU2 += -c - -GENERATED_FILES = patheval.texi init.texi mounting.texi syscalls.texi \ - fsrequirements.texi imfs.texi miniimfs.texi tftp.texi -COMMON_FILES += $(top_srcdir)/common/cpright.texi - -FILES = preface.texi - -info_TEXINFOS = filesystem.texi -filesystem_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES) - -patheval.texi: patheval.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -init.texi: init.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -mounting.texi: mounting.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -syscalls.texi: syscalls.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -fsrequirements.texi: fsrequirements.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -imfs.texi: imfs.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -miniimfs.texi: miniimfs.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -tftp.texi: tftp.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -EXTRA_DIST = fsrequirements.t imfs.t init.t miniimfs.t mounting.t patheval.t \ - syscalls.t tftp.t - -CLEANFILES += filesystem.info filesystem.info-? diff --git a/doc/filesystem/filesystem.texi b/doc/filesystem/filesystem.texi deleted file mode 100644 index fbc794b5f9..0000000000 --- a/doc/filesystem/filesystem.texi +++ /dev/null @@ -1,101 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename filesystem.info -@setcontentsaftertitlepage -@syncodeindex vr fn -@synindex ky cp -@paragraphindent 0 -@c %**end of header - -@c -@c COPYRIGHT (c) 1989-2013. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@c -@c Master file for the Filesystem Design Guide -@c - -@include version.texi -@include common/setup.texi -@include common/rtems.texi - -@ifset use-ascii -@dircategory RTEMS On-Line Manual -@direntry -* RTEMS Filesystem Design Guide: (filesystem). -@end direntry -@end ifset - -@c -@c Title Page Stuff -@c - -@c -@c I don't really like having a short title page. --joel -@c -@c @shorttitlepage RTEMS Filesystem Design Guide - -@setchapternewpage odd -@settitle RTEMS Filesystem Design Guide -@titlepage -@finalout - -@title RTEMS Filesystem Design Guide -@subtitle Edition @value{EDITION}, for RTEMS @value{VERSION} -@sp 1 -@subtitle @value{UPDATED} -@author On-Line Applications Research Corporation -@page -@include common/cpright.texi -@end titlepage - -@c This prevents a black box from being printed on "overflow" lines. -@c The alternative is to rework a sentence to avoid this problem. - -@contents - -@ifnottex -@node Top, Preface, (dir), (dir) -@top RTEMS Filesystem Design Guide - -@menu -* Preface:: -* Pathname Evaluation:: -* System Initialization:: -* Mounting and Unmounting Filesystems:: -* System Call Development Notes:: -* Filesystem Implementation Requirements:: -* In-Memory Filesystem:: -* Miniature In-Memory Filesystem:: -* Trivial FTP Client Filesystem:: -* Command and Variable Index:: -* Concept Index:: -@end menu -@end ifnottex - -@include preface.texi -@include patheval.texi -@include init.texi -@include mounting.texi -@include syscalls.texi -@include fsrequirements.texi -@include imfs.texi -@include miniimfs.texi -@include tftp.texi - -@node Command and Variable Index, Concept Index, , Top -@unnumbered Command and Variable Index - -There are currently no Command and Variable Index entries. - -@c @printindex fn - -@node Concept Index, , Command and Variable Index, Top -@unnumbered Concept Index - -There are currently no Concept Index entries. -@c @printindex cp - -@bye - diff --git a/doc/filesystem/fsrequirements.t b/doc/filesystem/fsrequirements.t deleted file mode 100644 index efc17112ec..0000000000 --- a/doc/filesystem/fsrequirements.t +++ /dev/null @@ -1,1180 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - - -@chapter Filesystem Implementation Requirements - -This chapter details the behavioral requirements that all filesystem -implementations must adhere to. - -@section General - -The RTEMS filesystem framework was intended to be compliant with the -POSIX Files and Directories interface standard. The following filesystem -characteristics resulted in a functional switching layer. - -@example -Figure of the Filesystem Functional Layering goes here. -This figure includes networking and disk caching layering. -@end example - -@ifset use-ascii -@example -@group -@end group -@end example -@end ifset - -@ifset use-tex -@c @image{FunctionalLayerCake,6in,4in} -@end ifset - -@ifset use-html -@end ifset - -@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 filesystem. The interfaces to these routines do -not reflect the type of subordinate filesystem implementation in which -the file will be found. - -@item The filesystem framework developed under RTEMS allows for mounting -filesystem of different types under the base filesystem. - -@item The mechanics of locating file information may be quite different -between filesystem types. - -@item The process of locating a file may require crossing filesystem -boundaries. - -@item The transitions between filesystem and the processing required to -access information in different filesystem 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 in other functions. - -@item The nature of the integer file descriptor and its associated -processing is operating system and filesystem 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 -filesystem are node specific but are still not reflected in the POSIX -interface routines. - -@end enumerate - - -@example -Figure of the Filesystem Functional Layering goes here. -This figure focuses on the Base Filesystem and IMFS. -@end example - -@example -Figure of the IMFS Memfile control blocks -@end example - -@section File and Directory Removal Constraints - -The following POSIX constraints must be honored by all filesystems. - -@itemize @bullet - -@item If a node is a directory with children it cannot be removed. - -@item The root node of any filesystem, whether the base filesystem or a -mounted filesystem, cannot be removed. - -@item A node that is a directory that is acting as the mount point of a file -system cannot be removed. - -@item On filesystems supporting hard links, a link count is maintained. -Prior to node removal, the node's link count is decremented by one. The -link count must be less than one to allow for removal of the node. - -@end itemize - -@c -@c -@c -@section API Layering - -@subsection 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: - -@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 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. - -@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; - 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; -@}; -@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 - -@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 filesystem. - -@example -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; -@}; -@end example - -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 - -@section Operation Tables - -Filesystem specific operations are invoked indirectly. The set of -routines that implement the filesystem are configured into two tables. -The Filesystem Handler Table has routines that are specific to a -filesystem but remain constant regardless of the actual file type. -The File Handler Table has routines that are both filesystem and file type -specific. - -@subsection Filesystem Handler Table Functions - -OPS table functions are defined in a @code{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. - -@example -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; -@end example - -@c -@c -@c -@c @page - -@subsubsection evalpath Handler - -@subheading Corresponding Structure Element: - -evalpath - -@subheading Arguments: - -@example - const char *pathname, /* IN */ - int flags, /* IN */ - rtems_filesystem_location_info_t *pathloc /* IN/OUT */ -@end example - -@subheading Description: - -This routine is responsible for evaluating the pathname passed in -based upon the flags and the valid @code{rthems_filesystem_location_info_t}. -Additionally, it must make any changes to pathloc necessary to identify -the pathname node. This should include calling the evalpath for a mounted -filesystem, if the given filesystem supports the mount command. - -This routine returns a 0 if the evaluation was successful. -Otherwise, it returns a -1 and sets errno to the correct error. - -This routine is required and should NOT be set to NULL. - -@c -@c -@c -@c @page - -@subsubsection evalformake Handler - -@subheading Corresponding Structure Element: - -evalformake - -@subheading Arguments: - -@example - const char *path, /* IN */ - rtems_filesystem_location_info_t *pathloc, /* IN/OUT */ - const char **name /* OUT */ -@end example - -@subheading Description: - -This method is given a path to evaluate and a valid start location. It -is responsible for finding the parent node for a requested make command, -setting pathloc information to identify the parent node, and setting -the name pointer to the first character of the name of the new node. -Additionally, if the filesystem supports the mount command, this method -should call the evalformake routine for the mounted filesystem. - -This routine returns a 0 if the evaluation was successful. Otherwise, it -returns a -1 and sets errno to the correct error. - -This routine is required and should NOT be set to NULL. However, if -the filesystem does not support user creation of a new node, it may -set errno to ENOSYS and return -1. - -@c -@c -@c -@c @page - -@subsubsection link Handler - -@subheading Corresponding Structure Element: - -link - -@subheading Arguments: - - -@example -rtems_filesystem_location_info_t *to_loc, /* IN */ -rtems_filesystem_location_info_t *parent_loc, /* IN */ -const char *token /* IN */ -@end example - -@subheading Description: - - -This routine is used to create a hard-link. - -It will first examine the st_nlink count of the node that we are trying to. -If the link count exceeds LINK_MAX an error will be returned. - -The name of the link will be normalized to remove extraneous separators from -the end of the name. - -This routine is not required and may be set to NULL. - -@c -@c -@c -@c @page - -@subsubsection unlink Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading Description: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection node_type Handler - -@subheading Corresponding Structure Element: - -node_type() - -@subheading Arguments: - -@example -rtems_filesystem_location_info_t *pathloc /* IN */ -@end example - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection mknod Handler - -@subheading Corresponding Structure Element: - -mknod() - -@subheading Arguments: - -@example -const char *token, /* IN */ -mode_t mode, /* IN */ -dev_t dev, /* IN */ -rtems_filesystem_location_info_t *pathloc /* IN/OUT */ -@end example - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection rmnod Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading Description: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection chown Handler - -@subheading Corresponding Structure Element: - -chown() - -@subheading Arguments: - -@example -rtems_filesystem_location_info_t *pathloc /* IN */ -uid_t owner /* IN */ -gid_t group /* IN */ -@end example - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection freenod Handler - -@subheading Corresponding Structure Element: - -freenod() - -@subheading Arguments: - -@example -rtems_filesystem_location_info_t *pathloc /* IN */ -@end example - -@subheading Description: - -This routine is used by the generic code to allow memory to be allocated -during the evaluate routines, and set free when the generic code is finished -accessing a node. If the evaluate routines allocate memory to identify -a node this routine should be utilized to free that memory. - -This routine is not required and may be set to NULL. - -@c -@c -@c -@c @page - -@subsubsection mount Handler - -@subheading Corresponding Structure Element: - -mount() - -@subheading Arguments: - -@example -rtems_filesystem_mount_table_entry_t *mt_entry -@end example - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection fsmount_me Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -@example -rtems_filesystem_mount_table_entry_t *mt_entry -@end example - -@subheading Description: - -This function is provided with a filesystem to take care of the internal -filesystem management details associated with mounting that filesystem -under the RTEMS environment. - -It is not responsible for the mounting details associated the filesystem -containing the mount point. - -The rtems_filesystem_mount_table_entry_t structure contains the key elements -below: - -rtems_filesystem_location_info_t *mt_point_node, - -This structure contains information about the mount point. This -allows us to find the ops-table and the handling functions -associated with the filesystem containing the mount point. - -rtems_filesystem_location_info_t *fs_root_node, - -This structure contains information about the root node in the file -system to be mounted. It allows us to find the ops-table and the -handling functions associated with the filesystem to be mounted. - -rtems_filesystem_options_t options, - -Read only or read/write access - -void *fs_info, - -This points to an allocated block of memory the will be used to -hold any filesystem specific information of a global nature. This -allocated region if important because it allows us to mount the -same filesystem type more than once under the RTEMS system. -Each instance of the mounted filesystem has its own set of global -management information that is separate from the global -management information associated with the other instances of the -mounted filesystem type. - -rtems_filesystem_limits_and_options_t pathconf_info, - -The table contains the following set of values associated with the -mounted filesystem: - -@itemize @bullet - -@item link_max - -@item max_canon - -@item max_input - -@item name_max - -@item path_max - -@item pipe_buf - -@item posix_async_io - -@item posix_chown_restrictions - -@item posix_no_trunc - -@item posix_prio_io - -@item posix_sync_io - -@item posix_vdisable - -@end itemize - -These values are accessed with the pathconf() and the fpathconf () -functions. - -const char *dev - -The is intended to contain a string that identifies the device that contains -the filesystem information. The filesystems that are currently implemented -are memory based and don't require a device specification. - -If the mt_point_node.node_access is NULL then we are mounting the base file -system. - -The routine will create a directory node for the root of the IMFS file -system. - -The node will have read, write and execute permissions for owner, group and -others. - -The node's name will be a null string. - -A filesystem information structure(fs_info) will be allocated and -initialized for the IMFS filesystem. The fs_info pointer in the mount table -entry will be set to point the filesystem information structure. - -The pathconf_info element of the mount table will be set to the appropriate -table of path configuration constants (LIMITS_AND_OPTIONS). - -The fs_root_node structure will be filled in with the following: - -@itemize @bullet - -@item pointer to the allocated root node of the filesystem - -@item directory handlers for a directory node under the IMFS filesystem - -@item OPS table functions for the IMFS - -@end itemize - -A 0 will be returned to the calling routine if the process succeeded, -otherwise a 1 will be returned. - - -@c -@c -@c -@c @page - -@subsubsection unmount Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading Description: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection fsunmount_me Handler - -@subheading Corresponding Structure Element: - -imfs_fsunmount_me() - -@subheading Arguments: - -@example -rtems_filesystem_mount_table_entry_t *mt_entry -@end example - -@subheading Description: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection utime Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection eval_link Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection symlink Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading Description: - -XXX - -@c -@c -@c -@c @page -@subsection File Handler Table Functions - -Handler table functions are defined in a @code{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. - -@example -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; -@end example - -@c -@c -@c -@c @page - -@subsubsection open Handler - -@subheading Corresponding Structure Element: - -open() - -@subheading Arguments: - -@example -rtems_libio_t *iop, -const char *pathname, -unsigned32 flag, -unsigned32 mode -@end example - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection close Handler - -@subheading Corresponding Structure Element: - -close() - -@subheading Arguments: - -@example -rtems_libio_t *iop -@end example - -@subheading Description: - -XXX - -@subheading NOTES: - -XXX - - - -@c -@c -@c -@c @page - -@subsubsection read Handler - -@subheading Corresponding Structure Element: - -read() - -@subheading Arguments: - -@example -rtems_libio_t *iop, -void *buffer, -unsigned32 count -@end example - -@subheading Description: - -XXX - -@subheading NOTES: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection write Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX -@subheading Description: - -XXX - -@subheading NOTES: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection ioctl Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -@example -rtems_libio_t *iop, -unsigned32 command, -void *buffer -@end example - -@subheading Description: - -XXX - -@subheading NOTES: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection lseek Handler - -@subheading Corresponding Structure Element: - -lseek() - -@subheading Arguments: - -@example -rtems_libio_t *iop, -off_t offset, -int whence -@end example - -@subheading Description: - -XXX - -@subheading NOTES: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection fstat Handler - -@subheading Corresponding Structure Element: - -fstat() - -@subheading Arguments: - -@example -rtems_filesystem_location_info_t *loc, -struct stat *buf -@end example - -@subheading Description: - -The following information is extracted from the filesystem -specific node and placed in the @code{stat} structure: - -@itemize @bullet - -@item st_mode - -@item st_nlink - -@item st_ino - -@item st_uid - -@item st_gid - -@item st_atime - -@item st_mtime - -@item st_ctime - -@end itemize - - -@subheading NOTES: - -Both the @code{stat()} and @code{lstat()} services are -implemented directly using the @code{fstat()} handler. The -difference in behavior is determined by how the path is evaluated -prior to this handler being called on a particular -file entity. - -The @code{fstat()} system call is implemented directly -on top of this filesystem handler. - -@c -@c -@c -@c @page - -@subsubsection fchmod Handler - -@subheading Corresponding Structure Element: - -fchmod() - -@subheading Arguments: - -@example -rtems_libio_t *iop -mode_t mode -@end example - -@subheading Description: - -XXX - - -@subheading NOTES: - -XXX - -@c -@c -@c -@c @page - -@subsubsection ftruncate Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX -@subheading Description: - -XXX - -@subheading NOTES: - -XXX - -@subsubsection fpathconf Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading Description: - -XXX - -@subheading NOTES: - -XXX - -@c -@c -@c -@c @page - -@subsubsection fsync Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX -@subheading Description: - -XXX - -@subheading NOTES: - -XXX - -@c -@c -@c -@c @page - -@subsubsection fdatasync Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading Description: - -XXX - -@subheading NOTES: - -XXX - -@c -@c -@c -@c @page - -@subsubsection fcntl Handler - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading Description: - -XXX - -@subheading NOTES: - -XXX diff --git a/doc/filesystem/imfs.t b/doc/filesystem/imfs.t deleted file mode 100644 index 2f7beb7722..0000000000 --- a/doc/filesystem/imfs.t +++ /dev/null @@ -1,2035 +0,0 @@ -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter In-Memory Filesystem - -This chapter describes the In-Memory FileSystem (IMFS). The IMFS is a -full featured POSIX filesystem that keeps all information in memory. - -@section IMFS Per Node Data Structure - -Each regular file, device, hard link, and directory is represented by a data -structure called a @code{jnode}. The @code{jnode} is formally represented by the -structure: - -@example -struct IMFS_jnode_tt @{ - Chain_Node Node; /* for chaining them together */ - IMFS_jnode_t *Parent; /* Parent node */ - char name[NAME_MAX+1]; /* "basename" */ - mode_t st_mode; /* File mode */ - nlink_t st_nlink; /* Link count */ - ino_t st_ino; /* inode */ - - uid_t st_uid; /* User ID of owner */ - gid_t st_gid; /* Group ID of owner */ - time_t st_atime; /* Time of last access */ - time_t st_mtime; /* Time of last modification */ - time_t st_ctime; /* Time of last status change */ - IMFS_jnode_types_t type; /* Type of this entry */ - IMFS_typs_union info; -@}; -@end example - -The key elements of this structure are listed below together with a brief -explanation of their role in the filesystem. - -@table @b - -@item Node -exists to allow the entire @code{jnode} structure to be included in a chain. - -@item Parent -is a pointer to another @code{jnode} structure that is the logical parent of the -node in which it appears. This field may be NULL if the file associated with -this node is deleted but there are open file descriptors on this file or -there are still hard links to this node. - -@item name -is the name of this node within the filesystem hierarchical tree. Example: If -the fully qualified pathname to the @code{jnode} was @code{/a/b/c}, the -@code{jnode} name field would contain the null terminated string @code{"c"}. - -@item st_mode -is the standard Unix access permissions for the file or directory. - -@item st_nlink -is the number of hard links to this file. When a @code{jnode} is first created -its link count is set to 1. A @code{jnode} and its associated resources -cannot be deleted unless its link count is less than 1. - -@item st_ino -is a unique node identification number - -@item st_uid -is the user ID of the file's owner - -@item st_gid -is the group ID of the file's owner - -@item st_atime -is the time of the last access to this file - -@item st_mtime -is the time of the last modification of this file - -@item st_ctime -is the time of the last status change to the file - -@item type -is the indication of node type must be one of the following states: - -@itemize @bullet -@item IMFS_DIRECTORY -@item IMFS_MEMORY_FILE -@item IMFS_HARD_LINK -@item IMFS_SYM_LINK -@item IMFS_DEVICE -@end itemize - - -@item info -is this contains a structure that is unique to file type (See IMFS_typs_union -in imfs.h). - -@itemize @bullet - -@item IMFS_DIRECTORY - -An IMFS directory contains a dynamic chain structure that -records all files and directories that are subordinate to the directory node. - -@item IMFS_MEMORY_FILE - -Under the in memory filesystem regular files hold data. Data is dynamically -allocated to the file in 128 byte chunks of memory. The individual chunks of -memory are tracked by arrays of pointers that record the address of the -allocated chunk of memory. Single, double, and triple indirection pointers -are used to record the locations of all segments of the file. The -memory organization of an IMFS file are discussed elsewhere in this manual. - -@item IMFS_HARD_LINK - -The IMFS filesystem supports the concept of hard links to other nodes in the -IMFS filesystem. These hard links are actual pointers to other nodes in the -same filesystem. This type of link cannot cross-filesystem boundaries. - -@item IMFS_SYM_LINK - -The IMFS filesystem supports the concept of symbolic links to other nodes in -any filesystem. A symbolic link consists of a pointer to a character string -that represents the pathname to the target node. This type of link can -cross-filesystem boundaries. Just as with most versions of UNIX supporting -symbolic links, a symbolic link can point to a non-existent file. - -@item IMFS_DEVICE - -All RTEMS devices now appear as files under the in memory filesystem. On -system initialization, all devices are registered as nodes under the file -system. - -@end itemize - -@end table - -@section Miscellaneous IMFS Information - -@section Memory associated with the IMFS - -A memory based filesystem draws its resources for files and directories -from the memory resources of the system. When it is time to un-mount the -filesystem, the memory resources that supported filesystem are set free. -In order to free these resources, a recursive walk of the filesystems -tree structure will be performed. As the leaf nodes under the filesystem -are encountered their resources are freed. When directories are made empty -by this process, their resources are freed. - -@subsection Node removal constraints for the IMFS - -The IMFS conforms to the general filesystem requirements for node -removal. See @ref{File and Directory Removal Constraints}. - -@subsection IMFS General Housekeeping Notes - -The following is a list of odd housekeeping notes for the IMFS. - -@itemize @bullet - -@item If the global variable rtems_filesystem_current refers to the node that -we are trying to remove, the node_access element of this structure must be -set to NULL to invalidate it. - -@item If the node was of IMFS_MEMORY_FILE type, free the memory associated -with the memory file before freeing the node. Use the IMFS_memfile_remove() -function. - -@end itemize - -@section IMFS Operation Tables - -@subsection IMFS 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. - -@example -rtems_filesystem_operations_table IMFS_ops = @{ - IMFS_eval_path, - IMFS_evaluate_for_make, - IMFS_link, - IMFS_unlink, - IMFS_node_type, - IMFS_mknod, - IMFS_rmnod, - IMFS_chown, - IMFS_freenodinfo, - IMFS_mount, - IMFS_initialize, - IMFS_unmount, - IMFS_fsunmount, - IMFS_utime, - IMFS_evaluate_link, - IMFS_symlink, - IMFS_readlink -@}; -@end example - -@c -@c -@c -@c @page - -@subsubsection IMFS_evalpath() - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading File: - -XXX - -@subheading Description: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection IMFS_evalformake() - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading File: - -XXX - -@subheading Description: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection IMFS_link() - -@subheading Corresponding Structure Element: - -link - -@subheading Arguments: - - -@example -rtems_filesystem_location_info_t *to_loc, /* IN */ -rtems_filesystem_location_info_t *parent_loc, /* IN */ -const char *token /* IN */ -@end example - -@subheading File: - -imfs_link.c - -@subheading Description: - - -This routine is used in the IMFS filesystem to create a hard-link. - -It will first examine the st_nlink count of the node that we are trying to. -If the link count exceeds LINK_MAX an error will be returned. - -The name of the link will be normalized to remove extraneous separators from -the end of the name. - -IMFS_create_node will be used to create a filesystem node that will have the -following characteristics: - -@itemize @bullet - -@item parent that was determined in the link() function in file link.c - -@item Type will be set to IMFS_HARD_LINK - -@item name will be set to the normalized name - -@item mode of the hard-link will be set to the mode of the target node - -@end itemize - -If there was trouble allocating memory for the new node an error will be -returned. - -The st_nlink count of the target node will be incremented to reflect the new -link. - -The time fields of the link will be set to reflect the creation time of the -hard-link. - - -@c -@c -@c -@c @page - -@subsubsection IMFS_unlink() - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading File: - -XXX - -@subheading Description: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection IMFS_node_type() - -@subheading Corresponding Structure Element: - -IMFS_node_type() - -@subheading Arguments: - -@example -rtems_filesystem_location_info_t *pathloc /* IN */ -@end example - -@subheading File: - -imfs_ntype.c - -@subheading Description: - -This routine will locate the IMFS_jnode_t structure that holds ownership -information for the selected node in the filesystem. - -This structure is pointed to by pathloc->node_access. - -The IMFS_jnode_t type element indicates one of the node types listed below: - -@itemize @bullet - -@item RTEMS_FILESYSTEM_DIRECTORY - -@item RTEMS_FILESYSTEM_DEVICE - -@item RTEMS_FILESYSTEM_HARD_LINK - -@item RTEMS_FILESYSTEM_MEMORY_FILE - -@end itemize - -@c -@c -@c -@c @page - -@subsubsection IMFS_mknod() - -@subheading Corresponding Structure Element: - -IMFS_mknod() - -@subheading Arguments: - -@example -const char *token, /* IN */ -mode_t mode, /* IN */ -dev_t dev, /* IN */ -rtems_filesystem_location_info_t *pathloc /* IN/OUT */ -@end example - -@subheading File: - -imfs_mknod.c - -@subheading Description: - -This routine will examine the mode argument to determine is we are trying to -create a directory, regular file and a device node. The creation of other -node types is not permitted and will cause an assert. - -Memory space will be allocated for a @code{jnode} and the node will be set up -according to the nodal type that was specified. The IMFS_create_node() -function performs the allocation and setup of the node. - -The only problem that is currently reported is the lack of memory when we -attempt to allocate space for the @code{jnode} (ENOMEN). - - -@c -@c -@c -@c @page - -@subsubsection IMFS_rmnod() - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading File: - -XXX - -@subheading Description: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection IMFS_chown() - -@subheading Corresponding Structure Element: - -IMFS_chown() - -@subheading Arguments: - -@example -rtems_filesystem_location_info_t *pathloc /* IN */ -uid_t owner /* IN */ -gid_t group /* IN */ -@end example - -@subheading File: - -imfs_chown.c - -@subheading Description: - -This routine will locate the IMFS_jnode_t structure that holds ownership -information for the selected node in the filesystem. - -This structure is pointed to by pathloc->node_access. - -The st_uid and st_gid fields of the node are then modified. Since this is a -memory based filesystem, no further action is required to alter the -ownership of the IMFS_jnode_t structure. - - -@c -@c -@c -@c @page - -@subsubsection IMFS_freenod() - -@subheading Corresponding Structure Element: - -IMFS_freenod() - -@subheading Arguments: - -@example -rtems_filesystem_location_info_t *pathloc /* IN */ -@end example - -@subheading File: - -imfs_free.c - -@subheading Description: - -This method is a private function to the IMFS. It is called by IMFS routines -to free nodes that have been allocated. Examples of where this routine -may be called from are unlink and rmnod. - -Note: This routine should not be confused with the filesystem callback -freenod. The IMFS allocates memory until the node no longer exists. - -@c -@c -@c -@c @page - -@subsubsection IMFS_freenodinfo() - -@subheading Corresponding Structure Element: - -IMFS_freenodinfo() - -@subheading Arguments: - -@example -rtems_filesystem_location_info_t *pathloc /* IN */ -@end example - -@subheading File: - -imfs_free.c - -@subheading Description: - -The In-Memory File System does not need to allocate memory during the -evaluate routines. Therefore, this routine simply routines PASS. - - -@c -@c -@c -@c @page - -@subsubsection IMFS_mount() - -@subheading Corresponding Structure Element: - -IMFS_mount() - -@subheading Arguments: - -@example -rtems_filesystem_mount_table_entry_t *mt_entry -@end example - -@subheading File: - -imfs_mount.c - -@subheading Description: - -This routine provides the filesystem specific processing required to mount a -filesystem for the system that contains the mount point. It will determine -if the point that we are trying to mount onto is a node of IMFS_DIRECTORY -type. - -If it is the node's info element is altered so that the info.directory.mt_fs -element points to the mount table chain entry that is associated with the -mounted filesystem at this point. The info.directory.mt_fs element can be -examined to determine if a filesystem is mounted at a directory. If it is -NULL, the directory does not serve as a mount point. A non-NULL entry -indicates that the directory does serve as a mount point and the value of -info.directory.mt_fs can be used to locate the mount table chain entry that -describes the filesystem mounted at this point. - - -@c -@c -@c -@c @page - -@subsubsection IMFS_fsmount_me() - -@subheading Corresponding Structure Element: - -IMFS_initialize() - -@subheading Arguments: - -@example -rtems_filesystem_mount_table_entry_t *mt_entry -@end example - -@subheading File: - -imfs_init.c - -@subheading Description: - -This function is provided with a filesystem to take care of the internal -filesystem management details associated with mounting that filesystem -under the RTEMS environment. - -It is not responsible for the mounting details associated the filesystem -containing the mount point. - -The rtems_filesystem_mount_table_entry_t structure contains the key elements -below: - -rtems_filesystem_location_info_t *mt_point_node, - -This structure contains information about the mount point. This -allows us to find the ops-table and the handling functions -associated with the filesystem containing the mount point. - -rtems_filesystem_location_info_t *fs_root_node, - -This structure contains information about the root node in the file -system to be mounted. It allows us to find the ops-table and the -handling functions associated with the filesystem to be mounted. - -rtems_filesystem_options_t options, - -Read only or read/write access - -void *fs_info, - -This points to an allocated block of memory the will be used to -hold any filesystem specific information of a global nature. This -allocated region if important because it allows us to mount the -same filesystem type more than once under the RTEMS system. -Each instance of the mounted filesystem has its own set of global -management information that is separate from the global -management information associated with the other instances of the -mounted filesystem type. - -rtems_filesystem_limits_and_options_t pathconf_info, - -The table contains the following set of values associated with the -mounted filesystem: - -@itemize @bullet - -@item link_max - -@item max_canon - -@item max_input - -@item name_max - -@item path_max - -@item pipe_buf - -@item posix_async_io - -@item posix_chown_restrictions - -@item posix_no_trunc - -@item posix_prio_io - -@item posix_sync_io - -@item posix_vdisable - -@end itemize - -These values are accessed with the pathconf() and the fpathconf () -functions. - -const char *dev - -The is intended to contain a string that identifies the device that contains -the filesystem information. The filesystems that are currently implemented -are memory based and don't require a device specification. - -If the mt_point_node.node_access is NULL then we are mounting the base file -system. - -The routine will create a directory node for the root of the IMFS file -system. - -The node will have read, write and execute permissions for owner, group and -others. - -The node's name will be a null string. - -A filesystem information structure(fs_info) will be allocated and -initialized for the IMFS filesystem. The fs_info pointer in the mount table -entry will be set to point the filesystem information structure. - -The pathconf_info element of the mount table will be set to the appropriate -table of path configuration constants ( IMFS_LIMITS_AND_OPTIONS ). - -The fs_root_node structure will be filled in with the following: - -@itemize @bullet - -@item pointer to the allocated root node of the filesystem - -@item directory handlers for a directory node under the IMFS filesystem - -@item OPS table functions for the IMFS - -@end itemize - -A 0 will be returned to the calling routine if the process succeeded, -otherwise a 1 will be returned. - - -@c -@c -@c -@c @page - -@subsubsection IMFS_unmount() - -@subheading Corresponding Structure Element: - -IMFS_unmount() - -@subheading Arguments: - -@example -rtems_filesystem_mount_table_entry_t *mt_entry -@end example - -@subheading File: - -imfs_unmount.c - -@subheading Description: - -This routine allows the IMFS to unmount a filesystem that has been -mounted onto a IMFS directory. - -The mount entry mount point node access is verified to be a mounted -directory. It's mt_fs is set to NULL. This identifies to future -calles into the IMFS that this directory node is no longer a mount -point. Additionally, it will allow any directories that were hidden -by the mounted system to again become visible. - -@c -@c -@c -@c @page - -@subsubsection IMFS_fsunmount() - -@subheading Corresponding Structure Element: - -imfs_fsunmount() - -@subheading Arguments: - -@example -rtems_filesystem_mount_table_entry_t *mt_entry -@end example - -@subheading File: - -imfs_init.c - -@subheading Description: - -This method unmounts this instance of the IMFS file system. It is the -counterpart to the IMFS_initialize routine. It is called by the generic -code under the fsunmount_me callback. - -All method loops finding the first encountered node with no children and -removing the node from the tree, thus returning allocated resources. This -is done until all allocated nodes are returned. - -@c -@c -@c -@c @page - -@subsubsection IMFS_utime() - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading File: - -XXX - -@subheading Description: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection IMFS_eval_link() - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading File: - -XXX - -@subheading Description: - -XXX - -@c -@c -@c -@c @page -@subsection Regular 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. - -@example -rtems_filesystem_file_handlers_r IMFS_memfile_handlers = @{ - memfile_open, - memfile_close, - memfile_read, - memfile_write, - memfile_ioctl, - memfile_lseek, - IMFS_stat, - IMFS_fchmod, - memfile_ftruncate, - NULL, /* fpathconf */ - NULL, /* fsync */ - IMFS_fdatasync, - IMFS_fcntl -@}; -@end example - - -@c -@c -@c -@c @page - -@subsubsection memfile_open() for Regular Files - -@subheading Corresponding Structure Element: - -memfile_open() - -@subheading Arguments: - -@example -rtems_libio_t *iop, -const char *pathname, -unsigned32 flag, -unsigned32 mode -@end example - -@subheading File: - -memfile.c - -@subheading Description: - -Currently this function is a shell. No meaningful processing is performed and -a success code is always returned. - -@c -@c -@c -@c @page - -@subsubsection memfile_close() for Regular Files - -@subheading Corresponding Structure Element: - -memfile_close() - -@subheading Arguments: - -@example -rtems_libio_t *iop -@end example - -@subheading File: - -memfile.c - -@subheading Description: - -This routine is a dummy for regular files under the base filesystem. It -performs a capture of the IMFS_jnode_t pointer from the file control block -and then immediately returns a success status. - - -@c -@c -@c -@c @page - -@subsubsection memfile_read() for Regular Files - -@subheading Corresponding Structure Element: - -memfile_read() - -@subheading Arguments: - -@example -rtems_libio_t *iop, -void *buffer, -unsigned32 count -@end example - -@subheading File: - -memfile.c - -@subheading Description: - -This routine will determine the @code{jnode} that is associated with this file. - -It will then call IMFS_memfile_read() with the @code{jnode}, file position index, -buffer and transfer count as arguments. - -IMFS_memfile_read() will do the following: - -@itemize @bullet - -@item Verify that the @code{jnode} is associated with a memory file - -@item Verify that the destination of the read is valid - -@item Adjust the length of the read if it is too long - -@item Acquire data from the memory blocks associated with the file - -@item Update the access time for the data in the file - -@end itemize - -@c -@c -@c -@c @page - -@subsubsection memfile_write() for Regular Files - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX -@subheading File: - -XXX - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection memfile_ioctl() for Regular Files - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -@example -rtems_libio_t *iop, -unsigned32 command, -void *buffer -@end example - -@subheading File: - -memfile.c - -@subheading Description: - -The current code is a placeholder for future development. The routine returns -a successful completion status. - -@c -@c -@c -@c @page - -@subsubsection memfile_lseek() for Regular Files - -@subheading Corresponding Structure Element: - -Memfile_lseek() - -@subheading Arguments: - -@example -rtems_libio_t *iop, -off_t offset, -int whence -@end example - -@subheading File: - -memfile.c - -@subheading Description: - -This routine make sure that the memory based file is sufficiently large to -allow for the new file position index. - -The IMFS_memfile_extend() function is used to evaluate the current size of -the memory file and allocate additional memory blocks if required by the new -file position index. A success code is always returned from this routine. - -@c -@c -@c -@c @page - -@subsubsection IMFS_stat() for Regular Files - -@subheading Corresponding Structure Element: - -IMFS_stat() - -@subheading Arguments: - -@example -rtems_filesystem_location_info_t *loc, -struct stat *buf -@end example - -@subheading File: - -imfs_stat.c - -@subheading Description: - -This routine actually performs status processing for both devices and regular -files. - -The IMFS_jnode_t structure is referenced to determine the type of node under -the filesystem. - -If the node is associated with a device, node information is extracted and -transformed to set the st_dev element of the stat structure. - -If the node is a regular file, the size of the regular file is extracted from -the node. - -This routine rejects other node types. - -The following information is extracted from the node and placed in the stat -structure: - -@itemize @bullet - -@item st_mode - -@item st_nlink - -@item st_ino - -@item st_uid - -@item st_gid - -@item st_atime - -@item st_mtime - -@item st_ctime - -@end itemize - -@c -@c -@c -@c @page - -@subsubsection IMFS_fchmod() for Regular Files - -@subheading Corresponding Structure Element: - -IMFS_fchmod() - -@subheading Arguments: - -@example -rtems_libio_t *iop -mode_t mode -@end example - -@subheading File: - -imfs_fchmod.c - -@subheading Description: - -This routine will obtain the pointer to the IMFS_jnode_t structure from the -information currently in the file control block. - -Based on configuration the routine will acquire the user ID from a call to -getuid() or from the IMFS_jnode_t structure. - -It then checks to see if we have the ownership rights to alter the mode of -the file. If the caller does not, an error code is returned. - -An additional test is performed to verify that the caller is not trying to -alter the nature of the node. If the caller is attempting to alter more than -the permissions associated with user group and other, an error is returned. - -If all the preconditions are met, the user, group and other fields are set -based on the mode calling parameter. - -@c -@c -@c -@c @page - -@subsubsection memfile_ftruncate() for Regular Files - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX -@subheading File: - -XXX - -@subheading Description: - -XXX - - -@subsubsection No pathconf() for Regular Files - -@subheading Corresponding Structure Element: - -NULL - -@subheading Arguments: - -Not Implemented - -@subheading File: - -Not Implemented - -@subheading Description: - -Not Implemented - - -@c -@c -@c -@c @page - -@subsubsection No fsync() for Regular Files - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX -@subheading File: - -XXX - -@subheading Description: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection IMFS_fdatasync() for Regular Files - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX -@subheading File: - -XXX - -@subheading Description: - -XXX - -@c -@c -@c -@c @page -@subsection Directory 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 directories contained in -this function management structure. - -@example -rtems_filesystem_file_handlers_r IMFS_directory_handlers = @{ - IMFS_dir_open, - IMFS_dir_close, - IMFS_dir_read, - NULL, /* write */ - NULL, /* ioctl */ - IMFS_dir_lseek, - IMFS_dir_fstat, - IMFS_fchmod, - NULL, /* ftruncate */ - NULL, /* fpathconf */ - NULL, /* fsync */ - IMFS_fdatasync, - IMFS_fcntl -@}; -@end example - - -@c -@c -@c -@c @page -@subsubsection IMFS_dir_open() for Directories - -@subheading Corresponding Structure Element: - -imfs_dir_open() - -@subheading Arguments: - -@example -rtems_libio_t *iop, -const char *pathname, -unsigned32 flag, -unsigned32 mode -@end example - -@subheading File: - -imfs_directory.c - -@subheading Description: - -This routine will look into the file control block to find the @code{jnode} that -is associated with the directory. - -The routine will verify that the node is a directory. If its not a directory -an error code will be returned. - -If it is a directory, the offset in the file control block will be set to 0. -This allows us to start reading at the beginning of the directory. - -@c -@c -@c -@c @page - -@subsubsection IMFS_dir_close() for Directories - -@subheading Corresponding Structure Element: - -imfs_dir_close() - -@subheading Arguments: - -@example -rtems_libio_t *iop -@end example - -@subheading File: - -imfs_directory.c - -@subheading Description: - -This routine is a dummy for directories under the base filesystem. It -immediately returns a success status. - -@c -@c -@c -@c @page - -@subsubsection IMFS_dir_read() for Directories - -@subheading Corresponding Structure Element: - -imfs_dir_read - -@subheading Arguments: - -@example -rtems_libio_t *iop, -void *buffer, -unsigned32 count -@end example - -@subheading File: - -imfs_directory.c - -@subheading Description: - -This routine will read a fixed number of directory entries from the current -directory offset. The number of directory bytes read will be returned from -this routine. - - -@c -@c -@c -@c @page - -@subsubsection No write() for Directories - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading File: - -XXX - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection No ioctl() for Directories - -@subheading Corresponding Structure Element: - -ioctl - -@subheading Arguments: - - -@subheading File: - -Not supported - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection IMFS_dir_lseek() for Directories - -@subheading Corresponding Structure Element: - -imfs_dir_lseek() - -@subheading Arguments: - -@example -rtems_libio_t *iop, -off_t offset, -int whence -@end example - -@subheading File: - -imfs_directory.c - -@subheading Description: - -This routine alters the offset in the file control block. - -No test is performed on the number of children under the current open -directory. The imfs_dir_read() function protects against reads beyond the -current size to the directory by returning a 0 bytes transfered to the -calling programs whenever the file position index exceeds the last entry in -the open directory. - -@c -@c -@c -@c @page - -@subsubsection IMFS_dir_fstat() for Directories - -@subheading Corresponding Structure Element: - -imfs_dir_fstat() - -@subheading Arguments: - - -@example -rtems_filesystem_location_info_t *loc, -struct stat *buf -@end example - -@subheading File: - -imfs_directory.c - -@subheading Description: - -The node access information in the rtems_filesystem_location_info_t structure -is used to locate the appropriate IMFS_jnode_t structure. The following -information is taken from the IMFS_jnode_t structure and placed in the stat -structure: - -@itemize @bullet -@item st_ino -@item st_mode -@item st_nlink -@item st_uid -@item st_gid -@item st_atime -@item st_mtime -@item st_ctime -@end itemize - -The st_size field is obtained by running through the chain of directory -entries and summing the sizes of the dirent structures associated with each -of the children of the directory. - -@c -@c -@c -@c @page - -@subsubsection IMFS_fchmod() for Directories - -@subheading Corresponding Structure Element: - -IMFS_fchmod() - -@subheading Arguments: - -@example -rtems_libio_t *iop -mode_t mode -@end example - -@subheading File: - -imfs_fchmod.c - -@subheading Description: - -This routine will obtain the pointer to the IMFS_jnode_t structure from the -information currently in the file control block. - -Based on configuration the routine will acquire the user ID from a call to -getuid() or from the IMFS_jnode_t structure. - -It then checks to see if we have the ownership rights to alter the mode of -the file. If the caller does not, an error code is returned. - -An additional test is performed to verify that the caller is not trying to -alter the nature of the node. If the caller is attempting to alter more than -the permissions associated with user group and other, an error is returned. - -If all the preconditions are met, the user, group and other fields are set -based on the mode calling parameter. - -@c -@c -@c -@c @page - -@subsubsection No ftruncate() for Directories - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading File: - -XXX - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection No fpathconf() for Directories - -@subheading Corresponding Structure Element: - -fpathconf - -@subheading Arguments: - -Not Implemented - -@subheading File: - -Not Implemented - -@subheading Description: - -Not Implemented - - -@c -@c -@c -@c @page - -@subsubsection No fsync() for Directories - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX -@subheading File: - -XXX - -@subheading Description: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection IMFS_fdatasync() for Directories - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading File: - -XXX - -@subheading Description: - -XXX - -@c -@c -@c -@c @page -@subsection Device 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 devices contained in -this function management structure. - -@example -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_file_handlers_r; -@end example - -@c -@c -@c -@c @page - -@subsubsection device_open() for Devices - -@subheading Corresponding Structure Element: - -device_open() - -@subheading Arguments: - -@example -rtems_libio_t *iop, -const char *pathname, -unsigned32 flag, -unsigned32 mode -@end example - -@subheading File: - -deviceio.c - -@subheading Description: - -This routine will use the file control block to locate the node structure for -the device. - -It will extract the major and minor device numbers from the @code{jnode}. - -The major and minor device numbers will be used to make a rtems_io_open() -function call to open the device driver. An argument list is sent to the -driver that contains the file control block, flags and mode information. - -@c -@c -@c -@c @page - -@subsubsection device_close() for Devices - -@subheading Corresponding Structure Element: - -device_close() - -@subheading Arguments: - -@example -rtems_libio_t *iop -@end example - -@subheading File: - -deviceio.c - -@subheading Description: - -This routine extracts the major and minor device driver numbers from the -IMFS_jnode_t that is referenced in the file control block. - -It also forms an argument list that contains the file control block. - -A rtems_io_close() function call is made to close the device specified by the -major and minor device numbers. - - -@c -@c -@c -@c @page - -@subsubsection device_read() for Devices - -@subheading Corresponding Structure Element: - -device_read() - -@subheading Arguments: - -@example -rtems_libio_t *iop, -void *buffer, -unsigned32 count -@end example - -@subheading File: - -deviceio.c - -@subheading Description: - -This routine will extract the major and minor numbers for the device from the - -jnode- associated with the file descriptor. - -A rtems_io_read() call will be made to the device driver associated with the file -descriptor. The major and minor device number will be sent as arguments as well -as an argument list consisting of: - -@itemize @bullet -@item file control block - -@item file position index - -@item buffer pointer where the data read is to be placed - -@item count indicating the number of bytes that the program wishes to read -from the device - -@item flags from the file control block - -@end itemize - -On return from the rtems_io_read() the number of bytes that were actually -read will be returned to the calling program. - - -@c -@c -@c -@c @page - -@subsubsection device_write() for Devices - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX -@subheading File: - -XXX - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection device_ioctl() for Devices - -@subheading Corresponding Structure Element: - -ioctl - -@subheading Arguments: - -@example -rtems_libio_t *iop, -unsigned32 command, -void *buffer -@end example - -@subheading File: - -deviceio.c - -@subheading Description: - -This handler will obtain status information about a device. - -The form of status is device dependent. - -The rtems_io_control() function uses the major and minor number of the device -to obtain the status information. - -rtems_io_control() requires an rtems_libio_ioctl_args_t argument list which -contains the file control block, device specific command and a buffer pointer -to return the device status information. - -The device specific command should indicate the nature of the information -that is desired from the device. - -After the rtems_io_control() is processed, the buffer should contain the -requested device information. - -If the device information is not obtained properly a -1 will be returned to -the calling program, otherwise the ioctl_return value is returned. - -@c -@c -@c -@c @page - -@subsubsection device_lseek() for Devices - -@subheading Corresponding Structure Element: - -device_lseek() - -@subheading Arguments: - -@example -rtems_libio_t *iop, -off_t offset, -int whence -@end example - -@subheading File: - -deviceio.c - -@subheading Description: - -At the present time this is a placeholder function. It always returns a -successful status. - -@c -@c -@c -@c @page - -@subsubsection IMFS_stat() for Devices - -@subheading Corresponding Structure Element: - -IMFS_stat() - -@subheading Arguments: - -@example -rtems_filesystem_location_info_t *loc, -struct stat *buf -@end example - -@subheading File: - -imfs_stat.c - -@subheading Description: - -This routine actually performs status processing for both devices and regular files. - -The IMFS_jnode_t structure is referenced to determine the type of node under the -filesystem. - -If the node is associated with a device, node information is extracted and -transformed to set the st_dev element of the stat structure. - -If the node is a regular file, the size of the regular file is extracted from the node. - -This routine rejects other node types. - -The following information is extracted from the node and placed in the stat -structure: - -@itemize @bullet - -@item st_mode - -@item st_nlink - -@item st_ino - -@item st_uid - -@item st_gid - -@item st_atime - -@item st_mtime - -@item st_ctime - -@end itemize - - - -@c -@c -@c -@c @page - -@subsubsection IMFS_fchmod() for Devices - -@subheading Corresponding Structure Element: - -IMFS_fchmod() - -@subheading Arguments: - -@example -rtems_libio_t *iop -mode_t mode -@end example - -@subheading File: - -imfs_fchmod.c - -@subheading Description: - -This routine will obtain the pointer to the IMFS_jnode_t structure from the -information currently in the file control block. - -Based on configuration the routine will acquire the user ID from a call to -getuid() or from the IMFS_jnode_t structure. - -It then checks to see if we have the ownership rights to alter the mode of -the file. If the caller does not, an error code is returned. - -An additional test is performed to verify that the caller is not trying to -alter the nature of the node. If the caller is attempting to alter more than -the permissions associated with user group and other, an error is returned. - -If all the preconditions are met, the user, group and other fields are set -based on the mode calling parameter. - - -@c -@c -@c -@c @page - -@subsubsection No ftruncate() for Devices - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX -@subheading File: - -XXX - -@subheading Description: - -XXX - -@c -@c -@c -@c @page - -@subsubsection No fpathconf() for Devices - -@subheading Corresponding Structure Element: - -fpathconf - -@subheading Arguments: - -Not Implemented - -@subheading File: - -Not Implemented - -@subheading Description: - -Not Implemented - - -@c -@c -@c -@c @page - -@subsubsection No fsync() for Devices - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading File: - -XXX - -@subheading Description: - -XXX - - -@c -@c -@c -@c @page - -@subsubsection No fdatasync() for Devices - -Not Implemented - -@subheading Corresponding Structure Element: - -XXX - -@subheading Arguments: - -XXX - -@subheading File: - -XXX - -@subheading Description: - -XXX - diff --git a/doc/filesystem/init.t b/doc/filesystem/init.t deleted file mode 100644 index 02bf8bb0d1..0000000000 --- a/doc/filesystem/init.t +++ /dev/null @@ -1,110 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter System Initialization - -After the RTEMS initialization is performed, the application's -initialization will be performed. Part of initialization is a call to -rtems_filesystem_initialize(). This routine will mount the `In Memory File -System' as the base filesystem. Mounting the base filesystem consists -of the following: - -@itemize @bullet - -@item Initialization of mount table chain control structure - -@item Allocation of a @code{jnode} structure that will server as the root node -of the `In Memory Filesystem' - -@item Initialization of the allocated @code{jnode} with the appropriate OPS, -directory handlers and pathconf limits and options. - -@item Allocation of a memory region for filesystem specific global -management variables - -@item Creation of first mount table entry for the base filesystem - -@item Initialization of the first mount table chain entry to indicate that -the mount point is NULL and the mounted filesystem is the base file -system - -@end itemize - - -After the base filesystem has been mounted, the following operations are -performed under its directory structure: - -@itemize @bullet - -@item Creation of the /dev directory - -@item Registration of devices under /dev directory - -@end itemize - -@section Base Filesystem - -RTEMS initially mounts a RAM based file system known as the base file system. -The root directory of this file system tree serves as the logical root of the -directory hierarchy (Figure 3). Under the root directory a `/dev' directory -is created under which all I/O device directories and files are registered as -part of the file system hierarchy. - -@example -Figure of the tree structure goes here. -@end example - -A RAM based file system draws its management resources from memory. File and -directory nodes are simply allocated blocks of memory. Data associated with -regular files is stored in collections of memory blocks. When the system is -turned off or restarted all memory-based components of the file system are -lost. - -The base file system serves as a starting point for the mounting of file -systems that are resident on semi-permanent storage media. Examples of such -media include non- volatile memory, flash memory and IDE hard disk drives -(Figure 3). File systems of other types will be mounted onto mount points -within the base file system or other file systems that are subordinate to the -base file system. The framework set up under the base file system will allow -for these new file system types and the unique data and functionality that is -required to manage the future file systems. - -@subsection Base Filesystem Mounting - -At present, the first file system to be mounted is the `In Memory File -System'. It is mounted using a standard MOUNT() command in which the mount -point is NULL. This flags the mount as the first file system to be -registered under the operating system and appropriate initialization of file -system management information is performed (See figures 4 and 5). If a -different file system type is desired as the base file system, alterations -must be made to base_fs.c. This routine handles the mount of the base file -system. - - -@example -Figure of the mount table chain goes here. -@end example - - -Once the root of the base file system has been established and it has been -recorded as the mount point of the base file system, devices are integrated -into the base file system. For every device that is configured into the -system (See ioman.c) a device registration process is performed. Device -registration produces a unique dev_t handle that consists of a major and -minor device number. In addition, the configuration information for each -device contains a text string that represents the fully qualified pathname to -that device's place in the base file system's hierarchy. A file system node -is created for the device along the specified registration path. - - -@example -Figure of the Mount Table Processing goes here. -@end example - - -Note: Other file systems can be mounted but they are mounted onto points -(directory mount points) in the base file system. - - diff --git a/doc/filesystem/miniimfs.t b/doc/filesystem/miniimfs.t deleted file mode 100644 index a4f03bb351..0000000000 --- a/doc/filesystem/miniimfs.t +++ /dev/null @@ -1,13 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Miniature In-Memory Filesystem - -This chapter describes the Miniature In-Memory FileSystem (miniIMFS). -The miniIMFS is a reduced feature version of the IMFS designed to -provide minimal functionality and have a low memory footprint. - -This chapter should be written after the IMFS chapter is completed -and describe the implementation of the mini-IMFS. diff --git a/doc/filesystem/mounting.t b/doc/filesystem/mounting.t deleted file mode 100644 index 5389f45e00..0000000000 --- a/doc/filesystem/mounting.t +++ /dev/null @@ -1,168 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Mounting and Unmounting Filesystems - -@section Mount Points - -The following is the list of the characteristics of a mount point: - -@itemize @bullet - -@item The mount point must be a directory. It may have files and other -directories under it. These files and directories will be hidden when the -filesystem is mounted. - -@item The task must have read/write/execute permissions to the mount point -or the mount attempt will be rejected. - -@item Only one filesystem can be mounted to a single mount point. - -@item The Root of the mountable filesystem will be referenced by the name -of the mount point after the mount is complete. - -@end itemize - -@section Mount Table Chain - -The mount table chain is a dynamic list of structures that describe -mounted filesystems a specific points in the filesystem hierarchy. It is -initialized to an empty state during the base filesystem initialization. -The mount operation will add entries to the mount table chain. The -un-mount operation will remove entries from the mount table chain. - -Each entry in the mount table chain is of the following type: - -@example -struct rtems_filesystem_mount_table_entry_tt -@{ - Chain_Node Node; - rtems_filesystem_location_info_t mt_point_node; - rtems_filesystem_location_info_t mt_fs_root; - int options; - void *fs_info; - - rtems_filesystem_limits_and_options_t pathconf_limits_and_options; - - /* - * When someone adds a mounted filesystem on a real device, - * this will need to be used. - * - * The best option long term for this is probably an - * open file descriptor. - */ - char *dev; -@}; -@end example - -@table @b -@item Node -The Node is used to produce a linked list of mount table entry nodes. - -@item mt_point_node -The mt_point_node contains all information necessary to access the -directory where a filesystem is mounted onto. This element may contain -memory that is allocated during a path evaluation of the filesystem -containing the mountpoint directory. The generic code allows this -memory to be returned by unmount when the filesystem identified by -mt_fs_root is unmounted. - -@item mt_fs_root -The mt_fs_root contains all information necessary to identify the root -of the mounted filesystem. The user is never allowed access to this -node by the generic code, but it is used to identify to the mounted -filesystem where to start evaluation of pathnames at. - -@item options -XXX - -@item fs_info -The fs_info element is a location available for use by the mounted file -system to identify unique things applicable to this instance of the file -system. For example the IMFS uses this space to provide node -identification that is unique for each instance (mounting) of the filesystem. - -@item pathconf_limits_and_options -XXX - -@item dev -This character string represents the device where the filesystem will reside. - -@end table - -@section Adding entries to the chain during mount - -When a filesystem is mounted, its presence and location in the file -system hierarchy is recorded in a dynamic list structure known as a chain. -A unique rtems_filesystem_mount_table_entry_tt structure is logged for -each filesystem that is mounted. This includes the base filesystem. - -@section Removing entries from the chain during unmount - -When a filesystem is dismounted its entry in the mount table chain is -extracted and the memory for this entry is freed. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/doc/filesystem/patheval.t b/doc/filesystem/patheval.t deleted file mode 100644 index 37d1a9a5e6..0000000000 --- a/doc/filesystem/patheval.t +++ /dev/null @@ -1,106 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Pathname Evaluation - -This chapter describes the pathname evaluation process for the -RTEMS Filesystem Infrastructure. - -@example -XXX Include graphic of the path evaluation process -@end example - -@section Pathname Evaluation Handlers - -There are two pathname evaluation routines. The handler patheval() -is called to find, verify privlages on and return information on a node -that exists. The handler evalformake() is called to find, verify -permissions, and return information on a node that is to become a parent. -Additionally, evalformake() returns a pointer to the start of the name of -the new node to be created. - -Pathname evaluation is specific to a filesystem. -Each filesystem is required to provide both a patheval() and an evalformake() -routine. Both of these routines gets a name to evaluate and a node indicating -where to start the evaluation. - -@section Crossing a Mount Point During Path Evaluation - -If the filesystem supports the mount command, the evaluate routines -must handle crossing the mountpoint. The evaluate routine should evaluate -the name upto the first directory node where the new filesystem is mounted. -The filesystem may process terminator characters prior to calling the -evaluate routine for the new filesystem. A pointer to the portion of the -name which has not been evaluated along with the root node of the new -file system ( gotten from the mount table entry ) is passed to the correct -mounted filesystem evaluate routine. - - -@section The rtems_filesystem_location_info_t Structure - -The @code{rtems_filesystem_location_info_t} structure contains all information -necessary for identification of a node. - -The generic rtems filesystem code defines two global -rtems_filesystem_location_info_t structures, the -@code{rtems_filesystem_root} and the @code{rtems_filesystem_current}. -Both are initially defined to be the root node of the base filesystem. -Once the chdir command is correctly used the @code{rtems_filesystem_current} -is set to the location specified by the command. - -The filesystem generic code peeks at the first character in the name to be -evaluated. If this character is a valid seperator, the -@code{rtems_filesystem_root} is used as the node to start the evaluation -with. Otherwise, the @code{rtems_filesystem_current} node is used as the -node to start evaluating with. Therefore, a valid -rtems_filesystem_location_info_t is given to the evaluate routine to start -evaluation with. The evaluate routines are then responsible for making -any changes necessary to this structure to correspond to the name being -parsed. - -@example -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; -@}; -@end example - -@table @b - -@item node_access -This element is filesystem specific. A filesystem can define and store -any information necessary to identify a node at this location. This element -is normally filled in by the filesystem's evaluate routine. For the -filesystem's root node, the filesystem's initilization routine should -fill this in, and it should remain valid until the instance of the -filesystem is unmounted. - -@item handlers -This element is defined as a set of routines that may change within a -given filesystem based upon node type. For example a directory and a -memory file may have to completely different read routines. This element -is set to an initialization state defined by the mount table, and may -be set to the desired state by the evaluation routines. - -@item ops -This element is defined as a set of routines that remain static for the -filesystem. This element identifies entry points into the filesystem -to the generic code. - -@item mt_entry -This element identifies the mount table entry for this instance of the -filesystem. - -@end table - - - - - - - - diff --git a/doc/filesystem/preface.texi b/doc/filesystem/preface.texi deleted file mode 100644 index 301f8499f6..0000000000 --- a/doc/filesystem/preface.texi +++ /dev/null @@ -1,78 +0,0 @@ -@c -@c COPYRIGHT (c) 1989-2011. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@node Preface, , Top, Top -@unnumbered Preface - -This document describes the implementation of the RTEMS filesystem -infrastructure. This infrastructure supports the following -capabilities: - -@itemize @bullet - -@item Mountable file systems - -@item Hierarchical file system directory structure - -@item POSIX compliant set of routines for the manipulation of files and directories - -@item Individual file and directory support for the following: - -@enumerate - -@item Permissions for read, write and execute - -@item User ID - -@item Group ID - -@item Access time - -@item Modification time - -@item Creation time - -@end enumerate - -@item Hard links to files and directories - -@item Symbolic links to files and directories - -@end itemize - -This has been implemented to provide the framework for a UNIX-like -file system support. POSIX file and directory functions have been -implemented that allow a standard method of accessing file, device and -directory information within file systems. The file system concept that -has been implemented allows for expansion and adaptation of the file -system to a variety of existing and future data storage devices. To this -end, file system mount and unmount capabilities have been included in this -RTEMS framework. - -This framework slightly alters the manner in which devices are handled -under RTEMS from that of public release 4.0.0 and earlier. Devices that -are defined under a given RTEMS configuration will now be registered as -files in a mounted file system. Access to these device drivers and their -associated devices may now be performed through the traditional file system -open(), read(), write(), lseek(), fstat() and ioctl() functions in addition -to the interface provided by the IO Manager in the RTEMS Classic API. - -An In-Memory File System (IMFS) is included which provides full POSIX -filesystem functionality yet is RAM based. The IMFS maintains a -node structure for each file, device, and directory in each mounted -instantiation of its file system. The node structure is used to -manage ownership, access rights, access time, modification time, -and creation time. A union of structures within the IMFS nodal -structure provide for manipulation of file data, device selection, -or directory content as required by the nodal type. Manipulation of -these properties is accomplished through the POSIX set of file and -directory functions. In addition to being useful in its own right, -the IMFS serves as a full featured example filesystem. - -The intended audience for this document is those persons implementing -their own filesystem. Users of the filesystem may find information -on the implementation useful. But the user interface to the filesystem -is through the ISO/ANSI C Library and POSIX 1003.1b file and directory -APIs. diff --git a/doc/filesystem/stamp-vti b/doc/filesystem/stamp-vti deleted file mode 100644 index 5634951ec8..0000000000 --- a/doc/filesystem/stamp-vti +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 24 February 2013 -@set UPDATED-MONTH February 2013 -@set EDITION 4.10.99.0 -@set VERSION 4.10.99.0 diff --git a/doc/filesystem/syscalls.t b/doc/filesystem/syscalls.t deleted file mode 100644 index cbc55ae711..0000000000 --- a/doc/filesystem/syscalls.t +++ /dev/null @@ -1,1127 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter System Call Development Notes - -This set of routines represents the application's interface to files and directories -under the RTEMS filesystem. All routines are compliant with POSIX standards if a -specific interface has been established. The list below represents the routines that have -been included as part of the application's interface. - -@enumerate -@item access() -@item chdir() -@item chmod() -@item chown() -@item close() -@item closedir() -@item dup() -@item dup2() -@item fchmod() -@item fcntl() -@item fdatasync() -@item fpathconf() -@item fstat() -@item ioctl() -@item link() -@item lseek() -@item mkdir() -@item mkfifo() -@item mknod() -@item mount() -@item open() -@item opendir() -@item pathconf() -@item read() -@item readdir() -@item unmount() -@end enumerate - -The sections that follow provide developmental information concerning each -of these functions. - - -@c @page -@section access - -@subheading File: - -access.c - -@subheading Processing: - -This routine is layered on the stat() function. It acquires the current -status information for the specified file and then determines if the -caller has the ability to access the file for read, write or execute -according to the mode argument to this function. - -@subheading Development Comments: - -This routine is layered on top of the stat() function. As long as the -st_mode element in the returned structure follow the standard UNIX -conventions, this function should support other filesystems without -alteration. - -@c @page -@section chdir - -@subheading File: - -chdir.c - - -@subheading Processing: - -This routine will determine if the pathname that we are attempting to make -that current directory exists and is in fact a directory. If these -conditions are met the global indication of the current directory -(rtems_filesystem_current) is set to the rtems_filesystem_location_info_t -structure that is returned by the rtems_filesystem_evaluate_path() -routine. - -@subheading Development Comments: - -This routine is layered on the rtems_filesystem_evaluate_path() routine -and the filesystem specific OP table function node_type(). - -The routine node_type() must be a routine provided for each filesystem -since it must access the filesystems node information to determine which -of the following types the node is: - -@itemize @bullet -@item RTEMS_FILESYSTEM_DIRECTORY -@item RTEMS_FILESYSTEM_DEVICE -@item RTEMS_FILESYSTEM_HARD_LINK -@item RTEMS_FILESYSTEM_MEMORY_FILE -@end itemize - -This acknowledges that the form of the node management information can -vary from one filesystem implementation to another. - -RTEMS has a special global structure that maintains the current directory -location. This global variable is of type rtems_filesystem_location_info_t -and is called rtems_filesystem_current. This structure is not always -valid. In order to determine if the structure is valid, you must first -test the node_access element of this structure. If the pointer is NULL, -then the structure does not contain a valid indication of what the current -directory is. - -@c @page -@section chmod - -@subheading File: - -chmod.c - -@subheading Processing: - -This routine is layered on the open(), fchmod() and close() functions. As -long as the standard interpretation of the mode_t value is maintained, -this routine should not need modification to support other filesystems. - -@subheading Development Comments: - -The routine first determines if the selected file can be open with -read/write access. This is required to allow modification of the mode -associated with the selected path. - -The fchmod() function is used to actually change the mode of the path -using the integer file descriptor returned by the open() function. - -After mode modification, the open file descriptor is closed. - -@c @page -@section chown - -@subheading File: - -chown.c - -@subheading Processing: - -This routine is layered on the rtems_filesystem_evaluate_path() and the -file system specific chown() routine that is specified in the OPS table -for the file system. - -@subheading Development Comments: - -rtems_filesystem_evaluate_path() is used to determine if the path -specified actually exists. If it does a rtems_filesystem_location_info_t -structure will be obtained that allows the shell function to locate the -OPS table that is to be used for this filesystem. - -It is possible that the chown() function that should be in the OPS table -is not defined. A test for a non-NULL OPS table chown() entry is performed -before the function is called. - -If the chown() function is defined in the indicated OPS table, the -function is called with the rtems_filesystem_location_info_t structure -returned from the path evaluation routine, the desired owner, and group -information. - -@c @page -@section close - -@subheading File: - -close.c - -@subheading Processing: - -This routine will allow for the closing of both network connections and -file system devices. If the file descriptor is associated with a network -device, the appropriate network function handler will be selected from a -table of previously registered network functions (rtems_libio_handlers) -and that function will be invoked. - -If the file descriptor refers to an entry in the filesystem, the -appropriate handler will be selected using information that has been -placed in the file control block for the device (rtems_libio_t structure). - -@subheading Development Comments: - -rtems_file_descriptor_type examines some of the upper bits of the file -descriptor index. If it finds that the upper bits are set in the file -descriptor index, the device referenced is a network device. - -Network device handlers are obtained from a special registration table -(rtems_libio_handlers) that is set up during network initialization. The -network handler invoked and the status of the network handler will be -returned to the calling process. - -If none of the upper bits are set in the file descriptor index, the file -descriptor refers to an element of the RTEMS filesystem. - -The following sequence will be performed for any filesystem file -descriptor: - -@enumerate - -@item Use the rtems_libio_iop() function to obtain the rtems_libio_t -structure for the file descriptor - -@item Range check the file descriptor using rtems_libio_check_fd() - -@item Determine if there is actually a function in the selected handler -table that processes the close() operation for the filesystem and node -type selected. This is generally done to avoid execution attempts on -functions that have not been implemented. - -@item If the function has been defined it is invoked with the file control -block pointer as its argument. - -@item The file control block that was associated with the open file -descriptor is marked as free using rtems_libio_free(). - -@item The return code from the close handler is then passed back to the -calling program. - -@end enumerate - -@c @page -@section closedir - -@subheading File: - -closedir.c - -@subheading Processing: - -The code was obtained from the BSD group. This routine must clean up the -memory resources that are required to track an open directory. The code is -layered on the close() function and standard memory free() functions. It -should not require alterations to support other filesystems. - -@subheading Development Comments: - -The routine alters the file descriptor and the index into the DIR -structure to make it an invalid file descriptor. Apparently the memory -that is about to be freed may still be referenced before it is -reallocated. - -The dd_buf structure's memory is reallocated before the control structure -that contains the pointer to the dd_buf region. - -DIR control memory is reallocated. - -The close() function is used to free the file descriptor index. - - -@c @page -@section dup() Unimplemented - -@subheading File: - -dup.c - -@subheading Processing: - - -@subheading Development Comments: - - - - - -@c @page -@section dup2() Unimplemented - -@subheading File: - -dup2.c - -@subheading Processing: - - -@subheading Development Comments: - - - - - - -@c @page -@section fchmod - -@subheading File: - -fchmod.c - -@subheading Processing: - -This routine will alter the permissions of a node in a filesystem. It is -layered on the following functions and macros: - -@itemize @bullet -@item rtems_file_descriptor_type() - -@item rtems_libio_iop() - -@item rtems_libio_check_fd() - -@item rtems_libio_check_permissions() - -@item fchmod() function that is referenced by the handler table in the -file control block associated with this file descriptor - -@end itemize - -@subheading Development Comments: - -The routine will test to see if the file descriptor index is associated -with a network connection. If it is, an error is returned from this -routine. - -The file descriptor index is used to obtain the associated file control -block. - -The file descriptor value is range checked. - -The file control block is examined to determine if it has write -permissions to allow us to alter the mode of the file. - -A test is made to determine if the handler table that is referenced in the -file control block contains an entry for the fchmod() handler function. If -it does not, an error is returned to the calling routine. - -If the fchmod() handler function exists, it is called with the file -control block and the desired mode as parameters. - -@c @page -@section fcntl() - -@subheading File: - -fcntl.c - -@subheading Processing: - -This routine currently only interacts with the file control block. If the -structure of the file control block and the associated meanings do not -change, the partial implementation of fcntl() should remain unaltered for -other filesystem implementations. - -@subheading Development Comments: - -The only commands that have been implemented are the F_GETFD and F_SETFD. -The commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC bit in the -@code{flags} element of the file control block associated with the file -descriptor index. - -The current implementation of the function performs the sequence of -operations below: - -@enumerate - -@item Test to see if we are trying to operate on a file descriptor -associated with a network connection - -@item Obtain the file control block that is associated with the file -descriptor index - -@item Perform a range check on the file descriptor index. - -@end enumerate - - - -@c @page -@section fdatasync - -@subheading File: - -fdatasync.c - -@subheading Processing: - -This routine is a template in the in memory filesystem that will route us to the -appropriate handler function to carry out the fdatasync() processing. In the in -memory filesystem this function is not necessary. Its function in a disk based file -system that employs a memory cache is to flush all memory based data buffers to -disk. It is layered on the following functions and macros: - -@itemize @bullet - -@item rtems_file_descriptor_type() - -@item rtems_libio_iop() - -@item rtems_libio_check_fd() - -@item rtems_libio_check_permissions() - -@item fdatasync() function that is referenced by the handler table in the -file control block associated with this file descriptor - -@end itemize - -@subheading Development Comments: - -The routine will test to see if the file descriptor index is associated -with a network connection. If it is, an error is returned from this -routine. - -The file descriptor index is used to obtain the associated file control -block. - -The file descriptor value is range checked. - -The file control block is examined to determine if it has write -permissions to the file. - -A test is made to determine if the handler table that is referenced in the -file control block contains an entry for the fdatasync() handler function. -If it does not an error is returned to the calling routine. - -If the fdatasync() handler function exists, it is called with the file -control block as its parameter. - -@c @page -@section fpathconf - -@subheading File: - -fpathconf.c - -@subheading Processing: - -This routine is layered on the following functions and macros: - -@itemize @bullet - -@item rtems_file_descriptor_type() - -@item rtems_libio_iop() - -@item rtems_libio_check_fd() - -@item rtems_libio_check_permissions() - -@end itemize - -When a filesystem is mounted, a set of constants is specified for the -filesystem. These constants are stored with the mount table entry for the -filesystem. These constants appear in the POSIX standard and are listed -below. - -@itemize @bullet - -@item PCLINKMAX - -@item PCMAXCANON - -@item PCMAXINPUT - -@item PCNAMEMAX - -@item PCPATHMAX - -@item PCPIPEBUF - -@item PCCHOWNRESTRICTED - -@item PCNOTRUNC - -@item PCVDISABLE - -@item PCASYNCIO - -@item PCPRIOIO - -@item PCSYNCIO - - -@end itemize - -This routine will find the mount table information associated the file -control block for the specified file descriptor parameter. The mount table -entry structure contains a set of filesystem specific constants that can -be accessed by individual identifiers. - -@subheading Development Comments: - -The routine will test to see if the file descriptor index is associated -with a network connection. If it is, an error is returned from this -routine. - -The file descriptor index is used to obtain the associated file control -block. - -The file descriptor value is range checked. - -The file control block is examined to determine if it has read permissions -to the file. - -Pathinfo in the file control block is used to locate the mount table entry -for the filesystem associated with the file descriptor. - -The mount table entry contains the pathconf_limits_and_options element. -This element is a table of constants that is associated with the -filesystem. - -The name argument is used to reference the desired constant from the -pathconf_limits_and_options table. - - -@c @page -@section fstat - -@subheading File: - -fstat.c - -@subheading Processing: - -This routine will return information concerning a file or network -connection. If the file descriptor is associated with a network -connection, the current implementation of @code{fstat()} will return a -mode set to @code{S_IFSOCK}. In a later version, this routine will map the -status of a network connection to an external handler routine. - -If the file descriptor is associated with a node under a filesystem, the -fstat() routine will map to the fstat() function taken from the node -handler table. - -@subheading Development Comments: - -This routine validates that the struct stat pointer is not NULL so that -the return location is valid. - -The struct stat is then initialized to all zeros. - -rtems_file_descriptor_type() is then used to determine if the file -descriptor is associated with a network connection. If it is, network -status processing is performed. In the current implementation, the file -descriptor type processing needs to be improved. It currently just drops -into the normal processing for file system nodes. - -If the file descriptor is associated with a node under a filesystem, the -following steps are performed: - -@enumerate - -@item Obtain the file control block that is associated with the file descriptor -index. - -@item Range check the file descriptor index. - -@item Test to see if there is a non-NULL function pointer in the handler -table for the fstat() function. If there is, invoke the function with the -file control block and the pointer to the stat structure. - -@end enumerate - -@c @page -@section ioctl - -@subheading File: - -ioctl.c - -@subheading Processing: - -Not defined in the POSIX 1003.1b standard but commonly supported in most -UNIX and POSIX system. Ioctl() is a catchall for I/O operations. Routine -is layered on external network handlers and filesystem specific handlers. -The development of new filesystems should not alter the basic processing -performed by this routine. - -@subheading Development Comments: - - -The file descriptor is examined to determine if it is associated with a -network device. If it is processing is mapped to an external network -handler. The value returned by this handler is then returned to the -calling program. - -File descriptors that are associated with a filesystem undergo the -following processing: - -@enumerate - -@item The file descriptor index is used to obtain the associated file -control block. - -@item The file descriptor value is range checked. - -@item A test is made to determine if the handler table that is referenced -in the file control block contains an entry for the ioctl() handler -function. If it does not, an error is returned to the calling routine. - -@item If the ioctl() handler function exists, it is called with the file -control block, the command and buffer as its parameters. - -@item The return code from this function is then sent to the calling -routine. - -@end enumerate - - -@c @page -@section link - -@subheading File: - -link.c - -@subheading Processing: - -This routine will establish a hard link to a file, directory or a device. -The target of the hard link must be in the same filesystem as the new link -being created. A link to an existing link is also permitted but the -existing link is evaluated before the new link is made. This implies that -links to links are reduced to links to files, directories or devices -before they are made. - -@subheading Development Comments: - -Calling parameters: -const char *existing - const char *new - -link() will determine if the target of the link actually exists using -rtems_filesystem_evaluate_path() - -rtems_filesystem_get_start_loc() is used to determine where to start the -path evaluation of the new name. This macro examines the first characters -of the name to see if the name of the new link starts with a -rtems_filesystem_is_separator. If it does the search starts from the root -of the RTEMS filesystem; otherwise the search will start from the current -directory. - -The OPS table evalformake() function for the parent's filesystem is used -to locate the node that will be the parent of the new link. It will also -locate the start of the new path's name. This name will be used to define -a child under the parent directory. - -If the parent is found, the routine will determine if the hard link that -we are trying to create will cross a filesystem boundary. This is not -permitted for hard-links. - -If the hard-link does not cross a filesystem boundary, a check is -performed to determine if the OPS table contains an entry for the link() -function. - -If a link() function is defined, the OPS table link() function will be -called to establish the actual link within the filesystem. - -The return code from the OPS table link() function is returned to the -calling program. - -@c @page -@section lseek - -@subheading File: - -lseek.c - -@subheading Processing: - -This routine is layered on both external handlers and filesystem / node -type specific handlers. This routine should allow for the support of new -filesystems without modification. - -@subheading Development Comments: - -This routine will determine if the file descriptor is associated with a -network device. If it is lseek will map to an external network handler. -The handler will be called with the file descriptor, offset and whence as -its calling parameters. The return code from the external handler will be -returned to the calling routine. - -If the file descriptor is not associated with a network connection, it is -associated with a node in a filesystem. The following steps will be -performed for filesystem nodes: - -@enumerate - -@item The file descriptor is used to obtain the file control block for the -node. - -@item The file descriptor is range checked. - -@item The offset element of the file control block is altered as indicated -by the offset and whence calling parameters - -@item The handler table in the file control block is examined to determine -if it contains an entry for the lseek() function. If it does not an error -is returned to the calling program. - -@item The lseek() function from the designated handler table is called -with the file control block, offset and whence as calling arguments - -@item The return code from the lseek() handler function is returned to the -calling program - -@end enumerate - - -@c @page -@section mkdir - -@subheading File: - -mkdir.c - -@subheading Processing: - -This routine attempts to create a directory node under the filesystem. The -routine is layered the mknod() function. - -@subheading Development Comments: - -See mknod() for developmental comments. - -@c @page -@section mkfifo - -@subheading File: - -mkfifo.c - -@subheading Processing: - -This routine attempts to create a FIFO node under the filesystem. The -routine is layered the mknod() function. - -@subheading Development Comments: - -See mknod() for developmental comments - -@c @page -@section mknod - -@subheading File: - -mknod.c - -@subheading Processing: - -This function will allow for the creation of the following types of nodes -under the filesystem: - -@itemize @bullet - -@item directories - -@item regular files - -@item character devices - -@item block devices - -@item fifos - -@end itemize - -At the present time, an attempt to create a FIFO will result in an ENOTSUP -error to the calling function. This routine is layered the filesystem -specific routines evalformake and mknod. The introduction of a new -filesystem must include its own evalformake and mknod function to support -the generic mknod() function. Under this condition the generic mknod() -function should accommodate other filesystem types without alteration. - -@subheading Development Comments: - -Test for nodal types - I thought that this test should look like the -following code: - -@example -if ( (mode & S_IFDIR) = = S_IFDIR) || - (mode & S_IFREG) = = S_IFREG) || - (mode & S_IFCHR) = = S_IFCHR) || - (mode & S_IFBLK) = = S_IFBLK) || - (mode & S_IFIFO) = = S_IFIFO)) - Set_errno_and_return_minus_one (EINVAL); - -@end example - -Where: - -@itemize @bullet -@item S_IFREG (0100000) - Creation of a regular file -@item S_IFCHR (0020000) - Creation of a character device -@item S_IFBLK (0060000) - Creation of a block device -@item S_IFIFO (0010000) - Creation of a FIFO -@end itemize - -Determine if the pathname that we are trying to create starts at the root -directory or is relative to the current directory using the -rtems_filesystem_get_start_loc() function. - -Determine if the pathname leads to a valid directory that can be accessed -for the creation of a node. - -If the pathname is a valid location to create a node, verify that a -filesystem specific mknod() function exists. - -If the mknod() function exists, call the filesystem specific mknod() -function. Pass the name, mode, device type and the location information -associated with the directory under which the node will be created. - -@c @page -@section mount - -@subheading File: - -mount.c - - -Arguments (Not a standard POSIX call): - -rtems_filesystem_mount_table_entry_t **mt_entry, - -If the mount operation is successful, this pointer to a pointer will be -set to reference the mount table chain entry that has been allocated for -this file system mount. - -rtems_filesystem_operations_table *fs_ops, - -This is a pointer to a table of functions that are associated with the -file system that we are about to mount. This is the mechanism to selected -file system type without keeping a dynamic database of all possible file -system types that are valid for the mount operation. Using this method, it -is only necessary to configure the filesystems that we wish to use into -the RTEMS build. Unused filesystems types will not be drawn into the -build. - -char *fsoptions, - -This argument points to a string that selects mounting for read only -access or read/write access. Valid states are "RO" and "RW" - -char *device, - -This argument is reserved for the name of a device that will be used to -access the filesystem information. Current filesystem implementations are -memory based and do not require a device to access filesystem information. - -char *mount_point - -This is a pathname to a directory in a currently mounted filesystem that -allows read, write and execute permissions. If successful, the node found -by evaluating this name, is stored in the mt_entry. - -@subheading Processing: - -This routine will handle the mounting of a filesystem on a mount point. If -the operation is successful, a pointer to the mount table chain entry -associated with the mounted filesystem will be returned to the calling -function. The specifics about the processing required at the mount point -and within the filesystem being mounted is isolated in the filesystem -specific mount() and fsmount_me() functions. This allows the generic -mount() function to remain unaltered even if new filesystem types are -introduced. - - - -@subheading Development Comments: - -This routine will use get_file_system_options() to determine if the mount -options are valid ("RO" or "RW"). - -It confirms that a filesystem ops-table has been selected. - -Space is allocated for a mount table entry and selective elements of the -temporary mount table entry are initialized. - -If a mount point is specified: The mount point is examined to determine -that it is a directory and also has the appropriate permissions to allow a -filesystem to be mounted. - -The current mount table chain is searched to determine that there is not -another filesystem mounted at the mount point we are trying to mount onto. - -If a mount function is defined in the ops table for the filesystem -containing the mount point, it is called at this time. - -If no mount point is specified: Processing if performed to set up the -mount table chain entry as the base filesystem. - -If the fsmount_me() function is specified for ops-table of the filesystem -being mounted, that function is called to initialize for the new -filesystem. - -On successful completion, the temporary mount table entry will be placed -on the mount table chain to record the presence of the mounted filesystem. - -@c @page -@section open - -@subheading File: - -open.c - -@subheading Processing: - -This routine is layered on both RTEMS calls and filesystem specific -implementations of the open() function. These functional interfaces should -not change for new filesystems and therefore this code should be stable as -new file systems are introduced. - -@subheading Development Comments: - -This routine will allocate a file control block for the file or device -that we are about to open. - -It will then test to see if the pathname exists. If it does a -rtems_filesystem_location_info_t data structure will be filled out. This -structure contains information that associates node information, -filesystem specific functions and mount table chain information with the -pathname. - -If the create option has been it will attempt to create a node for a -regular file along the specified path. If a file already exists along this -path, an error will be generated; otherwise, a node will be allocated for -the file under the filesystem that contains the pathname. When a new node -is created, it is also evaluated so that an appropriate -rtems_filesystem_location_info_t data structure can be filled out for the -newly created node. - -If the file exists or the new file was created successfully, the file -control block structure will be initialized with handler table -information, node information and the rtems_filesystem_location_info_t -data structure that describes the node and filesystem data in detail. - -If an open() function exists in the filesystem specific handlers table for -the node that we are trying to open, it will be called at this time. - -If any error is detected in the process, cleanup is performed. It consists -of freeing the file control block structure that was allocated at the -beginning of the generic open() routine. - -On a successful open(), the index into the file descriptor table will be -calculated and returned to the calling routine. - -@c @page -@section opendir - -@subheading File: - -opendir.c - -@subheading Processing: - -This routine will attempt to open a directory for read access. It will -setup a DIR control structure that will be used to access directory -information. This routine is layered on the generic open() routine and -filesystem specific directory processing routines. - -@subheading Development Comments: - -The BSD group provided this routine. - -@c @page -@section pathconf - -@subheading File: - -pathconf.c - -@subheading Processing: - -This routine will obtain the value of one of the path configuration -parameters and return it to the calling routine. It is layered on the -generic open() and fpathconf() functions. These interfaces should not -change with the addition of new filesystem types. - -@subheading Development Comments: - -This routine will try to open the file indicated by path. - -If successful, the file descriptor will be used to access the pathconf -value specified by @code{name} using the fpathconf() function. - -The file that was accessed is then closed. - -@c @page -@section read - -@subheading File: - -deviceio.c - -@subheading Processing: - -This routine is layered on a set of RTEMS calls and filesystem specific -read operations. The functions are layered in such a way as to isolate -them from change as new filesystems are introduced. - -@subheading Development Comments: - -This routine will examine the type of file descriptor it is sent. - -If the file descriptor is associated with a network device, the read -function will be mapped to a special network handler. The return code from -the network handler will then be sent as the return code from generic -read() function. - -For file descriptors that are associated with the filesystem the following -sequence will be performed: - -@enumerate - -@item Obtain the file control block associated with the file descriptor - -@item Range check the file descriptor - -@item Determine that the buffer pointer is not invalid - -@item Check that the count is not zero - -@item Check the file control block to see if we have permissions to read - -@item If there is a read function in the handler table, invoke the handler -table read() function - -@item Use the return code from the handler table read function(number of -bytes read) to increment the offset element of the file control block - -@item Return the number of bytes read to the calling program - -@end enumerate - -@c @page -@section readdir - -@subheading File: - -readdir.c - -@subheading Processing: - -This routine was acquired from the BSD group. It has not been altered from -its original form. - -@subheading Development Comments: - -The routine calls a customized getdents() function that is provided by the -user. This routine provides the filesystem specific aspects of reading a -directory. - -It is layered on the read() function in the directory handler table. This -function has been mapped to the Imfs_dir_read() function. - -@c @page -@section unmount - -@subheading File: - -unmount.c - -@subheading Processing: - -This routine will attempt to dismount a mounted filesystem and then free -all resources that were allocated for the management of that filesystem. - -@subheading Development Comments: - -@itemize @bullet - -@item This routine will determine if there are any filesystems currently -mounted under the filesystem that we are trying to dismount. This would -prevent the dismount of the filesystem. - -@item It will test to see if the current directory is in the filesystem -that we are attempting to dismount. This would prevent the dismount of the -filesystem. - -@item It will scan all the currently open file descriptors to determine is -there is an open file descriptor to a file in the filesystem that we are -attempting to unmount(). - -@end itemize - -If the above preconditions are met then the following sequence is -performed: - -@enumerate - -@item Call the filesystem specific unmount() function for the filesystem -that contains the mount point. This routine should indicate that the mount -point no longer has a filesystem mounted below it. - -@item Call the filesystem specific fsunmount_me() function for the mounted -filesystem that we are trying to unmount(). This routine should clean up -any resources that are no longer needed for the management of the file -system being un-mounted. - -@item Extract the mount table entry for the filesystem that was just -dismounted from the mount table chain. - -@item Free the memory associated with the extracted mount table entry. - -@end enumerate - -@c @page -@section eval - -@subheading File: - -XXX - -@subheading Processing: - -XXX - -@subheading Development Comments: - -XXX - -@c @page -@section getdentsc - -@subheading File: - -XXX - -@subheading Processing: - -XXX - -@subheading Development Comments: - -XXX - diff --git a/doc/filesystem/tftp.t b/doc/filesystem/tftp.t deleted file mode 100644 index a470317131..0000000000 --- a/doc/filesystem/tftp.t +++ /dev/null @@ -1,11 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Trivial FTP Client Filesystem - -This chapter describes the Trivial FTP (TFTP) Client Filesystem. - -This chapter should be written after the IMFS chapter is completed -and describe the implementation of the TFTP. diff --git a/doc/filesystem/version.texi b/doc/filesystem/version.texi deleted file mode 100644 index c0e4bbb7b6..0000000000 --- a/doc/filesystem/version.texi +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 17 July 2015 -@set UPDATED-MONTH July 2015 -@set EDITION 4.10.99.0 -@set VERSION 4.10.99.0 -- cgit v1.2.3