source: rtems/doc/filesystem/fsrequirements.t @ 55f5c1e

4.104.114.84.95
Last change on this file since 55f5c1e was 55f5c1e, checked in by Jennifer Averett <Jennifer.Averett@…>, on 10/25/99 at 17:41:03

+ Cleaned up lines that were too long.
+ Removed subheading File - This is not valid for the callback descriptions.
+ Filled in information on freenod

  • Property mode set to 100644
File size: 22.3 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9
10@chapter Filesystem Implementation Requirements
11
12This chapter details the behavioral requirements that all filesystem
13implementations must adhere to.
14
15@section General
16
17The RTEMS filesystem framework was intended to be compliant with the
18POSIX Files and Directories interface standard. The following filesystem
19characteristics resulted in a functional switching layer.
20
21@example
22Figure of the Filesystem Functional Layering goes here.
23This figure includes networking and disk caching layering.
24@end example
25
26@ifset use-ascii
27@example
28@group
29@end group
30@end example
31@end ifset
32
33@ifset use-tex
34@c @image{FunctionalLayerCake,6in,4in}
35@end ifset
36
37@ifset use-html
38@end ifset
39
40@enumerate
41
42@item Application programs are presented with a standard set of POSIX
43compliant functions that allow them to interface with the files, devices
44and directories in the filesystem. The interfaces to these routines do
45not reflect the type of subordinate filesystem implementation in which
46the file will be found.
47
48@item The filesystem framework developed under RTEMS allows for mounting
49filesystem of different types under the base filesystem.
50
51@item The mechanics of locating file information may be quite different
52between filesystem types.
53
54@item The process of locating a file may require crossing filesystem
55boundaries.
56
57@item The transitions between filesystem and the processing required to
58access information in different filesystem is not visible at the level
59of the POSIX function call.
60
61@item The POSIX interface standard provides file access by character
62pathname to the file in some functions and through an integer file
63descriptor in other functions.
64
65@item The nature of the integer file descriptor and its associated
66processing is operating system and filesystem specific.
67
68@item Directory and device information must be processed with some of the
69same routines that apply to files.
70
71@item The form and content of directory and device information differs
72greatly from that of a regular file.
73
74@item Files, directories and devices represent elements (nodes) of a tree
75hierarchy.
76
77@item The rules for processing each of the node types that exist under the
78filesystem are node specific but are still not reflected in the POSIX
79interface routines.
80
81@end enumerate
82
83
84@example
85Figure of the Filesystem Functional Layering goes here.
86This figure focuses on the Base Filesystem and IMFS.
87@end example
88
89@example
90Figure of the IMFS Memfile control blocks
91@end example
92
93@section File and Directory Removal Constraints
94
95The following POSIX constraints must be honored by all filesystems.
96
97@itemize @bullet
98
99@item If a node is a directory with children it cannot be removed.
100
101@item The root node of any filesystem, whether the base filesystem or a
102mounted filesystem, cannot be removed.
103
104@item A node that is a directory that is acting as the mount point of a file
105system cannot be removed.
106
107@item On filesystems supporting hard links, a link count is maintained.
108Prior to node removal, the node's link count is decremented by one.  The
109link count must be less than one to allow for removal of the node.
110
111@end itemize
112
113@c
114@c
115@c
116@section API Layering
117
118@subsection Mapping of Generic System Calls to Filesystem Specific Functions
119
120The list of generic system calls includes the routines open(), read(),
121write(), close(), etc..
122
123The Files and Directories section of the POSIX Application Programs
124Interface specifies a set of functions with calling arguments that are
125used to gain access to the information in a filesystem. To the
126application program, these functions allow access to information in any
127mounted filesystem without explicit knowledge of the filesystem type or
128the filesystem mount configuration. The following are functions that are
129provided to the application:
130
131@enumerate
132@item access()
133@item chdir()
134@item chmod()
135@item chown()
136@item close()
137@item closedir()
138@item fchmod()
139@item fcntl()
140@item fdatasync()
141@item fpathconf()
142@item fstat()
143@item fsync()
144@item ftruncate()
145@item link()
146@item lseek()
147@item mkdir()
148@item mknod()
149@item mount()
150@item open()
151@item opendir()
152@item pathconf()
153@item read()
154@item readdir()
155@item rewinddir()
156@item rmdir()
157@item rmnod()
158@item scandir()
159@item seekdir()
160@item stat()
161@item telldir()
162@item umask()
163@item unlink()
164@item unmount()
165@item utime()
166@item write()
167@end enumerate
168
169The filesystem's type as well as the node type within the filesystem
170determine the nature of the processing that must be performed for each of
171the functions above. The RTEMS filesystem provides a framework that
172allows new filesystem to be developed and integrated without alteration
173to the basic framework.
174
175To provide the functional switching that is required, each of the POSIX
176file and directory functions have been implemented as a shell function.
177The shell function adheres to the POSIX interface standard. Within this
178functional shell, filesystem and node type information is accessed which
179is then used to invoke the appropriate filesystem and node type specific
180routine to process the POSIX function call.
181
182@subsection File/Device/Directory function access via file control block - rtems_libio_t structure
183
184The POSIX open() function returns an integer file descriptor that is used
185as a reference to file control block information for a specific file. The
186file control block contains information that is used to locate node, file
187system, mount table and functional handler information. The diagram in
188Figure 8 depicts the relationship between and among the following
189components.
190
191@enumerate
192
193@item File Descriptor Table
194
195This is an internal RTEMS structure that tracks all currently defined file
196descriptors in the system. The index that is returned by the file open()
197operation references a slot in this table. The slot contains a pointer to
198the file descriptor table entry for this file. The rtems_libio_t structure
199represents the file control block.
200
201@item Allocation of entry in the File Descriptor Table
202
203Access to the file descriptor table is controlled through a semaphore that
204is implemented using the rtems_libio_allocate() function. This routine
205will grab a semaphore and then scan the file control blocks to determine
206which slot is free for use. The first free slot is marked as used and the
207index to this slot is returned as the file descriptor for the open()
208request. After the alterations have been made to the file control block
209table, the semaphore is released to allow further operations on the table.
210
211@item Maximum number of entries in the file descriptor table is
212configurable through the src/exec/sapi/headers/confdefs.h file. If the
213CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS constant is defined its value
214will represent the maximum number of file descriptors that are allowed. 
215If CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS is not specified a default
216value of 20 will be used as the maximum number of file descriptors
217allowed.
218
219@item File control block - rtems_libio_t structure
220
221@example
222struct rtems_libio_tt @{
223  rtems_driver_name_t              *driver;
224  off_t                             size;
225  off_t                             offset;
226  unsigned32                        flags;
227  rtems_filesystem_location_info_t  pathinfo;
228  Objects_Id                        sem;
229  unsigned32                        data0;
230  void                              data1;
231  void                              file_info;
232  rtems_filesystem_file_handlers_r  handlers;
233@};
234@end example
235
236A file control block can exist for regular files, devices and directories.
237The following fields are important for regular file and directory access:
238
239@itemize @bullet
240
241@item Size - For a file this represents the number of bytes currently
242stored in a file. For a directory this field is not filled in.
243
244@item Offset - For a file this is the byte file position index relative to
245the start of the file. For a directory this is the byte offset into a
246sequence of dirent structures.
247
248@item Pathinfo - This is a structure that provides a pointer to node
249information, OPS table functions, Handler functions and the mount table
250entry associated with this node.
251
252@item file_info - A pointer to node information that is used by Handler
253functions
254
255@item handlers - A pointer to a table of handler functions that operate on
256a file, device or directory through a file descriptor index
257
258@end itemize
259
260@end enumerate
261
262@subsection File/Directory function access via rtems_filesystem_location_info_t structure
263
264The rtems_filesystem_location_info_tt structure below provides sufficient
265information to process nodes under a mounted filesystem.
266
267@example
268struct rtems_filesystem_location_info_tt @{
269    void                                         *node_access;
270    rtems_filesystem_file_handlers_r         *handlers;
271    rtems_filesystem_operations_table        *ops;
272    rtems_filesystem_mount_table_entry_t     *mt_entry;
273@};
274@end example
275
276It contains a void pointer to filesystem specific nodal structure,
277pointers to the OPS table for the filesystem that contains the node, the
278node type specific handlers for the node and a reference pointer to the
279mount table entry associated with the filesystem containing the node
280
281@section Operation Tables
282
283Filesystem specific operations are invoked indirectly.  The set of
284routines that implement the filesystem are configured into two tables.
285The Filesystem Handler Table has routines that are specific to a
286filesystem but remain constant regardless of the actual file type.
287The File Handler Table has routines that are both filesystem and file type
288specific.
289
290@subsection Filesystem Handler Table Functions
291
292OPS table functions are defined in a @code{rtems_filesystem_operations_table}
293structure.  It defines functions that are specific to a given filesystem.
294One table exists for each filesystem that is supported in the RTEMS
295configuration. The structure definition appears below and is followed by
296general developmental information on each of the functions contained in this
297function management structure.
298
299@example
300typedef struct @{
301  rtems_filesystem_evalpath_t        evalpath;
302  rtems_filesystem_evalmake_t        evalformake;
303  rtems_filesystem_link_t            link;
304  rtems_filesystem_unlink_t          unlink;
305  rtems_filesystem_node_type_t       node_type;
306  rtems_filesystem_mknod_t           mknod;
307  rtems_filesystem_rmnod_t           rmnod;
308  rtems_filesystem_chown_t           chown;
309  rtems_filesystem_freenode_t        freenod;
310  rtems_filesystem_mount_t           mount;
311  rtems_filesystem_fsmount_me_t      fsmount_me;
312  rtems_filesystem_unmount_t         unmount;
313  rtems_filesystem_fsunmount_me_t    fsunmount_me;
314  rtems_filesystem_utime_t           utime;
315  rtems_filesystem_evaluate_link_t   eval_link;
316  rtems_filesystem_symlink_t         symlink;
317@} rtems_filesystem_operations_table;
318@end example
319
320@c
321@c
322@c
323@c @page
324
325@subsubsection evalpath Handler
326
327@subheading Corresponding Structure Element:
328
329XXX
330
331@subheading Arguments:
332
333XXX
334
335@subheading Description:
336
337XXX
338
339
340@c
341@c
342@c
343@c @page
344
345@subsubsection evalformake Handler
346
347@subheading Corresponding Structure Element:
348
349XXX
350
351@subheading Arguments:
352
353XXX
354
355@subheading Description:
356
357XXX
358
359
360@c
361@c
362@c
363@c @page
364
365@subsubsection link Handler
366
367@subheading Corresponding Structure Element:
368
369link
370
371@subheading Arguments:
372
373
374@example
375rtems_filesystem_location_info_t    *to_loc,      /* IN */
376rtems_filesystem_location_info_t    *parent_loc,  /* IN */
377const char                          *token        /* IN */
378@end example
379
380@subheading Description:
381
382
383This routine is used to create a hard-link.
384
385It will first examine the st_nlink count of the node that we are trying to.
386If the link count exceeds LINK_MAX an error will be returned.
387
388The name of the link will be normalized to remove extraneous separators from
389the end of the name.
390
391@c
392@c
393@c
394@c @page
395
396@subsubsection unlink Handler
397
398@subheading Corresponding Structure Element:
399
400XXX
401
402@subheading Arguments:
403
404XXX
405
406@subheading Description:
407
408XXX
409
410
411@c
412@c
413@c
414@c @page
415
416@subsubsection node_type Handler
417
418@subheading Corresponding Structure Element:
419
420node_type()
421
422@subheading Arguments:
423
424@example
425rtems_filesystem_location_info_t    *pathloc        /* IN */
426@end example
427
428@subheading Description:
429
430XXX
431
432@c
433@c
434@c
435@c @page
436
437@subsubsection mknod Handler
438
439@subheading Corresponding Structure Element:
440
441mknod()
442
443@subheading Arguments:
444
445@example
446const char                          *token,        /* IN */
447mode_t                               mode,         /* IN */
448dev_t                                dev,          /* IN */
449rtems_filesystem_location_info_t    *pathloc       /* IN/OUT */
450@end example
451
452@subheading Description:
453
454XXX
455
456@c
457@c
458@c
459@c @page
460
461@subsubsection rmnod Handler
462
463@subheading Corresponding Structure Element:
464
465XXX
466
467@subheading Arguments:
468
469XXX
470
471@subheading Description:
472
473XXX
474
475
476@c
477@c
478@c
479@c @page
480
481@subsubsection chown Handler
482
483@subheading Corresponding Structure Element:
484
485chown()
486
487@subheading Arguments:
488
489@example
490rtems_filesystem_location_info_t    *pathloc        /* IN */
491uid_t                                owner          /* IN */
492gid_t                                group          /* IN */
493@end example
494
495@subheading Description:
496
497XXX
498
499@c
500@c
501@c
502@c @page
503
504@subsubsection freenod Handler
505
506@subheading Corresponding Structure Element:
507
508freenod()
509
510@subheading Arguments:
511
512@example
513rtems_filesystem_location_info_t      *pathloc       /* IN */
514@end example
515
516@subheading Description:
517
518This routine is used by the generic code to allow memory to be allocated
519during the evaluate routines, and set free when the generic code is finished
520accessing a node.  If the evaluate routines allocate memory to identify
521a node this routine should be utilized to free that memory.
522
523This routine is not required and may be set to NULL.
524
525@c
526@c
527@c
528@c @page
529
530@subsubsection mount Handler
531
532@subheading Corresponding Structure Element:
533
534mount()
535
536@subheading Arguments:
537
538@example
539rtems_filesystem_mount_table_entry_t   *mt_entry
540@end example
541
542@subheading Description:
543
544XXX
545
546@c
547@c
548@c
549@c @page
550
551@subsubsection fsmount_me Handler
552
553@subheading Corresponding Structure Element:
554
555XXX
556
557@subheading Arguments:
558
559@example
560rtems_filesystem_mount_table_entry_t   *mt_entry   
561@end example
562
563@subheading Description:
564
565This function is provided with a filesystem to take care of the internal
566filesystem management details associated with mounting that filesystem
567under the RTEMS environment.
568
569It is not responsible for the mounting details associated the filesystem
570containing the mount point.
571
572The rtems_filesystem_mount_table_entry_t structure contains the key elements
573below:
574
575rtems_filesystem_location_info_t         *mt_point_node,
576
577This structure contains information about the mount point. This
578allows us to find the ops-table and the handling functions
579associated with the filesystem containing the mount point.
580
581rtems_filesystem_location_info_t         *fs_root_node,
582
583This structure contains information about the root node in the file
584system to be mounted. It allows us to find the ops-table and the
585handling functions associated with the filesystem to be mounted.
586
587rtems_filesystem_options_t                 options,
588
589Read only or read/write access
590
591void                                         *fs_info,
592
593This points to an allocated block of memory the will be used to
594hold any filesystem specific information of a global nature. This
595allocated region if important because it allows us to mount the
596same filesystem type more than once under the RTEMS system.
597Each instance of the mounted filesystem has its own set of global
598management information that is separate from the global
599management information associated with the other instances of the
600mounted filesystem type.
601
602rtems_filesystem_limits_and_options_t    pathconf_info,
603
604The table contains the following set of values associated with the
605mounted filesystem:
606
607@itemize @bullet
608
609@item link_max
610
611@item max_canon
612
613@item max_input
614
615@item name_max
616
617@item path_max
618
619@item pipe_buf
620
621@item posix_async_io
622
623@item posix_chown_restrictions
624
625@item posix_no_trunc
626
627@item posix_prio_io
628
629@item posix_sync_io
630
631@item posix_vdisable
632
633@end itemize
634
635These values are accessed with the pathconf() and the fpathconf () 
636functions.
637
638const char                                   *dev
639
640The is intended to contain a string that identifies the device that contains
641the filesystem information. The filesystems that are currently implemented
642are memory based and don't require a device specification.
643
644If the mt_point_node.node_access is NULL then we are mounting the base file
645system.
646
647The routine will create a directory node for the root of the IMFS file
648system.
649
650The node will have read, write and execute permissions for owner, group and
651others.
652
653The node's name will be a null string.
654
655A filesystem information structure(fs_info) will be allocated and
656initialized for the IMFS filesystem. The fs_info pointer in the mount table
657entry will be set to point the filesystem information structure.
658
659The pathconf_info element of the mount table will be set to the appropriate
660table of path configuration constants (LIMITS_AND_OPTIONS).
661
662The fs_root_node structure will be filled in with the following:
663
664@itemize @bullet
665
666@item pointer to the allocated root node of the filesystem
667
668@item directory handlers for a directory node under the IMFS filesystem
669
670@item OPS table functions for the IMFS
671
672@end itemize
673
674A 0 will be returned to the calling routine if the process succeeded,
675otherwise a 1 will be returned.
676
677
678@c
679@c
680@c
681@c @page
682
683@subsubsection unmount Handler
684
685@subheading Corresponding Structure Element:
686
687XXX
688
689@subheading Arguments:
690
691XXX
692
693@subheading Description:
694
695XXX
696
697
698@c
699@c
700@c
701@c @page
702
703@subsubsection fsunmount_me Handler
704
705@subheading Corresponding Structure Element:
706
707imfs_fsunmount_me()
708
709@subheading Arguments:
710
711@example
712rtems_filesystem_mount_table_entry_t   *mt_entry   
713@end example
714
715@subheading Description:
716
717XXX
718
719
720@c
721@c
722@c
723@c @page
724
725@subsubsection utime Handler
726
727@subheading Corresponding Structure Element:
728
729XXX
730
731@subheading Arguments:
732
733XXX
734
735@subheading Description:
736
737XXX
738
739@c
740@c
741@c
742@c @page
743
744@subsubsection eval_link Handler
745
746@subheading Corresponding Structure Element:
747
748XXX
749
750@subheading Arguments:
751
752XXX
753
754@subheading Description:
755
756XXX
757
758@c
759@c
760@c
761@c @page
762
763@subsubsection symlink Handler
764
765@subheading Corresponding Structure Element:
766
767XXX
768
769@subheading Arguments:
770
771XXX
772
773@subheading Description:
774
775XXX
776
777@c
778@c
779@c
780@c @page
781@subsection File Handler Table Functions
782
783Handler table functions are defined in a @code{rtems_filesystem_file_handlers_r}
784structure. It defines functions that are specific to a node type in a given
785filesystem. One table exists for each of the filesystem's node types. The
786structure definition appears below. It is followed by general developmental
787information on each of the functions associated with regular files contained
788in this function management structure.
789
790@example
791typedef struct @{
792    rtems_filesystem_open_t           open;
793    rtems_filesystem_close_t          close;
794    rtems_filesystem_read_t           read;
795    rtems_filesystem_write_t          write;
796    rtems_filesystem_ioctl_t          ioctl;
797    rtems_filesystem_lseek_t          lseek;
798    rtems_filesystem_fstat_t          fstat;
799    rtems_filesystem_fchmod_t         fchmod;
800    rtems_filesystem_ftruncate_t      ftruncate;
801    rtems_filesystem_fpathconf_t      fpathconf;
802    rtems_filesystem_fsync_t          fsync;
803    rtems_filesystem_fdatasync_t      fdatasync;
804    rtems_filesystem_fcntl_t          fcntl;
805@} rtems_filesystem_file_handlers_r;
806@end example
807
808@c
809@c
810@c
811@c @page
812
813@subsubsection open Handler
814
815@subheading Corresponding Structure Element:
816
817open()
818
819@subheading Arguments:
820
821@example
822rtems_libio_t   *iop,
823const char      *pathname,
824unsigned32       flag,
825unsigned32       mode
826@end example
827
828@subheading Description:
829
830XXX
831
832@c
833@c
834@c
835@c @page
836
837@subsubsection close Handler
838
839@subheading Corresponding Structure Element:
840
841close()
842
843@subheading Arguments:
844
845@example
846rtems_libio_t     *iop
847@end example
848
849@subheading Description:
850
851XXX
852
853@subheading NOTES:
854
855XXX
856
857
858
859@c
860@c
861@c
862@c @page
863
864@subsubsection read Handler
865
866@subheading Corresponding Structure Element:
867
868read()
869
870@subheading Arguments:
871
872@example
873rtems_libio_t     *iop,
874void              *buffer,
875unsigned32         count
876@end example
877
878@subheading Description:
879
880XXX
881
882@subheading NOTES:
883
884XXX
885
886
887@c
888@c
889@c
890@c @page
891
892@subsubsection write Handler
893
894@subheading Corresponding Structure Element:
895
896XXX
897
898@subheading Arguments:
899
900XXX
901@subheading Description:
902
903XXX
904
905@subheading NOTES:
906
907XXX
908
909
910@c
911@c
912@c
913@c @page
914
915@subsubsection ioctl Handler
916
917@subheading Corresponding Structure Element:
918
919XXX
920
921@subheading Arguments:
922
923@example
924rtems_libio_t     *iop,
925unsigned32       command,
926void              *buffer
927@end example
928
929@subheading Description:
930
931XXX
932
933@subheading NOTES:
934
935XXX
936
937
938@c
939@c
940@c
941@c @page
942
943@subsubsection lseek Handler
944
945@subheading Corresponding Structure Element:
946
947lseek()
948
949@subheading Arguments:
950
951@example
952rtems_libio_t     *iop,
953off_t              offset,
954int                whence
955@end example
956
957@subheading Description:
958
959XXX
960
961@subheading NOTES:
962
963XXX
964
965
966@c
967@c
968@c
969@c @page
970
971@subsubsection fstat Handler
972
973@subheading Corresponding Structure Element:
974
975fstat()
976
977@subheading Arguments:
978
979@example
980rtems_filesystem_location_info_t   *loc,
981struct stat                        *buf
982@end example
983
984@subheading Description:
985
986The following information is extracted from the filesystem
987specific node and placed in the @code{stat} structure:
988
989@itemize @bullet
990
991@item st_mode
992
993@item st_nlink
994
995@item st_ino
996
997@item st_uid
998
999@item st_gid
1000
1001@item st_atime
1002
1003@item st_mtime
1004
1005@item st_ctime
1006
1007@end itemize
1008
1009
1010@subheading NOTES:
1011
1012XXX
1013
1014@c
1015@c
1016@c
1017@c @page
1018
1019@subsubsection fchmod Handler
1020
1021@subheading Corresponding Structure Element:
1022
1023fchmod()
1024
1025@subheading Arguments:
1026
1027@example
1028rtems_libio_t     *iop
1029mode_t              mode
1030@end example
1031
1032@subheading Description:
1033
1034XXX
1035
1036
1037@subheading NOTES:
1038
1039XXX
1040
1041@c
1042@c
1043@c
1044@c @page
1045
1046@subsubsection ftruncate Handler
1047
1048@subheading Corresponding Structure Element:
1049
1050XXX
1051
1052@subheading Arguments:
1053
1054XXX
1055@subheading Description:
1056
1057XXX
1058
1059@subheading NOTES:
1060
1061XXX
1062
1063@subsubsection fpathconf Handler
1064
1065@subheading Corresponding Structure Element:
1066
1067XXX
1068
1069@subheading Arguments:
1070
1071XXX
1072
1073@subheading Description:
1074
1075XXX
1076
1077@subheading NOTES:
1078
1079XXX
1080
1081@c
1082@c
1083@c
1084@c @page
1085
1086@subsubsection fsync Handler
1087
1088@subheading Corresponding Structure Element:
1089
1090XXX
1091
1092@subheading Arguments:
1093
1094XXX
1095@subheading Description:
1096
1097XXX
1098
1099@subheading NOTES:
1100
1101XXX
1102
1103@c
1104@c
1105@c
1106@c @page
1107
1108@subsubsection fdatasync Handler
1109
1110@subheading Corresponding Structure Element:
1111
1112XXX
1113
1114@subheading Arguments:
1115
1116XXX
1117
1118@subheading Description:
1119
1120XXX
1121
1122@subheading NOTES:
1123
1124XXX
1125
1126@c
1127@c
1128@c
1129@c @page
1130
1131@subsubsection fcntl Handler
1132
1133@subheading Corresponding Structure Element:
1134
1135XXX
1136
1137@subheading Arguments:
1138
1139XXX
1140
1141@subheading Description:
1142
1143XXX
1144
1145@subheading NOTES:
1146
1147XXX
Note: See TracBrowser for help on using the repository browser.