From 10c1befe7e4f12dbd8f6e65b135806e78dec64fe Mon Sep 17 00:00:00 2001 From: Jennifer Averett Date: Tue, 26 Oct 1999 15:42:10 +0000 Subject: Added information on the evaluate and evaluate for make routines. Added details on how generic code starts the pathevaluation process. --- doc/filesystem/fsrequirements.t | 41 +++++++++++++++--- doc/filesystem/patheval.t | 95 ++++++++++++++++++++++++++++++++++------- 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 -- cgit v1.2.3