summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/filesystem/fsrequirements.t41
-rw-r--r--doc/filesystem/patheval.t95
2 files changed, 115 insertions, 21 deletions
diff --git a/doc/filesystem/fsrequirements.t b/doc/filesystem/fsrequirements.t
index dfcdc486fe..1c368f5dfd 100644
--- a/doc/filesystem/fsrequirements.t
+++ b/doc/filesystem/fsrequirements.t
@@ -326,16 +326,28 @@ typedef struct @{
@subheading Corresponding Structure Element:
-XXX
+evalpath
@subheading Arguments:
-XXX
+@example
+ const char *pathname, /* IN */
+ int flags, /* IN */
+ rtems_filesystem_location_info_t *pathloc /* IN/OUT */
+@end example
@subheading Description:
-XXX
+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
@@ -346,16 +358,31 @@ XXX
@subheading Corresponding Structure Element:
-XXX
+evalformake
@subheading Arguments:
-XXX
+@example
+ const char *path, /* IN */
+ rtems_filesystem_location_info_t *pathloc, /* IN/OUT */
+ const char **name /* OUT */
+@end example
@subheading Description:
-XXX
+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
@@ -388,6 +415,8 @@ 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
diff --git a/doc/filesystem/patheval.t b/doc/filesystem/patheval.t
index b5108f08fb..de8c1bb01f 100644
--- a/doc/filesystem/patheval.t
+++ b/doc/filesystem/patheval.t
@@ -8,38 +8,103 @@
@chapter Pathname Evaluation
+This chapter describes the pathname evaluation process for the
+RTEMS Filesystem Infrastructure.
+
+@example
XXX Include graphic of the path evaluation process with Jennifer's
-explanations
+XXX explanations
+@end example
-@itemize @bullet
+@section Pathname Evaluation Handlers
-@item There are two pathname evaluation routines. The handler patheval()
+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.
-@item Pathname evaluation is specific to a filesystem
+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 Mechanics of crossing a mount point during the evaluation of a path
-name
+@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 Role of rtems_filesystem_location_info_t structure
+@item mt_entry
+This element identifies the mount table entry for this instance of the
+filesystem.
-@itemize @bullet
+@end table
-@item Finding filesystem node information
-@item Finding filesystem node handlers
-@item Finding filesystem node operations table
-@item Finding mount table entry for the filesystem that this node is part
-of
-@end itemize
-@end itemize