Subversion Repositories or1k_old

@c  COPYRIGHT (c) 1988-2002.

@c  On-Line Applications Research Corporation (OAR).

@c  All rights reserved.

@c

@c  imfs.t,v 1.9 2002/01/17 21:47:44 joel Exp

@c

@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