Changeset 4cacea0 in rtems-docs


Ignore:
Timestamp:
Oct 28, 2016, 1:01:51 AM (3 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, master
Children:
4120668
Parents:
b0f2977
git-author:
Chris Johns <chrisj@…> (10/28/16 01:01:51)
git-committer:
Chris Johns <chrisj@…> (10/28/16 01:03:57)
Message:

Fix filesystem formatting.

Location:
filesystem
Files:
11 edited

Legend:

Unmodified
Added
Removed
  • filesystem/call_development.rst

    rb0f2977 r4cacea0  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37System Call Development Notes
    48#############################
    59
    6 This set of routines represents the application's interface to files and directories
    7 under the RTEMS filesystem. All routines are compliant with POSIX standards if a
    8 specific interface has been established. The list below represents the routines that have
    9 been included as part of the application's interface.
     10This set of routines represents the application's interface to files and
     11directories under the RTEMS filesystem. All routines are compliant with POSIX
     12standards if a specific interface has been established. The list below
     13represents the routines that have been included as part of the application's
     14interface.
    1015
    1116# access()
     
    6166# unmount()
    6267
    63 The sections that follow provide developmental information concerning each
    64 of these functions.
    65 
    66 .. COMMENT: @page
     68The sections that follow provide developmental information concerning each of
     69these functions.
    6770
    6871access
     
    7578**Processing:**
    7679
    77 This routine is layered on the stat() function. It acquires the current
    78 status information for the specified file and then determines if the
    79 caller has the ability to access the file for read, write or execute
    80 according to the mode argument to this function.
    81 
    82 **Development Comments:**
    83 
    84 This routine is layered on top of the stat() function. As long as the
    85 st_mode element in the returned structure follow the standard UNIX
    86 conventions, this function should support other filesystems without
    87 alteration.
    88 
    89 .. COMMENT: @page
     80This routine is layered on the stat() function. It acquires the current status
     81information for the specified file and then determines if the caller has the
     82ability to access the file for read, write or execute according to the mode
     83argument to this function.
     84
     85**Development Comments:**
     86
     87This routine is layered on top of the stat() function. As long as the st_mode
     88element in the returned structure follow the standard UNIX conventions, this
     89function should support other filesystems without alteration.
    9090
    9191chdir
     
    9898**Processing:**
    9999
    100 This routine will determine if the pathname that we are attempting to make
    101 that current directory exists and is in fact a directory. If these
    102 conditions are met the global indication of the current directory
    103 (rtems_filesystem_current) is set to the rtems_filesystem_location_info_t
    104 structure that is returned by the rtems_filesystem_evaluate_path()
    105 routine.
    106 
    107 **Development Comments:**
    108 
    109 This routine is layered on the rtems_filesystem_evaluate_path() routine
    110 and the filesystem specific OP table function node_type().
    111 
    112 The routine node_type() must be a routine provided for each filesystem
    113 since it must access the filesystems node information to determine which
    114 of the following types the node is:
     100This routine will determine if the pathname that we are attempting to make that
     101current directory exists and is in fact a directory. If these conditions are
     102met the global indication of the current directory (rtems_filesystem_current)
     103is set to the rtems_filesystem_location_info_t structure that is returned by
     104the rtems_filesystem_evaluate_path() routine.
     105
     106**Development Comments:**
     107
     108This routine is layered on the rtems_filesystem_evaluate_path() routine and the
     109filesystem specific OP table function node_type().
     110
     111The routine ``node_type()`` must be a routine provided for each filesystem
     112since it must access the filesystems node information to determine which of the
     113following types the node is:
    115114
    116115- RTEMS_FILESYSTEM_DIRECTORY
     
    122121- RTEMS_FILESYSTEM_MEMORY_FILE
    123122
    124 This acknowledges that the form of the node management information can
    125 vary from one filesystem implementation to another.
     123This acknowledges that the form of the node management information can vary
     124from one filesystem implementation to another.
    126125
    127126RTEMS has a special global structure that maintains the current directory
    128 location. This global variable is of type rtems_filesystem_location_info_t
    129 and is called rtems_filesystem_current. This structure is not always
    130 valid. In order to determine if the structure is valid, you must first
    131 test the node_access element of this structure. If the pointer is NULL,
    132 then the structure does not contain a valid indication of what the current
    133 directory is.
    134 
    135 .. COMMENT: @page
     127location. This global variable is of type rtems_filesystem_location_info_t and
     128is called rtems_filesystem_current. This structure is not always valid. In
     129order to determine if the structure is valid, you must first test the
     130node_access element of this structure. If the pointer is NULL, then the
     131structure does not contain a valid indication of what the current directory is.
    136132
    137133chmod
     
    144140**Processing:**
    145141
    146 This routine is layered on the open(), fchmod() and close() functions. As
    147 long as the standard interpretation of the mode_t value is maintained,
    148 this routine should not need modification to support other filesystems.
    149 
    150 **Development Comments:**
    151 
    152 The routine first determines if the selected file can be open with
    153 read/write access.  This is required to allow modification of the mode
    154 associated with the selected path.
    155 
    156 The fchmod() function is used to actually change the mode of the path
    157 using the integer file descriptor returned by the open() function.
     142This routine is layered on the ``open()``, ``fchmod()`` and ``close()``
     143functions. As long as the standard interpretation of the mode_t value is
     144maintained, this routine should not need modification to support other
     145filesystems.
     146
     147**Development Comments:**
     148
     149The routine first determines if the selected file can be open with read/write
     150access.  This is required to allow modification of the mode associated with the
     151selected path.
     152
     153The ``fchmod()`` function is used to actually change the mode of the path using
     154the integer file descriptor returned by the ``open()`` function.
    158155
    159156After mode modification, the open file descriptor is closed.
    160 
    161 .. COMMENT: @page
    162157
    163158chown
     
    170165**Processing:**
    171166
    172 This routine is layered on the rtems_filesystem_evaluate_path() and the
    173 file system specific chown() routine that is specified in the OPS table
    174 for the file system.
    175 
    176 **Development Comments:**
    177 
    178 rtems_filesystem_evaluate_path() is used to determine if the path
    179 specified actually exists. If it does a rtems_filesystem_location_info_t
    180 structure will be obtained that allows the shell function to locate the
    181 OPS table that is to be used for this filesystem.
    182 
    183 It is possible that the chown() function that should be in the OPS table
    184 is not defined. A test for a non-NULL OPS table chown() entry is performed
     167This routine is layered on the ``rtems_filesystem_evaluate_path()`` and the
     168file system specific ``chown()`` routine that is specified in the OPS table for
     169the file system.
     170
     171**Development Comments:**
     172
     173``rtems_filesystem_evaluate_path()`` is used to determine if the path specified
     174actually exists. If it does a ``rtems_filesystem_location_info_t`` structure
     175will be obtained that allows the shell function to locate the OPS table that is
     176to be used for this filesystem.
     177
     178It is possible that the ``chown()`` function that should be in the OPS table is
     179not defined. A test for a non-NULL OPS table ``chown()`` entry is performed
    185180before the function is called.
    186181
    187 If the chown() function is defined in the indicated OPS table, the
    188 function is called with the rtems_filesystem_location_info_t structure
    189 returned from the path evaluation routine, the desired owner, and group
    190 information.
    191 
    192 .. COMMENT: @page
     182If the ``chown()`` function is defined in the indicated OPS table, the function
     183is called with the ``rtems_filesystem_location_info_t`` structure returned from
     184the path evaluation routine, the desired owner, and group information.
    193185
    194186close
     
    201193**Processing:**
    202194
    203 This routine will allow for the closing of both network connections and
    204 file system devices. If the file descriptor is associated with a network
    205 device, the appropriate network function handler will be selected from a
    206 table of previously registered network functions (rtems_libio_handlers)
    207 and that function will be invoked.
    208 
    209 If the file descriptor refers to an entry in the filesystem, the
    210 appropriate handler will be selected using information that has been
    211 placed in the file control block for the device (rtems_libio_t structure).
    212 
    213 **Development Comments:**
    214 
    215 rtems_file_descriptor_type examines some of the upper bits of the file
     195This routine will allow for the closing of both network connections and file
     196system devices. If the file descriptor is associated with a network device, the
     197appropriate network function handler will be selected from a table of
     198previously registered network functions (``rtems_libio_handlers``) and that
     199function will be invoked.
     200
     201If the file descriptor refers to an entry in the filesystem, the appropriate
     202handler will be selected using information that has been placed in the file
     203control block for the device (``rtems_libio_t`` structure).
     204
     205**Development Comments:**
     206
     207``rtems_file_descriptor_type`` examines some of the upper bits of the file
    216208descriptor index. If it finds that the upper bits are set in the file
    217209descriptor index, the device referenced is a network device.
    218210
    219211Network device handlers are obtained from a special registration table
    220 (rtems_libio_handlers) that is set up during network initialization. The
    221 network handler invoked and the status of the network handler will be
    222 returned to the calling process.
     212(``rtems_libio_handlers``) that is set up during network initialization. The
     213network handler invoked and the status of the network handler will be returned
     214to the calling process.
    223215
    224216If none of the upper bits are set in the file descriptor index, the file
    225217descriptor refers to an element of the RTEMS filesystem.
    226218
    227 The following sequence will be performed for any filesystem file
    228 descriptor:
    229 
    230 # Use the rtems_libio_iop() function to obtain the rtems_libio_t
     219The following sequence will be performed for any filesystem file descriptor:
     220
     221# Use the ``rtems_libio_iop()`` function to obtain the ``rtems_libio_t``
    231222  structure for the file descriptor
    232223
    233 # Range check the file descriptor using rtems_libio_check_fd()
    234 
    235 # Determine if there is actually a function in the selected handler
    236   table that processes the close() operation for the filesystem and node
    237   type selected.  This is generally done to avoid execution attempts on
    238   functions that have not been implemented.
     224# Range check the file descriptor using ``rtems_libio_check_fd()``
     225
     226# Determine if there is actually a function in the selected handler table that
     227  processes the ``close()`` operation for the filesystem and node type
     228  selected.  This is generally done to avoid execution attempts on functions
     229  that have not been implemented.
    239230
    240231# If the function has been defined it is invoked with the file control
    241232  block pointer as its argument.
    242233
    243 # The file control block that was associated with the open file
    244   descriptor is marked as free using rtems_libio_free().
    245 
    246 # The return code from the close handler is then passed back to the
    247   calling program.
    248 
    249 .. COMMENT: @page
     234# The file control block that was associated with the open file descriptor is
     235  marked as free using ``rtems_libio_free()``.
     236
     237# The return code from the close handler is then passed back to the calling
     238  program.
    250239
    251240closedir
     
    258247**Processing:**
    259248
    260 The code was obtained from the BSD group. This routine must clean up the
    261 memory resources that are required to track an open directory. The code is
    262 layered on the close() function and standard memory free() functions. It
    263 should not require alterations to support other filesystems.
    264 
    265 **Development Comments:**
    266 
    267 The routine alters the file descriptor and the index into the DIR
    268 structure to make it an invalid file descriptor. Apparently the memory
    269 that is about to be freed may still be referenced before it is
    270 reallocated.
    271 
    272 The dd_buf structure's memory is reallocated before the control structure
    273 that contains the pointer to the dd_buf region.
     249The code was obtained from the BSD group. This routine must clean up the memory
     250resources that are required to track an open directory. The code is layered on
     251the ``close()`` function and standard memory ``free()`` functions. It should
     252not require alterations to support other filesystems.
     253
     254**Development Comments:**
     255
     256The routine alters the file descriptor and the index into the DIR structure to
     257make it an invalid file descriptor. Apparently the memory that is about to be
     258freed may still be referenced before it is reallocated.
     259
     260The dd_buf structure's memory is reallocated before the control structure that
     261contains the pointer to the dd_buf region.
    274262
    275263DIR control memory is reallocated.
    276264
    277 The close() function is used to free the file descriptor index.
    278 
    279 .. COMMENT: @page
     265The ``close()`` function is used to free the file descriptor index.
    280266
    281267dup()      Unimplemented
     
    290276**Development Comments:**
    291277
    292 .. COMMENT: @page
    293 
    294278dup2()      Unimplemented
    295279=========================
     
    303287**Development Comments:**
    304288
    305 .. COMMENT: @page
    306 
    307289fchmod
    308290======
     
    325307- rtems_libio_check_permissions()
    326308
    327 - fchmod() function that is referenced by the handler table in the
    328   file control block associated with this file descriptor
    329 
    330 **Development Comments:**
    331 
    332 The routine will test to see if the file descriptor index is associated
    333 with a network connection. If it is, an error is returned from this
    334 routine.
    335 
    336 The file descriptor index is used to obtain the associated file control
    337 block.
     309- fchmod() function that is referenced by the handler table in the file control
     310  block associated with this file descriptor
     311
     312**Development Comments:**
     313
     314The routine will test to see if the file descriptor index is associated with a
     315network connection. If it is, an error is returned from this routine.
     316
     317The file descriptor index is used to obtain the associated file control block.
    338318
    339319The file descriptor value is range checked.
    340320
    341 The file control block is examined to determine if it has write
    342 permissions to allow us to alter the mode of the file.
    343 
    344 A test is made to determine if the handler table that is referenced in the
    345 file control block contains an entry for the fchmod() handler function. If
    346 it does not, an error is returned to the calling routine.
    347 
    348 If the fchmod() handler function exists, it is called with the file
    349 control block and the desired mode as parameters.
    350 
    351 .. COMMENT: @page
     321The file control block is examined to determine if it has write permissions to
     322allow us to alter the mode of the file.
     323
     324A test is made to determine if the handler table that is referenced in the file
     325control block contains an entry for the ``fchmod()`` handler function. If it does
     326not, an error is returned to the calling routine.
     327
     328If the ``fchmod()`` handler function exists, it is called with the file control
     329block and the desired mode as parameters.
    352330
    353331fcntl()
     
    361339
    362340This routine currently only interacts with the file control block. If the
    363 structure of the file control block and the associated meanings do not
    364 change, the partial implementation of fcntl() should remain unaltered for
    365 other filesystem implementations.
    366 
    367 **Development Comments:**
    368 
    369 The only commands that have been implemented are the F_GETFD and F_SETFD.
    370 The commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC bit in the``flags`` element of the file control block associated with the file
    371 descriptor index.
     341structure of the file control block and the associated meanings do not change,
     342the partial implementation of ``fcntl()`` should remain unaltered for other
     343filesystem implementations.
     344
     345**Development Comments:**
     346
     347The only commands that have been implemented are the F_GETFD and F_SETFD.  The
     348commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC bit in the``flags`` element
     349of the file control block associated with the file descriptor index.
    372350
    373351The current implementation of the function performs the sequence of
     
    382360# Perform a range check on the file descriptor index.
    383361
    384 .. COMMENT: @page
    385 
    386362fdatasync
    387363=========
     
    393369**Processing:**
    394370
    395 This routine is a template in the in memory filesystem that will route us to the
    396 appropriate handler function to carry out the fdatasync() processing. In the in
    397 memory filesystem this function is not necessary. Its function in a disk based file
    398 system that employs a memory cache is to flush all memory based data buffers to
    399 disk. It is layered on the following functions and macros:
     371This routine is a template in the in memory filesystem that will route us to
     372the appropriate handler function to carry out the fdatasync() processing. In
     373the in memory filesystem this function is not necessary. Its function in a disk
     374based file system that employs a memory cache is to flush all memory based data
     375buffers to disk. It is layered on the following functions and macros:
    400376
    401377- rtems_file_descriptor_type()
     
    407383- rtems_libio_check_permissions()
    408384
    409 - fdatasync() function that is referenced by the handler table in the
    410   file control block associated with this file descriptor
    411 
    412 **Development Comments:**
    413 
    414 The routine will test to see if the file descriptor index is associated
    415 with a network connection. If it is, an error is returned from this
    416 routine.
    417 
    418 The file descriptor index is used to obtain the associated file control
    419 block.
     385- fdatasync() function that is referenced by the handler table in the file
     386  control block associated with this file descriptor
     387
     388**Development Comments:**
     389
     390The routine will test to see if the file descriptor index is associated with a
     391network connection. If it is, an error is returned from this routine.
     392
     393The file descriptor index is used to obtain the associated file control block.
    420394
    421395The file descriptor value is range checked.
    422396
    423 The file control block is examined to determine if it has write
    424 permissions to the file.
    425 
    426 A test is made to determine if the handler table that is referenced in the
    427 file control block contains an entry for the fdatasync() handler function.
    428 If it does not an error is returned to the calling routine.
    429 
    430 If the fdatasync() handler function exists, it is called with the file
    431 control block as its parameter.
    432 
    433 .. COMMENT: @page
     397The file control block is examined to determine if it has write permissions to
     398the file.
     399
     400A test is made to determine if the handler table that is referenced in the file
     401control block contains an entry for the fdatasync() handler function.  If it
     402does not an error is returned to the calling routine.
     403
     404If the fdatasync() handler function exists, it is called with the file control
     405block as its parameter.
    434406
    435407fpathconf
     
    454426When a filesystem is mounted, a set of constants is specified for the
    455427filesystem.  These constants are stored with the mount table entry for the
    456 filesystem. These constants appear in the POSIX standard and are listed
    457 below.
     428filesystem. These constants appear in the POSIX standard and are listed below.
    458429
    459430- PCLINKMAX
     
    481452- PCSYNCIO
    482453
    483 This routine will find the mount table information associated the file
    484 control block for the specified file descriptor parameter. The mount table
    485 entry structure contains a set of filesystem specific constants that can
    486 be accessed by individual identifiers.
    487 
    488 **Development Comments:**
    489 
    490 The routine will test to see if the file descriptor index is associated
    491 with a network connection. If it is, an error is returned from this
    492 routine.
    493 
    494 The file descriptor index is used to obtain the associated file control
    495 block.
     454This routine will find the mount table information associated the file control
     455block for the specified file descriptor parameter. The mount table entry
     456structure contains a set of filesystem specific constants that can be accessed
     457by individual identifiers.
     458
     459**Development Comments:**
     460
     461The routine will test to see if the file descriptor index is associated with a
     462network connection. If it is, an error is returned from this routine.
     463
     464The file descriptor index is used to obtain the associated file control block.
    496465
    497466The file descriptor value is range checked.
    498467
    499 The file control block is examined to determine if it has read permissions
    500 to the file.
    501 
    502 Pathinfo in the file control block is used to locate the mount table entry
    503 for the filesystem associated with the file descriptor.
    504 
    505 The mount table entry contains the pathconf_limits_and_options element.
    506 This element is a table of constants that is associated with the
    507 filesystem.
     468The file control block is examined to determine if it has read permissions to
     469the file.
     470
     471Pathinfo in the file control block is used to locate the mount table entry for
     472the filesystem associated with the file descriptor.
     473
     474The mount table entry contains the pathconf_limits_and_options element.  This
     475element is a table of constants that is associated with the filesystem.
    508476
    509477The name argument is used to reference the desired constant from the
    510478pathconf_limits_and_options table.
    511479
    512 .. COMMENT: @page
    513 
    514480fstat
    515481=====
     
    522488
    523489This routine will return information concerning a file or network
    524 connection. If the file descriptor is associated with a network
    525 connection, the current implementation of ``fstat()`` will return a
    526 mode set to ``S_IFSOCK``. In a later version, this routine will map the
    527 status of a network connection to an external handler routine.
     490connection. If the file descriptor is associated with a network connection, the
     491current implementation of ``fstat()`` will return a mode set to
     492``S_IFSOCK``. In a later version, this routine will map the status of a network
     493connection to an external handler routine.
    528494
    529495If the file descriptor is associated with a node under a filesystem, the
    530 fstat()  routine will map to the fstat() function taken from the node
    531 handler table.
    532 
    533 **Development Comments:**
    534 
    535 This routine validates that the struct stat pointer is not NULL so that
    536 the return location is valid.
     496fstat() routine will map to the fstat() function taken from the node handler
     497table.
     498
     499**Development Comments:**
     500
     501This routine validates that the struct stat pointer is not NULL so that the
     502return location is valid.
    537503
    538504The struct stat is then initialized to all zeros.
    539505
    540 rtems_file_descriptor_type() is then used to determine if the file
    541 descriptor is associated with a network connection. If it is, network
    542 status processing is performed. In the current implementation, the file
    543 descriptor type processing needs to be improved. It currently just drops
    544 into the normal processing for file system nodes.
     506rtems_file_descriptor_type() is then used to determine if the file descriptor
     507is associated with a network connection. If it is, network status processing is
     508performed. In the current implementation, the file descriptor type processing
     509needs to be improved. It currently just drops into the normal processing for
     510file system nodes.
    545511
    546512If the file descriptor is associated with a node under a filesystem, the
     
    552518# Range check the file descriptor index.
    553519
    554 # Test to see if there is a non-NULL function pointer in the handler
    555   table for the fstat() function. If there is, invoke the function with the
    556   file control block and the pointer to the stat structure.
    557 
    558 .. COMMENT: @page
     520# Test to see if there is a non-NULL function pointer in the handler table for
     521  the fstat() function. If there is, invoke the function with the file control
     522  block and the pointer to the stat structure.
    559523
    560524ioctl
     
    567531**Processing:**
    568532
    569 Not defined in the POSIX 1003.1b standard but commonly supported in most
    570 UNIX and POSIX system. Ioctl() is a catchall for I/O operations. Routine
    571 is layered on external network handlers and filesystem specific handlers.
    572 The development of new filesystems should not alter the basic processing
    573 performed by this routine.
    574 
    575 **Development Comments:**
    576 
    577 The file descriptor is examined to determine if it is associated with a
    578 network device. If it is processing is mapped to an external network
    579 handler. The value returned by this handler is then returned to the
    580 calling program.
    581 
    582 File descriptors that are associated with a filesystem undergo the
    583 following processing:
    584 
    585 # The file descriptor index is used to obtain the associated file
    586   control block.
     533Not defined in the POSIX 1003.1b standard but commonly supported in most UNIX
     534and POSIX system. Ioctl() is a catchall for I/O operations. Routine is layered
     535on external network handlers and filesystem specific handlers.  The development
     536of new filesystems should not alter the basic processing performed by this
     537routine.
     538
     539**Development Comments:**
     540
     541The file descriptor is examined to determine if it is associated with a network
     542device. If it is processing is mapped to an external network handler. The value
     543returned by this handler is then returned to the calling program.
     544
     545File descriptors that are associated with a filesystem undergo the following
     546processing:
     547
     548# The file descriptor index is used to obtain the associated file control
     549  block.
    587550
    588551# The file descriptor value is range checked.
     
    592555  function. If it does not, an error is returned to the calling routine.
    593556
    594 # If the ioctl() handler function exists, it is called with the file
    595   control block, the command and buffer as its parameters.
    596 
    597 # The return code from this function is then sent to the calling
    598   routine.
    599 
    600 .. COMMENT: @page
     557# If the ioctl() handler function exists, it is called with the file control
     558  block, the command and buffer as its parameters.
     559
     560# The return code from this function is then sent to the calling routine.
    601561
    602562link
     
    609569**Processing:**
    610570
    611 This routine will establish a hard link to a file, directory or a device.
    612 The target of the hard link must be in the same filesystem as the new link
    613 being created. A link to an existing link is also permitted but the
    614 existing link is evaluated before the new link is made. This implies that
    615 links to links are reduced to links to files, directories or devices
    616 before they are made.
     571This routine will establish a hard link to a file, directory or a device.  The
     572target of the hard link must be in the same filesystem as the new link being
     573created. A link to an existing link is also permitted but the existing link is
     574evaluated before the new link is made. This implies that links to links are
     575reduced to links to files, directories or devices before they are made.
    617576
    618577**Development Comments:**
    619578
    620579Calling parameters:
    621 const char   \*existing
    622 const char   \*new
     580
     581.. code-block:: c
     582
     583    const char   *existing
     584    const char   *new
    623585
    624586link() will determine if the target of the link actually exists using
    625587rtems_filesystem_evaluate_path()
    626588
    627 rtems_filesystem_get_start_loc() is used to determine where to start the
    628 path evaluation of the new name. This macro examines the first characters
    629 of the name to see if the name of the new link starts with a
    630 rtems_filesystem_is_separator. If it does the search starts from the root
    631 of the RTEMS filesystem; otherwise the search will start from the current
     589rtems_filesystem_get_start_loc() is used to determine where to start the path
     590evaluation of the new name. This macro examines the first characters of the
     591name to see if the name of the new link starts with a
     592rtems_filesystem_is_separator. If it does the search starts from the root of
     593the RTEMS filesystem; otherwise the search will start from the current
    632594directory.
    633595
    634 The OPS table evalformake() function for the parent's filesystem is used
    635 to locate the node that will be the parent of the new link. It will also
    636 locate the start of the new path's name. This name will be used to define
    637 a child under the parent directory.
    638 
    639 If the parent is found, the routine will determine if the hard link that
    640 we are trying to create will cross a filesystem boundary. This is not
    641 permitted for hard-links.
    642 
    643 If the hard-link does not cross a filesystem boundary, a check is
    644 performed to determine if the OPS table contains an entry for the link()
    645 function.
    646 
    647 If a link() function is defined, the OPS table link() function will be
    648 called to establish the actual link within the filesystem.
    649 
    650 The return code from the OPS table link() function is returned to the
    651 calling program.
    652 
    653 .. COMMENT: @page
     596The OPS table evalformake() function for the parent's filesystem is used to
     597locate the node that will be the parent of the new link. It will also locate
     598the start of the new path's name. This name will be used to define a child
     599under the parent directory.
     600
     601If the parent is found, the routine will determine if the hard link that we are
     602trying to create will cross a filesystem boundary. This is not permitted for
     603hard-links.
     604
     605If the hard-link does not cross a filesystem boundary, a check is performed to
     606determine if the OPS table contains an entry for the link() function.
     607
     608If a link() function is defined, the OPS table link() function will be called
     609to establish the actual link within the filesystem.
     610
     611The return code from the OPS table link() function is returned to the calling
     612program.
    654613
    655614lseek
     
    662621**Processing:**
    663622
    664 This routine is layered on both external handlers and filesystem / node
    665 type specific handlers. This routine should allow for the support of new
    666 filesystems without modification.
    667 
    668 **Development Comments:**
    669 
    670 This routine will determine if the file descriptor is associated with a
    671 network device. If it is lseek will map to an external network handler.
    672 The handler will be called with the file descriptor, offset and whence as
    673 its calling parameters. The return code from the external handler will be
    674 returned to the calling routine.
     623This routine is layered on both external handlers and filesystem / node type
     624specific handlers. This routine should allow for the support of new filesystems
     625without modification.
     626
     627**Development Comments:**
     628
     629This routine will determine if the file descriptor is associated with a network
     630device. If it is lseek will map to an external network handler.  The handler
     631will be called with the file descriptor, offset and whence as its calling
     632parameters. The return code from the external handler will be returned to the
     633calling routine.
    675634
    676635If the file descriptor is not associated with a network connection, it is
    677 associated with a node in a filesystem. The following steps will be
    678 performed for filesystem nodes:
    679 
    680 # The file descriptor is used to obtain the file control block for the
    681   node.
     636associated with a node in a filesystem. The following steps will be performed
     637for filesystem nodes:
     638
     639# The file descriptor is used to obtain the file control block for the node.
    682640
    683641# The file descriptor is range checked.
    684642
    685 # The offset element of the file control block is altered as indicated
    686   by the offset and whence calling parameters
    687 
    688 # The handler table in the file control block is examined to determine
    689   if it contains an entry for the lseek() function. If it does not an error
    690   is returned to the calling program.
    691 
    692 # The lseek() function from the designated handler table is called
    693   with the file control block, offset and whence as calling arguments
    694 
    695 # The return code from the lseek() handler function is returned to the
    696   calling program
    697 
    698 .. COMMENT: @page
     643# The offset element of the file control block is altered as indicated by the
     644  offset and whence calling parameters
     645
     646# The handler table in the file control block is examined to determine if it
     647  contains an entry for the lseek() function. If it does not an error is
     648  returned to the calling program.
     649
     650# The lseek() function from the designated handler table is called with the
     651  file control block, offset and whence as calling arguments
     652
     653# The return code from the lseek() handler function is returned to the calling
     654  program
    699655
    700656mkdir
     
    714670See mknod() for developmental comments.
    715671
    716 .. COMMENT: @page
    717 
    718672mkfifo
    719673======
     
    725679**Processing:**
    726680
    727 This routine attempts to create a FIFO node under the filesystem. The
    728 routine is layered the mknod() function.
     681This routine attempts to create a FIFO node under the filesystem. The routine
     682is layered the mknod() function.
    729683
    730684**Development Comments:**
     
    743697**Processing:**
    744698
    745 This function will allow for the creation of the following types of nodes
    746 under the filesystem:
     699This function will allow for the creation of the following types of nodes under
     700the filesystem:
    747701
    748702- directories
     
    757711
    758712At the present time, an attempt to create a FIFO will result in an ENOTSUP
    759 error to the calling function. This routine is layered the filesystem
    760 specific routines evalformake and mknod. The introduction of a new
    761 filesystem must include its own evalformake and mknod function to support
    762 the generic mknod() function.  Under this condition the generic mknod()
    763 function should accommodate other filesystem types without alteration.
    764 
    765 **Development Comments:**
    766 
    767 Test for nodal types - I thought that this test should look like the
    768 following code:
    769 .. code:: c
    770 
    771     if ( (mode & S_IFDIR) = = S_IFDIR) \||
    772     (mode & S_IFREG) = = S_IFREG) \||
    773     (mode & S_IFCHR) = = S_IFCHR) \||
    774     (mode & S_IFBLK) = = S_IFBLK) \||
    775     (mode & S_IFIFO) = = S_IFIFO))
    776     Set_errno_and_return_minus_one (EINVAL);
     713error to the calling function. This routine is layered the filesystem specific
     714routines evalformake and mknod. The introduction of a new filesystem must
     715include its own evalformake and mknod function to support the generic mknod()
     716function.  Under this condition the generic mknod() function should accommodate
     717other filesystem types without alteration.
     718
     719**Development Comments:**
     720
     721Test for nodal types - I thought that this test should look like the following
     722code:
     723
     724.. code-block:: c
     725
     726    if ( (mode & S_IFDIR) = = S_IFDIR) ||
     727         (mode & S_IFREG) = = S_IFREG) ||
     728         (mode & S_IFCHR) = = S_IFCHR) ||
     729         (mode & S_IFBLK) = = S_IFBLK) ||
     730         (mode & S_IFIFO) = = S_IFIFO))
     731            Set_errno_and_return_minus_one (EINVAL);
    777732
    778733Where:
     
    788743Determine if the pathname that we are trying to create starts at the root
    789744directory or is relative to the current directory using the
    790 rtems_filesystem_get_start_loc()  function.
    791 
    792 Determine if the pathname leads to a valid directory that can be accessed
    793 for the creation of a node.
    794 
    795 If the pathname is a valid location to create a node, verify that a
    796 filesystem specific mknod() function exists.
    797 
    798 If the mknod() function exists, call the filesystem specific mknod()
    799 function.  Pass the name, mode, device type and the location information
    800 associated with the directory under which the node will be created.
    801 
    802 .. COMMENT: @page
     745``rtems_filesystem_get_start_loc()`` function.
     746
     747Determine if the pathname leads to a valid directory that can be accessed for
     748the creation of a node.
     749
     750If the pathname is a valid location to create a node, verify that a filesystem
     751specific mknod() function exists.
     752
     753If the mknod() function exists, call the filesystem specific mknod() function.
     754Pass the name, mode, device type and the location information associated with
     755the directory under which the node will be created.
    803756
    804757mount
     
    811764Arguments (Not a standard POSIX call):
    812765
    813 rtems_filesystem_mount_table_entry_t   \**mt_entry,
    814 
    815 If the mount operation is successful, this pointer to a pointer will be
    816 set to reference the mount table chain entry that has been allocated for
    817 this file system mount.
    818 
    819 rtems_filesystem_operations_table   \*fs_ops,
    820 
    821 This is a pointer to a table of functions that are associated with the
    822 file system that we are about to mount. This is the mechanism to selected
    823 file system type without keeping a dynamic database of all possible file
    824 system types that are valid for the mount operation. Using this method, it
    825 is only necessary to configure the filesystems that we wish to use into
    826 the RTEMS build. Unused filesystems types will not be drawn into the
    827 build.
    828 
    829 char                      \*fsoptions,
     766.. code-block:: c
     767
     768    rtems_filesystem_mount_table_entry_t   **mt_entry,
     769
     770If the mount operation is successful, this pointer to a pointer will be set to
     771reference the mount table chain entry that has been allocated for this file
     772system mount.
     773
     774.. code-block:: c
     775
     776    rtems_filesystem_operations_table   *fs_ops,
     777
     778This is a pointer to a table of functions that are associated with the file
     779system that we are about to mount. This is the mechanism to selected file
     780system type without keeping a dynamic database of all possible file system
     781types that are valid for the mount operation. Using this method, it is only
     782necessary to configure the filesystems that we wish to use into the RTEMS
     783build. Unused filesystems types will not be drawn into the build.
     784
     785.. code-block:: c
     786
     787    char                      *fsoptions,
    830788
    831789This argument points to a string that selects mounting for read only
    832790access or read/write access. Valid states are "RO" and "RW"
    833791
    834 char                      \*device,
    835 
    836 This argument is reserved for the name of a device that will be used to
    837 access the filesystem information. Current filesystem implementations are
    838 memory based and do not require a device to access filesystem information.
    839 
    840 char                      \*mount_point
    841 
    842 This is a pathname to a directory in a currently mounted filesystem that
    843 allows read, write and execute permissions.  If successful, the node found
    844 by evaluating this name, is stored in the mt_entry.
    845 
    846 **Processing:**
    847 
    848 This routine will handle the mounting of a filesystem on a mount point. If
    849 the operation is successful, a pointer to the mount table chain entry
    850 associated with the mounted filesystem will be returned to the calling
    851 function. The specifics about the processing required at the mount point
    852 and within the filesystem being mounted is isolated in the filesystem
    853 specific mount() and fsmount_me()  functions. This allows the generic
    854 mount() function to remain unaltered even if new filesystem types are
    855 introduced.
     792.. code-block:: c
     793
     794    char                      *device,
     795
     796This argument is reserved for the name of a device that will be used to access
     797the filesystem information. Current filesystem implementations are memory based
     798and do not require a device to access filesystem information.
     799
     800.. code-block:: c
     801
     802    char                      *mount_point
     803
     804This is a pathname to a directory in a currently mounted filesystem that allows
     805read, write and execute permissions.  If successful, the node found by
     806evaluating this name, is stored in the mt_entry.
     807
     808**Processing:**
     809
     810This routine will handle the mounting of a filesystem on a mount point. If the
     811operation is successful, a pointer to the mount table chain entry associated
     812with the mounted filesystem will be returned to the calling function. The
     813specifics about the processing required at the mount point and within the
     814filesystem being mounted is isolated in the filesystem specific mount() and
     815fsmount_me() functions. This allows the generic mount() function to remain
     816unaltered even if new filesystem types are introduced.
    856817
    857818**Development Comments:**
     
    865826temporary mount table entry are initialized.
    866827
    867 If a mount point is specified: The mount point is examined to determine
    868 that it is a directory and also has the appropriate permissions to allow a
    869 filesystem to be mounted.
     828If a mount point is specified: The mount point is examined to determine that it
     829is a directory and also has the appropriate permissions to allow a filesystem
     830to be mounted.
    870831
    871832The current mount table chain is searched to determine that there is not
    872833another filesystem mounted at the mount point we are trying to mount onto.
    873834
    874 If a mount function is defined in the ops table for the filesystem
    875 containing the mount point, it is called at this time.
    876 
    877 If no mount point is specified: Processing if performed to set up the
    878 mount table chain entry as the base filesystem.
    879 
    880 If the fsmount_me() function is specified for ops-table of the filesystem
    881 being mounted, that function is called to initialize for the new
    882 filesystem.
    883 
    884 On successful completion, the temporary mount table entry will be placed
    885 on the mount table chain to record the presence of the mounted filesystem.
    886 
    887 .. COMMENT: @page
     835If a mount function is defined in the ops table for the filesystem containing
     836the mount point, it is called at this time.
     837
     838If no mount point is specified: Processing if performed to set up the mount
     839table chain entry as the base filesystem.
     840
     841If the fsmount_me() function is specified for ops-table of the filesystem being
     842mounted, that function is called to initialize for the new filesystem.
     843
     844On successful completion, the temporary mount table entry will be placed on the
     845mount table chain to record the presence of the mounted filesystem.
    888846
    889847open
     
    897855
    898856This routine is layered on both RTEMS calls and filesystem specific
    899 implementations of the open() function. These functional interfaces should
    900 not change for new filesystems and therefore this code should be stable as
    901 new file systems are introduced.
    902 
    903 **Development Comments:**
    904 
    905 This routine will allocate a file control block for the file or device
    906 that we are about to open.
     857implementations of the open() function. These functional interfaces should not
     858change for new filesystems and therefore this code should be stable as new file
     859systems are introduced.
     860
     861**Development Comments:**
     862
     863This routine will allocate a file control block for the file or device that we
     864are about to open.
    907865
    908866It will then test to see if the pathname exists. If it does a
    909867rtems_filesystem_location_info_t data structure will be filled out. This
    910 structure contains information that associates node information,
    911 filesystem specific functions and mount table chain information with the
    912 pathname.
    913 
    914 If the create option has been it will attempt to create a node for a
    915 regular file along the specified path. If a file already exists along this
    916 path, an error will be generated; otherwise, a node will be allocated for
    917 the file under the filesystem that contains the pathname. When a new node
    918 is created, it is also evaluated so that an appropriate
    919 rtems_filesystem_location_info_t data structure can be filled out for the
    920 newly created node.
    921 
    922 If the file exists or the new file was created successfully, the file
    923 control block structure will be initialized with handler table
    924 information, node information and the rtems_filesystem_location_info_t
    925 data structure that describes the node and filesystem data in detail.
    926 
    927 If an open() function exists in the filesystem specific handlers table for
    928 the node that we are trying to open, it will be called at this time.
    929 
    930 If any error is detected in the process, cleanup is performed. It consists
    931 of freeing the file control block structure that was allocated at the
    932 beginning of the generic open() routine.
     868structure contains information that associates node information, filesystem
     869specific functions and mount table chain information with the pathname.
     870
     871If the create option has been it will attempt to create a node for a regular
     872file along the specified path. If a file already exists along this path, an
     873error will be generated; otherwise, a node will be allocated for the file under
     874the filesystem that contains the pathname. When a new node is created, it is
     875also evaluated so that an appropriate rtems_filesystem_location_info_t data
     876structure can be filled out for the newly created node.
     877
     878If the file exists or the new file was created successfully, the file control
     879block structure will be initialized with handler table information, node
     880information and the rtems_filesystem_location_info_t data structure that
     881describes the node and filesystem data in detail.
     882
     883If an open() function exists in the filesystem specific handlers table for the
     884node that we are trying to open, it will be called at this time.
     885
     886If any error is detected in the process, cleanup is performed. It consists of
     887freeing the file control block structure that was allocated at the beginning of
     888the generic open() routine.
    933889
    934890On a successful open(), the index into the file descriptor table will be
    935891calculated and returned to the calling routine.
    936892
    937 .. COMMENT: @page
    938 
    939893opendir
    940894=======
     
    946900**Processing:**
    947901
    948 This routine will attempt to open a directory for read access. It will
    949 setup a DIR control structure that will be used to access directory
    950 information. This routine is layered on the generic open() routine and
    951 filesystem specific directory processing routines.
     902This routine will attempt to open a directory for read access. It will setup a
     903DIR control structure that will be used to access directory information. This
     904routine is layered on the generic open() routine and filesystem specific
     905directory processing routines.
    952906
    953907**Development Comments:**
    954908
    955909The BSD group provided this routine.
    956 
    957 .. COMMENT: @page
    958910
    959911pathconf
     
    966918**Processing:**
    967919
    968 This routine will obtain the value of one of the path configuration
    969 parameters and return it to the calling routine. It is layered on the
    970 generic open() and fpathconf()  functions. These interfaces should not
    971 change with the addition of new filesystem types.
     920This routine will obtain the value of one of the path configuration parameters
     921and return it to the calling routine. It is layered on the generic open() and
     922fpathconf() functions. These interfaces should not change with the addition of
     923new filesystem types.
    972924
    973925**Development Comments:**
     
    975927This routine will try to open the file indicated by path.
    976928
    977 If successful, the file descriptor will be used to access the pathconf
    978 value specified by ``name`` using the fpathconf() function.
     929If successful, the file descriptor will be used to access the pathconf value
     930specified by ``name`` using the fpathconf() function.
    979931
    980932The file that was accessed is then closed.
    981 
    982 .. COMMENT: @page
    983933
    984934read
     
    991941**Processing:**
    992942
    993 This routine is layered on a set of RTEMS calls and filesystem specific
    994 read operations. The functions are layered in such a way as to isolate
    995 them from change as new filesystems are introduced.
     943This routine is layered on a set of RTEMS calls and filesystem specific read
     944operations. The functions are layered in such a way as to isolate them from
     945change as new filesystems are introduced.
    996946
    997947**Development Comments:**
     
    999949This routine will examine the type of file descriptor it is sent.
    1000950
    1001 If the file descriptor is associated with a network device, the read
    1002 function will be mapped to a special network handler. The return code from
    1003 the network handler will then be sent as the return code from generic
    1004 read() function.
     951If the file descriptor is associated with a network device, the read function
     952will be mapped to a special network handler. The return code from the network
     953handler will then be sent as the return code from generic read() function.
    1005954
    1006955For file descriptors that are associated with the filesystem the following
     
    1017966# Check the file control block to see if we have permissions to read
    1018967
    1019 # If there is a read function in the handler table, invoke the handler
    1020   table read() function
    1021 
    1022 # Use the return code from the handler table read function(number of
    1023   bytes read) to increment the offset element of the file control block
     968# If there is a read function in the handler table, invoke the handler table
     969  read() function
     970
     971# Use the return code from the handler table read function(number of bytes
     972  read) to increment the offset element of the file control block
    1024973
    1025974# Return the number of bytes read to the calling program
    1026 
    1027 .. COMMENT: @page
    1028975
    1029976readdir
     
    1036983**Processing:**
    1037984
    1038 This routine was acquired from the BSD group. It has not been altered from
    1039 its original form.
     985This routine was acquired from the BSD group. It has not been altered from its
     986original form.
    1040987
    1041988**Development Comments:**
     
    1048995function has been mapped to the Imfs_dir_read() function.
    1049996
    1050 .. COMMENT: @page
    1051 
    1052997unmount
    1053998=======
     
    10591004**Processing:**
    10601005
    1061 This routine will attempt to dismount a mounted filesystem and then free
    1062 all resources that were allocated for the management of that filesystem.
    1063 
    1064 **Development Comments:**
    1065 
    1066 - This routine will determine if there are any filesystems currently
    1067   mounted under the filesystem that we are trying to dismount. This would
    1068   prevent the dismount of the filesystem.
    1069 
    1070 - It will test to see if the current directory is in the filesystem
    1071   that we are attempting to dismount. This would prevent the dismount of the
    1072   filesystem.
    1073 
    1074 - It will scan all the currently open file descriptors to determine is
    1075   there is an open file descriptor to a file in the filesystem that we are
    1076   attempting to unmount().
    1077 
    1078 If the above preconditions are met then the following sequence is
    1079 performed:
    1080 
    1081 # Call the filesystem specific unmount() function for the filesystem
    1082   that contains the mount point. This routine should indicate that the mount
    1083   point no longer has a filesystem mounted below it.
     1006This routine will attempt to dismount a mounted filesystem and then free all
     1007resources that were allocated for the management of that filesystem.
     1008
     1009**Development Comments:**
     1010
     1011- This routine will determine if there are any filesystems currently mounted
     1012  under the filesystem that we are trying to dismount. This would prevent the
     1013  dismount of the filesystem.
     1014
     1015- It will test to see if the current directory is in the filesystem that we are
     1016  attempting to dismount. This would prevent the dismount of the filesystem.
     1017
     1018- It will scan all the currently open file descriptors to determine is there is
     1019  an open file descriptor to a file in the filesystem that we are attempting to
     1020  unmount().
     1021
     1022If the above preconditions are met then the following sequence is performed:
     1023
     1024# Call the filesystem specific unmount() function for the filesystem that
     1025  contains the mount point. This routine should indicate that the mount point
     1026  no longer has a filesystem mounted below it.
    10841027
    10851028# Call the filesystem specific fsunmount_me() function for the mounted
    1086   filesystem that we are trying to unmount(). This routine should clean up
    1087   any resources that are no longer needed for the management of the file
    1088   system being un-mounted.
    1089 
    1090 # Extract the mount table entry for the filesystem that was just
    1091   dismounted from the mount table chain.
     1029  filesystem that we are trying to unmount(). This routine should clean up any
     1030  resources that are no longer needed for the management of the file system
     1031  being un-mounted.
     1032
     1033# Extract the mount table entry for the filesystem that was just dismounted
     1034  from the mount table chain.
    10921035
    10931036# Free the memory associated with the extracted mount table entry.
    1094 
    1095 .. COMMENT: @page
    10961037
    10971038eval
     
    11101051XXX
    11111052
    1112 .. COMMENT: @page
    1113 
    11141053getdentsc
    11151054=========
     
    11261065
    11271066XXX
    1128 
    1129 .. COMMENT: COPYRIGHT (c) 1988-2002.
    1130 
    1131 .. COMMENT: On-Line Applications Research Corporation (OAR).
    1132 
    1133 .. COMMENT: All rights reserved.
    1134 
  • filesystem/command_and_variable.rst

    rb0f2977 r4cacea0  
    55
    66There are currently no Command and Variable Index entries.
    7 
    8 .. COMMENT: @printindex fn
    9 
  • filesystem/fileystem_implmentation.rst

    rb0f2977 r4cacea0  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37Filesystem Implementation Requirements
     
    1014=======
    1115
    12 The RTEMS filesystem framework was intended to be compliant with the
    13 POSIX Files and Directories interface standard. The following filesystem
     16The RTEMS filesystem framework was intended to be compliant with the POSIX
     17Files and Directories interface standard. The following filesystem
    1418characteristics resulted in a functional switching layer.
    15 .. code:: c
     19
     20.. code-block:: shell
    1621
    1722    Figure of the Filesystem Functional Layering goes here.
    1823    This figure includes networking and disk caching layering.
    1924
    20 # Application programs are presented with a standard set of POSIX
    21   compliant functions that allow them to interface with the files, devices
    22   and directories in the filesystem. The interfaces to these routines do
    23   not reflect the type of subordinate filesystem implementation in which
    24   the file will be found.
    25 
    26 # The filesystem framework developed under RTEMS allows for mounting
    27   filesystem of different types under the base filesystem.
    28 
    29 # The mechanics of locating file information may be quite different
    30   between filesystem types.
    31 
    32 # The process of locating a file may require crossing filesystem
    33   boundaries.
    34 
    35 # The transitions between filesystem and the processing required to
    36   access information in different filesystem is not visible at the level
    37   of the POSIX function call.
    38 
    39 # The POSIX interface standard provides file access by character
    40   pathname to the file in some functions and through an integer file
    41   descriptor in other functions.
    42 
    43 # The nature of the integer file descriptor and its associated
    44   processing is operating system and filesystem specific.
    45 
    46 # Directory and device information must be processed with some of the
    47   same routines that apply to files.
    48 
    49 # The form and content of directory and device information differs
    50   greatly from that of a regular file.
     25# Application programs are presented with a standard set of POSIX compliant
     26  functions that allow them to interface with the files, devices and
     27  directories in the filesystem. The interfaces to these routines do not
     28  reflect the type of subordinate filesystem implementation in which the file
     29  will be found.
     30
     31# The filesystem framework developed under RTEMS allows for mounting filesystem
     32  of different types under the base filesystem.
     33
     34# The mechanics of locating file information may be quite different between
     35  filesystem types.
     36
     37# The process of locating a file may require crossing filesystem boundaries.
     38
     39# The transitions between filesystem and the processing required to access
     40  information in different filesystem is not visible at the level of the POSIX
     41  function call.
     42
     43# The POSIX interface standard provides file access by character pathname to
     44  the file in some functions and through an integer file descriptor in other
     45  functions.
     46
     47# The nature of the integer file descriptor and its associated processing is
     48  operating system and filesystem specific.
     49
     50# Directory and device information must be processed with some of the same
     51  routines that apply to files.
     52
     53# The form and content of directory and device information differs greatly from
     54  that of a regular file.
    5155
    5256# Files, directories and devices represent elements (nodes) of a tree
     
    5761  interface routines.
    5862
    59 .. code:: c
     63.. code-block:: shell
    6064
    6165    Figure of the Filesystem Functional Layering goes here.
    6266    This figure focuses on the Base Filesystem and IMFS.
    6367
    64 .. code:: c
     68.. code-block:: shell
    6569
    6670    Figure of the IMFS Memfile control blocks
    6771
     72.. _file-and-directory-removal-constraints:
    6873
    6974File and Directory Removal Constraints
     
    7479- If a node is a directory with children it cannot be removed.
    7580
    76 - The root node of any filesystem, whether the base filesystem or a
    77   mounted filesystem, cannot be removed.
    78 
    79 - A node that is a directory that is acting as the mount point of a file
    80   system cannot be removed.
    81 
    82 - On filesystems supporting hard links, a link count is maintained.
    83   Prior to node removal, the node's link count is decremented by one.  The
    84   link count must be less than one to allow for removal of the node.
     81- The root node of any filesystem, whether the base filesystem or a mounted
     82  filesystem, cannot be removed.
     83
     84- A node that is a directory that is acting as the mount point of a file system
     85  cannot be removed.
     86
     87- On filesystems supporting hard links, a link count is maintained.  Prior to
     88  node removal, the node's link count is decremented by one.  The link count
     89  must be less than one to allow for removal of the node.
    8590
    8691API Layering
     
    9095----------------------------------------------------------------
    9196
    92 The list of generic system calls includes the routines open(), read(),
    93 write(), close(), etc..
    94 
    95 The Files and Directories section of the POSIX Application Programs
    96 Interface specifies a set of functions with calling arguments that are
    97 used to gain access to the information in a filesystem. To the
    98 application program, these functions allow access to information in any
    99 mounted filesystem without explicit knowledge of the filesystem type or
    100 the filesystem mount configuration. The following are functions that are
    101 provided to the application:
     97The list of generic system calls includes the routines open(), read(), write(),
     98close(), etc..
     99
     100The Files and Directories section of the POSIX Application Programs Interface
     101specifies a set of functions with calling arguments that are used to gain
     102access to the information in a filesystem. To the application program, these
     103functions allow access to information in any mounted filesystem without
     104explicit knowledge of the filesystem type or the filesystem mount
     105configuration. The following are functions that are provided to the
     106application:
    102107
    103108# access()
     
    171176# write()
    172177
    173 The filesystem's type as well as the node type within the filesystem
    174 determine the nature of the processing that must be performed for each of
    175 the functions above. The RTEMS filesystem provides a framework that
    176 allows new filesystem to be developed and integrated without alteration
    177 to the basic framework.
    178 
    179 To provide the functional switching that is required, each of the POSIX
    180 file and directory functions have been implemented as a shell function.
    181 The shell function adheres to the POSIX interface standard. Within this
    182 functional shell, filesystem and node type information is accessed which
    183 is then used to invoke the appropriate filesystem and node type specific
    184 routine to process the POSIX function call.
     178The filesystem's type as well as the node type within the filesystem determine
     179the nature of the processing that must be performed for each of the functions
     180above. The RTEMS filesystem provides a framework that allows new filesystem to
     181be developed and integrated without alteration to the basic framework.
     182
     183To provide the functional switching that is required, each of the POSIX file
     184and directory functions have been implemented as a shell function.  The shell
     185function adheres to the POSIX interface standard. Within this functional shell,
     186filesystem and node type information is accessed which is then used to invoke
     187the appropriate filesystem and node type specific routine to process the POSIX
     188function call.
    185189
    186190File/Device/Directory function access via file control block - rtems_libio_t structure
    187191--------------------------------------------------------------------------------------
    188192
    189 The POSIX open() function returns an integer file descriptor that is used
    190 as a reference to file control block information for a specific file. The
    191 file control block contains information that is used to locate node, file
    192 system, mount table and functional handler information. The diagram in
    193 Figure 8 depicts the relationship between and among the following
    194 components.
     193The POSIX open() function returns an integer file descriptor that is used as a
     194reference to file control block information for a specific file. The file
     195control block contains information that is used to locate node, file system,
     196mount table and functional handler information. The diagram in Figure 8 depicts
     197the relationship between and among the following components.
    195198
    196199# File Descriptor Table
    197200  This is an internal RTEMS structure that tracks all currently defined file
    198201  descriptors in the system. The index that is returned by the file open()
    199   operation references a slot in this table. The slot contains a pointer to
    200   the file descriptor table entry for this file. The rtems_libio_t structure
     202  operation references a slot in this table. The slot contains a pointer to the
     203  file descriptor table entry for this file. The rtems_libio_t structure
    201204  represents the file control block.
    202205
    203206# Allocation of entry in the File Descriptor Table
    204   Access to the file descriptor table is controlled through a semaphore that
    205   is implemented using the rtems_libio_allocate() function. This routine
    206   will grab a semaphore and then scan the file control blocks to determine
    207   which slot is free for use. The first free slot is marked as used and the
    208   index to this slot is returned as the file descriptor for the open()
    209   request. After the alterations have been made to the file control block
    210   table, the semaphore is released to allow further operations on the table.
    211 
    212 # Maximum number of entries in the file descriptor table is
    213   configurable through the src/exec/sapi/headers/confdefs.h file. If the
    214   CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS constant is defined its value
    215   will represent the maximum number of file descriptors that are allowed.
    216   If CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS is not specified a default
    217   value of 20 will be used as the maximum number of file descriptors
    218   allowed.
     207  Access to the file descriptor table is controlled through a semaphore that is
     208  implemented using the rtems_libio_allocate() function. This routine will grab
     209  a semaphore and then scan the file control blocks to determine which slot is
     210  free for use. The first free slot is marked as used and the index to this
     211  slot is returned as the file descriptor for the open() request. After the
     212  alterations have been made to the file control block table, the semaphore is
     213  released to allow further operations on the table.
     214
     215# Maximum number of entries in the file descriptor table is configurable
     216  through the src/exec/sapi/headers/confdefs.h file. If the
     217  CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS constant is defined its value will
     218  represent the maximum number of file descriptors that are allowed.  If
     219  CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS is not specified a default value of
     220  20 will be used as the maximum number of file descriptors allowed.
    219221
    220222# File control block - rtems_libio_t structure
    221223
    222   .. code:: c
     224  .. code-block:: c
    223225
    224226      struct rtems_libio_tt {
    225       rtems_driver_name_t              \*driver;
    226       off_t                             size;
    227       off_t                             offset;
    228       unsigned32                        flags;
    229       rtems_filesystem_location_info_t  pathinfo;
    230       Objects_Id                        sem;
    231       unsigned32                        data0;
    232       void                              data1;
    233       void                              file_info;
    234       rtems_filesystem_file_handlers_r  handlers;
     227          rtems_driver_name_t              *driver;
     228          off_t                             size;
     229          off_t                             offset;
     230          unsigned32                        flags;
     231          rtems_filesystem_location_info_t  pathinfo;
     232          Objects_Id                        sem;
     233          unsigned32                        data0;
     234          void                              data1;
     235          void                              file_info;
     236          rtems_filesystem_file_handlers_r  handlers;
    235237      };
    236238
     
    238240  The following fields are important for regular file and directory access:
    239241
    240   - Size - For a file this represents the number of bytes currently
    241     stored in a file. For a directory this field is not filled in.
    242 
    243   - Offset - For a file this is the byte file position index relative to
    244     the start of the file. For a directory this is the byte offset into a
    245     sequence of dirent structures.
    246 
    247   - Pathinfo - This is a structure that provides a pointer to node
    248     information, OPS table functions, Handler functions and the mount table
    249     entry associated with this node.
    250 
    251   - file_info - A pointer to node information that is used by Handler
    252     functions
    253 
    254   - handlers - A pointer to a table of handler functions that operate on
    255     a file, device or directory through a file descriptor index
     242  - Size - For a file this represents the number of bytes currently stored in a
     243    file. For a directory this field is not filled in.
     244
     245  - Offset - For a file this is the byte file position index relative to the
     246    start of the file. For a directory this is the byte offset into a sequence
     247    of dirent structures.
     248
     249  - Pathinfo - This is a structure that provides a pointer to node information,
     250    OPS table functions, Handler functions and the mount table entry associated
     251    with this node.
     252
     253  - file_info - A pointer to node information that is used by Handler functions
     254
     255  - handlers - A pointer to a table of handler functions that operate on a
     256    file, device or directory through a file descriptor index
    256257
    257258File/Directory function access via rtems_filesystem_location_info_t structure
     
    261262information to process nodes under a mounted filesystem.
    262263
    263 .. code:: c
     264.. code-block:: c
    264265
    265266    struct rtems_filesystem_location_info_tt {
    266     void                                     \*node_access;
    267     rtems_filesystem_file_handlers_r         \*handlers;
    268     rtems_filesystem_operations_table        \*ops;
    269     rtems_filesystem_mount_table_entry_t     \*mt_entry;
     267        void                                     *node_access;
     268        rtems_filesystem_file_handlers_r         *handlers;
     269        rtems_filesystem_operations_table        *ops;
     270        rtems_filesystem_mount_table_entry_t     *mt_entry;
    270271    };
    271272
    272 It contains a void pointer to filesystem specific nodal structure,
    273 pointers to the OPS table for the filesystem that contains the node, the
    274 node type specific handlers for the node and a reference pointer to the
    275 mount table entry associated with the filesystem containing the node
     273It contains a void pointer to filesystem specific nodal structure, pointers to
     274the OPS table for the filesystem that contains the node, the node type specific
     275handlers for the node and a reference pointer to the mount table entry
     276associated with the filesystem containing the node
    276277
    277278Operation Tables
    278279================
    279280
    280 Filesystem specific operations are invoked indirectly.  The set of
    281 routines that implement the filesystem are configured into two tables.
    282 The Filesystem Handler Table has routines that are specific to a
    283 filesystem but remain constant regardless of the actual file type.
    284 The File Handler Table has routines that are both filesystem and file type
    285 specific.
     281Filesystem specific operations are invoked indirectly.  The set of routines
     282that implement the filesystem are configured into two tables.  The Filesystem
     283Handler Table has routines that are specific to a filesystem but remain
     284constant regardless of the actual file type.  The File Handler Table has
     285routines that are both filesystem and file type specific.
    286286
    287287Filesystem Handler Table Functions
     
    289289
    290290OPS table functions are defined in a ``rtems_filesystem_operations_table``
    291 structure.  It defines functions that are specific to a given filesystem.
    292 One table exists for each filesystem that is supported in the RTEMS
     291structure.  It defines functions that are specific to a given filesystem.  One
     292table exists for each filesystem that is supported in the RTEMS
    293293configuration. The structure definition appears below and is followed by
    294294general developmental information on each of the functions contained in this
    295295function management structure.
    296296
    297 .. code:: c
     297.. code-block:: c
    298298
    299299    typedef struct {
    300     rtems_filesystem_evalpath_t        evalpath;
    301     rtems_filesystem_evalmake_t        evalformake;
    302     rtems_filesystem_link_t            link;
    303     rtems_filesystem_unlink_t          unlink;
    304     rtems_filesystem_node_type_t       node_type;
    305     rtems_filesystem_mknod_t           mknod;
    306     rtems_filesystem_rmnod_t           rmnod;
    307     rtems_filesystem_chown_t           chown;
    308     rtems_filesystem_freenode_t        freenod;
    309     rtems_filesystem_mount_t           mount;
    310     rtems_filesystem_fsmount_me_t      fsmount_me;
    311     rtems_filesystem_unmount_t         unmount;
    312     rtems_filesystem_fsunmount_me_t    fsunmount_me;
    313     rtems_filesystem_utime_t           utime;
    314     rtems_filesystem_evaluate_link_t   eval_link;
    315     rtems_filesystem_symlink_t         symlink;
     300        rtems_filesystem_evalpath_t        evalpath;
     301        rtems_filesystem_evalmake_t        evalformake;
     302        rtems_filesystem_link_t            link;
     303        rtems_filesystem_unlink_t          unlink;
     304        rtems_filesystem_node_type_t       node_type;
     305        rtems_filesystem_mknod_t           mknod;
     306        rtems_filesystem_rmnod_t           rmnod;
     307        rtems_filesystem_chown_t           chown;
     308        rtems_filesystem_freenode_t        freenod;
     309        rtems_filesystem_mount_t           mount;
     310        rtems_filesystem_fsmount_me_t      fsmount_me;
     311        rtems_filesystem_unmount_t         unmount;
     312        rtems_filesystem_fsunmount_me_t    fsunmount_me;
     313        rtems_filesystem_utime_t           utime;
     314        rtems_filesystem_evaluate_link_t   eval_link;
     315        rtems_filesystem_symlink_t         symlink;
    316316    } rtems_filesystem_operations_table;
    317 
    318 .. COMMENT: @page
    319317
    320318evalpath Handler
     
    327325**Arguments:**
    328326
    329 .. code:: c
    330 
    331     const char                        \*pathname,      /* IN     \*/
    332     int                                flags,         /* IN     \*/
    333     rtems_filesystem_location_info_t  \*pathloc        /* IN/OUT \*/
    334 
    335 **Description:**
    336 
    337 This routine is responsible for evaluating the pathname passed in
    338 based upon the flags and the valid ``rthems_filesystem_location_info_t``.
    339 Additionally, it must make any changes to pathloc necessary to identify
    340 the pathname node.  This should include calling the evalpath for a mounted
    341 filesystem, if the given filesystem supports the mount command.
    342 
    343 This routine returns a 0 if the evaluation was successful.
    344 Otherwise, it returns a -1 and sets errno to the correct error.
     327.. code-block:: c
     328
     329    const char                        *pathname,      /* IN     */
     330    int                                flags,         /* IN     */
     331    rtems_filesystem_location_info_t  *pathloc        /* IN/OUT */
     332
     333**Description:**
     334
     335This routine is responsible for evaluating the pathname passed in based upon
     336the flags and the valid ``rthems_filesystem_location_info_t``.  Additionally,
     337it must make any changes to pathloc necessary to identify the pathname node.
     338This should include calling the evalpath for a mounted filesystem, if the given
     339filesystem supports the mount command.
     340
     341This routine returns a 0 if the evaluation was successful.  Otherwise, it
     342returns a -1 and sets errno to the correct error.
    345343
    346344This routine is required and should NOT be set to NULL.
    347 
    348 .. COMMENT: @page
    349345
    350346evalformake Handler
     
    357353**Arguments:**
    358354
    359 .. code:: c
    360 
    361     const char                       \*path,       /* IN \*/
    362     rtems_filesystem_location_info_t \*pathloc,    /* IN/OUT \*/
    363     const char                      \**name        /* OUT    \*/
    364 
    365 **Description:**
    366 
    367 This method is given a path to evaluate and a valid start location.  It
    368 is responsible for finding the parent node for a requested make command,
    369 setting pathloc information to identify the parent node, and setting
    370 the name pointer to the first character of the name of the new node.
    371 Additionally, if the filesystem supports the mount command, this method
    372 should call the evalformake routine for the mounted filesystem.
     355.. code-block:: c
     356
     357    const char                       *path,       /* IN */
     358    rtems_filesystem_location_info_t *pathloc,    /* IN/OUT */
     359    const char                      **name        /* OUT */
     360
     361**Description:**
     362
     363This method is given a path to evaluate and a valid start location.  It is
     364responsible for finding the parent node for a requested make command, setting
     365pathloc information to identify the parent node, and setting the name pointer
     366to the first character of the name of the new node.  Additionally, if the
     367filesystem supports the mount command, this method should call the evalformake
     368routine for the mounted filesystem.
    373369
    374370This routine returns a 0 if the evaluation was successful.  Otherwise, it
    375371returns a -1 and sets errno to the correct error.
    376372
    377 This routine is required and should NOT be set to NULL.  However, if
    378 the filesystem does not support user creation of a new node, it may
    379 set errno to ENOSYS and return -1.
    380 
    381 .. COMMENT: @page
     373This routine is required and should NOT be set to NULL.  However, if the
     374filesystem does not support user creation of a new node, it may set errno to
     375ENOSYS and return -1.
    382376
    383377link Handler
     
    390384**Arguments:**
    391385
    392 .. code:: c
    393 
    394     rtems_filesystem_location_info_t    \*to_loc,      /* IN \*/
    395     rtems_filesystem_location_info_t    \*parent_loc,  /* IN \*/
    396     const char                          \*token        /* IN \*/
     386.. code-block:: c
     387
     388    rtems_filesystem_location_info_t    *to_loc,      /* IN */
     389    rtems_filesystem_location_info_t    *parent_loc,  /* IN */
     390    const char                          *token        /* IN */
    397391
    398392**Description:**
     
    400394This routine is used to create a hard-link.
    401395
    402 It will first examine the st_nlink count of the node that we are trying to.
    403 If the link count exceeds LINK_MAX an error will be returned.
     396It will first examine the st_nlink count of the node that we are trying to.  If
     397the link count exceeds LINK_MAX an error will be returned.
    404398
    405399The name of the link will be normalized to remove extraneous separators from
     
    408402This routine is not required and may be set to NULL.
    409403
    410 .. COMMENT: @page
    411 
    412404unlink Handler
    413405~~~~~~~~~~~~~~
     
    425417XXX
    426418
    427 .. COMMENT: @page
    428 
    429419node_type Handler
    430420~~~~~~~~~~~~~~~~~
     
    436426**Arguments:**
    437427
    438 .. code:: c
    439 
    440     rtems_filesystem_location_info_t    \*pathloc        /* IN \*/
    441 
    442 **Description:**
    443 
    444 XXX
    445 
    446 .. COMMENT: @page
     428.. code-block:: c
     429
     430    rtems_filesystem_location_info_t    *pathloc        /* IN */
     431
     432**Description:**
     433
     434XXX
    447435
    448436mknod Handler
     
    455443**Arguments:**
    456444
    457 .. code:: c
    458 
    459     const char                          \*token,        /* IN \*/
    460     mode_t                               mode,         /* IN \*/
    461     dev_t                                dev,          /* IN \*/
    462     rtems_filesystem_location_info_t    \*pathloc       /* IN/OUT \*/
    463 
    464 **Description:**
    465 
    466 XXX
    467 
    468 .. COMMENT: @page
     445.. code-block:: c
     446
     447    const char                          *token,        /* IN */
     448    mode_t                               mode,         /* IN */
     449    dev_t                                dev,          /* IN */
     450    rtems_filesystem_location_info_t    *pathloc       /* IN/OUT */
     451
     452**Description:**
     453
     454XXX
    469455
    470456rmnod Handler
     
    483469XXX
    484470
    485 .. COMMENT: @page
    486 
    487471chown Handler
    488472~~~~~~~~~~~~~
     
    494478**Arguments:**
    495479
    496 .. code:: c
    497 
    498     rtems_filesystem_location_info_t    \*pathloc        /* IN \*/
    499     uid_t                                owner          /* IN \*/
    500     gid_t                                group          /* IN \*/
     480.. code-block:: c
     481
     482    rtems_filesystem_location_info_t    *pathloc        /* IN */
     483    uid_t                                owner          /* IN */
     484    gid_t                                group          /* IN */
    501485
    502486**Description:**
     
    515499**Arguments:**
    516500
    517 .. code:: c
    518 
    519     rtems_filesystem_location_info_t      \*pathloc       /* IN \*/
    520 
    521 **Description:**
    522 
    523 This routine is used by the generic code to allow memory to be allocated
    524 during the evaluate routines, and set free when the generic code is finished
    525 accessing a node.  If the evaluate routines allocate memory to identify
    526 a node this routine should be utilized to free that memory.
     501.. code-block:: c
     502
     503    rtems_filesystem_location_info_t      *pathloc       /* IN */
     504
     505**Description:**
     506
     507This routine is used by the generic code to allow memory to be allocated during
     508the evaluate routines, and set free when the generic code is finished accessing
     509a node.  If the evaluate routines allocate memory to identify a node this
     510routine should be utilized to free that memory.
    527511
    528512This routine is not required and may be set to NULL.
    529513
    530 .. COMMENT: @page
    531 
    532514mount Handler
    533515~~~~~~~~~~~~~
     
    539521**Arguments:**
    540522
    541 .. code:: c
    542 
    543     rtems_filesystem_mount_table_entry_t   \*mt_entry
    544 
    545 **Description:**
    546 
    547 XXX
    548 
    549 .. COMMENT: @page
     523.. code-block:: c
     524
     525    rtems_filesystem_mount_table_entry_t   *mt_entry
     526
     527**Description:**
     528
     529XXX
    550530
    551531fsmount_me Handler
     
    558538**Arguments:**
    559539
    560 .. code:: c
    561 
    562     rtems_filesystem_mount_table_entry_t   \*mt_entry
     540.. code-block:: c
     541
     542    rtems_filesystem_mount_table_entry_t   *mt_entry
    563543
    564544**Description:**
    565545
    566546This function is provided with a filesystem to take care of the internal
    567 filesystem management details associated with mounting that filesystem
    568 under the RTEMS environment.
     547filesystem management details associated with mounting that filesystem under
     548the RTEMS environment.
    569549
    570550It is not responsible for the mounting details associated the filesystem
     
    574554below:
    575555
    576 rtems_filesystem_location_info_t         \*mt_point_node,
     556.. code-block:: c
     557
     558    rtems_filesystem_location_info_t         *mt_point_node,
    577559
    578560This structure contains information about the mount point. This
     
    580562associated with the filesystem containing the mount point.
    581563
    582 rtems_filesystem_location_info_t         \*fs_root_node,
     564.. code-block:: c
     565
     566    rtems_filesystem_location_info_t         *fs_root_node,
    583567
    584568This structure contains information about the root node in the file
     
    586570handling functions associated with the filesystem to be mounted.
    587571
    588 rtems_filesystem_options_t                 options,
     572.. code-block:: c
     573
     574    rtems_filesystem_options_t                 options,
    589575
    590576Read only or read/write access
    591577
    592 void                                         \*fs_info,
    593 
    594 This points to an allocated block of memory the will be used to
    595 hold any filesystem specific information of a global nature. This
    596 allocated region if important because it allows us to mount the
    597 same filesystem type more than once under the RTEMS system.
    598 Each instance of the mounted filesystem has its own set of global
    599 management information that is separate from the global
    600 management information associated with the other instances of the
    601 mounted filesystem type.
    602 
    603 rtems_filesystem_limits_and_options_t    pathconf_info,
    604 
    605 The table contains the following set of values associated with the
    606 mounted filesystem:
     578.. code-block:: c
     579
     580    void                                         *fs_info,
     581
     582This points to an allocated block of memory the will be used to hold any
     583filesystem specific information of a global nature. This allocated region if
     584important because it allows us to mount the same filesystem type more than once
     585under the RTEMS system.  Each instance of the mounted filesystem has its own
     586set of global management information that is separate from the global
     587management information associated with the other instances of the mounted
     588filesystem type.
     589
     590.. code-block:: c
     591
     592    rtems_filesystem_limits_and_options_t    pathconf_info,
     593
     594The table contains the following set of values associated with the mounted
     595filesystem:
    607596
    608597- link_max
     
    630619- posix_vdisable
    631620
    632 These values are accessed with the pathconf() and the fpathconf ()
    633 functions.
    634 
    635 const char                                   \*dev
     621These values are accessed with the pathconf() and the fpathconf () functions.
     622
     623.. code-block:: c
     624
     625    const char                                   *dev
    636626
    637627The is intended to contain a string that identifies the device that contains
    638 the filesystem information. The filesystems that are currently implemented
    639 are memory based and don't require a device specification.
     628the filesystem information. The filesystems that are currently implemented are
     629memory based and don't require a device specification.
    640630
    641631If the mt_point_node.node_access is NULL then we are mounting the base file
    642632system.
    643633
    644 The routine will create a directory node for the root of the IMFS file
    645 system.
     634The routine will create a directory node for the root of the IMFS file system.
    646635
    647636The node will have read, write and execute permissions for owner, group and
     
    650639The node's name will be a null string.
    651640
    652 A filesystem information structure(fs_info) will be allocated and
    653 initialized for the IMFS filesystem. The fs_info pointer in the mount table
    654 entry will be set to point the filesystem information structure.
     641A filesystem information structure(fs_info) will be allocated and initialized
     642for the IMFS filesystem. The fs_info pointer in the mount table entry will be
     643set to point the filesystem information structure.
    655644
    656645The pathconf_info element of the mount table will be set to the appropriate
     
    665654- OPS table functions for the IMFS
    666655
    667 A 0 will be returned to the calling routine if the process succeeded,
    668 otherwise a 1 will be returned.
    669 
    670 .. COMMENT: @page
     656A 0 will be returned to the calling routine if the process succeeded, otherwise
     657a 1 will be returned.
    671658
    672659unmount Handler
     
    685672XXX
    686673
    687 .. COMMENT: @page
    688 
    689674fsunmount_me Handler
    690675~~~~~~~~~~~~~~~~~~~~
     
    696681**Arguments:**
    697682
    698 .. code:: c
    699 
    700     rtems_filesystem_mount_table_entry_t   \*mt_entry
    701 
    702 **Description:**
    703 
    704 XXX
    705 
    706 .. COMMENT: @page
     683.. code-block:: c
     684
     685    rtems_filesystem_mount_table_entry_t   *mt_entry
     686
     687**Description:**
     688
     689XXX
    707690
    708691utime Handler
     
    720703
    721704XXX
    722 
    723 .. COMMENT: @page
    724705
    725706eval_link Handler
     
    738719XXX
    739720
    740 .. COMMENT: @page
    741 
    742721symlink Handler
    743722~~~~~~~~~~~~~~~
     
    754733
    755734XXX
    756 
    757 .. COMMENT: @page
    758735
    759736File Handler Table Functions
     
    764741filesystem. One table exists for each of the filesystem's node types. The
    765742structure definition appears below. It is followed by general developmental
    766 information on each of the functions associated with regular files contained
    767 in this function management structure.
    768 .. code:: c
     743information on each of the functions associated with regular files contained in
     744this function management structure.
     745
     746.. code-block:: c
    769747
    770748    typedef struct {
    771     rtems_filesystem_open_t           open;
    772     rtems_filesystem_close_t          close;
    773     rtems_filesystem_read_t           read;
    774     rtems_filesystem_write_t          write;
    775     rtems_filesystem_ioctl_t          ioctl;
    776     rtems_filesystem_lseek_t          lseek;
    777     rtems_filesystem_fstat_t          fstat;
    778     rtems_filesystem_fchmod_t         fchmod;
    779     rtems_filesystem_ftruncate_t      ftruncate;
    780     rtems_filesystem_fpathconf_t      fpathconf;
    781     rtems_filesystem_fsync_t          fsync;
    782     rtems_filesystem_fdatasync_t      fdatasync;
    783     rtems_filesystem_fcntl_t          fcntl;
     749        rtems_filesystem_open_t           open;
     750        rtems_filesystem_close_t          close;
     751        rtems_filesystem_read_t           read;
     752        rtems_filesystem_write_t          write;
     753        rtems_filesystem_ioctl_t          ioctl;
     754        rtems_filesystem_lseek_t          lseek;
     755        rtems_filesystem_fstat_t          fstat;
     756        rtems_filesystem_fchmod_t         fchmod;
     757        rtems_filesystem_ftruncate_t      ftruncate;
     758        rtems_filesystem_fpathconf_t      fpathconf;
     759        rtems_filesystem_fsync_t          fsync;
     760        rtems_filesystem_fdatasync_t      fdatasync;
     761        rtems_filesystem_fcntl_t          fcntl;
    784762    } rtems_filesystem_file_handlers_r;
    785 
    786 .. COMMENT: @page
    787763
    788764open Handler
     
    795771**Arguments:**
    796772
    797 .. code:: c
    798 
    799     rtems_libio_t   \*iop,
    800     const char      \*pathname,
     773.. code-block:: c
     774
     775    rtems_libio_t   *iop,
     776    const char      *pathname,
    801777    unsigned32       flag,
    802778    unsigned32       mode
     
    806782XXX
    807783
    808 .. COMMENT: @page
    809 
    810784close Handler
    811785~~~~~~~~~~~~~
     
    817791**Arguments:**
    818792
    819 .. code:: c
    820 
    821     rtems_libio_t     \*iop
    822 
    823 **Description:**
    824 
    825 XXX
    826 
    827 **NOTES:**
    828 
    829 XXX
    830 
    831 .. COMMENT: @page
     793.. code-block:: c
     794
     795    rtems_libio_t     *iop
     796
     797**Description:**
     798
     799XXX
     800
     801**NOTES:**
     802
     803XXX
    832804
    833805read Handler
     
    840812**Arguments:**
    841813
    842 .. code:: c
    843 
    844     rtems_libio_t     \*iop,
    845     void              \*buffer,
     814.. code-block:: c
     815
     816    rtems_libio_t     *iop,
     817    void              *buffer,
    846818    unsigned32         count
    847819
     
    854826XXX
    855827
    856 .. COMMENT: @page
    857 
    858828write Handler
    859829~~~~~~~~~~~~~
     
    875845XXX
    876846
    877 .. COMMENT: @page
    878 
    879847ioctl Handler
    880848~~~~~~~~~~~~~
     
    886854**Arguments:**
    887855
    888 .. code:: c
    889 
    890     rtems_libio_t     \*iop,
     856.. code-block:: c
     857
     858    rtems_libio_t     *iop,
    891859    unsigned32       command,
    892     void              \*buffer
    893 
    894 **Description:**
    895 
    896 XXX
    897 
    898 **NOTES:**
    899 
    900 XXX
    901 
    902 .. COMMENT: @page
     860    void              *buffer
     861
     862**Description:**
     863
     864XXX
     865
     866**NOTES:**
     867
     868XXX
    903869
    904870lseek Handler
     
    911877**Arguments:**
    912878
    913 .. code:: c
    914 
    915     rtems_libio_t     \*iop,
     879.. code-block:: c
     880
     881    rtems_libio_t     *iop,
    916882    off_t              offset,
    917883    int                whence
     
    925891XXX
    926892
    927 .. COMMENT: @page
    928 
    929893fstat Handler
    930894~~~~~~~~~~~~~
     
    936900**Arguments:**
    937901
    938 .. code:: c
    939 
    940     rtems_filesystem_location_info_t   \*loc,
    941     struct stat                        \*buf
    942 
    943 **Description:**
    944 
    945 The following information is extracted from the filesystem
    946 specific node and placed in the ``stat`` structure:
     902.. code-block:: c
     903
     904    rtems_filesystem_location_info_t   *loc,
     905    struct stat                        *buf
     906
     907**Description:**
     908
     909The following information is extracted from the filesystem specific node and
     910placed in the ``stat`` structure:
    947911
    948912- st_mode
     
    964928**NOTES:**
    965929
    966 Both the ``stat()`` and ``lstat()`` services are
    967 implemented directly using the ``fstat()`` handler.  The
    968 difference in behavior is determined by how the path is evaluated
    969 prior to this handler being called on a particular
    970 file entity.
    971 
    972 The ``fstat()`` system call is implemented directly
    973 on top of this filesystem handler.
    974 
    975 .. COMMENT: @page
     930Both the ``stat()`` and ``lstat()`` services are implemented directly using the
     931``fstat()`` handler.  The difference in behavior is determined by how the path
     932is evaluated prior to this handler being called on a particular file entity.
     933
     934The ``fstat()`` system call is implemented directly on top of this filesystem
     935handler.
    976936
    977937fchmod Handler
     
    984944**Arguments:**
    985945
    986 .. code:: c
    987 
    988     rtems_libio_t     \*iop
    989     mode_t              mode
    990 
    991 **Description:**
    992 
    993 XXX
    994 
    995 **NOTES:**
    996 
    997 XXX
    998 
    999 .. COMMENT: @page
     946.. code-block:: c
     947
     948    rtems_libio_t     *iop
     949    mode_t             mode
     950
     951**Description:**
     952
     953XXX
     954
     955**NOTES:**
     956
     957XXX
    1000958
    1001959ftruncate Handler
     
    1037995XXX
    1038996
    1039 .. COMMENT: @page
    1040 
    1041997fsync Handler
    1042998~~~~~~~~~~~~~
     
    10571013
    10581014XXX
    1059 
    1060 .. COMMENT: @page
    10611015
    10621016fdatasync Handler
     
    10791033XXX
    10801034
    1081 .. COMMENT: @page
    1082 
    10831035fcntl Handler
    10841036~~~~~~~~~~~~~
     
    10991051
    11001052XXX
    1101 
    1102 .. COMMENT: COPYRIGHT (c) 1988-2002.
    1103 
    1104 .. COMMENT: On-Line Applications Research Corporation (OAR).
    1105 
    1106 .. COMMENT: All rights reserved.
    1107 
  • filesystem/in-memory.rst

    rb0f2977 r4cacea0  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37In-Memory Filesystem
    48####################
    59
    6 This chapter describes the In-Memory FileSystem (IMFS).  The IMFS is a
    7 full featured POSIX filesystem that keeps all information in memory.
     10This chapter describes the In-Memory FileSystem (IMFS).  The IMFS is a full
     11featured POSIX filesystem that keeps all information in memory.
    812
    913IMFS Per Node Data Structure
     
    1317structure called a ``jnode``. The ``jnode`` is formally represented by the
    1418structure:
    15 .. code:: c
     19
     20.. code-block:: c
    1621
    1722    struct IMFS_jnode_tt {
    18     Chain_Node          Node;             /* for chaining them together \*/
    19     IMFS_jnode_t       \*Parent;           /* Parent node \*/
    20     char                name[NAME_MAX+1]; /* "basename" \*/
    21     mode_t              st_mode;          /* File mode \*/
    22     nlink_t             st_nlink;         /* Link count \*/
    23     ino_t               st_ino;           /* inode \*/
    24     uid_t               st_uid;           /* User ID of owner \*/
    25     gid_t               st_gid;           /* Group ID of owner \*/
    26     time_t              st_atime;         /* Time of last access \*/
    27     time_t              st_mtime;         /* Time of last modification \*/
    28     time_t              st_ctime;         /* Time of last status change \*/
    29     IMFS_jnode_types_t  type;             /* Type of this entry \*/
    30     IMFS_typs_union     info;
     23        Chain_Node          Node;             /* for chaining them together */
     24        IMFS_jnode_t       *Parent;           /* Parent node */
     25        char                name[NAME_MAX+1]; /* "basename" */
     26        mode_t              st_mode;          /* File mode */
     27        nlink_t             st_nlink;         /* Link count */
     28        ino_t               st_ino;           /* inode */
     29        uid_t               st_uid;           /* User ID of owner */
     30        gid_t               st_gid;           /* Group ID of owner */
     31        time_t              st_atime;         /* Time of last access */
     32        time_t              st_mtime;         /* Time of last modification */
     33        time_t              st_ctime;         /* Time of last status change */
     34        IMFS_jnode_types_t  type;             /* Type of this entry */
     35        IMFS_typs_union     info;
    3136    };
    3237
     
    3843
    3944*Parent*
    40     is a pointer to another ``jnode`` structure that is the logical parent of the
    41     node in which it appears.  This field may be NULL if the file associated with
    42     this node is deleted but there are open file descriptors on this file or
    43     there are still hard links to this node.
     45    is a pointer to another ``jnode`` structure that is the logical parent of
     46    the node in which it appears.  This field may be NULL if the file
     47    associated with this node is deleted but there are open file descriptors on
     48    this file or there are still hard links to this node.
    4449
    4550*name*
    46     is the name of this node within the filesystem hierarchical tree. Example:  If
    47     the fully qualified pathname to the ``jnode`` was ``/a/b/c``, the``jnode`` name field would contain the null terminated string ``"c"``.
     51    is the name of this node within the filesystem hierarchical tree. Example:
     52    If the fully qualified pathname to the ``jnode`` was ``/a/b/c``, the
     53    ``jnode`` name field would contain the null terminated string ``"c"``.
    4854
    4955*st_mode*
     
    5258*st_nlink*
    5359    is the number of hard links to this file. When a ``jnode`` is first created
    54     its link count is set to 1. A ``jnode`` and its associated resources
    55     cannot be deleted unless its link count is less than 1.
     60    its link count is set to 1. A ``jnode`` and its associated resources cannot
     61    be deleted unless its link count is less than 1.
    5662
    5763*st_ino*
     
    7581*type*
    7682    is the indication of node type must be one of the following states:
     83      - IMFS_DIRECTORY
     84      - IMFS_MEMORY_FILE
     85      - IMFS_HARD_LINK
     86      - IMFS_SYM_LINK
     87      - IMFS_DEVICE
     88
     89*info*
     90    is this contains a structure that is unique to file type (See
     91    IMFS_typs_union in imfs.h).
     92
    7793    - IMFS_DIRECTORY
     94
     95      An IMFS directory contains a dynamic chain structure that records all
     96      files and directories that are subordinate to the directory node.
     97
    7898    - IMFS_MEMORY_FILE
     99
     100      Under the in memory filesystem regular files hold data. Data is
     101      dynamically allocated to the file in 128 byte chunks of memory.  The
     102      individual chunks of memory are tracked by arrays of pointers that record
     103      the address of the allocated chunk of memory. Single, double, and triple
     104      indirection pointers are used to record the locations of all segments of
     105      the file.  The memory organization of an IMFS file are discussed
     106      elsewhere in this manual.
     107
    79108    - IMFS_HARD_LINK
     109
     110      The IMFS filesystem supports the concept of hard links to other nodes in
     111      the IMFS filesystem.  These hard links are actual pointers to other nodes
     112      in the same filesystem. This type of link cannot cross-filesystem
     113      boundaries.
     114
    80115    - IMFS_SYM_LINK
    81     - IMFS_DEVICE
    82 
    83 *info*
    84     is this contains a structure that is unique to file type (See IMFS_typs_union
    85     in imfs.h).
    86 
    87     - IMFS_DIRECTORY
    88 
    89       An IMFS directory contains a dynamic chain structure that
    90       records all files and directories that are subordinate to the directory node.
    91 
    92     - IMFS_MEMORY_FILE
    93 
    94       Under the in memory filesystem regular files hold data. Data is dynamically
    95       allocated to the file in 128 byte chunks of memory.  The individual chunks of
    96       memory are tracked by arrays of pointers that record the address of the
    97       allocated chunk of memory. Single, double, and triple indirection pointers
    98       are used to record the locations of all segments of the file.  The
    99       memory organization of an IMFS file are discussed elsewhere in this manual.
    100 
    101     - IMFS_HARD_LINK
    102 
    103       The IMFS filesystem supports the concept of hard links to other nodes in the
    104       IMFS filesystem.  These hard links are actual pointers to other nodes in the
    105       same filesystem. This type of link cannot cross-filesystem boundaries.
    106 
    107     - IMFS_SYM_LINK
    108 
    109       The IMFS filesystem supports the concept of symbolic links to other nodes in
    110       any filesystem. A symbolic link consists of a pointer to a character string
    111       that represents the pathname to the target node. This type of link can
    112       cross-filesystem boundaries.  Just as with most versions of UNIX supporting
    113       symbolic links, a symbolic link can point to a non-existent file.
     116
     117      The IMFS filesystem supports the concept of symbolic links to other nodes
     118      in any filesystem. A symbolic link consists of a pointer to a character
     119      string that represents the pathname to the target node. This type of link
     120      can cross-filesystem boundaries.  Just as with most versions of UNIX
     121      supporting symbolic links, a symbolic link can point to a non-existent
     122      file.
    114123
    115124    - IMFS_DEVICE
     
    125134===============================
    126135
    127 A memory based filesystem draws its resources for files and directories
    128 from the memory resources of the system. When it is time to un-mount the
    129 filesystem, the memory resources that supported filesystem are set free.
    130 In order to free these resources, a recursive walk of the filesystems
    131 tree structure will be performed. As the leaf nodes under the filesystem
    132 are encountered their resources are freed. When directories are made empty
    133 by this process, their resources are freed.
     136A memory based filesystem draws its resources for files and directories from
     137the memory resources of the system. When it is time to un-mount the filesystem,
     138the memory resources that supported filesystem are set free.  In order to free
     139these resources, a recursive walk of the filesystems tree structure will be
     140performed. As the leaf nodes under the filesystem are encountered their
     141resources are freed. When directories are made empty by this process, their
     142resources are freed.
    134143
    135144Node removal constraints for the IMFS
    136145-------------------------------------
    137146
    138 The IMFS conforms to the general filesystem requirements for node
    139 removal.  See `File and Directory Removal Constraints`_.
     147The IMFS conforms to the general filesystem requirements for node removal.  See
     148:ref:`file-and-directory-removal-constraints`.
    140149
    141150IMFS General Housekeeping Notes
     
    144153The following is a list of odd housekeeping notes for the IMFS.
    145154
    146 - If the global variable rtems_filesystem_current refers to the node that
    147   we are trying to remove, the node_access element of this structure must be
    148   set to NULL to invalidate it.
    149 
    150 - If the node was of IMFS_MEMORY_FILE type, free the memory associated
    151   with the memory file before freeing the node. Use the IMFS_memfile_remove()
    152   function.
     155- If the global variable rtems_filesystem_current refers to the node that we
     156  are trying to remove, the node_access element of this structure must be set
     157  to NULL to invalidate it.
     158
     159- If the node was of IMFS_MEMORY_FILE type, free the memory associated with the
     160  memory file before freeing the node. Use the IMFS_memfile_remove() function.
    153161
    154162IMFS Operation Tables
     
    159167
    160168OPS table functions are defined in a rtems_filesystem_operations_table
    161 structure.  It defines functions that are specific to a given filesystem.
    162 One table exists for each filesystem that is supported in the RTEMS
     169structure.  It defines functions that are specific to a given filesystem.  One
     170table exists for each filesystem that is supported in the RTEMS
    163171configuration. The structure definition appears below and is followed by
    164172general developmental information on each of the functions contained in this
    165173function management structure.
    166 .. code:: c
     174
     175.. code-block:: c
    167176
    168177    rtems_filesystem_operations_table  IMFS_ops = {
    169     IMFS_eval_path,
    170     IMFS_evaluate_for_make,
    171     IMFS_link,
    172     IMFS_unlink,
    173     IMFS_node_type,
    174     IMFS_mknod,
    175     IMFS_rmnod,
    176     IMFS_chown,
    177     IMFS_freenodinfo,
    178     IMFS_mount,
    179     IMFS_initialize,
    180     IMFS_unmount,
    181     IMFS_fsunmount,
    182     IMFS_utime,
    183     IMFS_evaluate_link,
    184     IMFS_symlink,
    185     IMFS_readlink
     178        IMFS_eval_path,
     179        IMFS_evaluate_for_make,
     180        IMFS_link,
     181        IMFS_unlink,
     182        IMFS_node_type,
     183        IMFS_mknod,
     184        IMFS_rmnod,
     185        IMFS_chown,
     186        IMFS_freenodinfo,
     187        IMFS_mount,
     188        IMFS_initialize,
     189        IMFS_unmount,
     190        IMFS_fsunmount,
     191        IMFS_utime,
     192        IMFS_evaluate_link,
     193        IMFS_symlink,
     194        IMFS_readlink
    186195    };
    187196
     
    207216XXX
    208217
    209 .. COMMENT: @page
    210 
    211218IMFS_evalformake()
    212219~~~~~~~~~~~~~~~~~~
     
    228235XXX
    229236
    230 .. COMMENT: @page
    231 
    232237IMFS_link()
    233238~~~~~~~~~~~
     
    239244**Arguments:**
    240245
    241 .. code:: c
    242 
    243     rtems_filesystem_location_info_t    \*to_loc,      /* IN \*/
    244     rtems_filesystem_location_info_t    \*parent_loc,  /* IN \*/
    245     const char                          \*token        /* IN \*/
     246.. code-block:: c
     247
     248    rtems_filesystem_location_info_t    *to_loc,      /* IN */
     249    rtems_filesystem_location_info_t    *parent_loc,  /* IN */
     250    const char                          *token        /* IN */
    246251
    247252**File:**
     
    253258This routine is used in the IMFS filesystem to create a hard-link.
    254259
    255 It will first examine the st_nlink count of the node that we are trying to.
    256 If the link count exceeds LINK_MAX an error will be returned.
     260It will first examine the st_nlink count of the node that we are trying to.  If
     261the link count exceeds LINK_MAX an error will be returned.
    257262
    258263The name of the link will be normalized to remove extraneous separators from
     
    279284hard-link.
    280285
    281 .. COMMENT: @page
    282 
    283286IMFS_unlink()
    284287~~~~~~~~~~~~~
     
    300303XXX
    301304
    302 .. COMMENT: @page
    303 
    304305IMFS_node_type()
    305306~~~~~~~~~~~~~~~~
     
    311312**Arguments:**
    312313
    313 .. code:: c
    314 
    315     rtems_filesystem_location_info_t    \*pathloc        /* IN \*/
     314.. code-block:: c
     315
     316    rtems_filesystem_location_info_t    *pathloc        /* IN */
    316317
    317318**File:**
     
    347348**Arguments:**
    348349
    349 .. code:: c
    350 
    351     const char                          \*token,        /* IN \*/
    352     mode_t                               mode,         /* IN \*/
    353     dev_t                                dev,          /* IN \*/
    354     rtems_filesystem_location_info_t    \*pathloc       /* IN/OUT \*/
     350.. code-block:: c
     351
     352    const char                          *token,        /* IN */
     353    mode_t                               mode,         /* IN */
     354    dev_t                                dev,          /* IN */
     355    rtems_filesystem_location_info_t    *pathloc       /* IN/OUT */
    355356
    356357**File:**
     
    361362
    362363This routine will examine the mode argument to determine is we are trying to
    363 create a directory, regular file and a device node. The creation of other
    364 node types is not permitted and will cause an assert.
     364create a directory, regular file and a device node. The creation of other node
     365types is not permitted and will cause an assert.
    365366
    366367Memory space will be allocated for a ``jnode`` and the node will be set up
    367 according to the nodal type that was specified. The IMFS_create_node()
    368 function performs the allocation and setup of the node.
     368according to the nodal type that was specified. The IMFS_create_node() function
     369performs the allocation and setup of the node.
    369370
    370371The only problem that is currently reported is the lack of memory when we
    371372attempt to allocate space for the ``jnode`` (ENOMEN).
    372373
    373 .. COMMENT: @page
    374 
    375374IMFS_rmnod()
    376375~~~~~~~~~~~~
     
    392391XXX
    393392
    394 .. COMMENT: @page
    395 
    396393IMFS_chown()
    397394~~~~~~~~~~~~
     
    403400**Arguments:**
    404401
    405 .. code:: c
    406 
    407     rtems_filesystem_location_info_t    \*pathloc        /* IN \*/
    408     uid_t                                owner          /* IN \*/
    409     gid_t                                group          /* IN \*/
     402.. code-block:: c
     403
     404    rtems_filesystem_location_info_t    *pathloc        /* IN */
     405    uid_t                                owner          /* IN */
     406    gid_t                                group          /* IN */
    410407
    411408**File:**
     
    421418
    422419The st_uid and st_gid fields of the node are then modified. Since this is a
    423 memory based filesystem, no further action is required to alter the
    424 ownership of the IMFS_jnode_t structure.
    425 
    426 .. COMMENT: @page
     420memory based filesystem, no further action is required to alter the ownership
     421of the IMFS_jnode_t structure.
    427422
    428423IMFS_freenod()
     
    435430**Arguments:**
    436431
    437 .. code:: c
    438 
    439     rtems_filesystem_location_info_t      \*pathloc       /* IN \*/
     432.. code-block:: c
     433
     434    rtems_filesystem_location_info_t      *pathloc       /* IN */
    440435
    441436**File:**
     
    446441
    447442This method is a private function to the IMFS.  It is called by IMFS routines
    448 to free nodes that have been allocated.  Examples of where this routine
    449 may be called from are unlink and rmnod.
    450 
    451 Note:  This routine should not be confused with the filesystem callback
    452 freenod.  The IMFS allocates memory until the node no longer exists.
    453 
    454 .. COMMENT: @page
     443to free nodes that have been allocated.  Examples of where this routine may be
     444called from are unlink and rmnod.
     445
     446Note: This routine should not be confused with the filesystem callback freenod.
     447The IMFS allocates memory until the node no longer exists.
    455448
    456449IMFS_freenodinfo()
     
    463456**Arguments:**
    464457
    465 .. code:: c
    466 
    467     rtems_filesystem_location_info_t      \*pathloc       /* IN \*/
     458.. code-block:: c
     459
     460    rtems_filesystem_location_info_t      *pathloc       /* IN */
    468461
    469462**File:**
     
    473466**Description:**
    474467
    475 The In-Memory File System does not need to allocate memory during the
    476 evaluate routines. Therefore, this routine simply routines PASS.
    477 
    478 .. COMMENT: @page
     468The In-Memory File System does not need to allocate memory during the evaluate
     469routines. Therefore, this routine simply routines PASS.
    479470
    480471IMFS_mount()
     
    487478**Arguments:**
    488479
    489 .. code:: c
    490 
    491     rtems_filesystem_mount_table_entry_t   \*mt_entry
     480.. code-block:: c
     481
     482    rtems_filesystem_mount_table_entry_t   *mt_entry
    492483
    493484**File:**
     
    498489
    499490This routine provides the filesystem specific processing required to mount a
    500 filesystem for the system that contains the mount point. It will determine
    501 if the point that we are trying to mount onto is a node of IMFS_DIRECTORY
    502 type.
     491filesystem for the system that contains the mount point. It will determine if
     492the point that we are trying to mount onto is a node of IMFS_DIRECTORY type.
    503493
    504494If it is the node's info element is altered so that the info.directory.mt_fs
    505495element points to the mount table chain entry that is associated with the
    506496mounted filesystem at this point. The info.directory.mt_fs element can be
    507 examined to determine if a filesystem is mounted at a directory. If it is
    508 NULL, the directory does not serve as a mount point. A non-NULL entry
    509 indicates that the directory does serve as a mount point and the value of
    510 info.directory.mt_fs can be used to locate the mount table chain entry that
    511 describes the filesystem mounted at this point.
    512 
    513 .. COMMENT: @page
     497examined to determine if a filesystem is mounted at a directory. If it is NULL,
     498the directory does not serve as a mount point. A non-NULL entry indicates that
     499the directory does serve as a mount point and the value of info.directory.mt_fs
     500can be used to locate the mount table chain entry that describes the filesystem
     501mounted at this point.
    514502
    515503IMFS_fsmount_me()
     
    522510**Arguments:**
    523511
    524 .. code:: c
    525 
    526     rtems_filesystem_mount_table_entry_t   \*mt_entry
     512.. code-block:: c
     513
     514    rtems_filesystem_mount_table_entry_t   *mt_entry
    527515
    528516**File:**
     
    533521
    534522This function is provided with a filesystem to take care of the internal
    535 filesystem management details associated with mounting that filesystem
    536 under the RTEMS environment.
     523filesystem management details associated with mounting that filesystem under
     524the RTEMS environment.
    537525
    538526It is not responsible for the mounting details associated the filesystem
     
    542530below:
    543531
    544 rtems_filesystem_location_info_t         \*mt_point_node,
     532.. code-block:: c
     533
     534    rtems_filesystem_location_info_t         *mt_point_node,
    545535
    546536This structure contains information about the mount point. This
     
    548538associated with the filesystem containing the mount point.
    549539
    550 rtems_filesystem_location_info_t         \*fs_root_node,
     540.. code-block:: c
     541
     542    rtems_filesystem_location_info_t         *fs_root_node,
    551543
    552544This structure contains information about the root node in the file
     
    554546handling functions associated with the filesystem to be mounted.
    555547
    556 rtems_filesystem_options_t                 options,
     548.. code-block:: c
     549
     550    rtems_filesystem_options_t                 options,
    557551
    558552Read only or read/write access
    559553
    560 void                                         \*fs_info,
    561 
    562 This points to an allocated block of memory the will be used to
    563 hold any filesystem specific information of a global nature. This
    564 allocated region if important because it allows us to mount the
    565 same filesystem type more than once under the RTEMS system.
    566 Each instance of the mounted filesystem has its own set of global
    567 management information that is separate from the global
    568 management information associated with the other instances of the
    569 mounted filesystem type.
    570 
    571 rtems_filesystem_limits_and_options_t    pathconf_info,
    572 
    573 The table contains the following set of values associated with the
    574 mounted filesystem:
     554.. code-block:: c
     555
     556    void                                         *fs_info,
     557
     558This points to an allocated block of memory the will be used to hold any
     559filesystem specific information of a global nature. This allocated region if
     560important because it allows us to mount the same filesystem type more than once
     561under the RTEMS system.  Each instance of the mounted filesystem has its own
     562set of global management information that is separate from the global
     563management information associated with the other instances of the mounted
     564filesystem type.
     565
     566.. code-block:: c
     567
     568    rtems_filesystem_limits_and_options_t    pathconf_info,
     569
     570The table contains the following set of values associated with the mounted
     571filesystem:
    575572
    576573- link_max
     
    598595- posix_vdisable
    599596
    600 These values are accessed with the pathconf() and the fpathconf ()
    601 functions.
    602 
    603 const char                                   \*dev
     597These values are accessed with the pathconf() and the fpathconf () functions.
     598
     599.. code-block:: c
     600
     601    const char                                   *dev
    604602
    605603The is intended to contain a string that identifies the device that contains
    606 the filesystem information. The filesystems that are currently implemented
    607 are memory based and don't require a device specification.
     604the filesystem information. The filesystems that are currently implemented are
     605memory based and don't require a device specification.
    608606
    609607If the mt_point_node.node_access is NULL then we are mounting the base file
    610608system.
    611609
    612 The routine will create a directory node for the root of the IMFS file
    613 system.
     610The routine will create a directory node for the root of the IMFS file system.
    614611
    615612The node will have read, write and execute permissions for owner, group and
     
    618615The node's name will be a null string.
    619616
    620 A filesystem information structure(fs_info) will be allocated and
    621 initialized for the IMFS filesystem. The fs_info pointer in the mount table
    622 entry will be set to point the filesystem information structure.
     617A filesystem information structure(fs_info) will be allocated and initialized
     618for the IMFS filesystem. The fs_info pointer in the mount table entry will be
     619set to point the filesystem information structure.
    623620
    624621The pathconf_info element of the mount table will be set to the appropriate
     
    633630- OPS table functions for the IMFS
    634631
    635 A 0 will be returned to the calling routine if the process succeeded,
    636 otherwise a 1 will be returned.
    637 
    638 .. COMMENT: @page
     632A 0 will be returned to the calling routine if the process succeeded, otherwise
     633a 1 will be returned.
    639634
    640635IMFS_unmount()
     
    647642**Arguments:**
    648643
    649 .. code:: c
    650 
    651     rtems_filesystem_mount_table_entry_t   \*mt_entry
     644.. code-block:: c
     645
     646    rtems_filesystem_mount_table_entry_t   *mt_entry
    652647
    653648**File:**
     
    657652**Description:**
    658653
    659 This routine allows the IMFS to unmount a filesystem that has been
    660 mounted onto a IMFS directory.
    661 
    662 The mount entry mount point node access is verified to be a mounted
    663 directory.  It's mt_fs is set to NULL.  This identifies to future
    664 calles into the IMFS that this directory node is no longer a mount
    665 point.  Additionally, it will allow any directories that were hidden
    666 by the mounted system to again become visible.
    667 
    668 .. COMMENT: @page
     654This routine allows the IMFS to unmount a filesystem that has been mounted onto
     655a IMFS directory.
     656
     657The mount entry mount point node access is verified to be a mounted directory.
     658It's mt_fs is set to NULL.  This identifies to future calles into the IMFS that
     659this directory node is no longer a mount point.  Additionally, it will allow
     660any directories that were hidden by the mounted system to again become visible.
    669661
    670662IMFS_fsunmount()
     
    677669**Arguments:**
    678670
    679 .. code:: c
    680 
    681     rtems_filesystem_mount_table_entry_t   \*mt_entry
     671.. code-block:: c
     672
     673    rtems_filesystem_mount_table_entry_t   *mt_entry
    682674
    683675**File:**
     
    688680
    689681This method unmounts this instance of the IMFS file system.  It is the
    690 counterpart to the IMFS_initialize routine.  It is called by the generic
    691 code under the fsunmount_me callback.
     682counterpart to the IMFS_initialize routine.  It is called by the generic code
     683under the fsunmount_me callback.
    692684
    693685All method loops finding the first encountered node with no children and
    694 removing the node from the tree, thus returning allocated resources.  This
    695 is done until all allocated nodes are returned.
    696 
    697 .. COMMENT: @page
     686removing the node from the tree, thus returning allocated resources.  This is
     687done until all allocated nodes are returned.
    698688
    699689IMFS_utime()
     
    716706XXX
    717707
    718 .. COMMENT: @page
    719 
    720708IMFS_eval_link()
    721709~~~~~~~~~~~~~~~~
     
    736724
    737725XXX
    738 
    739 .. COMMENT: @page
    740726
    741727Regular File Handler Table Functions
     
    746732filesystem. One table exists for each of the filesystem's node types. The
    747733structure definition appears below. It is followed by general developmental
    748 information on each of the functions associated with regular files contained
    749 in this function management structure.
    750 .. code:: c
     734information on each of the functions associated with regular files contained in
     735this function management structure.
     736
     737.. code-block:: c
    751738
    752739    rtems_filesystem_file_handlers_r IMFS_memfile_handlers = {
    753     memfile_open,
    754     memfile_close,
    755     memfile_read,
    756     memfile_write,
    757     memfile_ioctl,
    758     memfile_lseek,
    759     IMFS_stat,
    760     IMFS_fchmod,
    761     memfile_ftruncate,
    762     NULL,                /* fpathconf \*/
    763     NULL,                /* fsync \*/
    764     IMFS_fdatasync,
    765     IMFS_fcntl
     740        memfile_open,
     741        memfile_close,
     742        memfile_read,
     743        memfile_write,
     744        memfile_ioctl,
     745        memfile_lseek,
     746        IMFS_stat,
     747        IMFS_fchmod,
     748        memfile_ftruncate,
     749        NULL,                /* fpathconf */
     750        NULL,                /* fsync */
     751        IMFS_fdatasync,
     752        IMFS_fcntl
    766753    };
    767 
    768 .. COMMENT: @page
    769754
    770755memfile_open() for Regular Files
     
    777762**Arguments:**
    778763
    779 .. code:: c
    780 
    781     rtems_libio_t   \*iop,
    782     const char      \*pathname,
     764.. code-block:: c
     765
     766    rtems_libio_t   *iop,
     767    const char      *pathname,
    783768    unsigned32       flag,
    784769    unsigned32       mode
     
    790775**Description:**
    791776
    792 Currently this function is a shell. No meaningful processing is performed and
    793 a success code is always returned.
    794 
    795 .. COMMENT: @page
     777Currently this function is a shell. No meaningful processing is performed and a
     778success code is always returned.
    796779
    797780memfile_close() for Regular Files
     
    804787**Arguments:**
    805788
    806 .. code:: c
    807 
    808     rtems_libio_t     \*iop
     789.. code-block:: c
     790
     791    rtems_libio_t     *iop
    809792
    810793**File:**
     
    815798
    816799This routine is a dummy for regular files under the base filesystem. It
    817 performs a capture of the IMFS_jnode_t pointer from the file control block
    818 and then immediately returns a success status.
    819 
    820 .. COMMENT: @page
     800performs a capture of the IMFS_jnode_t pointer from the file control block and
     801then immediately returns a success status.
    821802
    822803memfile_read() for Regular Files
     
    829810**Arguments:**
    830811
    831 .. code:: c
    832 
    833     rtems_libio_t     \*iop,
    834     void              \*buffer,
     812.. code-block:: c
     813
     814    rtems_libio_t     *iop,
     815    void              *buffer,
    835816    unsigned32         count
    836817
     
    858839- Update the access time for the data in the file
    859840
    860 .. COMMENT: @page
    861 
    862841memfile_write() for Regular Files
    863842~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    879858XXX
    880859
    881 .. COMMENT: @page
    882 
    883860memfile_ioctl() for Regular Files
    884861~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    890867**Arguments:**
    891868
    892 .. code:: c
    893 
    894     rtems_libio_t     \*iop,
     869.. code-block:: c
     870
     871    rtems_libio_t   *iop,
    895872    unsigned32       command,
    896     void              \*buffer
     873    void            *buffer
    897874
    898875**File:**
     
    905882a successful completion status.
    906883
    907 .. COMMENT: @page
    908 
    909884memfile_lseek() for Regular Files
    910885~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    916891**Arguments:**
    917892
    918 .. code:: c
    919 
    920     rtems_libio_t     \*iop,
     893.. code-block:: c
     894
     895    rtems_libio_t     *iop,
    921896    off_t              offset,
    922897    int                whence
     
    931906allow for the new file position index.
    932907
    933 The IMFS_memfile_extend() function is used to evaluate the current size of
    934 the memory file and allocate additional memory blocks if required by the new
    935 file position index. A success code is always returned from this routine.
    936 
    937 .. COMMENT: @page
     908The IMFS_memfile_extend() function is used to evaluate the current size of the
     909memory file and allocate additional memory blocks if required by the new file
     910position index. A success code is always returned from this routine.
    938911
    939912IMFS_stat() for Regular Files
     
    946919**Arguments:**
    947920
    948 .. code:: c
    949 
    950     rtems_filesystem_location_info_t   \*loc,
    951     struct stat                        \*buf
     921.. code-block:: c
     922
     923    rtems_filesystem_location_info_t   *loc,
     924    struct stat                        *buf
    952925
    953926**File:**
     
    990963- st_ctime
    991964
    992 .. COMMENT: @page
    993 
    994965IMFS_fchmod() for Regular Files
    995966~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    1001972**Arguments:**
    1002973
    1003 .. code:: c
    1004 
    1005     rtems_libio_t     \*iop
    1006     mode_t              mode
     974.. code-block:: c
     975
     976    rtems_libio_t     *iop
     977    mode_t             mode
    1007978
    1008979**File:**
     
    1016987
    1017988Based on configuration the routine will acquire the user ID from a call to
    1018 getuid()  or from the IMFS_jnode_t structure.
    1019 
    1020 It then checks to see if we have the ownership rights to alter the mode of
    1021 the file.  If the caller does not, an error code is returned.
     989getuid() or from the IMFS_jnode_t structure.
     990
     991It then checks to see if we have the ownership rights to alter the mode of the
     992file.  If the caller does not, an error code is returned.
    1022993
    1023994An additional test is performed to verify that the caller is not trying to
     
    1028999based on the mode calling parameter.
    10291000
    1030 .. COMMENT: @page
    1031 
    10321001memfile_ftruncate() for Regular Files
    10331002~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    10681037Not Implemented
    10691038
    1070 .. COMMENT: @page
    1071 
    10721039No fsync() for Regular Files
    10731040~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    10891056XXX
    10901057
    1091 .. COMMENT: @page
    1092 
    10931058IMFS_fdatasync() for Regular Files
    10941059~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    11091074
    11101075XXX
    1111 
    1112 .. COMMENT: @page
    11131076
    11141077Directory Handler Table Functions
     
    11211084information on each of the functions associated with directories contained in
    11221085this function management structure.
     1086
    11231087.. code:: c
    11241088
    11251089    rtems_filesystem_file_handlers_r IMFS_directory_handlers = {
    1126     IMFS_dir_open,
    1127     IMFS_dir_close,
    1128     IMFS_dir_read,
    1129     NULL,             /* write \*/
    1130     NULL,             /* ioctl \*/
    1131     IMFS_dir_lseek,
    1132     IMFS_dir_fstat,
    1133     IMFS_fchmod,
    1134     NULL,             /* ftruncate \*/
    1135     NULL,             /* fpathconf \*/
    1136     NULL,             /* fsync \*/
    1137     IMFS_fdatasync,
    1138     IMFS_fcntl
     1090        IMFS_dir_open,
     1091        IMFS_dir_close,
     1092        IMFS_dir_read,
     1093        NULL,             /* write */
     1094        NULL,             /* ioctl */
     1095        IMFS_dir_lseek,
     1096        IMFS_dir_fstat,
     1097        IMFS_fchmod,
     1098        NULL,             /* ftruncate */
     1099        NULL,             /* fpathconf */
     1100        NULL,             /* fsync */
     1101        IMFS_fdatasync,
     1102        IMFS_fcntl
    11391103    };
    1140 
    1141 .. COMMENT: @page
    11421104
    11431105IMFS_dir_open() for Directories
     
    11501112**Arguments:**
    11511113
    1152 .. code:: c
    1153 
    1154     rtems_libio_t  \*iop,
    1155     const char     \*pathname,
     1114.. code-block:: c
     1115
     1116    rtems_libio_t  *iop,
     1117    const char     *pathname,
    11561118    unsigned32      flag,
    11571119    unsigned32      mode
     
    11661128is associated with the directory.
    11671129
    1168 The routine will verify that the node is a directory. If its not a directory
    1169 an error code will be returned.
     1130The routine will verify that the node is a directory. If its not a directory an
     1131error code will be returned.
    11701132
    11711133If it is a directory, the offset in the file control block will be set to 0.
    11721134This allows us to start reading at the beginning of the directory.
    11731135
    1174 .. COMMENT: @page
    1175 
    11761136IMFS_dir_close() for Directories
    11771137~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    11831143**Arguments:**
    11841144
    1185 .. code:: c
     1145.. code-block:: c
    11861146
    11871147    rtems_libio_t     \*iop
     
    11961156immediately returns a success status.
    11971157
    1198 .. COMMENT: @page
    1199 
    12001158IMFS_dir_read() for Directories
    12011159~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    12071165**Arguments:**
    12081166
    1209 .. code:: c
    1210 
    1211     rtems_libio_t  \*iop,
    1212     void           \*buffer,
     1167.. code-block:: c
     1168
     1169    rtems_libio_t  *iop,
     1170    void           *buffer,
    12131171    unsigned32      count
    12141172
     
    12201178
    12211179This routine will read a fixed number of directory entries from the current
    1222 directory offset. The number of directory bytes read will be returned from
    1223 this routine.
    1224 
    1225 .. COMMENT: @page
     1180directory offset. The number of directory bytes read will be returned from this
     1181routine.
    12261182
    12271183No write() for Directories
     
    12441200XXX
    12451201
    1246 .. COMMENT: @page
    1247 
    12481202No ioctl() for Directories
    12491203~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    12631217XXX
    12641218
    1265 .. COMMENT: @page
    1266 
    12671219IMFS_dir_lseek() for Directories
    12681220~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    12741226**Arguments:**
    12751227
    1276 .. code:: c
    1277 
    1278     rtems_libio_t      \*iop,
     1228.. code-block:: c
     1229
     1230    rtems_libio_t      *iop,
    12791231    off_t               offset,
    12801232    int                 whence
     
    12901242No test is performed on the number of children under the current open
    12911243directory.  The imfs_dir_read() function protects against reads beyond the
    1292 current size to the directory by returning a 0 bytes transfered to the
    1293 calling programs whenever the file position index exceeds the last entry in
    1294 the open directory.
    1295 
    1296 .. COMMENT: @page
     1244current size to the directory by returning a 0 bytes transfered to the calling
     1245programs whenever the file position index exceeds the last entry in the open
     1246directory.
    12971247
    12981248IMFS_dir_fstat() for Directories
     
    13051255**Arguments:**
    13061256
    1307 .. code:: c
    1308 
    1309     rtems_filesystem_location_info_t   \*loc,
    1310     struct stat                        \*buf
     1257.. code-block:: c
     1258
     1259    rtems_filesystem_location_info_t   *loc,
     1260    struct stat                        *buf
    13111261
    13121262**File:**
     
    13371287- st_ctime
    13381288
    1339 The st_size field is obtained by running through the chain of directory
    1340 entries and summing the sizes of the dirent structures associated with each
    1341 of the children of the directory.
    1342 
    1343 .. COMMENT: @page
     1289The st_size field is obtained by running through the chain of directory entries
     1290and summing the sizes of the dirent structures associated with each of the
     1291children of the directory.
    13441292
    13451293IMFS_fchmod() for Directories
     
    13521300**Arguments:**
    13531301
    1354 .. code:: c
    1355 
    1356     rtems_libio_t     \*iop
     1302.. code-block:: c
     1303
     1304    rtems_libio_t     *iop
    13571305    mode_t             mode
    13581306
     
    13671315
    13681316Based on configuration the routine will acquire the user ID from a call to
    1369 getuid()  or from the IMFS_jnode_t structure.
    1370 
    1371 It then checks to see if we have the ownership rights to alter the mode of
    1372 the file.  If the caller does not, an error code is returned.
     1317getuid() or from the IMFS_jnode_t structure.
     1318
     1319It then checks to see if we have the ownership rights to alter the mode of the
     1320file.  If the caller does not, an error code is returned.
    13731321
    13741322An additional test is performed to verify that the caller is not trying to
     
    13791327based on the mode calling parameter.
    13801328
    1381 .. COMMENT: @page
    1382 
    13831329No ftruncate() for Directories
    13841330~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    14001346XXX
    14011347
    1402 .. COMMENT: @page
    1403 
    14041348No fpathconf() for Directories
    14051349~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    14211365Not Implemented
    14221366
    1423 .. COMMENT: @page
    1424 
    14251367No fsync() for Directories
    14261368~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    14421384XXX
    14431385
    1444 .. COMMENT: @page
    1445 
    14461386IMFS_fdatasync() for Directories
    14471387~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    14621402
    14631403XXX
    1464 
    1465 .. COMMENT: @page
    14661404
    14671405Device Handler Table Functions
     
    14721410filesystem. One table exists for each of the filesystem's node types. The
    14731411structure definition appears below. It is followed by general developmental
    1474 information on each of the functions associated with devices contained in
    1475 this function management structure.
    1476 .. code:: c
     1412information on each of the functions associated with devices contained in this
     1413function management structure.
     1414
     1415.. code-block:: c
    14771416
    14781417    typedef struct {
    1479     rtems_filesystem_open_t           open;
    1480     rtems_filesystem_close_t          close;
    1481     rtems_filesystem_read_t           read;
    1482     rtems_filesystem_write_t          write;
    1483     rtems_filesystem_ioctl_t          ioctl;
    1484     rtems_filesystem_lseek_t          lseek;
    1485     rtems_filesystem_fstat_t          fstat;
    1486     rtems_filesystem_fchmod_t         fchmod;
    1487     rtems_filesystem_ftruncate_t      ftruncate;
    1488     rtems_filesystem_fpathconf_t      fpathconf;
    1489     rtems_filesystem_fsync_t          fsync;
    1490     rtems_filesystem_fdatasync_t      fdatasync;
     1418        rtems_filesystem_open_t           open;
     1419        rtems_filesystem_close_t          close;
     1420        rtems_filesystem_read_t           read;
     1421        rtems_filesystem_write_t          write;
     1422        rtems_filesystem_ioctl_t          ioctl;
     1423        rtems_filesystem_lseek_t          lseek;
     1424        rtems_filesystem_fstat_t          fstat;
     1425        rtems_filesystem_fchmod_t         fchmod;
     1426        rtems_filesystem_ftruncate_t      ftruncate;
     1427        rtems_filesystem_fpathconf_t      fpathconf;
     1428        rtems_filesystem_fsync_t          fsync;
     1429        rtems_filesystem_fdatasync_t      fdatasync;
    14911430    } rtems_filesystem_file_handlers_r;
    1492 
    1493 .. COMMENT: @page
    14941431
    14951432device_open() for Devices
     
    15021439**Arguments:**
    15031440
    1504 .. code:: c
    1505 
    1506     rtems_libio_t     \*iop,
    1507     const char        \*pathname,
     1441.. code-block:: c
     1442
     1443    rtems_libio_t     *iop,
     1444    const char        *pathname,
    15081445    unsigned32         flag,
    15091446    unsigned32         mode
     
    15211458
    15221459The major and minor device numbers will be used to make a rtems_io_open()
    1523 function call to open the device driver. An argument list is sent to the
    1524 driver that contains the file control block, flags and mode information.
    1525 
    1526 .. COMMENT: @page
     1460function call to open the device driver. An argument list is sent to the driver
     1461that contains the file control block, flags and mode information.
    15271462
    15281463device_close() for Devices
     
    15351470**Arguments:**
    15361471
    1537 .. code:: c
    1538 
    1539     rtems_libio_t     \*iop
     1472.. code-block:: c
     1473
     1474    rtems_libio_t     *iop
    15401475
    15411476**File:**
     
    15531488major and minor device numbers.
    15541489
    1555 .. COMMENT: @page
    1556 
    15571490device_read() for Devices
    15581491~~~~~~~~~~~~~~~~~~~~~~~~~
     
    15641497**Arguments:**
    15651498
    1566 .. code:: c
    1567 
    1568     rtems_libio_t     \*iop,
    1569     void              \*buffer,
     1499.. code-block:: c
     1500
     1501    rtems_libio_t     *iop,
     1502    void              *buffer,
    15701503    unsigned32         count
    15711504
     
    15791512jnode- associated with the file descriptor.
    15801513
    1581 A rtems_io_read() call will be made to the device driver associated with the file
    1582 descriptor. The major and minor device number will be sent as arguments as well
    1583 as an argument list consisting of:
     1514A rtems_io_read() call will be made to the device driver associated with the
     1515file descriptor. The major and minor device number will be sent as arguments as
     1516well as an argument list consisting of:
    15841517
    15851518- file control block
     
    15941527- flags from the file control block
    15951528
    1596 On return from the rtems_io_read() the number of bytes that were actually
    1597 read will be returned to the calling program.
    1598 
    1599 .. COMMENT: @page
     1529On return from the rtems_io_read() the number of bytes that were actually read
     1530will be returned to the calling program.
    16001531
    16011532device_write() for Devices
     
    16181549XXX
    16191550
    1620 .. COMMENT: @page
    1621 
    16221551device_ioctl() for Devices
    16231552~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    16291558**Arguments:**
    16301559
    1631 .. code:: c
    1632 
    1633     rtems_libio_t     \*iop,
     1560.. code-block:: c
     1561
     1562    rtems_libio_t     *iop,
    16341563    unsigned32         command,
    1635     void              \*buffer
     1564    void              *buffer
    16361565
    16371566**File:**
     
    16521581to return the device status information.
    16531582
    1654 The device specific command should indicate the nature of the information
    1655 that is desired from the device.
     1583The device specific command should indicate the nature of the information that
     1584is desired from the device.
    16561585
    16571586After the rtems_io_control() is processed, the buffer should contain the
    16581587requested device information.
    16591588
    1660 If the device information is not obtained properly a -1 will be returned to
    1661 the calling program, otherwise the ioctl_return value is returned.
    1662 
    1663 .. COMMENT: @page
     1589If the device information is not obtained properly a -1 will be returned to the
     1590calling program, otherwise the ioctl_return value is returned.
    16641591
    16651592device_lseek() for Devices
     
    16721599**Arguments:**
    16731600
    1674 .. code:: c
    1675 
    1676     rtems_libio_t     \*iop,
     1601.. code-block:: c
     1602
     1603    rtems_libio_t     *iop,
    16771604    off_t              offset,
    16781605    int                whence
     
    16871614successful status.
    16881615
    1689 .. COMMENT: @page
    1690 
    16911616IMFS_stat() for Devices
    16921617~~~~~~~~~~~~~~~~~~~~~~~
     
    16981623**Arguments:**
    16991624
    1700 .. code:: c
    1701 
    1702     rtems_filesystem_location_info_t   \*loc,
    1703     struct stat                        \*buf
     1625.. code-block:: c
     1626
     1627    rtems_filesystem_location_info_t   *loc,
     1628    struct stat                        *buf
    17041629
    17051630**File:**
     
    17111636This routine actually performs status processing for both devices and regular files.
    17121637
    1713 The IMFS_jnode_t structure is referenced to determine the type of node under the
    1714 filesystem.
     1638The IMFS_jnode_t structure is referenced to determine the type of node under
     1639the filesystem.
    17151640
    17161641If the node is associated with a device, node information is extracted and
    17171642transformed to set the st_dev element of the stat structure.
    17181643
    1719 If the node is a regular file, the size of the regular file is extracted from the node.
     1644If the node is a regular file, the size of the regular file is extracted from
     1645the node.
    17201646
    17211647This routine rejects other node types.
     
    17401666- st_ctime
    17411667
    1742 .. COMMENT: @page
    1743 
    17441668IMFS_fchmod() for Devices
    17451669~~~~~~~~~~~~~~~~~~~~~~~~~
     
    17511675**Arguments:**
    17521676
    1753 .. code:: c
    1754 
    1755     rtems_libio_t     \*iop
     1677.. code-block:: c
     1678
     1679    rtems_libio_t     *iop
    17561680    mode_t             mode
    17571681
     
    17681692getuid()  or from the IMFS_jnode_t structure.
    17691693
    1770 It then checks to see if we have the ownership rights to alter the mode of
    1771 the file.  If the caller does not, an error code is returned.
     1694It then checks to see if we have the ownership rights to alter the mode of the
     1695file.  If the caller does not, an error code is returned.
    17721696
    17731697An additional test is performed to verify that the caller is not trying to
     
    17781702based on the mode calling parameter.
    17791703
    1780 .. COMMENT: @page
    1781 
    17821704No ftruncate() for Devices
    17831705~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    17991721XXX
    18001722
    1801 .. COMMENT: @page
    1802 
    18031723No fpathconf() for Devices
    18041724~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    18201740Not Implemented
    18211741
    1822 .. COMMENT: @page
    1823 
    18241742No fsync() for Devices
    18251743~~~~~~~~~~~~~~~~~~~~~~
     
    18411759XXX
    18421760
    1843 .. COMMENT: @page
    1844 
    18451761No fdatasync() for Devices
    18461762~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    18631779
    18641780XXX
    1865 
    1866 .. COMMENT: COPYRIGHT (c) 1988-2002.
    1867 
    1868 .. COMMENT: On-Line Applications Research Corporation (OAR).
    1869 
    1870 .. COMMENT: All rights reserved.
    1871 
  • filesystem/index.rst

    rb0f2977 r4cacea0  
    55=============================
    66
    7 COPYRIGHT (c) 1988 - 2015.
     7 | COPYRIGHT (c) 1988 - 2015.
     8 | On-Line Applications Research Corporation (OAR).
    89
    9 On-Line Applications Research Corporation (OAR).
     10The authors have used their best efforts in preparing this material.  These
     11efforts include the development, research, and testing of the theories and
     12programs to determine their effectiveness.  No warranty of any kind, expressed
     13or implied, with regard to the software or the material contained in this
     14document is provided.  No liability arising out of the application or use of
     15any product described in this document is assumed.  The authors reserve the
     16right to revise this material and to make changes from time to time in the
     17content hereof without obligation to notify anyone of such revision or changes.
    1018
    11 The authors have used their best efforts in preparing
    12 this material.  These efforts include the development, research,
    13 and testing of the theories and programs to determine their
    14 effectiveness.  No warranty of any kind, expressed or implied,
    15 with regard to the software or the material contained in this
    16 document is provided.  No liability arising out of the
    17 application or use of any product described in this document is
    18 assumed.  The authors reserve the right to revise this material
    19 and to make changes from time to time in the content hereof
    20 without obligation to notify anyone of such revision or changes.
     19The RTEMS Project is hosted at http://www.rtems.org/.  Any inquiries concerning
     20RTEMS, its related support components, or its documentation should be directed
     21to the Community Project hosted at http://www.rtems.org/.
    2122
    22 The RTEMS Project is hosted at http://www.rtems.org.  Any
    23 inquiries concerning RTEMS, its related support components, or its
    24 documentation should be directed to the Community Project hosted athttp://www.rtems.org.
     23.. topic:: RTEMS Online Resources
    2524
    26 Any inquiries for commercial services including training, support, custom
    27 development, application development assistance should be directed to http://www.rtems.com.
    28 
    29 
    30 Table of Contents
    31 -----------------
    32 
    33 .. toctree::
    34 
    35         preface
    36 
     25  ================  =============================
     26  Home              https://www.rtems.org/
     27  Developers        https://devel.rtems.org/
     28  Documentation     https://docs.rtems.org/
     29  Bug Reporting     https://devel.rtems.org/query
     30  Mailing Lists     https://lists.rtems.org/
     31  Git Repositories  https://git.rtems.org/
     32  ================  =============================
    3733
    3834.. toctree::
     
    4036        :numbered:
    4137
     38        preface
    4239        pathname_eval
    4340        system_init
     
    4946        trivial_ftp
    5047        command_and_variable
    51        
     48
    5249*       :ref:`genindex`
    5350*       :ref:`search`
    54 
    55 
  • filesystem/minature_in-memory.rst

    rb0f2977 r4cacea0  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37Miniature In-Memory Filesystem
    48##############################
    59
    6 This chapter describes the Miniature In-Memory FileSystem (miniIMFS).
    7 The miniIMFS is a reduced feature version of the IMFS designed to
    8 provide minimal functionality and have a low memory footprint.
     10This chapter describes the Miniature In-Memory FileSystem (miniIMFS).  The
     11miniIMFS is a reduced feature version of the IMFS designed to provide minimal
     12functionality and have a low memory footprint.
    913
    10 This chapter should be written after the IMFS chapter is completed
    11 and describe the implementation of the mini-IMFS.
    12 
    13 .. COMMENT: COPYRIGHT (c) 1988-2002.
    14 
    15 .. COMMENT: On-Line Applications Research Corporation (OAR).
    16 
    17 .. COMMENT: All rights reserved.
    18 
     14This chapter should be written after the IMFS chapter is completed and describe
     15the implementation of the mini-IMFS.
  • filesystem/mounting_and_unmounting.rst

    rb0f2977 r4cacea0  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37Mounting and Unmounting Filesystems
     
    913The following is the list of the characteristics of a mount point:
    1014
    11 - The mount point must be a directory. It may have files and other
    12   directories under it. These files and directories will be hidden when the
    13   filesystem is mounted.
     15- The mount point must be a directory. It may have files and other directories
     16  under it. These files and directories will be hidden when the filesystem is
     17  mounted.
    1418
    15 - The task must have read/write/execute permissions to the mount point
    16   or the mount attempt will be rejected.
     19- The task must have read/write/execute permissions to the mount point or the
     20  mount attempt will be rejected.
    1721
    1822- Only one filesystem can be mounted to a single mount point.
    1923
    20 - The Root of the mountable filesystem will be referenced by the name
    21   of the mount point after the mount is complete.
     24- The Root of the mountable filesystem will be referenced by the name of the
     25  mount point after the mount is complete.
    2226
    2327Mount Table Chain
    2428=================
    2529
    26 The mount table chain is a dynamic list of structures that describe
    27 mounted filesystems a specific points in the filesystem hierarchy. It is
    28 initialized to an empty state during the base filesystem initialization.
    29 The mount operation will add entries to the mount table chain. The
    30 un-mount operation will remove entries from the mount table chain.
     30The mount table chain is a dynamic list of structures that describe mounted
     31filesystems a specific points in the filesystem hierarchy. It is initialized to
     32an empty state during the base filesystem initialization.  The mount operation
     33will add entries to the mount table chain. The un-mount operation will remove
     34entries from the mount table chain.
    3135
    3236Each entry in the mount table chain is of the following type:
    33 .. code:: c
     37
     38.. code-block:: c
    3439
    3540    struct rtems_filesystem_mount_table_entry_tt
    3641    {
    37     Chain_Node                             Node;
    38     rtems_filesystem_location_info_t       mt_point_node;
    39     rtems_filesystem_location_info_t       mt_fs_root;
    40     int                                    options;
    41     void                                  \*fs_info;
    42     rtems_filesystem_limits_and_options_t  pathconf_limits_and_options;
    43     /*
    44     *  When someone adds a mounted filesystem on a real device,
    45     *  this will need to be used.
    46     *
    47     *  The best option long term for this is probably an
    48     *  open file descriptor.
    49     \*/
    50     char                                  \*dev;
     42        Chain_Node                             Node;
     43        rtems_filesystem_location_info_t       mt_point_node;
     44        rtems_filesystem_location_info_t       mt_fs_root;
     45        int                                    options;
     46        void                                  *fs_info;
     47        rtems_filesystem_limits_and_options_t  pathconf_limits_and_options;
     48        /*
     49         *  When someone adds a mounted filesystem on a real device,
     50         *  this will need to be used.
     51         *
     52         *  The best option long term for this is probably an
     53         *  open file descriptor.
     54         */
     55         char                                  \*dev;
    5156    };
    5257
     
    5863    directory where a filesystem is mounted onto.  This element may contain
    5964    memory that is allocated during a path evaluation of the filesystem
    60     containing the mountpoint directory.  The generic code allows this
    61     memory to be returned by unmount when the filesystem identified by
    62     mt_fs_root is unmounted.
     65    containing the mountpoint directory.  The generic code allows this memory
     66    to be returned by unmount when the filesystem identified by mt_fs_root is
     67    unmounted.
    6368
    6469*mt_fs_root*
    65     The mt_fs_root contains all information necessary to identify the root
    66     of the mounted filesystem. The user is never allowed access to this
    67     node by the generic code, but it is used to identify to the mounted
    68     filesystem where to start evaluation of pathnames at.
     70    The mt_fs_root contains all information necessary to identify the root of
     71    the mounted filesystem. The user is never allowed access to this node by
     72    the generic code, but it is used to identify to the mounted filesystem
     73    where to start evaluation of pathnames at.
    6974
    7075*options*
     
    7580    system to identify unique things applicable to this instance of the file
    7681    system.  For example the IMFS uses this space to provide node
    77     identification that is unique for each instance (mounting) of the filesystem.
     82    identification that is unique for each instance (mounting) of the
     83    filesystem.
    7884
    7985*pathconf_limits_and_options*
     
    8692========================================
    8793
    88 When a filesystem is mounted, its presence and location in the file
    89 system hierarchy is recorded in a dynamic list structure known as a chain.
    90 A unique rtems_filesystem_mount_table_entry_tt structure is logged for
    91 each filesystem that is mounted. This includes the base filesystem.
     94When a filesystem is mounted, its presence and location in the file system
     95hierarchy is recorded in a dynamic list structure known as a chain.  A unique
     96rtems_filesystem_mount_table_entry_tt structure is logged for each filesystem
     97that is mounted. This includes the base filesystem.
    9298
    9399Removing entries from the chain during unmount
    94100==============================================
    95101
    96 When a filesystem is dismounted its entry in the mount table chain is
    97 extracted and the memory for this entry is freed.
    98 
    99 .. COMMENT: COPYRIGHT (c) 1988-2002.
    100 
    101 .. COMMENT: On-Line Applications Research Corporation (OAR).
    102 
    103 .. COMMENT: All rights reserved.
    104 
     102When a filesystem is dismounted its entry in the mount table chain is extracted
     103and the memory for this entry is freed.
  • filesystem/pathname_eval.rst

    rb0f2977 r4cacea0  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37Pathname Evaluation
    48###################
    59
    6 This chapter describes the pathname evaluation process for the
    7 RTEMS Filesystem Infrastructure.
    8 .. code:: c
     10This chapter describes the pathname evaluation process for the RTEMS Filesystem
     11Infrastructure.
     12
     13.. code-block:: shell
    914
    1015    XXX Include graphic of the path evaluation process
     
    1318============================
    1419
    15 There are two pathname evaluation routines.  The handler patheval()
    16 is called to find, verify privlages on and return information on a node
    17 that exists.  The handler evalformake() is called to find, verify
    18 permissions, and return information on a node that is to become a parent.
    19 Additionally, evalformake() returns a pointer to the start of the name of
    20 the new node to be created.
     20There are two pathname evaluation routines.  The handler patheval() is called
     21to find, verify privlages on and return information on a node that exists.  The
     22handler ``evalformake()`` is called to find, verify permissions, and return
     23information on a node that is to become a parent.  Additionally, evalformake()
     24returns a pointer to the start of the name of the new node to be created.
    2125
    22 Pathname evaluation is specific to a filesystem.
    23 Each filesystem is required to provide both a patheval() and an evalformake()
    24 routine.  Both of these routines gets a name to evaluate and a node indicating
    25 where to start the evaluation.
     26Pathname evaluation is specific to a filesystem.  Each filesystem is required
     27to provide both a ``patheval()`` and an ``evalformake()`` routine.  Both of
     28these routines gets a name to evaluate and a node indicating where to start the
     29evaluation.
    2630
    2731Crossing a Mount Point During Path Evaluation
    2832=============================================
    2933
    30 If the filesystem supports the mount command, the evaluate routines
    31 must handle crossing the mountpoint.  The evaluate routine should evaluate
    32 the name upto the first directory node where the new filesystem is mounted.
    33 The filesystem may process terminator characters prior to calling the
    34 evaluate routine for the new filesystem.   A pointer to the portion of the
    35 name which has not been evaluated along with the root node of the new
    36 file system ( gotten from the mount table entry ) is passed to the correct
    37 mounted filesystem evaluate routine.
     34If the filesystem supports the mount command, the evaluate routines must handle
     35crossing the mountpoint.  The evaluate routine should evaluate the name upto
     36the first directory node where the new filesystem is mounted.  The filesystem
     37may process terminator characters prior to calling the evaluate routine for the
     38new filesystem.  A pointer to the portion of the name which has not been
     39evaluated along with the root node of the new file system (gotten from the
     40mount table entry) is passed to the correct mounted filesystem evaluate
     41routine.
    3842
    3943The rtems_filesystem_location_info_t Structure
     
    4448
    4549The generic rtems filesystem code defines two global
    46 rtems_filesystem_location_info_t structures, the``rtems_filesystem_root`` and the ``rtems_filesystem_current``.
    47 Both are initially defined to be the root node of the base filesystem.
    48 Once the chdir command is correctly used the ``rtems_filesystem_current``
    49 is set to the location specified by the command.
     50rtems_filesystem_location_info_t structures, the``rtems_filesystem_root`` and
     51the ``rtems_filesystem_current``.  Both are initially defined to be the root
     52node of the base filesystem.  Once the chdir command is correctly used the
     53``rtems_filesystem_current`` is set to the location specified by the command.
    5054
    5155The filesystem generic code peeks at the first character in the name to be
    52 evaluated.  If this character is a valid seperator, the``rtems_filesystem_root`` is used as the node to start the evaluation
    53 with.  Otherwise, the ``rtems_filesystem_current`` node is used as the
    54 node to start evaluating with.  Therefore, a valid
    55 rtems_filesystem_location_info_t is given to the evaluate routine to start
    56 evaluation with.  The evaluate routines are then responsible for making
    57 any changes necessary to this structure to correspond to the name being
    58 parsed.
    59 .. code:: c
     56evaluated.  If this character is a valid seperator,
     57the``rtems_filesystem_root`` is used as the node to start the evaluation with.
     58Otherwise, the ``rtems_filesystem_current`` node is used as the node to start
     59evaluating with.  Therefore, a valid rtems_filesystem_location_info_t is given
     60to the evaluate routine to start evaluation with.  The evaluate routines are
     61then responsible for making any changes necessary to this structure to
     62correspond to the name being parsed.
     63
     64.. code-block:: c
    6065
    6166    struct rtems_filesystem_location_info_tt {
    62     void                                     \*node_access;
    63     rtems_filesystem_file_handlers_r         \*handlers;
    64     rtems_filesystem_operations_table        \*ops;
    65     rtems_filesystem_mount_table_entry_t     \*mt_entry;
     67        void                                     *node_access;
     68        rtems_filesystem_file_handlers_r         *handlers;
     69        rtems_filesystem_operations_table        *ops;
     70        rtems_filesystem_mount_table_entry_t     *mt_entry;
    6671    };
    6772
    6873*node_access*
    69     This element is filesystem specific.  A filesystem can define and store
    70     any information necessary to identify a node at this location.  This element
    71     is normally filled in by the filesystem's evaluate routine. For the
    72     filesystem's root node, the filesystem's initilization routine should
    73     fill this in, and it should remain valid until the instance of the
    74     filesystem is unmounted.
     74    This element is filesystem specific.  A filesystem can define and store any
     75    information necessary to identify a node at this location.  This element is
     76    normally filled in by the filesystem's evaluate routine. For the
     77    filesystem's root node, the filesystem's initilization routine should fill
     78    this in, and it should remain valid until the instance of the filesystem is
     79    unmounted.
    7580
    7681*handlers*
    77     This element is defined as a set of routines that may change within a
    78     given filesystem based upon node type.  For example a directory and a
    79     memory file may have to completely different read routines.  This element
    80     is set to an initialization state defined by the mount table, and may
    81     be set to the desired state by the evaluation routines.
     82    This element is defined as a set of routines that may change within a given
     83    filesystem based upon node type.  For example a directory and a memory file
     84    may have to completely different read routines.  This element is set to an
     85    initialization state defined by the mount table, and may be set to the
     86    desired state by the evaluation routines.
    8287
    8388*ops*
    8489    This element is defined as a set of routines that remain static for the
    85     filesystem.  This element identifies entry points into the filesystem
    86     to the generic code.
     90    filesystem.  This element identifies entry points into the filesystem to
     91    the generic code.
    8792
    8893*mt_entry*
    8994    This element identifies the mount table entry for this instance of the
    9095    filesystem.
    91 
    92 .. COMMENT: COPYRIGHT (c) 1988-2002.
    93 
    94 .. COMMENT: On-Line Applications Research Corporation (OAR).
    95 
    96 .. COMMENT: All rights reserved.
    97 
  • filesystem/preface.rst

    rb0f2977 r4cacea0  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37=======
     
    610
    711This document describes the implementation of the RTEMS filesystem
    8 infrastructure.  This infrastructure supports the following
    9 capabilities:
     12infrastructure.  This infrastructure supports the following capabilities:
    1013
    1114- Mountable file systems
     
    1619
    1720- Individual file and directory support for the following:
     21
    1822  # Permissions for read, write and execute
    1923  # User ID
     
    2731- Symbolic links to files and directories
    2832
    29 This has been implemented to provide the framework for a UNIX-like
    30 file system support. POSIX file and directory functions have been
    31 implemented that allow a standard method of accessing file, device and
    32 directory information within file systems. The file system concept that
    33 has been implemented allows for expansion and adaptation of the file
    34 system to a variety of existing and future data storage devices. To this
    35 end, file system mount and unmount capabilities have been included in this
    36 RTEMS framework.
     33This has been implemented to provide the framework for a UNIX-like file system
     34support. POSIX file and directory functions have been implemented that allow a
     35standard method of accessing file, device and directory information within file
     36systems. The file system concept that has been implemented allows for expansion
     37and adaptation of the file system to a variety of existing and future data
     38storage devices. To this end, file system mount and unmount capabilities have
     39been included in this RTEMS framework.
    3740
    38 This framework slightly alters the manner in which devices are handled
    39 under RTEMS from that of public release 4.0.0 and earlier.  Devices that
    40 are defined under a given RTEMS configuration will now be registered as
    41 files in a mounted file system.  Access to these device drivers and their
    42 associated devices may now be performed through the traditional file system
    43 open(), read(), write(), lseek(), fstat() and ioctl() functions in addition
    44 to the interface provided by the IO Manager in the RTEMS Classic API.
     41This framework slightly alters the manner in which devices are handled under
     42RTEMS from that of public release 4.0.0 and earlier.  Devices that are defined
     43under a given RTEMS configuration will now be registered as files in a mounted
     44file system.  Access to these device drivers and their associated devices may
     45now be performed through the traditional file system open(), read(), write(),
     46lseek(), fstat() and ioctl() functions in addition to the interface provided by
     47the IO Manager in the RTEMS Classic API.
    4548
    4649An In-Memory File System (IMFS) is included which provides full POSIX
    47 filesystem functionality yet is RAM based.  The IMFS maintains a
    48 node structure for each file, device, and directory in each mounted
    49 instantiation of its file system. The node structure is used to
    50 manage ownership, access rights, access time, modification time,
    51 and creation time.  A union of structures within the IMFS nodal
    52 structure provide for manipulation of file data, device selection,
    53 or directory content as required by the nodal type. Manipulation of
    54 these properties is accomplished through the POSIX set of file and
    55 directory functions.  In addition to being useful in its own right,
    56 the IMFS serves as a full featured example filesystem.
     50filesystem functionality yet is RAM based.  The IMFS maintains a node structure
     51for each file, device, and directory in each mounted instantiation of its file
     52system. The node structure is used to manage ownership, access rights, access
     53time, modification time, and creation time.  A union of structures within the
     54IMFS nodal structure provide for manipulation of file data, device selection,
     55or directory content as required by the nodal type. Manipulation of these
     56properties is accomplished through the POSIX set of file and directory
     57functions.  In addition to being useful in its own right, the IMFS serves as a
     58full featured example filesystem.
    5759
    58 The intended audience for this document is those persons implementing
    59 their own filesystem.  Users of the filesystem may find information
    60 on the implementation useful.  But the user interface to the filesystem
    61 is through the ISO/ANSI C Library and POSIX 1003.1b file and directory
    62 APIs.
    63 
    64 .. COMMENT: COPYRIGHT (c) 1988-2002.
    65 
    66 .. COMMENT: On-Line Applications Research Corporation (OAR).
    67 
    68 .. COMMENT: All rights reserved.
    69 
     60The intended audience for this document is those persons implementing their own
     61filesystem.  Users of the filesystem may find information on the implementation
     62useful.  But the user interface to the filesystem is through the ISO/ANSI C
     63Library and POSIX 1003.1b file and directory APIs.
  • filesystem/system_init.rst

    rb0f2977 r4cacea0  
    11.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     2
     3.. COMMENT: COPYRIGHT (c) 1988-2002.
     4.. COMMENT: On-Line Applications Research Corporation (OAR).
     5.. COMMENT: All rights reserved.
    26
    37System Initialization
    48#####################
    59
    6 After the RTEMS initialization is performed, the application's
    7 initialization will be performed. Part of initialization is a call to
    8 rtems_filesystem_initialize(). This routine will mount the 'In Memory File
    9 System' as the base filesystem.  Mounting the base filesystem consists
    10 of the following:
     10After the RTEMS initialization is performed, the application's initialization
     11will be performed. Part of initialization is a call to
     12``rtems_filesystem_initialize()``. This routine will mount the 'In Memory File
     13System' as the base filesystem.  Mounting the base filesystem consists of the
     14following:
    1115
    1216- Initialization of mount table chain control structure
    1317
    14 - Allocation of a ``jnode`` structure that will server as the root node
    15   of the 'In Memory Filesystem'
     18- Allocation of a ``jnode`` structure that will server as the root node of the
     19  'In Memory Filesystem'
    1620
    17 - Initialization of the allocated ``jnode`` with the appropriate OPS,
    18   directory handlers and pathconf limits and options.
     21- Initialization of the allocated ``jnode`` with the appropriate OPS, directory
     22  handlers and pathconf limits and options.
    1923
    20 - Allocation of a memory region for filesystem specific global
    21   management variables
     24- Allocation of a memory region for filesystem specific global management
     25  variables
    2226
    2327- Creation of first mount table entry for the base filesystem
    2428
    25 - Initialization of the first mount table chain entry to indicate that
    26   the mount point is NULL and the mounted filesystem is the base file
    27   system
     29- Initialization of the first mount table chain entry to indicate that the
     30  mount point is NULL and the mounted filesystem is the base file system
    2831
    2932After the base filesystem has been mounted, the following operations are
     
    3942RTEMS initially mounts a RAM based file system known as the base file system.
    4043The root directory of this file system tree serves as the logical root of the
    41 directory hierarchy (Figure 3). Under the root directory a '/dev' directory
    42 is created under which all I/O device directories and files are registered as
    43 part of the file system hierarchy.
    44 .. code:: c
     44directory hierarchy (Figure 3). Under the root directory a '/dev' directory is
     45created under which all I/O device directories and files are registered as part
     46of the file system hierarchy.
     47
     48.. code-block:: shell
    4549
    4650    Figure of the tree structure goes here.
     
    6670At present, the first file system to be mounted is the 'In Memory File
    6771System'. It is mounted using a standard MOUNT() command in which the mount
    68 point is NULL.  This flags the mount as the first file system to be
    69 registered under the operating system and appropriate initialization of file
    70 system management information is performed (See figures 4 and 5). If a
    71 different file system type is desired as the base file system, alterations
    72 must be made to base_fs.c. This routine handles the mount of the base file
    73 system.
     72point is NULL.  This flags the mount as the first file system to be registered
     73under the operating system and appropriate initialization of file system
     74management information is performed (See figures 4 and 5). If a different file
     75system type is desired as the base file system, alterations must be made to
     76base_fs.c. This routine handles the mount of the base file system.
    7477
    75 .. code:: c
     78.. code-block:: shell
    7679
    7780    Figure of the mount table chain goes here.
     
    7982Once the root of the base file system has been established and it has been
    8083recorded as the mount point of the base file system, devices are integrated
    81 into the base file system. For every device that is configured into the
    82 system (See ioman.c) a device registration process is performed. Device
    83 registration produces a unique dev_t handle that consists of a major and
    84 minor device number. In addition, the configuration information for each
    85 device contains a text string that represents the fully qualified pathname to
    86 that device's place in the base file system's hierarchy. A file system node
    87 is created for the device along the specified registration path.
     84into the base file system. For every device that is configured into the system
     85(See ioman.c) a device registration process is performed. Device registration
     86produces a unique dev_t handle that consists of a major and minor device
     87number. In addition, the configuration information for each device contains a
     88text string that represents the fully qualified pathname to that device's place
     89in the base file system's hierarchy. A file system node is created for the
     90device along the specified registration path.
    8891
    89 .. code:: c
     92.. code-block:: shell
    9093
    9194    Figure  of the Mount Table Processing goes here.
     
    9396Note: Other file systems can be mounted but they are mounted onto points
    9497(directory mount points) in the base file system.
    95 
    96 .. COMMENT: COPYRIGHT (c) 1988-2002.
    97 
    98 .. COMMENT: On-Line Applications Research Corporation (OAR).
    99 
    100 .. COMMENT: All rights reserved.
    101 
  • filesystem/trivial_ftp.rst

    rb0f2977 r4cacea0  
    66This chapter describes the Trivial FTP (TFTP) Client Filesystem.
    77
    8 This chapter should be written after the IMFS chapter is completed
    9 and describe the implementation of the TFTP.
    10 
     8This chapter should be written after the IMFS chapter is completed and describe
     9the implementation of the TFTP.
Note: See TracChangeset for help on using the changeset viewer.