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

4.104.114.84.9
Last change on this file since c3ffd24 was c3ffd24, checked in by Jennifer Averett <Jennifer.Averett@…>, on Oct 25, 1999 at 5:41:33 PM

+ Filled in information on IMFS_freenod and IMFS_freenodinfo
+ Filled in information on the imfs_fsunmount and imfs_unmount methods.

  • Property mode set to 100644
File size: 38.5 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@c
477@c
478@c
479@c @page
480
481@subsubsection IMFS_freenod()
482
483@subheading Corresponding Structure Element:
484
485IMFS_freenod()
486
487@subheading Arguments:
488
489@example
490rtems_filesystem_location_info_t      *pathloc       /* IN */
491@end example
492
493@subheading File:
494
495imfs_free.c
496
497@subheading Description:
498
499This method is a private function to the IMFS.  It is called by IMFS routines
500to free nodes that have been allocated.  Examples of where this routine
501may be called from are unlink and rmnod. 
502
503Note:  This routine should not be confused with the filesystem callback
504freenod.  The IMFS allocates memory until the node no longer exists.
505
506@c
507@c
508@c
509@c @page
510
511@subsubsection IMFS_freenodinfo()
512
513@subheading Corresponding Structure Element:
514
515IMFS_freenodinfo()
516
517@subheading Arguments:
518
519@example
520rtems_filesystem_location_info_t      *pathloc       /* IN */
521@end example
522
523@subheading File:
524
525imfs_free.c
526
527@subheading Description:
528
529The In-Memory File System does not need to allocate memory during the
530evaluate routines. Therefore, this routine simply routines PASS.
531
532
533@c
534@c
535@c
536@c @page
537
538@subsubsection IMFS_mount()
539
540@subheading Corresponding Structure Element:
541
542IMFS_mount()
543
544@subheading Arguments:
545
546@example
547rtems_filesystem_mount_table_entry_t   *mt_entry
548@end example
549
550@subheading File:
551
552imfs_mount.c
553
554@subheading Description:
555
556This routine provides the filesystem specific processing required to mount a
557filesystem for the system that contains the mount point. It will determine
558if the point that we are trying to mount onto is a node of IMFS_DIRECTORY
559type.
560
561If it is the node's info element is altered so that the info.directory.mt_fs
562element points to the mount table chain entry that is associated with the
563mounted filesystem at this point. The info.directory.mt_fs element can be
564examined to determine if a filesystem is mounted at a directory. If it is
565NULL, the directory does not serve as a mount point. A non-NULL entry
566indicates that the directory does serve as a mount point and the value of
567info.directory.mt_fs can be used to locate the mount table chain entry that
568describes the filesystem mounted at this point.
569
570
571@c
572@c
573@c
574@c @page
575
576@subsubsection IMFS_fsmount_me()
577
578@subheading Corresponding Structure Element:
579
580IMFS_initialize()
581
582@subheading Arguments:
583
584@example
585rtems_filesystem_mount_table_entry_t   *mt_entry   
586@end example
587
588@subheading File:
589
590imfs_init.c
591
592@subheading Description:
593
594This function is provided with a filesystem to take care of the internal
595filesystem management details associated with mounting that filesystem
596under the RTEMS environment.
597
598It is not responsible for the mounting details associated the filesystem
599containing the mount point.
600
601The rtems_filesystem_mount_table_entry_t structure contains the key elements
602below:
603
604rtems_filesystem_location_info_t         *mt_point_node,
605
606This structure contains information about the mount point. This
607allows us to find the ops-table and the handling functions
608associated with the filesystem containing the mount point.
609
610rtems_filesystem_location_info_t         *fs_root_node,
611
612This structure contains information about the root node in the file
613system to be mounted. It allows us to find the ops-table and the
614handling functions associated with the filesystem to be mounted.
615
616rtems_filesystem_options_t                 options,
617
618Read only or read/write access
619
620void                                         *fs_info,
621
622This points to an allocated block of memory the will be used to
623hold any filesystem specific information of a global nature. This
624allocated region if important because it allows us to mount the
625same filesystem type more than once under the RTEMS system.
626Each instance of the mounted filesystem has its own set of global
627management information that is separate from the global
628management information associated with the other instances of the
629mounted filesystem type.
630
631rtems_filesystem_limits_and_options_t    pathconf_info,
632
633The table contains the following set of values associated with the
634mounted filesystem:
635
636@itemize @bullet
637
638@item link_max
639
640@item max_canon
641
642@item max_input
643
644@item name_max
645
646@item path_max
647
648@item pipe_buf
649
650@item posix_async_io
651
652@item posix_chown_restrictions
653
654@item posix_no_trunc
655
656@item posix_prio_io
657
658@item posix_sync_io
659
660@item posix_vdisable
661
662@end itemize
663
664These values are accessed with the pathconf() and the fpathconf () 
665functions.
666
667const char                                   *dev
668
669The is intended to contain a string that identifies the device that contains
670the filesystem information. The filesystems that are currently implemented
671are memory based and don't require a device specification.
672
673If the mt_point_node.node_access is NULL then we are mounting the base file
674system.
675
676The routine will create a directory node for the root of the IMFS file
677system.
678
679The node will have read, write and execute permissions for owner, group and
680others.
681
682The node's name will be a null string.
683
684A filesystem information structure(fs_info) will be allocated and
685initialized for the IMFS filesystem. The fs_info pointer in the mount table
686entry will be set to point the filesystem information structure.
687
688The pathconf_info element of the mount table will be set to the appropriate
689table of path configuration constants ( IMFS_LIMITS_AND_OPTIONS ).
690
691The fs_root_node structure will be filled in with the following:
692
693@itemize @bullet
694
695@item pointer to the allocated root node of the filesystem
696
697@item directory handlers for a directory node under the IMFS filesystem
698
699@item OPS table functions for the IMFS
700
701@end itemize
702
703A 0 will be returned to the calling routine if the process succeeded,
704otherwise a 1 will be returned.
705
706
707@c
708@c
709@c
710@c @page
711
712@subsubsection IMFS_unmount()
713
714@subheading Corresponding Structure Element:
715
716IMFS_unmount()
717
718@subheading Arguments:
719
720@example
721rtems_filesystem_mount_table_entry_t   *mt_entry   
722@end example
723
724@subheading File:
725
726imfs_unmount.c
727
728@subheading Description:
729
730This routine allows the IMFS to unmount a filesystem that has been
731mounted onto a IMFS directory. 
732
733The mount entry mount point node access is verified to be a mounted
734directory.  It's mt_fs is set to NULL.  This identifies to future
735calles into the IMFS that this directory node is no longer a mount
736point.  Additionally, it will allow any directories that were hidden
737by the mounted system to again become visible.
738
739@c
740@c
741@c
742@c @page
743
744@subsubsection IMFS_fsunmount()
745
746@subheading Corresponding Structure Element:
747
748imfs_fsunmount()
749
750@subheading Arguments:
751
752@example
753rtems_filesystem_mount_table_entry_t   *mt_entry   
754@end example
755
756@subheading File:
757
758imfs_init.c
759
760@subheading Description:
761
762This method unmounts this instance of the IMFS file system.  It is the
763counterpart to the IMFS_initialize routine.  It is called by the generic
764code under the fsunmount_me callback.
765
766All method loops finding the first encountered node with no children and
767removing the node from the tree, thus returning allocated resources.  This
768is done until all allocated nodes are returned.
769
770@c
771@c
772@c
773@c @page
774
775@subsubsection IMFS_utime()
776
777@subheading Corresponding Structure Element:
778
779XXX
780
781@subheading Arguments:
782
783XXX
784
785@subheading File:
786
787XXX
788
789@subheading Description:
790
791XXX
792
793
794@c
795@c
796@c
797@c @page
798
799@subsubsection IMFS_eval_link()
800
801@subheading Corresponding Structure Element:
802
803XXX
804
805@subheading Arguments:
806
807XXX
808
809@subheading File:
810
811XXX
812
813@subheading Description:
814
815XXX
816
817@c
818@c
819@c
820@c @page
821@subsection Regular File Handler Table Functions
822
823Handler table functions are defined in a rtems_filesystem_file_handlers_r
824structure. It defines functions that are specific to a node type in a given
825filesystem. One table exists for each of the filesystem's node types. The
826structure definition appears below. It is followed by general developmental
827information on each of the functions associated with regular files contained
828in this function management structure.
829
830@example
831rtems_filesystem_file_handlers_r IMFS_memfile_handlers = @{
832  memfile_open,
833  memfile_close,
834  memfile_read,
835  memfile_write,
836  memfile_ioctl,
837  memfile_lseek,
838  IMFS_stat,
839  IMFS_fchmod,
840  memfile_ftruncate,
841  NULL,                /* fpathconf */
842  NULL,                /* fsync */
843  IMFS_fdatasync,
844  IMFS_fcntl
845@};
846@end example
847
848
849@c
850@c
851@c
852@c @page
853
854@subsubsection memfile_open() for Regular Files
855
856@subheading Corresponding Structure Element:
857
858memfile_open()
859
860@subheading Arguments:
861
862@example
863rtems_libio_t   *iop,
864const char      *pathname,
865unsigned32       flag,
866unsigned32       mode
867@end example
868
869@subheading File:
870
871memfile.c
872
873@subheading Description:
874
875Currently this function is a shell. No meaningful processing is performed and
876a success code is always returned.
877
878@c
879@c
880@c
881@c @page
882
883@subsubsection memfile_close() for Regular Files
884
885@subheading Corresponding Structure Element:
886
887memfile_close()
888
889@subheading Arguments:
890
891@example
892rtems_libio_t     *iop
893@end example
894
895@subheading File:
896
897memfile.c
898
899@subheading Description:
900
901This routine is a dummy for regular files under the base filesystem. It
902performs a capture of the IMFS_jnode_t pointer from the file control block
903and then immediately returns a success status.
904
905
906@c
907@c
908@c
909@c @page
910
911@subsubsection memfile_read() for Regular Files
912
913@subheading Corresponding Structure Element:
914
915memfile_read()
916
917@subheading Arguments:
918
919@example
920rtems_libio_t     *iop,
921void              *buffer,
922unsigned32         count
923@end example
924
925@subheading File:
926
927memfile.c
928
929@subheading Description:
930
931This routine will determine the @code{jnode} that is associated with this file.
932
933It will then call IMFS_memfile_read() with the @code{jnode}, file position index,
934buffer and transfer count as arguments.
935
936IMFS_memfile_read() will do the following:
937
938@itemize @bullet
939
940@item Verify that the @code{jnode} is associated with a memory file
941
942@item Verify that the destination of the read is valid
943
944@item Adjust the length of the read if it is too long
945
946@item Acquire data from the memory blocks associated with the file
947
948@item Update the access time for the data in the file
949
950@end itemize
951
952@c
953@c
954@c
955@c @page
956
957@subsubsection memfile_write() for Regular Files
958
959@subheading Corresponding Structure Element:
960
961XXX
962
963@subheading Arguments:
964
965XXX
966@subheading File:
967
968XXX
969
970@subheading Description:
971
972XXX
973
974@c
975@c
976@c
977@c @page
978
979@subsubsection memfile_ioctl() for Regular Files
980
981@subheading Corresponding Structure Element:
982
983XXX
984
985@subheading Arguments:
986
987@example
988rtems_libio_t     *iop,
989unsigned32       command,
990void              *buffer
991@end example
992
993@subheading File:
994
995memfile.c
996
997@subheading Description:
998
999The current code is a placeholder for future development. The routine returns
1000a successful completion status.
1001
1002@c
1003@c
1004@c
1005@c @page
1006
1007@subsubsection memfile_lseek() for Regular Files
1008
1009@subheading Corresponding Structure Element:
1010
1011Memfile_lseek()
1012
1013@subheading Arguments:
1014
1015@example
1016rtems_libio_t     *iop,
1017off_t              offset,
1018int                whence
1019@end example
1020
1021@subheading File:
1022
1023memfile.c
1024
1025@subheading Description:
1026
1027This routine make sure that the memory based file is sufficiently large to
1028allow for the new file position index.
1029
1030The IMFS_memfile_extend() function is used to evaluate the current size of
1031the memory file and allocate additional memory blocks if required by the new
1032file position index. A success code is always returned from this routine.
1033
1034@c
1035@c
1036@c
1037@c @page
1038
1039@subsubsection IMFS_stat() for Regular Files
1040
1041@subheading Corresponding Structure Element:
1042
1043IMFS_stat()
1044
1045@subheading Arguments:
1046
1047@example
1048rtems_filesystem_location_info_t   *loc,
1049struct stat                        *buf
1050@end example
1051
1052@subheading File:
1053
1054imfs_stat.c
1055
1056@subheading Description:
1057
1058This routine actually performs status processing for both devices and regular
1059files.
1060
1061The IMFS_jnode_t structure is referenced to determine the type of node under
1062the filesystem.
1063
1064If the node is associated with a device, node information is extracted and
1065transformed to set the st_dev element of the stat structure.
1066
1067If the node is a regular file, the size of the regular file is extracted from
1068the node.
1069
1070This routine rejects other node types.
1071
1072The following information is extracted from the node and placed in the stat
1073structure:
1074
1075@itemize @bullet
1076
1077@item st_mode
1078
1079@item st_nlink
1080
1081@item st_ino
1082
1083@item st_uid
1084
1085@item st_gid
1086
1087@item st_atime
1088
1089@item st_mtime
1090
1091@item st_ctime
1092
1093@end itemize
1094
1095@c
1096@c
1097@c
1098@c @page
1099
1100@subsubsection IMFS_fchmod() for Regular Files
1101
1102@subheading Corresponding Structure Element:
1103
1104IMFS_fchmod()
1105
1106@subheading Arguments:
1107
1108@example
1109rtems_libio_t     *iop
1110mode_t              mode
1111@end example
1112
1113@subheading File:
1114
1115imfs_fchmod.c
1116
1117@subheading Description:
1118
1119This routine will obtain the pointer to the IMFS_jnode_t structure from the
1120information currently in the file control block.
1121
1122Based on configuration the routine will acquire the user ID from a call to
1123getuid()  or from the IMFS_jnode_t structure.
1124
1125It then checks to see if we have the ownership rights to alter the mode of
1126the file.  If the caller does not, an error code is returned.
1127
1128An additional test is performed to verify that the caller is not trying to
1129alter the nature of the node. If the caller is attempting to alter more than
1130the permissions associated with user group and other, an error is returned.
1131
1132If all the preconditions are met, the user, group and other fields are set
1133based on the mode calling parameter.
1134
1135@c
1136@c
1137@c
1138@c @page
1139
1140@subsubsection memfile_ftruncate() for Regular Files
1141
1142@subheading Corresponding Structure Element:
1143
1144XXX
1145
1146@subheading Arguments:
1147
1148XXX
1149@subheading File:
1150
1151XXX
1152
1153@subheading Description:
1154
1155XXX
1156
1157
1158@subsubsection No pathconf() for Regular Files
1159
1160@subheading Corresponding Structure Element:
1161
1162NULL
1163
1164@subheading Arguments:
1165
1166Not Implemented
1167
1168@subheading File:
1169
1170Not Implemented
1171
1172@subheading Description:
1173
1174Not Implemented
1175
1176
1177@c
1178@c
1179@c
1180@c @page
1181
1182@subsubsection No fsync() for Regular Files
1183
1184@subheading Corresponding Structure Element:
1185
1186XXX
1187
1188@subheading Arguments:
1189
1190XXX
1191@subheading File:
1192
1193XXX
1194
1195@subheading Description:
1196
1197XXX
1198
1199
1200@c
1201@c
1202@c
1203@c @page
1204
1205@subsubsection IMFS_fdatasync() for Regular Files
1206
1207@subheading Corresponding Structure Element:
1208
1209XXX
1210
1211@subheading Arguments:
1212
1213XXX
1214@subheading File:
1215
1216XXX
1217
1218@subheading Description:
1219
1220XXX
1221
1222@c
1223@c
1224@c
1225@c @page
1226@subsection Directory Handler Table Functions
1227
1228Handler table functions are defined in a rtems_filesystem_file_handlers_r
1229structure. It defines functions that are specific to a node type in a given
1230filesystem. One table exists for each of the filesystem's node types. The
1231structure definition appears below. It is followed by general developmental
1232information on each of the functions associated with directories contained in
1233this function management structure.
1234
1235@example
1236rtems_filesystem_file_handlers_r IMFS_directory_handlers = @{
1237  IMFS_dir_open,
1238  IMFS_dir_close,
1239  IMFS_dir_read,
1240  NULL,             /* write */
1241  NULL,             /* ioctl */
1242  IMFS_dir_lseek,
1243  IMFS_dir_fstat,
1244  IMFS_fchmod,
1245  NULL,             /* ftruncate */
1246  NULL,             /* fpathconf */
1247  NULL,             /* fsync */
1248  IMFS_fdatasync,
1249  IMFS_fcntl
1250@};
1251@end example
1252
1253
1254@c
1255@c
1256@c
1257@c @page
1258@subsubsection IMFS_dir_open() for Directories
1259
1260@subheading Corresponding Structure Element:
1261
1262imfs_dir_open()
1263
1264@subheading Arguments:
1265
1266@example
1267rtems_libio_t  *iop,
1268const char     *pathname,
1269unsigned32      flag,
1270unsigned32      mode
1271@end example
1272
1273@subheading File:
1274
1275imfs_directory.c
1276
1277@subheading Description:
1278
1279This routine will look into the file control block to find the @code{jnode} that
1280is associated with the directory.
1281
1282The routine will verify that the node is a directory. If its not a directory
1283an error code will be returned.
1284
1285If it is a directory, the offset in the file control block will be set to 0.
1286This allows us to start reading at the beginning of the directory.
1287
1288@c
1289@c
1290@c
1291@c @page
1292
1293@subsubsection IMFS_dir_close() for Directories
1294
1295@subheading Corresponding Structure Element:
1296
1297imfs_dir_close()
1298
1299@subheading Arguments:
1300
1301@example
1302rtems_libio_t     *iop
1303@end example
1304
1305@subheading File:
1306
1307imfs_directory.c
1308
1309@subheading Description:
1310
1311This routine is a dummy for directories under the base filesystem. It
1312immediately returns a success status.
1313
1314@c
1315@c
1316@c
1317@c @page
1318
1319@subsubsection IMFS_dir_read() for Directories
1320
1321@subheading Corresponding Structure Element:
1322
1323imfs_dir_read
1324
1325@subheading Arguments:
1326
1327@example
1328rtems_libio_t  *iop,
1329void           *buffer,
1330unsigned32      count
1331@end example
1332
1333@subheading File:
1334
1335imfs_directory.c
1336
1337@subheading Description:
1338
1339This routine will read a fixed number of directory entries from the current
1340directory offset. The number of directory bytes read will be returned from
1341this routine.
1342
1343
1344@c
1345@c
1346@c
1347@c @page
1348
1349@subsubsection No write() for Directories
1350
1351@subheading Corresponding Structure Element:
1352
1353XXX
1354
1355@subheading Arguments:
1356
1357XXX
1358
1359@subheading File:
1360
1361XXX
1362
1363@subheading Description:
1364
1365XXX
1366
1367@c
1368@c
1369@c
1370@c @page
1371
1372@subsubsection No ioctl() for Directories
1373
1374@subheading Corresponding Structure Element:
1375
1376ioctl
1377
1378@subheading Arguments:
1379
1380
1381@subheading File:
1382
1383Not supported
1384
1385@subheading Description:
1386
1387XXX
1388
1389@c
1390@c
1391@c
1392@c @page
1393
1394@subsubsection IMFS_dir_lseek() for Directories
1395
1396@subheading Corresponding Structure Element:
1397
1398imfs_dir_lseek()
1399
1400@subheading Arguments:
1401
1402@example
1403rtems_libio_t      *iop,
1404off_t               offset,
1405int                 whence
1406@end example
1407
1408@subheading File:
1409
1410imfs_directory.c
1411
1412@subheading Description:
1413
1414This routine alters the offset in the file control block.
1415
1416No test is performed on the number of children under the current open
1417directory.  The imfs_dir_read() function protects against reads beyond the
1418current size to the directory by returning a 0 bytes transfered to the
1419calling programs whenever the file position index exceeds the last entry in
1420the open directory.
1421
1422@c
1423@c
1424@c
1425@c @page
1426
1427@subsubsection IMFS_dir_fstat() for Directories
1428
1429@subheading Corresponding Structure Element:
1430
1431imfs_dir_fstat()
1432
1433@subheading Arguments:
1434
1435
1436@example
1437rtems_filesystem_location_info_t   *loc,
1438struct stat                        *buf
1439@end example
1440
1441@subheading File:
1442
1443imfs_directory.c
1444
1445@subheading Description:
1446
1447The node access information in the rtems_filesystem_location_info_t structure
1448is used to locate the appropriate IMFS_jnode_t structure. The following
1449information is taken from the IMFS_jnode_t structure and placed in the stat
1450structure:
1451
1452@itemize @bullet
1453@item st_ino
1454@item st_mode
1455@item st_nlink
1456@item st_uid
1457@item st_gid
1458@item st_atime
1459@item st_mtime
1460@item st_ctime
1461@end itemize
1462
1463The st_size field is obtained by running through the chain of directory
1464entries and summing the sizes of the dirent structures associated with each
1465of the children of the directory.
1466
1467@c
1468@c
1469@c
1470@c @page
1471
1472@subsubsection IMFS_fchmod() for Directories
1473
1474@subheading Corresponding Structure Element:
1475
1476IMFS_fchmod()
1477
1478@subheading Arguments:
1479
1480@example
1481rtems_libio_t     *iop
1482mode_t             mode
1483@end example
1484
1485@subheading File:
1486
1487imfs_fchmod.c
1488
1489@subheading Description:
1490
1491This routine will obtain the pointer to the IMFS_jnode_t structure from the
1492information currently in the file control block.
1493
1494Based on configuration the routine will acquire the user ID from a call to
1495getuid()  or from the IMFS_jnode_t structure.
1496
1497It then checks to see if we have the ownership rights to alter the mode of
1498the file.  If the caller does not, an error code is returned.
1499
1500An additional test is performed to verify that the caller is not trying to
1501alter the nature of the node. If the caller is attempting to alter more than
1502the permissions associated with user group and other, an error is returned.
1503
1504If all the preconditions are met, the user, group and other fields are set
1505based on the mode calling parameter.
1506
1507@c
1508@c
1509@c
1510@c @page
1511
1512@subsubsection No ftruncate() for Directories
1513
1514@subheading Corresponding Structure Element:
1515
1516XXX
1517
1518@subheading Arguments:
1519
1520XXX
1521
1522@subheading File:
1523
1524XXX
1525
1526@subheading Description:
1527
1528XXX
1529
1530@c
1531@c
1532@c
1533@c @page
1534
1535@subsubsection No fpathconf() for Directories
1536
1537@subheading Corresponding Structure Element:
1538
1539fpathconf
1540
1541@subheading Arguments:
1542
1543Not Implemented
1544
1545@subheading File:
1546
1547Not Implemented
1548
1549@subheading Description:
1550
1551Not Implemented
1552
1553
1554@c
1555@c
1556@c
1557@c @page
1558
1559@subsubsection No fsync() for Directories
1560
1561@subheading Corresponding Structure Element:
1562
1563XXX
1564
1565@subheading Arguments:
1566
1567XXX
1568@subheading File:
1569
1570XXX
1571
1572@subheading Description:
1573
1574XXX
1575
1576
1577@c
1578@c
1579@c
1580@c @page
1581
1582@subsubsection IMFS_fdatasync() for Directories
1583
1584@subheading Corresponding Structure Element:
1585
1586XXX
1587
1588@subheading Arguments:
1589
1590XXX
1591
1592@subheading File:
1593
1594XXX
1595
1596@subheading Description:
1597
1598XXX
1599
1600@c
1601@c
1602@c
1603@c @page
1604@subsection Device Handler Table Functions
1605
1606Handler table functions are defined in a rtems_filesystem_file_handlers_r
1607structure. It defines functions that are specific to a node type in a given
1608filesystem. One table exists for each of the filesystem's node types. The
1609structure definition appears below. It is followed by general developmental
1610information on each of the functions associated with devices contained in
1611this function management structure.
1612
1613@example
1614typedef struct @{
1615  rtems_filesystem_open_t           open;
1616  rtems_filesystem_close_t          close;
1617  rtems_filesystem_read_t           read;
1618  rtems_filesystem_write_t          write;
1619  rtems_filesystem_ioctl_t          ioctl;
1620  rtems_filesystem_lseek_t          lseek;
1621  rtems_filesystem_fstat_t          fstat;
1622  rtems_filesystem_fchmod_t         fchmod;
1623  rtems_filesystem_ftruncate_t      ftruncate;
1624  rtems_filesystem_fpathconf_t      fpathconf;
1625  rtems_filesystem_fsync_t          fsync;
1626  rtems_filesystem_fdatasync_t      fdatasync;
1627@} rtems_filesystem_file_handlers_r;
1628@end example
1629
1630@c
1631@c
1632@c
1633@c @page
1634
1635@subsubsection device_open() for Devices
1636
1637@subheading Corresponding Structure Element:
1638
1639device_open()
1640
1641@subheading Arguments:
1642
1643@example
1644rtems_libio_t     *iop,
1645const char        *pathname,
1646unsigned32         flag,
1647unsigned32         mode
1648@end example
1649
1650@subheading File:
1651
1652deviceio.c
1653
1654@subheading Description:
1655
1656This routine will use the file control block to locate the node structure for
1657the device.
1658
1659It will extract the major and minor device numbers from the @code{jnode}.
1660
1661The major and minor device numbers will be used to make a rtems_io_open() 
1662function call to open the device driver. An argument list is sent to the
1663driver that contains the file control block, flags and mode information.
1664
1665@c
1666@c
1667@c
1668@c @page
1669
1670@subsubsection device_close() for Devices
1671
1672@subheading Corresponding Structure Element:
1673
1674device_close()
1675
1676@subheading Arguments:
1677
1678@example
1679rtems_libio_t     *iop
1680@end example
1681
1682@subheading File:
1683
1684deviceio.c
1685
1686@subheading Description:
1687
1688This routine extracts the major and minor device driver numbers from the
1689IMFS_jnode_t that is referenced in the file control block.
1690
1691It also forms an argument list that contains the file control block.
1692
1693A rtems_io_close() function call is made to close the device specified by the
1694major and minor device numbers.
1695
1696
1697@c
1698@c
1699@c
1700@c @page
1701
1702@subsubsection device_read() for Devices
1703
1704@subheading Corresponding Structure Element:
1705
1706device_read()
1707
1708@subheading Arguments:
1709
1710@example
1711rtems_libio_t     *iop,
1712void              *buffer,
1713unsigned32         count
1714@end example
1715
1716@subheading File:
1717
1718deviceio.c
1719
1720@subheading Description:
1721
1722This routine will extract the major and minor numbers for the device from the -
1723jnode- associated with the file descriptor.
1724
1725A rtems_io_read() call will be made to the device driver associated with the file
1726descriptor. The major and minor device number will be sent as arguments as well
1727as an argument list consisting of:
1728
1729@itemize @bullet
1730@item file control block
1731
1732@item file position index
1733
1734@item buffer pointer where the data read is to be placed
1735
1736@item count indicating the number of bytes that the program wishes to read
1737from the device
1738
1739@item flags from the file control block
1740
1741@end itemize
1742
1743On return from the rtems_io_read() the number of bytes that were actually
1744read will be returned to the calling program.
1745
1746
1747@c
1748@c
1749@c
1750@c @page
1751
1752@subsubsection device_write() for Devices
1753
1754@subheading Corresponding Structure Element:
1755
1756XXX
1757
1758@subheading Arguments:
1759
1760XXX
1761@subheading File:
1762
1763XXX
1764
1765@subheading Description:
1766
1767XXX
1768
1769@c
1770@c
1771@c
1772@c @page
1773
1774@subsubsection device_ioctl() for Devices
1775
1776@subheading Corresponding Structure Element:
1777
1778ioctl
1779
1780@subheading Arguments:
1781
1782@example
1783rtems_libio_t     *iop,
1784unsigned32         command,
1785void              *buffer
1786@end example
1787
1788@subheading File:
1789
1790deviceio.c
1791
1792@subheading Description:
1793
1794This handler will obtain status information about a device.
1795
1796The form of status is device dependent.
1797
1798The rtems_io_control() function uses the major and minor number of the device
1799to obtain the status information.
1800
1801rtems_io_control() requires an rtems_libio_ioctl_args_t argument list which
1802contains the file control block, device specific command and a buffer pointer
1803to return the device status information.
1804
1805The device specific command should indicate the nature of the information
1806that is desired from the device.
1807
1808After the rtems_io_control() is processed, the buffer should contain the
1809requested device information.
1810
1811If the device information is not obtained properly a -1 will be returned to
1812the calling program, otherwise the ioctl_return value is returned.
1813
1814@c
1815@c
1816@c
1817@c @page
1818
1819@subsubsection device_lseek() for Devices
1820
1821@subheading Corresponding Structure Element:
1822
1823device_lseek()
1824
1825@subheading Arguments:
1826
1827@example
1828rtems_libio_t     *iop,
1829off_t              offset,
1830int                whence
1831@end example
1832
1833@subheading File:
1834
1835deviceio.c
1836
1837@subheading Description:
1838
1839At the present time this is a placeholder function. It always returns a
1840successful status.
1841
1842@c
1843@c
1844@c
1845@c @page
1846
1847@subsubsection IMFS_stat() for Devices
1848
1849@subheading Corresponding Structure Element:
1850
1851IMFS_stat()
1852
1853@subheading Arguments:
1854
1855@example
1856rtems_filesystem_location_info_t   *loc,
1857struct stat                        *buf
1858@end example
1859
1860@subheading File:
1861
1862imfs_stat.c
1863
1864@subheading Description:
1865
1866This routine actually performs status processing for both devices and regular files.
1867
1868The IMFS_jnode_t structure is referenced to determine the type of node under the
1869filesystem.
1870
1871If the node is associated with a device, node information is extracted and
1872transformed to set the st_dev element of the stat structure.
1873
1874If the node is a regular file, the size of the regular file is extracted from the node.
1875
1876This routine rejects other node types.
1877
1878The following information is extracted from the node and placed in the stat
1879structure:
1880
1881@itemize @bullet
1882
1883@item st_mode
1884
1885@item st_nlink
1886
1887@item st_ino
1888
1889@item st_uid
1890
1891@item st_gid
1892
1893@item st_atime
1894
1895@item st_mtime
1896
1897@item st_ctime
1898
1899@end itemize
1900
1901
1902
1903@c
1904@c
1905@c
1906@c @page
1907
1908@subsubsection IMFS_fchmod() for Devices
1909
1910@subheading Corresponding Structure Element:
1911
1912IMFS_fchmod()
1913
1914@subheading Arguments:
1915
1916@example
1917rtems_libio_t     *iop
1918mode_t             mode
1919@end example
1920
1921@subheading File:
1922
1923imfs_fchmod.c
1924
1925@subheading Description:
1926
1927This routine will obtain the pointer to the IMFS_jnode_t structure from the
1928information currently in the file control block.
1929
1930Based on configuration the routine will acquire the user ID from a call to
1931getuid()  or from the IMFS_jnode_t structure.
1932
1933It then checks to see if we have the ownership rights to alter the mode of
1934the file.  If the caller does not, an error code is returned.
1935
1936An additional test is performed to verify that the caller is not trying to
1937alter the nature of the node. If the caller is attempting to alter more than
1938the permissions associated with user group and other, an error is returned.
1939
1940If all the preconditions are met, the user, group and other fields are set
1941based on the mode calling parameter.
1942
1943
1944@c
1945@c
1946@c
1947@c @page
1948
1949@subsubsection No ftruncate() for Devices
1950
1951@subheading Corresponding Structure Element:
1952
1953XXX
1954
1955@subheading Arguments:
1956
1957XXX
1958@subheading File:
1959
1960XXX
1961
1962@subheading Description:
1963
1964XXX
1965
1966@c
1967@c
1968@c
1969@c @page
1970
1971@subsubsection No fpathconf() for Devices
1972
1973@subheading Corresponding Structure Element:
1974
1975fpathconf
1976
1977@subheading Arguments:
1978
1979Not Implemented
1980
1981@subheading File:
1982
1983Not Implemented
1984
1985@subheading Description:
1986
1987Not Implemented
1988
1989
1990@c
1991@c
1992@c
1993@c @page
1994
1995@subsubsection No fsync() for Devices
1996
1997@subheading Corresponding Structure Element:
1998
1999XXX
2000
2001@subheading Arguments:
2002
2003XXX
2004
2005@subheading File:
2006
2007XXX
2008
2009@subheading Description:
2010
2011XXX
2012
2013
2014@c
2015@c
2016@c
2017@c @page
2018
2019@subsubsection No fdatasync() for Devices
2020
2021Not Implemented
2022
2023@subheading Corresponding Structure Element:
2024
2025XXX
2026
2027@subheading Arguments:
2028
2029XXX
2030
2031@subheading File:
2032
2033XXX
2034
2035@subheading Description:
2036
2037XXX
2038
Note: See TracBrowser for help on using the repository browser.