3 <!-- =============================================================== -->
7 <!-- eCos Generic File I/O package documentation -->
9 <!-- =============================================================== -->
10 <!-- ####COPYRIGHTBEGIN#### -->
12 <!-- =============================================================== -->
13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc. -->
14 <!-- This material may be distributed only subject to the terms -->
15 <!-- and conditions set forth in the Open Publication License, v1.0 -->
16 <!-- or later (the latest version is presently available at -->
17 <!-- http://www.opencontent.org/openpub/) -->
18 <!-- Distribution of the work or derivative of the work in any -->
19 <!-- standard (paper) book form is prohibited unless prior -->
20 <!-- permission obtained from the copyright holder -->
21 <!-- =============================================================== -->
23 <!-- ####COPYRIGHTEND#### -->
24 <!-- =============================================================== -->
25 <!-- #####DESCRIPTIONBEGIN#### -->
27 <!-- ####DESCRIPTIONEND#### -->
28 <!-- =============================================================== -->
33 <title>File System Support Infrastructure</title>
35 <!-- {{{ Introduction -->
37 <chapter id="fileio-intro">
38 <title>Introduction</title>
41 This document describes the filesystem infrastructure provided in
42 eCos. This is implemented by the FILEIO package and provides POSIX
43 compliant file and IO operations together with the BSD socket
44 API. These APIs are described in the relevant standards and original
45 documentation and will not be described here. See <xref
46 linkend="posix-standard-support"> for details of which parts of the
47 POSIX standard are supported.
51 This document is concerned with the interfaces presented to client
52 filesystems and network protocol stacks.
56 The FILEIO infrastructure consist mainly of a set of tables containing
57 pointers to the primary interface functions of a file system. This
58 approach avoids problems of namespace pollution (for example several
59 filesystems can have a function called <function>read()</function>, so long as they are
60 static). The system is also structured to eliminate the need for
61 dynamic memory allocation.
65 New filesystems can be written directly to the interfaces described
66 here. Existing filesystems can be ported very easily by the
67 introduction of a thin veneer porting layer that translates FILEIO
68 calls into native filesystem calls.
72 The term filesystem should be read fairly loosely in this
73 document. Object accessed through these interfaces could equally be
74 network protocol sockets, device drivers, fifos, message queues or any
75 other object that can present a file-like interface.
81 <!-- {{{ File System Table -->
83 <chapter id="fileio-fstab">
84 <title>File System Table</title>
87 The filesystem table is an array of entries that describe each
88 filesystem implementation that is part of the system image. Each
89 resident filesystem should export an entry to this table using the
90 <literal>FSTAB_ENTRY()</literal> macro.
96 At present we do not support dynamic addition or removal of table
97 entries. However, an API similar to <function>mount()</function> would
98 allow new entries to be added to the table.
103 The table entries are described by the following structure:
107 struct cyg_fstab_entry
109 const char *name; // filesystem name
110 CYG_ADDRWORD data; // private data value
111 cyg_uint32 syncmode; // synchronization mode
113 int (*mount) ( cyg_fstab_entry *fste, cyg_mtab_entry *mte );
114 int (*umount) ( cyg_mtab_entry *mte );
115 int (*open) ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
116 int mode, cyg_file *fte );
117 int (*unlink) ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
118 int (*mkdir) ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
119 int (*rmdir) ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
120 int (*rename) ( cyg_mtab_entry *mte, cyg_dir dir1, const char *name1,
121 cyg_dir dir2, const char *name2 );
122 int (*link) ( cyg_mtab_entry *mte, cyg_dir dir1, const char *name1,
123 cyg_dir dir2, const char *name2, int type );
124 int (*opendir) ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
126 int (*chdir) ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
128 int (*stat) ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
130 int (*getinfo) ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
131 int key, char *buf, int len );
132 int (*setinfo) ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
133 int key, char *buf, int len );
138 The <structfield>name</structfield> field points to a string that
139 identifies this filesystem implementation. Typical values might be
140 "romfs", "msdos", "ext2" etc.
144 The <structfield>data</structfield> field contains any private data
145 that the filesystem needs, perhaps the root of its data structures.
149 The <structfield>syncmode</structfield> field contains a description of
150 the locking protocol to be used when accessing this filesystem. It
151 will be described in more detail in <xref linkend="fileio-synchronization">.
155 The remaining fields are pointers to functions that implement
156 filesystem operations that apply to files and directories as whole
157 objects. The operation implemented by each function should be obvious
158 from the names, with a few exceptions:
162 The <function>opendir()</function> function pointer opens a directory
163 for reading. See <xref linkend="fileio-directories"> for details.
167 The <function>getinfo()</function> and
168 <function>setinfo()</function> function pointers provide support for
169 various minor control and information functions such as
170 <function>pathconf()</function> and <function>access()</function>.
174 With the exception of the <function>mount()</function> and
175 <function>umount()</function> functions, all of these functions
176 take three standard arguments, a pointer to a mount table entry (see
177 later) a directory pointer (also see later) and a file name relative
178 to the directory. These should be used by the filesystem to locate the
185 <!-- {{{ Mount Table -->
187 <chapter id="fileio-mount-table">
188 <title>Mount Table</title>
191 The mount table records the filesystems that are actually active.
192 These can be seen as being analogous to mount points in Unix systems.
196 There are two sources of mount table entries. Filesystems (or other
197 components) may export static entries to the table using the
198 <literal>MTAB_ENTRY()</literal> macro. Alternatively, new entries may
199 be installed at run time using the <function>mount()</function>
200 function. Both types of entry may be unmounted with the
201 <function>umount()</function> function.
205 A mount table entry has the following structure:
209 struct cyg_mtab_entry
211 const char *name; // name of mount point
212 const char *fsname; // name of implementing filesystem
213 const char *devname; // name of hardware device
214 CYG_ADDRWORD data; // private data value
215 cyg_bool valid; // Valid entry?
216 cyg_fstab_entry *fs; // pointer to fstab entry
217 cyg_dir root; // root directory pointer
222 The <structfield>name</structfield> field identifies the mount
223 point. This is used to direct rooted filenames (filenames that
224 begin with "/") to the correct filesystem. When a file
225 name that begins with "/" is submitted, it is matched
226 against the <structfield>name</structfield> fields of all valid mount
227 table entries. The entry that yields the longest match terminating
228 before a "/", or end of string, wins and the appropriate
229 function from the filesystem table entry is then passed the remainder
230 of the file name together with a pointer to the table entry and the
231 value of the <structfield>root</structfield> field as the directory
236 For example, consider a mount table that contains the following
241 { "/", "msdos", "/dev/hd0", ... }
242 { "/fd", "msdos", "/dev/fd0", ... }
243 { "/rom", "romfs", "", ... }
244 { "/tmp", "ramfs", "", ... }
245 { "/dev", "devfs", "", ... }
249 An attempt to open "/tmp/foo" would be directed to the RAM
250 filesystem while an open of "/bar/bundy" would be directed
251 to the hard disc MSDOS filesystem. Opening "/dev/tty0" would
252 be directed to the device management filesystem for lookup in the
257 Unrooted file names (those that do not begin with a '/') are passed
258 straight to the filesystem that contains the current directory. The
259 current directory is represented by a pair consisting of a mount table
260 entry and a directory pointer.
264 The <structfield>fsname</structfield> field points to a string that
265 should match the <structfield>name</structfield> field of the
266 implementing filesystem. During initialization the mount table is
267 scanned and the <structfield>fsname</structfield> entries looked up in
268 the filesystem table. For each match, the filesystem's _mount_
269 function is called and if successful the mount table entry is marked
270 as valid and the <structfield>fs</structfield> pointer installed.
274 The <structfield>devname</structfield> field contains the name of the
275 device that this filesystem is to use. This may match an entry in the
276 device table (see later) or may be a string that is specific to the
277 filesystem if it has its own internal device drivers.
281 The <structfield>data</structfield> field is a private data value. This
282 may be installed either statically when the table entry is defined, or
283 may be installed during the <function>mount()</function> operation.
287 The <structfield>valid</structfield> field indicates whether this mount
288 point has actually been mounted successfully. Entries with a false
289 <structfield>valid</structfield> field are ignored when searching for a
294 The <structfield>fs</structfield> field is installed after a successful
295 <function>mount()</function> operation to point to the implementing
300 The <structfield>root</structfield> field contains a directory pointer
301 value that the filesystem can interpret as the root of its directory
302 tree. This is passed as the <parameter>dir</parameter> argument of
303 filesystem functions that operate on rooted filenames. This field must
304 be initialized by the filesystem's <function>mount()</function>
311 <!-- {{{ File Table -->
313 <chapter id="fileio-file-table">
314 <title>File Table</title>
317 Once a file has been opened it is represented by an open file
318 object. These are allocated from an array of available file
319 objects. User code accesses these open file objects via a second array
320 of pointers which is indexed by small integer offsets. This gives the
321 usual Unix file descriptor functionality, complete with the various
322 duplication mechanisms.
326 A file table entry has the following structure:
332 cyg_uint32 f_flag; /* file state */
333 cyg_uint16 f_ucount; /* use count */
334 cyg_uint16 f_type; /* descriptor type */
335 cyg_uint32 f_syncmode; /* synchronization protocol */
336 struct CYG_FILEOPS_TAG *f_ops; /* file operations */
337 off_t f_offset; /* current offset */
338 CYG_ADDRWORD f_data; /* file or socket */
339 CYG_ADDRWORD f_xops; /* extra type specific ops */
340 cyg_mtab_entry *f_mte; /* mount table entry */
345 The <structfield>f_flag</structfield> field contains some FILEIO
346 control bits and some bits propagated from the
347 <parameter>flags</parameter> argument of the
348 <function>open()</function> call (defined by
349 <literal>CYG_FILE_MODE_MASK</literal>).
353 The <structfield>f_ucount</structfield> field contains a use count that
354 controls when a file will be closed. Each duplicate in the file
355 descriptor array counts for one reference here. It is also
356 incremented around each I/O operation to ensure that the file cannot
357 be closed while it has current I/O operations.
361 The <structfield>f_type</structfield> field indicates the type of the
362 underlying file object. Some of the possible values here are
363 <literal>CYG_FILE_TYPE_FILE</literal>,
364 <literal>CYG_FILE_TYPE_SOCKET</literal> or <literal>CYG_FILE_TYPE_DEVICE</literal>.
368 The <structfield>f_syncmode</structfield> field is copied from the
369 <structfield>syncmode</structfield> field of the implementing
370 filesystem. Its use is described in <xref linkend="fileio-synchronization">.
374 The <structfield>f_offset</structfield> field records the current file
375 position. It is the responsibility of the file operation functions to
376 keep this field up to date.
380 The <structfield>f_data</structfield> field contains private data
381 placed here by the underlying filesystem. Normally this will be a
382 pointer to, or handle on, the filesystem object that implements this
387 The <structfield>f_xops</structfield> field contains a pointer to any
388 extra type specific operation functions. For example, the socket I/O
389 system installs a pointer to a table of functions that implement the
390 standard socket operations.
394 The <structfield>f_mte</structfield> field contains a pointer to the
395 parent mount table entry for this file. It is used mainly to implement
396 the synchronization protocol. This may contain a pointer to some other
397 data structure in file objects not derived from a filesystem.
401 The <structfield>f_ops</structfield> field contains a pointer to a
402 table of file I/O operations. This has the following structure:
406 struct CYG_FILEOPS_TAG
408 int (*fo_read) (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
409 int (*fo_write) (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
410 int (*fo_lseek) (struct CYG_FILE_TAG *fp, off_t *pos, int whence );
411 int (*fo_ioctl) (struct CYG_FILE_TAG *fp, CYG_ADDRWORD com,
413 int (*fo_select) (struct CYG_FILE_TAG *fp, int which, CYG_ADDRWORD info);
414 int (*fo_fsync) (struct CYG_FILE_TAG *fp, int mode );
415 int (*fo_close) (struct CYG_FILE_TAG *fp);
416 int (*fo_fstat) (struct CYG_FILE_TAG *fp, struct stat *buf );
417 int (*fo_getinfo) (struct CYG_FILE_TAG *fp, int key, char *buf, int len );
418 int (*fo_setinfo) (struct CYG_FILE_TAG *fp, int key, char *buf, int len );
423 It should be obvious from the names of most of these functions what
424 their responsibilities are. The <function>fo_getinfo()</function>
425 and <function>fo_setinfo()</function> function pointers, like their
426 counterparts in the filesystem structure, implement minor control and
427 info functions such as <function>fpathconf()</function>.
431 The second argument to the <function>fo_read()</function> and
432 <function>fo_write()</function> function pointers is a pointer to a
439 struct CYG_IOVEC_TAG *uio_iov; /* pointer to array of iovecs */
440 int uio_iovcnt; /* number of iovecs in array */
441 off_t uio_offset; /* offset into file this uio corresponds to */
442 ssize_t uio_resid; /* residual i/o count */
443 enum cyg_uio_seg uio_segflg; /* see above */
444 enum cyg_uio_rw uio_rw; /* see above */
449 void *iov_base; /* Base address. */
450 ssize_t iov_len; /* Length. */
455 This structure encapsulates the parameters of any data transfer
456 operation. It provides support for scatter/gather operations and
457 records the progress of any data transfer. It is also compatible with
458 the I/O operations of any BSD-derived network stacks and filesystems.
462 When a file is opened (or a file object created by some other means,
463 such as <function>socket()</function> or <function>accept()</function>) it is the
464 responsibility of the filesystem open operation to initialize all the
465 fields of the object except the <structfield>f_ucount</structfield>,
466 <structfield>f_syncmode</structfield> and
467 <structfield>f_mte</structfield> fields. Since the
468 <structfield>f_flag</structfield> field will already contain bits belonging to the FILEIO
469 infrastructure, any changes to it must be made with the appropriate
476 <!-- {{{ Directories -->
478 <chapter id="fileio-directories">
479 <title>Directories</title>
482 Filesystem operations all take a directory pointer as one of their
483 arguments. A directory pointer is an opaque handle managed by the
484 filesystem. It should encapsulate a reference to a specific directory
485 within the filesystem. For example, it may be a pointer to the data
486 structure that represents that directory (such as an inode), or a
487 pointer to a pathname for the directory.
491 The <function>chdir()</function> filesystem function pointer has two
492 modes of use. When passed a pointer in the
493 <parameter>dir_out</parameter> argument, it should locate the named
494 directory and place a directory pointer there. If the
495 <parameter>dir_out</parameter> argument is NULL then the
496 <parameter>dir</parameter> argument is a previously generated
497 directory pointer that can now be disposed of. When the infrastructure
498 is implementing the <function>chdir()</function> function it makes two
499 calls to filesystem <function>chdir()</function> functions. The first
500 is to get a directory pointer for the new current directory. If this
501 succeeds the second is to dispose of the old current directory
506 The <function>opendir()</function> function is used to open a
507 directory for reading. This results in an open file object that can be
508 read to return a sequence of <structname>struct dirent</structname>
509 objects. The only operations that are allowed on this file are
510 <function>read</function>, <function>lseek</function> and
511 <function>close</function>. Each read operation on this file should
512 return a single <structname>struct dirent</structname> object. When
513 the end of the directory is reached, zero should be returned. The only
514 seek operation allowed is a rewind to the start of the directory, by
515 supplying an offset of zero and a <parameter>whence</parameter>
516 specifier of <literal>SEEK_SET</literal>.
520 Most of these considerations are invisible to clients of a filesystem
521 since they will access directories via the POSIX
522 <function>opendir()</function>, <function>readdir()</function> and
523 <function>closedir()</function> functions.
527 Support for the <function>getcwd()</function> function is provided by
528 three mechanisms. The first is to use the
529 <literal>FS_INFO_GETCWD</literal> getinfo key on the filesystem to use
530 any internal support that it has for this. If that fails it falls back
531 on one of the two other mechanisms. If
532 <literal>CYGPKG_IO_FILEIO_TRACK_CWD</literal> is set then the current
533 directory is tracked textually in <function>chdir()</function> and the result of that is
534 reported in getcwd(). Otherwise an attempt is made to traverse the
535 directory tree to its root using ".." entries.
539 This last option is complicated and expensive, and relies on the
540 filesystem supporting "." and ".." entries. This is not always the
541 case, particularly if the filesystem has been ported from a
542 non-UNIX-compatible source. Tracking the pathname textually will
543 usually work, but might not produce optimum results when symbolic
544 links are being used.
550 <!-- {{{ Synchronization -->
552 <chapter id="fileio-synchronization">
553 <title>Synchronization</title>
556 The FILEIO infrastructure provides a synchronization mechanism for
557 controlling concurrent access to filesystems. This allows existing
558 filesystems to be ported to eCos, even if they do not have their own
559 synchronization mechanisms. It also allows new filesystems to be
560 implemented easily without having to consider the synchronization
565 The infrastructure maintains a mutex for each entry in each of
566 the main tables: filesystem table, mount table and file table. For
567 each class of operation each of these mutexes may be locked before the
568 corresponding filesystem operation is invoked.
572 The synchronization protocol required by a filesystem is described
573 by the <structfield>syncmode</structfield> field of the filesystem
574 table entry. This is a combination of the following flags:
579 <term><literal>CYG_SYNCMODE_FILE_FILESYSTEM</literal></term>
582 Lock the filesystem table entry mutex
583 during all filesystem level operations.
589 <term><literal>CYG_SYNCMODE_FILE_MOUNTPOINT</literal></term>
592 Lock the mount table entry mutex
593 during all filesystem level operations.
599 <term><literal>CYG_SYNCMODE_IO_FILE</literal></term>
602 Lock the file table entry mutex during all
609 <term><literal>CYG_SYNCMODE_IO_FILESYSTEM</literal></term>
612 Lock the filesystem table entry mutex during all I/O operations.
618 <term><literal>CYG_SYNCMODE_IO_MOUNTPOINT</literal></term>
620 Lock the mount table entry mutex during all I/O operations.
626 <term><literal>CYG_SYNCMODE_SOCK_FILE</literal></term>
629 Lock the file table entry mutex during all socket operations.
635 <term><literal>CYG_SYNCMODE_SOCK_NETSTACK</literal></term>
638 Lock the network stack table entry mutex during all socket operations.
644 <term><literal>CYG_SYNCMODE_NONE</literal></term>
647 Perform no locking at all during any operations.
655 The value of the <structfield>syncmode</structfield> field in the
656 filesystem table entry will be copied by the infrastructure to the
657 open file object after a successful <function>open()</function> operation.
663 <!-- {{{ Initialization and Mounting -->
665 <chapter id="fileio-mounting">
666 <title>Initialization and Mounting</title>
669 As mentioned previously, mount table entries can be sourced from two
670 places. Static entries may be defined by using the
671 <literal>MTAB_ENTRY()</literal> macro. Such entries will be
672 automatically mounted on system startup. For each entry in the mount
673 table that has a non-null <structfield>name</structfield> field the
674 filesystem table is searched for a match with the
675 <structfield>fsname</structfield> field. If a match is found the
676 filesystem's <structfield>mount</structfield> entry is called and if
677 successful the mount table entry marked valid and the
678 <structfield>fs</structfield> field initialized. The
679 <function>mount()</function> function is responsible for initializing
680 the <structfield>root</structfield> field.
685 The size of the mount table is defined by the configuration value
686 <literal>CYGNUM_FILEIO_MTAB_MAX</literal>. Any entries that have not
687 been statically defined are available for use by dynamic mounts.
691 A filesystem may be mounted dynamically by calling <function>mount()</function>. This
692 function has the following prototype:
695 <programlisting width=72>
696 int mount( const char *devname,
702 The <parameter>devname</parameter> argument identifies a device that
703 will be used by this filesystem and will be assigned to the
704 <structfield>devname</structfield> field of the mount table entry.
708 The <parameter>dir</parameter> argument is the mount point name, it
709 will be assigned to the <structfield>name</structfield> field of the
714 The <parameter>fsname</parameter> argument is the name of the
715 implementing filesystem, it will be assigned to the
716 <structfield>fsname</structfield> entry of the mount table entry.
720 The process of mounting a filesystem dynamically is as follows. First
721 a search is made of the mount table for an entry with a NULL
722 <structfield>name</structfield> field to be used for the new mount
723 point. The filesystem table is then searched for an entry whose name
724 matches <structfield>fsname</structfield>. If this is successful then
725 the mount table entry is initialized and the filesystem's
726 <function>mount()</function> operation called. If this is successful,
727 the mount table entry is marked valid and the
728 <structfield>fs</structfield> field initialized.
732 Unmounting a filesystem is done by the <function>umount()</function>
733 function. This can unmount filesystems whether they were mounted
734 statically or dynamically.
738 The <function>umount()</function> function has the following prototype:
741 <programlisting width=72>
742 int umount( const char *name );
746 The mount table is searched for a match between the
747 <parameter>name</parameter> argument and the entry
748 <structfield>name</structfield> field. When a match is found the
749 filesystem's <function>umount()</function> operation is called and if
750 successful, the mount table entry is invalidated by setting its
751 <structfield>valid</structfield> field false and the
752 <structfield>name</structfield> field to NULL.
765 <chapter id="fileio-sockets">
766 <title>Sockets</title>
769 If a network stack is present, then the FILEIO infrastructure also
770 provides access to the standard BSD socket calls.
774 The netstack table contains entries which describe the network
775 protocol stacks that are in the system image. Each resident stack
776 should export an entry to this table using the
777 <literal>NSTAB_ENTRY()</literal> macro.
781 Each table entry has the following structure:
784 <programlisting width=72>
785 struct cyg_nstab_entry
787 cyg_bool valid; // true if stack initialized
788 cyg_uint32 syncmode; // synchronization protocol
789 char *name; // stack name
790 char *devname; // hardware device name
791 CYG_ADDRWORD data; // private data value
793 int (*init)( cyg_nstab_entry *nste );
794 int (*socket)( cyg_nstab_entry *nste, int domain, int type,
795 int protocol, cyg_file *file );
800 This table is analogous to a combination of the filesystem and mount
805 The <structfield>valid</structfield> field is set
806 <literal>true</literal> if the stack's <function>init()</function>
807 function returned successfully and the
808 <structfield>syncmode</structfield> field contains the
809 <literal>CYG_SYNCMODE_SOCK_*</literal> bits described above.
818 The <structfield>name</structfield> field contains the name of the
828 The <structfield>devname</structfield> field names the device that the stack is using. This may
829 reference a device under "/dev", or may be a name that is only
830 meaningful to the stack itself.
839 The <function>init()</function> function pointer is called during
840 system initialization to start the protocol stack running. If it
841 returns non-zero the <structfield>valid</structfield> field is set
842 false and the stack will be ignored subsequently.
846 The <function>socket()</function> function is called to attempt to create a socket in the
847 stack. When the <function>socket()</function> API function is called the netstack table is
848 scanned and for each valid entry the <function>socket()</function>
849 function pointer is called. If
850 this returns non-zero then the scan continues to the next valid stack,
851 or terminates with an error if the end of the table is reached.
855 The result of a successful socket call is an initialized file object
856 with the <structfield>f_xops</structfield> field pointing to the
860 <programlisting width=72>
863 int (*bind) ( cyg_file *fp, const sockaddr *sa, socklen_t len );
864 int (*connect) ( cyg_file *fp, const sockaddr *sa, socklen_t len );
865 int (*accept) ( cyg_file *fp, cyg_file *new_fp,
866 struct sockaddr *name, socklen_t *anamelen );
867 int (*listen) ( cyg_file *fp, int len );
868 int (*getname) ( cyg_file *fp, sockaddr *sa, socklen_t *len, int peer );
869 int (*shutdown) ( cyg_file *fp, int flags );
870 int (*getsockopt)( cyg_file *fp, int level, int optname,
871 void *optval, socklen_t *optlen);
872 int (*setsockopt)( cyg_file *fp, int level, int optname,
873 const void *optval, socklen_t optlen);
874 int (*sendmsg) ( cyg_file *fp, const struct msghdr *m,
875 int flags, ssize_t *retsize );
876 int (*recvmsg) ( cyg_file *fp, struct msghdr *m,
877 socklen_t *namelen, ssize_t *retsize );
882 It should be obvious from the names of these functions which API calls
883 they provide support for. The <function>getname()</function> function
884 pointer provides support for both <function>getsockname()</function>
885 and <function>getpeername()</function> while the
886 <function>sendmsg()</function> and <function>recvmsg()</function>
887 function pointers provide support for <function>send()</function>,
888 <function>sendto()</function>, <function>sendmsg()</function>,
889 <function>recv()</function>, <function>recvfrom()</function> and
890 <function>recvmsg()</function> as appropriate.
898 <chapter id="fileio-select">
899 <title>Select</title>
902 The infrastructure provides support for implementing a select
903 mechanism. This is modeled on the mechanism in the BSD kernel, but has
904 been modified to make it implementation independent.
908 The main part of the mechanism is the <function>select()</function>
909 API call. This processes its arguments and calls the
910 <function>fo_select()</function> function pointer on all file objects
911 referenced by the file descriptor sets passed to it. If the same
912 descriptor appears in more than one descriptor set, the
913 <function>fo_select()</function> function will be called separately
918 The <parameter>which</parameter> argument of the
919 <function>fo_select()</function> function will either be
920 <literal>CYG_FREAD</literal> to test for read conditions,
921 <literal>CYG_FWRITE</literal> to test for write conditions or zero to
922 test for exceptions. For each of these options the function should
923 test whether the condition is satisfied and if so return true. If it
924 is not satisfied then it should call
925 <function>cyg_selrecord()</function> with the
926 <parameter>info</parameter> argument that was passed to the function
927 and a pointer to a <structname>cyg_selinfo</structname> structure.
931 The <structname>cyg_selinfo</structname> structure is used to record information about current
932 select operations. Any object that needs to support select must
933 contain an instance of this structure. Separate <structname>cyg_selinfo</structname>
934 structures should be kept for each of the options that the object can
935 select on - read, write or exception.
939 If none of the file objects report that the select condition is
940 satisfied, then the <function>select()</function> API function puts
941 the calling thread to sleep waiting either for a condition to become
942 satisfied, or for the optional timeout to expire.
946 A selectable object must have some asynchronous activity that may
947 cause a select condition to become true - either via interrupts or the
948 activities of other threads. Whenever a selectable condition is
949 satisfied, the object should call <function>cyg_selwakeup()</function> with a pointer to
950 the appropriate <structname>cyg_selinfo</structname> structure. If the thread is still waiting,
951 this will cause it to wake up and repeat its poll of the file
952 descriptors. This time around, the object that caused the wakeup
953 should indicate that the select condition is satisfied, and the
954 <function>select()</function> API call will return.
958 Note that <function>select()</function> does not exhibit real time
959 behaviour: the iterative poll of the descriptors, and the wakeup
960 mechanism mitigate against this. If real time response to device or
961 socket I/O is required then separate threads should be devoted to each
962 device of interest and should use blocking calls to wait for a
963 condition to become ready.
971 <chapter id="fileio-devices">
972 <title>Devices</title>
975 Devices are accessed by means of a pseudo-filesystem, "devfs", that is
976 mounted on "/dev". Open operations are translated into calls to
977 <function>cyg_io_lookup()</function> and if successful result in a file object whose
978 <structfield>f_ops</structfield> functions translate filesystem API functions into calls into
985 <!-- {{{ Writing a New Filesystem -->
987 <chapter id="fileio-writing">
988 <title>Writing a New Filesystem</title>
991 To create a new filesystem it is necessary to define the fstab entry
992 and the file IO operations. The easiest way to do this is to copy an
993 existing filesystem: either the test filesystem in the FILEIO package,
994 or the RAM or ROM filesystem packages.
998 To make this clearer, the following is a brief tour of the FILEIO
999 relevant parts of the RAM filesystem.
1003 First, it is necessary to provide forward definitions of the functions
1004 that constitute the filesystem interface:
1007 <programlisting width=72>
1008 //==========================================================================
1009 // Forward definitions
1011 // Filesystem operations
1012 static int ramfs_mount ( cyg_fstab_entry *fste, cyg_mtab_entry *mte );
1013 static int ramfs_umount ( cyg_mtab_entry *mte );
1014 static int ramfs_open ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
1015 int mode, cyg_file *fte );
1016 static int ramfs_unlink ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
1017 static int ramfs_mkdir ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
1018 static int ramfs_rmdir ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
1019 static int ramfs_rename ( cyg_mtab_entry *mte, cyg_dir dir1, const char *name1,
1020 cyg_dir dir2, const char *name2 );
1021 static int ramfs_link ( cyg_mtab_entry *mte, cyg_dir dir1, const char *name1,
1022 cyg_dir dir2, const char *name2, int type );
1023 static int ramfs_opendir ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
1025 static int ramfs_chdir ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
1027 static int ramfs_stat ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
1029 static int ramfs_getinfo ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
1030 int key, void *buf, int len );
1031 static int ramfs_setinfo ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
1032 int key, void *buf, int len );
1035 static int ramfs_fo_read (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
1036 static int ramfs_fo_write (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
1037 static int ramfs_fo_lseek (struct CYG_FILE_TAG *fp, off_t *pos, int whence );
1038 static int ramfs_fo_ioctl (struct CYG_FILE_TAG *fp, CYG_ADDRWORD com,
1040 static int ramfs_fo_fsync (struct CYG_FILE_TAG *fp, int mode );
1041 static int ramfs_fo_close (struct CYG_FILE_TAG *fp);
1042 static int ramfs_fo_fstat (struct CYG_FILE_TAG *fp, struct stat *buf );
1043 static int ramfs_fo_getinfo (struct CYG_FILE_TAG *fp, int key, void *buf, int len );
1044 static int ramfs_fo_setinfo (struct CYG_FILE_TAG *fp, int key, void *buf, int len );
1046 // Directory operations
1047 static int ramfs_fo_dirread (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
1048 static int ramfs_fo_dirlseek (struct CYG_FILE_TAG *fp, off_t *pos, int whence );
1052 We define all of the fstab entries and all of the file IO
1053 operations. We also define alternatives for the
1054 <structfield>fo_read</structfield> and
1055 <structfield>fo_lseek</structfield> file IO operations.
1059 We can now define the filesystem table entry. There is a macro,
1060 <literal>FSTAB_ENTRY</literal> to do this:
1064 <programlisting width=72>
1065 //==========================================================================
1066 // Filesystem table entries
1068 // -------------------------------------------------------------------------
1070 // This defines the entry in the filesystem table.
1071 // For simplicity we use _FILESYSTEM synchronization for all accesses since
1072 // we should never block in any filesystem operations.
1074 FSTAB_ENTRY( ramfs_fste, "ramfs", 0,
1075 CYG_SYNCMODE_FILE_FILESYSTEM|CYG_SYNCMODE_IO_FILESYSTEM,
1092 The first argument to this macro gives the fstab entry a name, the
1093 remainder are initializers for the field of the structure.
1097 We must also define the file operations table that is installed in all
1098 open file table entries:
1101 <programlisting width=72>
1102 // -------------------------------------------------------------------------
1104 // This set of file operations are used for normal open files.
1106 static cyg_fileops ramfs_fileops =
1122 These all point to functions supplied by the filesystem except the
1123 <structfield>fo_select</structfield> field which is filled with a
1124 pointer to <function>cyg_fileio_seltrue()</function>. This is provided
1125 by the FILEIO package and is a select function that always returns
1126 true to all operations.
1130 Finally, we need to define a set of file operations for use when
1131 reading directories. This table only defines the
1132 <structfield>fo_read</structfield> and
1133 <structfield>fo_lseek</structfield> operations. The rest are filled
1134 with stub functions supplied by the FILEIO package that just return an
1138 <programlisting width=72>
1139 // -------------------------------------------------------------------------
1140 // Directory file operations.
1141 // This set of operations are used for open directories. Most entries
1142 // point to error-returning stub functions. Only the read, lseek and
1143 // close entries are functional.
1145 static cyg_fileops ramfs_dirops =
1148 (cyg_fileop_write *)cyg_fileio_enosys,
1150 (cyg_fileop_ioctl *)cyg_fileio_enosys,
1152 (cyg_fileop_fsync *)cyg_fileio_enosys,
1154 (cyg_fileop_fstat *)cyg_fileio_enosys,
1155 (cyg_fileop_getinfo *)cyg_fileio_enosys,
1156 (cyg_fileop_setinfo *)cyg_fileio_enosys
1161 If the filesystem wants to have an instance automatically mounted on
1162 system startup, it must also define a mount table entry. This is done
1163 with the <literal>MTAB_ENTRY</literal> macro. This is an example from
1164 the test filesystem of how this is used:
1167 <programlisting width=72>
1168 MTAB_ENTRY( testfs_mte1,
1176 The first argument provides a name for the table entry. The following
1177 arguments provide initialization for the
1178 <structfield>name</structfield>, <structfield>fsname</structfield>,
1179 <structfield>devname</structfield> and <structfield>data</structfield>
1180 fields respectively.
1184 These definitions are adequate to let the new filesystem interact
1185 with the FILEIO package. The new filesystem now needs to be fleshed
1186 out with implementations of the functions defined above. Obviously,
1187 the exact form this takes will depend on what the filesystem is
1188 intended to do. Take a look at the RAM and ROM filesystems for
1189 examples of how this has been done.