source: rtems/doc/filesystem/imfs.t @ de0711ec

4.104.114.84.95
Last change on this file since de0711ec was de0711ec, checked in by Joel Sherrill <joel.sherrill@…>, on 10/13/99 at 19:48:17

Reorganized a lot per Jennifer's suggestions.

  • Property mode set to 100644
File size: 36.8 KB
Line 
1@c  COPYRIGHT (c) 1988-1998.
2@c  On-Line Applications Research Corporation (OAR).
3@c  All rights reserved.
4@c
5@c  $Id$
6@c
7
8@chapter In-Memory Filesystem
9
10This chapter describes the In-Memory Filesystem (IMFS).  The IMFS is a
11full featured POSIX filesystem that keeps all information in memory.
12
13@section IMFS Per Node Data Structure
14
15Each regular file, device, hard link, and directory is represented by a data
16structure called a @code{jnode}. The @code{jnode} is formally represented by the
17structure:
18
19@example
20struct IMFS_jnode_tt @{
21  Chain_Node          Node;             /* for chaining them together */
22  IMFS_jnode_t       *Parent;           /* Parent node */
23  char                name[NAME_MAX+1]; /* "basename" */
24  mode_t              st_mode;          /* File mode */
25  nlink_t             st_nlink;         /* Link count */
26  ino_t               st_ino;           /* inode */
27
28  uid_t               st_uid;           /* User ID of owner */
29  gid_t               st_gid;           /* Group ID of owner */
30  time_t              st_atime;         /* Time of last access */
31  time_t              st_mtime;         /* Time of last modification */
32  time_t              st_ctime;         /* Time of last status change */
33  IMFS_jnode_types_t  type;             /* Type of this entry */
34  IMFS_typs_union     info;
35@};
36@end example
37
38The key elements of this structure are listed below together with a brief
39explanation of their role in the filesystem.
40
41@table @b
42
43@item Node
44exists to allow the entire @code{jnode} structure to be included in a chain.
45
46@item Parent
47is a pointer to another @code{jnode} structure that is the logical parent of the
48node in which it appears.  This field may be NULL if the file associated with
49this node is deleted but there are open file descriptors on this file or
50there are still hard links to this node.
51
52@item name
53is the name of this node within the filesystem hierarchical tree. Example:  If
54the fully qualified pathname to the @code{jnode} was @code{/a/b/c}, the
55@code{jnode} name field would contain the null terminated string @code{"c"}.
56
57@item st_mode
58is the standard Unix access permissions for the file or directory.
59
60@item st_nlink
61is the number of hard links to this file. When a @code{jnode} is first created
62its link count is set to 1. A @code{jnode} and its associated resources
63cannot be deleted unless its link count is less than 1.
64
65@item st_ino
66is a unique node identification number
67
68@item st_uid
69is the user ID of the file's owner
70
71@item st_gid
72is the group ID of the file's owner
73
74@item st_atime
75is the time of the last access to this file
76
77@item st_mtime
78is the time of the last modification of this file
79
80@item st_ctime
81is the time of the last status change to the file
82
83@item type
84is the indication of node type must be one of the following states:
85
86@itemize @bullet
87@item IMFS_DIRECTORY
88@item IMFS_MEMORY_FILE
89@item IMFS_HARD_LINK
90@item IMFS_SYM_LINK
91@item IMFS_DEVICE
92@end itemize
93
94
95@item info
96is this contains a structure that is unique to file type (See IMFS_typs_union
97in imfs.h).
98
99@itemize @bullet
100
101@item IMFS_DIRECTORY
102
103An IMFS directory contains a dynamic chain structure that
104records all files and directories that are subordinate to the directory node.
105
106@item IMFS_MEMORY_FILE
107
108Under the in memory filesystem regular files hold data. Data is dynamically
109allocated to the file in 128 byte chunks of memory.  The individual chunks of
110memory are tracked by arrays of pointers that record the address of the
111allocated chunk of memory. Single, double, and triple indirection pointers
112are used to record the locations of all segments of the file.  The
113memory organization of an IMFS file are discussed elsewhere in this manual.
114
115@item IMFS_HARD_LINK
116
117The IMFS filesystem supports the concept of hard links to other nodes in the
118IMFS filesystem.  These hard links are actual pointers to other nodes in the
119same filesystem. This type of link cannot cross-filesystem boundaries.
120
121@item IMFS_SYM_LINK
122
123The IMFS filesystem supports the concept of symbolic links to other nodes in
124any filesystem. A symbolic link consists of a pointer to a character string
125that represents the pathname to the target node. This type of link can
126cross-filesystem boundaries.  Just as with most versions of UNIX supporting
127symbolic links, a symbolic link can point to a non-existent file.
128
129@item IMFS_DEVICE
130
131All RTEMS devices now appear as files under the in memory filesystem. On
132system initialization, all devices are registered as nodes under the file
133system.
134
135@end itemize
136
137@end table
138
139@section Miscellaneous IMFS Information
140
141@section Memory associated with the IMFS
142
143A memory based filesystem draws its resources for files and directories
144from the memory resources of the system. When it is time to un-mount the
145filesystem, the memory resources that supported filesystem are set free.
146In order to free these resources, a recursive walk of the filesystems
147tree structure will be performed. As the leaf nodes under the filesystem
148are encountered their resources are freed. When directories are made empty
149by this process, their resources are freed.
150
151@subsection Node removal constraints for the IMFS
152
153The IMFS conforms to the general filesystem requirements for node
154removal.  See @ref{File and Directory Removal Constraints}.
155
156@subsection IMFS General Housekeeping Notes
157
158The following is a list of odd housekeeping notes for the IMFS.
159
160@itemize @bullet
161
162@item If the global variable rtems_filesystem_current refers to the node that
163we are trying to remove, the node_access element of this structure must be
164set to NULL to invalidate it.
165
166@item If the node was of IMFS_MEMORY_FILE type, free the memory associated
167with the memory file before freeing the node. Use the IMFS_memfile_remove()
168function.
169
170@end itemize
171
172@section IMFS Operation Tables
173
174@subsection IMFS Filesystem Handler Table Functions
175
176OPS table functions are defined in a rtems_filesystem_operations_table
177structure.  It defines functions that are specific to a given filesystem.
178One table exists for each filesystem that is supported in the RTEMS
179configuration. The structure definition appears below and is followed by
180general developmental information on each of the functions contained in this
181function management structure.
182
183@example
184rtems_filesystem_operations_table  IMFS_ops = @{
185  IMFS_eval_path,
186  IMFS_evaluate_for_make,
187  IMFS_link,
188  IMFS_unlink,
189  IMFS_node_type,
190  IMFS_mknod,
191  IMFS_rmnod,
192  IMFS_chown,
193  IMFS_freenodinfo,
194  IMFS_mount,
195  IMFS_initialize,
196  IMFS_unmount,
197  IMFS_fsunmount,
198  IMFS_utime,
199  IMFS_evaluate_link,
200  IMFS_symlink,
201  IMFS_readlink
202@};
203@end example
204
205@c
206@c
207@c
208@c @page
209
210@subsubsection IMFS_evalpath()
211
212@subheading Corresponding Structure Element:
213
214XXX
215
216@subheading Arguments:
217
218XXX
219
220@subheading File:
221
222XXX
223
224@subheading Description:
225
226XXX
227
228
229@c
230@c
231@c
232@c @page
233
234@subsubsection IMFS_evalformake()
235
236@subheading Corresponding Structure Element:
237
238XXX
239
240@subheading Arguments:
241
242XXX
243
244@subheading File:
245
246XXX
247
248@subheading Description:
249
250XXX
251
252
253@c
254@c
255@c
256@c @page
257
258@subsubsection IMFS_link()
259
260@subheading Corresponding Structure Element:
261
262link
263
264@subheading Arguments:
265
266
267@example
268rtems_filesystem_location_info_t    *to_loc,      /* IN */
269rtems_filesystem_location_info_t    *parent_loc,  /* IN */
270const char                          *token        /* IN */
271@end example
272
273@subheading File:
274
275imfs_link.c
276
277@subheading Description:
278
279
280This routine is used in the IMFS filesystem to create a hard-link.
281
282It will first examine the st_nlink count of the node that we are trying to.
283If the link count exceeds LINK_MAX an error will be returned.
284
285The name of the link will be normalized to remove extraneous separators from
286the end of the name.
287
288IMFS_create_node will be used to create a filesystem node that will have the
289following characteristics:
290
291@itemize @bullet
292
293@item parent that was determined in the link() function in file link.c
294
295@item Type will be set to IMFS_HARD_LINK
296
297@item name will be set to the normalized name
298
299@item mode of the hard-link will be set to the mode of the target node
300
301@end itemize
302
303If there was trouble allocating memory for the new node an error will be
304returned.
305
306The st_nlink count of the target node will be incremented to reflect the new
307link.
308
309The time fields of the link will be set to reflect the creation time of the
310hard-link.
311
312
313@c
314@c
315@c
316@c @page
317
318@subsubsection IMFS_unlink()
319
320@subheading Corresponding Structure Element:
321
322XXX
323
324@subheading Arguments:
325
326XXX
327
328@subheading File:
329
330XXX
331
332@subheading Description:
333
334XXX
335
336
337@c
338@c
339@c
340@c @page
341
342@subsubsection IMFS_node_type()
343
344@subheading Corresponding Structure Element:
345
346IMFS_node_type()
347
348@subheading Arguments:
349
350@example
351rtems_filesystem_location_info_t    *pathloc        /* IN */
352@end example
353
354@subheading File:
355
356imfs_ntype.c
357
358@subheading Description:
359
360This routine will locate the IMFS_jnode_t structure that holds ownership
361information for the selected node in the filesystem.
362
363This structure is pointed to by pathloc->node_access.
364
365The IMFS_jnode_t type element indicates one of the node types listed below:
366
367@itemize @bullet
368
369@item RTEMS_FILESYSTEM_DIRECTORY
370
371@item RTEMS_FILESYSTEM_DEVICE
372
373@item RTEMS_FILESYSTEM_HARD_LINK
374
375@item RTEMS_FILESYSTEM_MEMORY_FILE
376
377@end itemize
378
379@c
380@c
381@c
382@c @page
383
384@subsubsection IMFS_mknod()
385
386@subheading Corresponding Structure Element:
387
388IMFS_mknod()
389
390@subheading Arguments:
391
392@example
393const char                          *token,        /* IN */
394mode_t                               mode,         /* IN */
395dev_t                                dev,          /* IN */
396rtems_filesystem_location_info_t    *pathloc       /* IN/OUT */
397@end example
398
399@subheading File:
400
401imfs_mknod.c
402
403@subheading Description:
404
405This routine will examine the mode argument to determine is we are trying to
406create a directory, regular file and a device node. The creation of other
407node types is not permitted and will cause an assert.
408
409Memory space will be allocated for a @code{jnode} and the node will be set up
410according to the nodal type that was specified. The IMFS_create_node()
411function performs the allocation and setup of the node.
412
413The only problem that is currently reported is the lack of memory when we
414attempt to allocate space for the @code{jnode} (ENOMEN).
415
416
417@c
418@c
419@c
420@c @page
421
422@subsubsection IMFS_rmnod()
423
424@subheading Corresponding Structure Element:
425
426XXX
427
428@subheading Arguments:
429
430XXX
431
432@subheading File:
433
434XXX
435
436@subheading Description:
437
438XXX
439
440
441@c
442@c
443@c
444@c @page
445
446@subsubsection IMFS_chown()
447
448@subheading Corresponding Structure Element:
449
450IMFS_chown()
451
452@subheading Arguments:
453
454@example
455rtems_filesystem_location_info_t    *pathloc        /* IN */
456uid_t                                owner          /* IN */
457gid_t                                group          /* IN */
458@end example
459
460@subheading File:
461
462imfs_chown.c
463
464@subheading Description:
465
466This routine will locate the IMFS_jnode_t structure that holds ownership
467information for the selected node in the filesystem.
468
469This structure is pointed to by pathloc->node_access.
470
471The st_uid and st_gid fields of the node are then modified. Since this is a
472memory based filesystem, no further action is required to alter the
473ownership of the IMFS_jnode_t structure.
474
475
476
477@c
478@c
479@c
480@c @page
481
482@subsubsection IMFS_freenod()
483
484@subheading Corresponding Structure Element:
485
486XXX
487
488@subheading Arguments:
489
490XXX
491
492@subheading File:
493
494XXX
495
496@subheading Description:
497
498XXX
499
500
501@c
502@c
503@c
504@c @page
505
506@subsubsection IMFS_mount()
507
508@subheading Corresponding Structure Element:
509
510IMFS_mount()
511
512@subheading Arguments:
513
514@example
515rtems_filesystem_mount_table_entry_t   *mt_entry
516@end example
517
518@subheading File:
519
520imfs_mount.c
521
522@subheading Description:
523
524This routine provides the filesystem specific processing required to mount a
525filesystem for the system that contains the mount point. It will determine
526if the point that we are trying to mount onto is a node of IMFS_DIRECTORY
527type.
528
529If it is the node's info element is altered so that the info.directory.mt_fs
530element points to the mount table chain entry that is associated with the
531mounted filesystem at this point. The info.directory.mt_fs element can be
532examined to determine if a filesystem is mounted at a directory. If it is
533NULL, the directory does not serve as a mount point. A non-NULL entry
534indicates that the directory does serve as a mount point and the value of
535info.directory.mt_fs can be used to locate the mount table chain entry that
536describes the filesystem mounted at this point.
537
538
539@c
540@c
541@c
542@c @page
543
544@subsubsection IMFS_fsmount_me()
545
546@subheading Corresponding Structure Element:
547
548IMFS_initialize()
549
550@subheading Arguments:
551
552@example
553rtems_filesystem_mount_table_entry_t   *mt_entry   
554@end example
555
556@subheading File:
557
558imfs_init.c
559
560@subheading Description:
561
562This function is provided with a filesystem to take care of the internal
563filesystem management details associated with mounting that filesystem
564under the RTEMS environment.
565
566It is not responsible for the mounting details associated the filesystem
567containing the mount point.
568
569The rtems_filesystem_mount_table_entry_t structure contains the key elements
570below:
571
572rtems_filesystem_location_info_t         *mt_point_node,
573
574This structure contains information about the mount point. This
575allows us to find the ops-table and the handling functions
576associated with the filesystem containing the mount point.
577
578rtems_filesystem_location_info_t         *fs_root_node,
579
580This structure contains information about the root node in the file
581system to be mounted. It allows us to find the ops-table and the
582handling functions associated with the filesystem to be mounted.
583
584rtems_filesystem_options_t                 options,
585
586Read only or read/write access
587
588void                                         *fs_info,
589
590This points to an allocated block of memory the will be used to
591hold any filesystem specific information of a global nature. This
592allocated region if important because it allows us to mount the
593same filesystem type more than once under the RTEMS system.
594Each instance of the mounted filesystem has its own set of global
595management information that is separate from the global
596management information associated with the other instances of the
597mounted filesystem type.
598
599rtems_filesystem_limits_and_options_t    pathconf_info,
600
601The table contains the following set of values associated with the
602mounted filesystem:
603
604@itemize @bullet
605
606@item link_max
607
608@item max_canon
609
610@item max_input
611
612@item name_max
613
614@item path_max
615
616@item pipe_buf
617
618@item posix_async_io
619
620@item posix_chown_restrictions
621
622@item posix_no_trunc
623
624@item posix_prio_io
625
626@item posix_sync_io
627
628@item posix_vdisable
629
630@end itemize
631
632These values are accessed with the pathconf() and the fpathconf () 
633functions.
634
635const char                                   *dev
636
637The is intended to contain a string that identifies the device that contains
638the filesystem information. The filesystems that are currently implemented
639are memory based and don't require a device specification.
640
641If the mt_point_node.node_access is NULL then we are mounting the base file
642system.
643
644The routine will create a directory node for the root of the IMFS file
645system.
646
647The node will have read, write and execute permissions for owner, group and
648others.
649
650The node's name will be a null string.
651
652A filesystem information structure(fs_info) will be allocated and
653initialized for the IMFS filesystem. The fs_info pointer in the mount table
654entry will be set to point the filesystem information structure.
655
656The pathconf_info element of the mount table will be set to the appropriate
657table of path configuration constants ( IMFS_LIMITS_AND_OPTIONS ).
658
659The fs_root_node structure will be filled in with the following:
660
661@itemize @bullet
662
663@item pointer to the allocated root node of the filesystem
664
665@item directory handlers for a directory node under the IMFS filesystem
666
667@item OPS table functions for the IMFS
668
669@end itemize
670
671A 0 will be returned to the calling routine if the process succeeded,
672otherwise a 1 will be returned.
673
674
675@c
676@c
677@c
678@c @page
679
680@subsubsection IMFS_unmount()
681
682@subheading Corresponding Structure Element:
683
684XXX
685
686@subheading Arguments:
687
688XXX
689
690@subheading File:
691
692XXX
693
694@subheading Description:
695
696XXX
697
698
699@c
700@c
701@c
702@c @page
703
704@subsubsection IMFS_fsunmount_me()
705
706@subheading Corresponding Structure Element:
707
708imfs_fsunmount_me()
709
710@subheading Arguments:
711
712@example
713rtems_filesystem_mount_table_entry_t   *mt_entry   
714@end example
715
716@subheading File:
717
718imfs_fsunmount_me.c
719
720@subheading Description:
721
722XXX
723
724
725@c
726@c
727@c
728@c @page
729
730@subsubsection IMFS_utime()
731
732@subheading Corresponding Structure Element:
733
734XXX
735
736@subheading Arguments:
737
738XXX
739
740@subheading File:
741
742XXX
743
744@subheading Description:
745
746XXX
747
748
749@c
750@c
751@c
752@c @page
753
754@subsubsection IMFS_eval_link()
755
756@subheading Corresponding Structure Element:
757
758XXX
759
760@subheading Arguments:
761
762XXX
763
764@subheading File:
765
766XXX
767
768@subheading Description:
769
770XXX
771
772@c
773@c
774@c
775@c @page
776@subsection Regular File Handler Table Functions
777
778Handler table functions are defined in a rtems_filesystem_file_handlers_r
779structure. It defines functions that are specific to a node type in a given
780filesystem. One table exists for each of the filesystem's node types. The
781structure definition appears below. It is followed by general developmental
782information on each of the functions associated with regular files contained
783in this function management structure.
784
785@example
786rtems_filesystem_file_handlers_r IMFS_memfile_handlers = @{
787  memfile_open,
788  memfile_close,
789  memfile_read,
790  memfile_write,
791  memfile_ioctl,
792  memfile_lseek,
793  IMFS_stat,
794  IMFS_fchmod,
795  memfile_ftruncate,
796  NULL,                /* fpathconf */
797  NULL,                /* fsync */
798  IMFS_fdatasync,
799  IMFS_fcntl
800@};
801@end example
802
803
804@c
805@c
806@c
807@c @page
808
809@subsubsection memfile_open() for Regular Files
810
811@subheading Corresponding Structure Element:
812
813memfile_open()
814
815@subheading Arguments:
816
817@example
818rtems_libio_t   *iop,
819const char      *pathname,
820unsigned32       flag,
821unsigned32       mode
822@end example
823
824@subheading File:
825
826memfile.c
827
828@subheading Description:
829
830Currently this function is a shell. No meaningful processing is performed and
831a success code is always returned.
832
833@c
834@c
835@c
836@c @page
837
838@subsubsection memfile_close() for Regular Files
839
840@subheading Corresponding Structure Element:
841
842memfile_close()
843
844@subheading Arguments:
845
846@example
847rtems_libio_t     *iop
848@end example
849
850@subheading File:
851
852memfile.c
853
854@subheading Description:
855
856This routine is a dummy for regular files under the base filesystem. It
857performs a capture of the IMFS_jnode_t pointer from the file control block
858and then immediately returns a success status.
859
860
861@c
862@c
863@c
864@c @page
865
866@subsubsection memfile_read() for Regular Files
867
868@subheading Corresponding Structure Element:
869
870memfile_read()
871
872@subheading Arguments:
873
874@example
875rtems_libio_t     *iop,
876void              *buffer,
877unsigned32         count
878@end example
879
880@subheading File:
881
882memfile.c
883
884@subheading Description:
885
886This routine will determine the @code{jnode} that is associated with this file.
887
888It will then call IMFS_memfile_read() with the @code{jnode}, file position index,
889buffer and transfer count as arguments.
890
891IMFS_memfile_read() will do the following:
892
893@itemize @bullet
894
895@item Verify that the @code{jnode} is associated with a memory file
896
897@item Verify that the destination of the read is valid
898
899@item Adjust the length of the read if it is too long
900
901@item Acquire data from the memory blocks associated with the file
902
903@item Update the access time for the data in the file
904
905@end itemize
906
907@c
908@c
909@c
910@c @page
911
912@subsubsection memfile_write() for Regular Files
913
914@subheading Corresponding Structure Element:
915
916XXX
917
918@subheading Arguments:
919
920XXX
921@subheading File:
922
923XXX
924
925@subheading Description:
926
927XXX
928
929@c
930@c
931@c
932@c @page
933
934@subsubsection memfile_ioctl() for Regular Files
935
936@subheading Corresponding Structure Element:
937
938XXX
939
940@subheading Arguments:
941
942@example
943rtems_libio_t     *iop,
944unsigned32       command,
945void              *buffer
946@end example
947
948@subheading File:
949
950memfile.c
951
952@subheading Description:
953
954The current code is a placeholder for future development. The routine returns
955a successful completion status.
956
957@c
958@c
959@c
960@c @page
961
962@subsubsection memfile_lseek() for Regular Files
963
964@subheading Corresponding Structure Element:
965
966Memfile_lseek()
967
968@subheading Arguments:
969
970@example
971rtems_libio_t     *iop,
972off_t              offset,
973int                whence
974@end example
975
976@subheading File:
977
978memfile.c
979
980@subheading Description:
981
982This routine make sure that the memory based file is sufficiently large to
983allow for the new file position index.
984
985The IMFS_memfile_extend() function is used to evaluate the current size of
986the memory file and allocate additional memory blocks if required by the new
987file position index. A success code is always returned from this routine.
988
989@c
990@c
991@c
992@c @page
993
994@subsubsection IMFS_stat() for Regular Files
995
996@subheading Corresponding Structure Element:
997
998IMFS_stat()
999
1000@subheading Arguments:
1001
1002@example
1003rtems_filesystem_location_info_t   *loc,
1004struct stat                        *buf
1005@end example
1006
1007@subheading File:
1008
1009imfs_stat.c
1010
1011@subheading Description:
1012
1013This routine actually performs status processing for both devices and regular
1014files.
1015
1016The IMFS_jnode_t structure is referenced to determine the type of node under
1017the filesystem.
1018
1019If the node is associated with a device, node information is extracted and
1020transformed to set the st_dev element of the stat structure.
1021
1022If the node is a regular file, the size of the regular file is extracted from
1023the node.
1024
1025This routine rejects other node types.
1026
1027The following information is extracted from the node and placed in the stat
1028structure:
1029
1030@itemize @bullet
1031
1032@item st_mode
1033
1034@item st_nlink
1035
1036@item st_ino
1037
1038@item st_uid
1039
1040@item st_gid
1041
1042@item st_atime
1043
1044@item st_mtime
1045
1046@item st_ctime
1047
1048@end itemize
1049
1050@c
1051@c
1052@c
1053@c @page
1054
1055@subsubsection IMFS_fchmod() for Regular Files
1056
1057@subheading Corresponding Structure Element:
1058
1059IMFS_fchmod()
1060
1061@subheading Arguments:
1062
1063@example
1064rtems_libio_t     *iop
1065mode_t              mode
1066@end example
1067
1068@subheading File:
1069
1070imfs_fchmod.c
1071
1072@subheading Description:
1073
1074This routine will obtain the pointer to the IMFS_jnode_t structure from the
1075information currently in the file control block.
1076
1077Based on configuration the routine will acquire the user ID from a call to
1078getuid()  or from the IMFS_jnode_t structure.
1079
1080It then checks to see if we have the ownership rights to alter the mode of
1081the file.  If the caller does not, an error code is returned.
1082
1083An additional test is performed to verify that the caller is not trying to
1084alter the nature of the node. If the caller is attempting to alter more than
1085the permissions associated with user group and other, an error is returned.
1086
1087If all the preconditions are met, the user, group and other fields are set
1088based on the mode calling parameter.
1089
1090@c
1091@c
1092@c
1093@c @page
1094
1095@subsubsection memfile_ftruncate() for Regular Files
1096
1097@subheading Corresponding Structure Element:
1098
1099XXX
1100
1101@subheading Arguments:
1102
1103XXX
1104@subheading File:
1105
1106XXX
1107
1108@subheading Description:
1109
1110XXX
1111
1112
1113@subsubsection No pathconf() for Regular Files
1114
1115@subheading Corresponding Structure Element:
1116
1117NULL
1118
1119@subheading Arguments:
1120
1121Not Implemented
1122
1123@subheading File:
1124
1125Not Implemented
1126
1127@subheading Description:
1128
1129Not Implemented
1130
1131
1132@c
1133@c
1134@c
1135@c @page
1136
1137@subsubsection No fsync() for Regular Files
1138
1139@subheading Corresponding Structure Element:
1140
1141XXX
1142
1143@subheading Arguments:
1144
1145XXX
1146@subheading File:
1147
1148XXX
1149
1150@subheading Description:
1151
1152XXX
1153
1154
1155@c
1156@c
1157@c
1158@c @page
1159
1160@subsubsection IMFS_fdatasync() for Regular Files
1161
1162@subheading Corresponding Structure Element:
1163
1164XXX
1165
1166@subheading Arguments:
1167
1168XXX
1169@subheading File:
1170
1171XXX
1172
1173@subheading Description:
1174
1175XXX
1176
1177@c
1178@c
1179@c
1180@c @page
1181@subsection Directory Handler Table Functions
1182
1183Handler table functions are defined in a rtems_filesystem_file_handlers_r
1184structure. It defines functions that are specific to a node type in a given
1185filesystem. One table exists for each of the filesystem's node types. The
1186structure definition appears below. It is followed by general developmental
1187information on each of the functions associated with directories contained in
1188this function management structure.
1189
1190@example
1191rtems_filesystem_file_handlers_r IMFS_directory_handlers = @{
1192  IMFS_dir_open,
1193  IMFS_dir_close,
1194  IMFS_dir_read,
1195  NULL,             /* write */
1196  NULL,             /* ioctl */
1197  IMFS_dir_lseek,
1198  IMFS_dir_fstat,
1199  IMFS_fchmod,
1200  NULL,             /* ftruncate */
1201  NULL,             /* fpathconf */
1202  NULL,             /* fsync */
1203  IMFS_fdatasync,
1204  IMFS_fcntl
1205@};
1206@end example
1207
1208
1209@c
1210@c
1211@c
1212@c @page
1213@subsubsection IMFS_dir_open() for Directories
1214
1215@subheading Corresponding Structure Element:
1216
1217imfs_dir_open()
1218
1219@subheading Arguments:
1220
1221@example
1222rtems_libio_t  *iop,
1223const char     *pathname,
1224unsigned32      flag,
1225unsigned32      mode
1226@end example
1227
1228@subheading File:
1229
1230imfs_directory.c
1231
1232@subheading Description:
1233
1234This routine will look into the file control block to find the @code{jnode} that
1235is associated with the directory.
1236
1237The routine will verify that the node is a directory. If its not a directory
1238an error code will be returned.
1239
1240If it is a directory, the offset in the file control block will be set to 0.
1241This allows us to start reading at the beginning of the directory.
1242
1243@c
1244@c
1245@c
1246@c @page
1247
1248@subsubsection IMFS_dir_close() for Directories
1249
1250@subheading Corresponding Structure Element:
1251
1252imfs_dir_close()
1253
1254@subheading Arguments:
1255
1256@example
1257rtems_libio_t     *iop
1258@end example
1259
1260@subheading File:
1261
1262imfs_directory.c
1263
1264@subheading Description:
1265
1266This routine is a dummy for directories under the base filesystem. It
1267immediately returns a success status.
1268
1269@c
1270@c
1271@c
1272@c @page
1273
1274@subsubsection IMFS_dir_read() for Directories
1275
1276@subheading Corresponding Structure Element:
1277
1278imfs_dir_read
1279
1280@subheading Arguments:
1281
1282@example
1283rtems_libio_t  *iop,
1284void           *buffer,
1285unsigned32      count
1286@end example
1287
1288@subheading File:
1289
1290imfs_directory.c
1291
1292@subheading Description:
1293
1294This routine will read a fixed number of directory entries from the current
1295directory offset. The number of directory bytes read will be returned from
1296this routine.
1297
1298
1299@c
1300@c
1301@c
1302@c @page
1303
1304@subsubsection No write() for Directories
1305
1306@subheading Corresponding Structure Element:
1307
1308XXX
1309
1310@subheading Arguments:
1311
1312XXX
1313
1314@subheading File:
1315
1316XXX
1317
1318@subheading Description:
1319
1320XXX
1321
1322@c
1323@c
1324@c
1325@c @page
1326
1327@subsubsection No ioctl() for Directories
1328
1329@subheading Corresponding Structure Element:
1330
1331ioctl
1332
1333@subheading Arguments:
1334
1335
1336@subheading File:
1337
1338Not supported
1339
1340@subheading Description:
1341
1342XXX
1343
1344@c
1345@c
1346@c
1347@c @page
1348
1349@subsubsection IMFS_dir_lseek() for Directories
1350
1351@subheading Corresponding Structure Element:
1352
1353imfs_dir_lseek()
1354
1355@subheading Arguments:
1356
1357@example
1358rtems_libio_t      *iop,
1359off_t               offset,
1360int                 whence
1361@end example
1362
1363@subheading File:
1364
1365imfs_directory.c
1366
1367@subheading Description:
1368
1369This routine alters the offset in the file control block.
1370
1371No test is performed on the number of children under the current open
1372directory.  The imfs_dir_read() function protects against reads beyond the
1373current size to the directory by returning a 0 bytes transfered to the
1374calling programs whenever the file position index exceeds the last entry in
1375the open directory.
1376
1377@c
1378@c
1379@c
1380@c @page
1381
1382@subsubsection IMFS_dir_fstat() for Directories
1383
1384@subheading Corresponding Structure Element:
1385
1386imfs_dir_fstat()
1387
1388@subheading Arguments:
1389
1390
1391@example
1392rtems_filesystem_location_info_t   *loc,
1393struct stat                        *buf
1394@end example
1395
1396@subheading File:
1397
1398imfs_directory.c
1399
1400@subheading Description:
1401
1402The node access information in the rtems_filesystem_location_info_t structure
1403is used to locate the appropriate IMFS_jnode_t structure. The following
1404information is taken from the IMFS_jnode_t structure and placed in the stat
1405structure:
1406
1407@itemize @bullet
1408@item st_ino
1409@item st_mode
1410@item st_nlink
1411@item st_uid
1412@item st_gid
1413@item st_atime
1414@item st_mtime
1415@item st_ctime
1416@end itemize
1417
1418The st_size field is obtained by running through the chain of directory
1419entries and summing the sizes of the dirent structures associated with each
1420of the children of the directory.
1421
1422@c
1423@c
1424@c
1425@c @page
1426
1427@subsubsection IMFS_fchmod() for Directories
1428
1429@subheading Corresponding Structure Element:
1430
1431IMFS_fchmod()
1432
1433@subheading Arguments:
1434
1435@example
1436rtems_libio_t     *iop
1437mode_t             mode
1438@end example
1439
1440@subheading File:
1441
1442imfs_fchmod.c
1443
1444@subheading Description:
1445
1446This routine will obtain the pointer to the IMFS_jnode_t structure from the
1447information currently in the file control block.
1448
1449Based on configuration the routine will acquire the user ID from a call to
1450getuid()  or from the IMFS_jnode_t structure.
1451
1452It then checks to see if we have the ownership rights to alter the mode of
1453the file.  If the caller does not, an error code is returned.
1454
1455An additional test is performed to verify that the caller is not trying to
1456alter the nature of the node. If the caller is attempting to alter more than
1457the permissions associated with user group and other, an error is returned.
1458
1459If all the preconditions are met, the user, group and other fields are set
1460based on the mode calling parameter.
1461
1462@c
1463@c
1464@c
1465@c @page
1466
1467@subsubsection No ftruncate() for Directories
1468
1469@subheading Corresponding Structure Element:
1470
1471XXX
1472
1473@subheading Arguments:
1474
1475XXX
1476
1477@subheading File:
1478
1479XXX
1480
1481@subheading Description:
1482
1483XXX
1484
1485@c
1486@c
1487@c
1488@c @page
1489
1490@subsubsection No fpathconf() for Directories
1491
1492@subheading Corresponding Structure Element:
1493
1494fpathconf
1495
1496@subheading Arguments:
1497
1498Not Implemented
1499
1500@subheading File:
1501
1502Not Implemented
1503
1504@subheading Description:
1505
1506Not Implemented
1507
1508
1509@c
1510@c
1511@c
1512@c @page
1513
1514@subsubsection No fsync() for Directories
1515
1516@subheading Corresponding Structure Element:
1517
1518XXX
1519
1520@subheading Arguments:
1521
1522XXX
1523@subheading File:
1524
1525XXX
1526
1527@subheading Description:
1528
1529XXX
1530
1531
1532@c
1533@c
1534@c
1535@c @page
1536
1537@subsubsection IMFS_fdatasync() for Directories
1538
1539@subheading Corresponding Structure Element:
1540
1541XXX
1542
1543@subheading Arguments:
1544
1545XXX
1546
1547@subheading File:
1548
1549XXX
1550
1551@subheading Description:
1552
1553XXX
1554
1555@c
1556@c
1557@c
1558@c @page
1559@subsection Device Handler Table Functions
1560
1561Handler table functions are defined in a rtems_filesystem_file_handlers_r
1562structure. It defines functions that are specific to a node type in a given
1563filesystem. One table exists for each of the filesystem's node types. The
1564structure definition appears below. It is followed by general developmental
1565information on each of the functions associated with devices contained in
1566this function management structure.
1567
1568@example
1569typedef struct @{
1570  rtems_filesystem_open_t           open;
1571  rtems_filesystem_close_t          close;
1572  rtems_filesystem_read_t           read;
1573  rtems_filesystem_write_t          write;
1574  rtems_filesystem_ioctl_t          ioctl;
1575  rtems_filesystem_lseek_t          lseek;
1576  rtems_filesystem_fstat_t          fstat;
1577  rtems_filesystem_fchmod_t         fchmod;
1578  rtems_filesystem_ftruncate_t      ftruncate;
1579  rtems_filesystem_fpathconf_t      fpathconf;
1580  rtems_filesystem_fsync_t          fsync;
1581  rtems_filesystem_fdatasync_t      fdatasync;
1582@} rtems_filesystem_file_handlers_r;
1583@end example
1584
1585@c
1586@c
1587@c
1588@c @page
1589
1590@subsubsection device_open() for Devices
1591
1592@subheading Corresponding Structure Element:
1593
1594device_open()
1595
1596@subheading Arguments:
1597
1598@example
1599rtems_libio_t     *iop,
1600const char        *pathname,
1601unsigned32         flag,
1602unsigned32         mode
1603@end example
1604
1605@subheading File:
1606
1607deviceio.c
1608
1609@subheading Description:
1610
1611This routine will use the file control block to locate the node structure for
1612the device.
1613
1614It will extract the major and minor device numbers from the @code{jnode}.
1615
1616The major and minor device numbers will be used to make a rtems_io_open() 
1617function call to open the device driver. An argument list is sent to the
1618driver that contains the file control block, flags and mode information.
1619
1620@c
1621@c
1622@c
1623@c @page
1624
1625@subsubsection device_close() for Devices
1626
1627@subheading Corresponding Structure Element:
1628
1629device_close()
1630
1631@subheading Arguments:
1632
1633@example
1634rtems_libio_t     *iop
1635@end example
1636
1637@subheading File:
1638
1639deviceio.c
1640
1641@subheading Description:
1642
1643This routine extracts the major and minor device driver numbers from the
1644IMFS_jnode_t that is referenced in the file control block.
1645
1646It also forms an argument list that contains the file control block.
1647
1648A rtems_io_close() function call is made to close the device specified by the
1649major and minor device numbers.
1650
1651
1652@c
1653@c
1654@c
1655@c @page
1656
1657@subsubsection device_read() for Devices
1658
1659@subheading Corresponding Structure Element:
1660
1661device_read()
1662
1663@subheading Arguments:
1664
1665@example
1666rtems_libio_t     *iop,
1667void              *buffer,
1668unsigned32         count
1669@end example
1670
1671@subheading File:
1672
1673deviceio.c
1674
1675@subheading Description:
1676
1677This routine will extract the major and minor numbers for the device from the -
1678jnode- associated with the file descriptor.
1679
1680A rtems_io_read() call will be made to the device driver associated with the file
1681descriptor. The major and minor device number will be sent as arguments as well
1682as an argument list consisting of:
1683
1684@itemize @bullet
1685@item file control block
1686
1687@item file position index
1688
1689@item buffer pointer where the data read is to be placed
1690
1691@item count indicating the number of bytes that the program wishes to read
1692from the device
1693
1694@item flags from the file control block
1695
1696@end itemize
1697
1698On return from the rtems_io_read() the number of bytes that were actually
1699read will be returned to the calling program.
1700
1701
1702@c
1703@c
1704@c
1705@c @page
1706
1707@subsubsection device_write() for Devices
1708
1709@subheading Corresponding Structure Element:
1710
1711XXX
1712
1713@subheading Arguments:
1714
1715XXX
1716@subheading File:
1717
1718XXX
1719
1720@subheading Description:
1721
1722XXX
1723
1724@c
1725@c
1726@c
1727@c @page
1728
1729@subsubsection device_ioctl() for Devices
1730
1731@subheading Corresponding Structure Element:
1732
1733ioctl
1734
1735@subheading Arguments:
1736
1737@example
1738rtems_libio_t     *iop,
1739unsigned32         command,
1740void              *buffer
1741@end example
1742
1743@subheading File:
1744
1745deviceio.c
1746
1747@subheading Description:
1748
1749This handler will obtain status information about a device.
1750
1751The form of status is device dependent.
1752
1753The rtems_io_control() function uses the major and minor number of the device
1754to obtain the status information.
1755
1756rtems_io_control() requires an rtems_libio_ioctl_args_t argument list which
1757contains the file control block, device specific command and a buffer pointer
1758to return the device status information.
1759
1760The device specific command should indicate the nature of the information
1761that is desired from the device.
1762
1763After the rtems_io_control() is processed, the buffer should contain the
1764requested device information.
1765
1766If the device information is not obtained properly a -1 will be returned to
1767the calling program, otherwise the ioctl_return value is returned.
1768
1769@c
1770@c
1771@c
1772@c @page
1773
1774@subsubsection device_lseek() for Devices
1775
1776@subheading Corresponding Structure Element:
1777
1778device_lseek()
1779
1780@subheading Arguments:
1781
1782@example
1783rtems_libio_t     *iop,
1784off_t              offset,
1785int                whence
1786@end example
1787
1788@subheading File:
1789
1790deviceio.c
1791
1792@subheading Description:
1793
1794At the present time this is a placeholder function. It always returns a
1795successful status.
1796
1797@c
1798@c
1799@c
1800@c @page
1801
1802@subsubsection IMFS_stat() for Devices
1803
1804@subheading Corresponding Structure Element:
1805
1806IMFS_stat()
1807
1808@subheading Arguments:
1809
1810@example
1811rtems_filesystem_location_info_t   *loc,
1812struct stat                        *buf
1813@end example
1814
1815@subheading File:
1816
1817imfs_stat.c
1818
1819@subheading Description:
1820
1821This routine actually performs status processing for both devices and regular files.
1822
1823The IMFS_jnode_t structure is referenced to determine the type of node under the
1824filesystem.
1825
1826If the node is associated with a device, node information is extracted and
1827transformed to set the st_dev element of the stat structure.
1828
1829If the node is a regular file, the size of the regular file is extracted from the node.
1830
1831This routine rejects other node types.
1832
1833The following information is extracted from the node and placed in the stat
1834structure:
1835
1836@itemize @bullet
1837
1838@item st_mode
1839
1840@item st_nlink
1841
1842@item st_ino
1843
1844@item st_uid
1845
1846@item st_gid
1847
1848@item st_atime
1849
1850@item st_mtime
1851
1852@item st_ctime
1853
1854@end itemize
1855
1856
1857
1858@c
1859@c
1860@c
1861@c @page
1862
1863@subsubsection IMFS_fchmod() for Devices
1864
1865@subheading Corresponding Structure Element:
1866
1867IMFS_fchmod()
1868
1869@subheading Arguments:
1870
1871@example
1872rtems_libio_t     *iop
1873mode_t             mode
1874@end example
1875
1876@subheading File:
1877
1878imfs_fchmod.c
1879
1880@subheading Description:
1881
1882This routine will obtain the pointer to the IMFS_jnode_t structure from the
1883information currently in the file control block.
1884
1885Based on configuration the routine will acquire the user ID from a call to
1886getuid()  or from the IMFS_jnode_t structure.
1887
1888It then checks to see if we have the ownership rights to alter the mode of
1889the file.  If the caller does not, an error code is returned.
1890
1891An additional test is performed to verify that the caller is not trying to
1892alter the nature of the node. If the caller is attempting to alter more than
1893the permissions associated with user group and other, an error is returned.
1894
1895If all the preconditions are met, the user, group and other fields are set
1896based on the mode calling parameter.
1897
1898
1899@c
1900@c
1901@c
1902@c @page
1903
1904@subsubsection No ftruncate() for Devices
1905
1906@subheading Corresponding Structure Element:
1907
1908XXX
1909
1910@subheading Arguments:
1911
1912XXX
1913@subheading File:
1914
1915XXX
1916
1917@subheading Description:
1918
1919XXX
1920
1921@c
1922@c
1923@c
1924@c @page
1925
1926@subsubsection No fpathconf() for Devices
1927
1928@subheading Corresponding Structure Element:
1929
1930fpathconf
1931
1932@subheading Arguments:
1933
1934Not Implemented
1935
1936@subheading File:
1937
1938Not Implemented
1939
1940@subheading Description:
1941
1942Not Implemented
1943
1944
1945@c
1946@c
1947@c
1948@c @page
1949
1950@subsubsection No fsync() for Devices
1951
1952@subheading Corresponding Structure Element:
1953
1954XXX
1955
1956@subheading Arguments:
1957
1958XXX
1959
1960@subheading File:
1961
1962XXX
1963
1964@subheading Description:
1965
1966XXX
1967
1968
1969@c
1970@c
1971@c
1972@c @page
1973
1974@subsubsection No fdatasync() for Devices
1975
1976Not Implemented
1977
1978@subheading Corresponding Structure Element:
1979
1980XXX
1981
1982@subheading Arguments:
1983
1984XXX
1985
1986@subheading File:
1987
1988XXX
1989
1990@subheading Description:
1991
1992XXX
1993
Note: See TracBrowser for help on using the repository browser.