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. The <structname> struct
524 dirent</structname> object returned by <function>readdir()</function>
525 will always contain <structname>d_name</structname> as required by
526 POSIX. When <literal>CYGPKG_FILEIO_DIRENT_DTYPE</literal> is enabled
527 it will also contain <structname>d_type</structname>, which is not
528 part of POSIX, but often implemented by OSes. Currently only the
529 FATFS, RAMFS, ROMFS and JFFS2 filesystem sets this value. For other
530 filesystems a value of 0 will be returned in the member.</para>
533 Support for the <function>getcwd()</function> function is provided by
534 three mechanisms. The first is to use the
535 <literal>FS_INFO_GETCWD</literal> getinfo key on the filesystem to use
536 any internal support that it has for this. If that fails it falls back
537 on one of the two other mechanisms. If
538 <literal>CYGPKG_IO_FILEIO_TRACK_CWD</literal> is set then the current
539 directory is tracked textually in <function>chdir()</function> and the result of that is
540 reported in getcwd(). Otherwise an attempt is made to traverse the
541 directory tree to its root using ".." entries.
545 This last option is complicated and expensive, and relies on the
546 filesystem supporting "." and ".." entries. This is not always the
547 case, particularly if the filesystem has been ported from a
548 non-UNIX-compatible source. Tracking the pathname textually will
549 usually work, but might not produce optimum results when symbolic
550 links are being used.
556 <!-- {{{ Synchronization -->
558 <chapter id="fileio-synchronization">
559 <title>Synchronization</title>
562 The FILEIO infrastructure provides a synchronization mechanism for
563 controlling concurrent access to filesystems. This allows existing
564 filesystems to be ported to eCos, even if they do not have their own
565 synchronization mechanisms. It also allows new filesystems to be
566 implemented easily without having to consider the synchronization
571 The infrastructure maintains a mutex for each entry in each of
572 the main tables: filesystem table, mount table and file table. For
573 each class of operation each of these mutexes may be locked before the
574 corresponding filesystem operation is invoked.
578 The synchronization protocol required by a filesystem is described
579 by the <structfield>syncmode</structfield> field of the filesystem
580 table entry. This is a combination of the following flags:
585 <term><literal>CYG_SYNCMODE_FILE_FILESYSTEM</literal></term>
588 Lock the filesystem table entry mutex
589 during all filesystem level operations.
595 <term><literal>CYG_SYNCMODE_FILE_MOUNTPOINT</literal></term>
598 Lock the mount table entry mutex
599 during all filesystem level operations.
605 <term><literal>CYG_SYNCMODE_IO_FILE</literal></term>
608 Lock the file table entry mutex during all
615 <term><literal>CYG_SYNCMODE_IO_FILESYSTEM</literal></term>
618 Lock the filesystem table entry mutex during all I/O operations.
624 <term><literal>CYG_SYNCMODE_IO_MOUNTPOINT</literal></term>
626 Lock the mount table entry mutex during all I/O operations.
632 <term><literal>CYG_SYNCMODE_SOCK_FILE</literal></term>
635 Lock the file table entry mutex during all socket operations.
641 <term><literal>CYG_SYNCMODE_SOCK_NETSTACK</literal></term>
644 Lock the network stack table entry mutex during all socket operations.
650 <term><literal>CYG_SYNCMODE_NONE</literal></term>
653 Perform no locking at all during any operations.
661 The value of the <structfield>syncmode</structfield> field in the
662 filesystem table entry will be copied by the infrastructure to the
663 open file object after a successful <function>open()</function> operation.
669 <!-- {{{ Initialization and Mounting -->
671 <chapter id="fileio-mounting">
672 <title>Initialization and Mounting</title>
675 As mentioned previously, mount table entries can be sourced from two
676 places. Static entries may be defined by using the
677 <literal>MTAB_ENTRY()</literal> macro. Such entries will be
678 automatically mounted on system startup. For each entry in the mount
679 table that has a non-null <structfield>name</structfield> field the
680 filesystem table is searched for a match with the
681 <structfield>fsname</structfield> field. If a match is found the
682 filesystem's <structfield>mount</structfield> entry is called and if
683 successful the mount table entry marked valid and the
684 <structfield>fs</structfield> field initialized. The
685 <function>mount()</function> function is responsible for initializing
686 the <structfield>root</structfield> field.
691 The size of the mount table is defined by the configuration value
692 <literal>CYGNUM_FILEIO_MTAB_MAX</literal>. Any entries that have not
693 been statically defined are available for use by dynamic mounts.
697 A filesystem may be mounted dynamically by calling <function>mount()</function>. This
698 function has the following prototype:
701 <programlisting width=72>
702 int mount( const char *devname,
708 The <parameter>devname</parameter> argument identifies a device that
709 will be used by this filesystem and will be assigned to the
710 <structfield>devname</structfield> field of the mount table entry.
714 The <parameter>dir</parameter> argument is the mount point name, it
715 will be assigned to the <structfield>name</structfield> field of the
720 The <parameter>fsname</parameter> argument is the name of the
721 implementing filesystem, it will be assigned to the
722 <structfield>fsname</structfield> entry of the mount table entry.
726 The process of mounting a filesystem dynamically is as follows. First
727 a search is made of the mount table for an entry with a NULL
728 <structfield>name</structfield> field to be used for the new mount
729 point. The filesystem table is then searched for an entry whose name
730 matches <structfield>fsname</structfield>. If this is successful then
731 the mount table entry is initialized and the filesystem's
732 <function>mount()</function> operation called. If this is successful,
733 the mount table entry is marked valid and the
734 <structfield>fs</structfield> field initialized.
738 Unmounting a filesystem is done by the <function>umount()</function>
739 function. This can unmount filesystems whether they were mounted
740 statically or dynamically.
744 The <function>umount()</function> function has the following prototype:
747 <programlisting width=72>
748 int umount( const char *name );
752 The mount table is searched for a match between the
753 <parameter>name</parameter> argument and the entry
754 <structfield>name</structfield> field. When a match is found the
755 filesystem's <function>umount()</function> operation is called and if
756 successful, the mount table entry is invalidated by setting its
757 <structfield>valid</structfield> field false and the
758 <structfield>name</structfield> field to NULL.
771 <chapter id="fileio-sockets">
772 <title>Sockets</title>
775 If a network stack is present, then the FILEIO infrastructure also
776 provides access to the standard BSD socket calls.
780 The netstack table contains entries which describe the network
781 protocol stacks that are in the system image. Each resident stack
782 should export an entry to this table using the
783 <literal>NSTAB_ENTRY()</literal> macro.
787 Each table entry has the following structure:
790 <programlisting width=72>
791 struct cyg_nstab_entry
793 cyg_bool valid; // true if stack initialized
794 cyg_uint32 syncmode; // synchronization protocol
795 char *name; // stack name
796 char *devname; // hardware device name
797 CYG_ADDRWORD data; // private data value
799 int (*init)( cyg_nstab_entry *nste );
800 int (*socket)( cyg_nstab_entry *nste, int domain, int type,
801 int protocol, cyg_file *file );
806 This table is analogous to a combination of the filesystem and mount
811 The <structfield>valid</structfield> field is set
812 <literal>true</literal> if the stack's <function>init()</function>
813 function returned successfully and the
814 <structfield>syncmode</structfield> field contains the
815 <literal>CYG_SYNCMODE_SOCK_*</literal> bits described above.
824 The <structfield>name</structfield> field contains the name of the
834 The <structfield>devname</structfield> field names the device that the stack is using. This may
835 reference a device under "/dev", or may be a name that is only
836 meaningful to the stack itself.
845 The <function>init()</function> function pointer is called during
846 system initialization to start the protocol stack running. If it
847 returns non-zero the <structfield>valid</structfield> field is set
848 false and the stack will be ignored subsequently.
852 The <function>socket()</function> function is called to attempt to create a socket in the
853 stack. When the <function>socket()</function> API function is called the netstack table is
854 scanned and for each valid entry the <function>socket()</function>
855 function pointer is called. If
856 this returns non-zero then the scan continues to the next valid stack,
857 or terminates with an error if the end of the table is reached.
861 The result of a successful socket call is an initialized file object
862 with the <structfield>f_xops</structfield> field pointing to the
866 <programlisting width=72>
869 int (*bind) ( cyg_file *fp, const sockaddr *sa, socklen_t len );
870 int (*connect) ( cyg_file *fp, const sockaddr *sa, socklen_t len );
871 int (*accept) ( cyg_file *fp, cyg_file *new_fp,
872 struct sockaddr *name, socklen_t *anamelen );
873 int (*listen) ( cyg_file *fp, int len );
874 int (*getname) ( cyg_file *fp, sockaddr *sa, socklen_t *len, int peer );
875 int (*shutdown) ( cyg_file *fp, int flags );
876 int (*getsockopt)( cyg_file *fp, int level, int optname,
877 void *optval, socklen_t *optlen);
878 int (*setsockopt)( cyg_file *fp, int level, int optname,
879 const void *optval, socklen_t optlen);
880 int (*sendmsg) ( cyg_file *fp, const struct msghdr *m,
881 int flags, ssize_t *retsize );
882 int (*recvmsg) ( cyg_file *fp, struct msghdr *m,
883 socklen_t *namelen, ssize_t *retsize );
888 It should be obvious from the names of these functions which API calls
889 they provide support for. The <function>getname()</function> function
890 pointer provides support for both <function>getsockname()</function>
891 and <function>getpeername()</function> while the
892 <function>sendmsg()</function> and <function>recvmsg()</function>
893 function pointers provide support for <function>send()</function>,
894 <function>sendto()</function>, <function>sendmsg()</function>,
895 <function>recv()</function>, <function>recvfrom()</function> and
896 <function>recvmsg()</function> as appropriate.
904 <chapter id="fileio-select">
905 <title>Select</title>
908 The infrastructure provides support for implementing a select
909 mechanism. This is modeled on the mechanism in the BSD kernel, but has
910 been modified to make it implementation independent.
914 The main part of the mechanism is the <function>select()</function>
915 API call. This processes its arguments and calls the
916 <function>fo_select()</function> function pointer on all file objects
917 referenced by the file descriptor sets passed to it. If the same
918 descriptor appears in more than one descriptor set, the
919 <function>fo_select()</function> function will be called separately
924 The <parameter>which</parameter> argument of the
925 <function>fo_select()</function> function will either be
926 <literal>CYG_FREAD</literal> to test for read conditions,
927 <literal>CYG_FWRITE</literal> to test for write conditions or zero to
928 test for exceptions. For each of these options the function should
929 test whether the condition is satisfied and if so return true. If it
930 is not satisfied then it should call
931 <function>cyg_selrecord()</function> with the
932 <parameter>info</parameter> argument that was passed to the function
933 and a pointer to a <structname>cyg_selinfo</structname> structure.
937 The <structname>cyg_selinfo</structname> structure is used to record information about current
938 select operations. Any object that needs to support select must
939 contain an instance of this structure. Separate <structname>cyg_selinfo</structname>
940 structures should be kept for each of the options that the object can
941 select on - read, write or exception.
945 If none of the file objects report that the select condition is
946 satisfied, then the <function>select()</function> API function puts
947 the calling thread to sleep waiting either for a condition to become
948 satisfied, or for the optional timeout to expire.
952 A selectable object must have some asynchronous activity that may
953 cause a select condition to become true - either via interrupts or the
954 activities of other threads. Whenever a selectable condition is
955 satisfied, the object should call <function>cyg_selwakeup()</function> with a pointer to
956 the appropriate <structname>cyg_selinfo</structname> structure. If the thread is still waiting,
957 this will cause it to wake up and repeat its poll of the file
958 descriptors. This time around, the object that caused the wakeup
959 should indicate that the select condition is satisfied, and the
960 <function>select()</function> API call will return.
964 Note that <function>select()</function> does not exhibit real time
965 behaviour: the iterative poll of the descriptors, and the wakeup
966 mechanism mitigate against this. If real time response to device or
967 socket I/O is required then separate threads should be devoted to each
968 device of interest and should use blocking calls to wait for a
969 condition to become ready.
977 <chapter id="fileio-devices">
978 <title>Devices</title>
981 Devices are accessed by means of a pseudo-filesystem, "devfs", that is
982 mounted on "/dev". Open operations are translated into calls to
983 <function>cyg_io_lookup()</function> and if successful result in a file object whose
984 <structfield>f_ops</structfield> functions translate filesystem API functions into calls into
991 <!-- {{{ Writing a New Filesystem -->
993 <chapter id="fileio-writing">
994 <title>Writing a New Filesystem</title>
997 To create a new filesystem it is necessary to define the fstab entry
998 and the file IO operations. The easiest way to do this is to copy an
999 existing filesystem: either the test filesystem in the FILEIO package,
1000 or the RAM or ROM filesystem packages.
1004 To make this clearer, the following is a brief tour of the FILEIO
1005 relevant parts of the RAM filesystem.
1009 First, it is necessary to provide forward definitions of the functions
1010 that constitute the filesystem interface:
1013 <programlisting width=72>
1014 //==========================================================================
1015 // Forward definitions
1017 // Filesystem operations
1018 static int ramfs_mount ( cyg_fstab_entry *fste, cyg_mtab_entry *mte );
1019 static int ramfs_umount ( cyg_mtab_entry *mte );
1020 static int ramfs_open ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
1021 int mode, cyg_file *fte );
1022 static int ramfs_unlink ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
1023 static int ramfs_mkdir ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
1024 static int ramfs_rmdir ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
1025 static int ramfs_rename ( cyg_mtab_entry *mte, cyg_dir dir1, const char *name1,
1026 cyg_dir dir2, const char *name2 );
1027 static int ramfs_link ( cyg_mtab_entry *mte, cyg_dir dir1, const char *name1,
1028 cyg_dir dir2, const char *name2, int type );
1029 static int ramfs_opendir ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
1031 static int ramfs_chdir ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
1033 static int ramfs_stat ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
1035 static int ramfs_getinfo ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
1036 int key, void *buf, int len );
1037 static int ramfs_setinfo ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
1038 int key, void *buf, int len );
1041 static int ramfs_fo_read (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
1042 static int ramfs_fo_write (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
1043 static int ramfs_fo_lseek (struct CYG_FILE_TAG *fp, off_t *pos, int whence );
1044 static int ramfs_fo_ioctl (struct CYG_FILE_TAG *fp, CYG_ADDRWORD com,
1046 static int ramfs_fo_fsync (struct CYG_FILE_TAG *fp, int mode );
1047 static int ramfs_fo_close (struct CYG_FILE_TAG *fp);
1048 static int ramfs_fo_fstat (struct CYG_FILE_TAG *fp, struct stat *buf );
1049 static int ramfs_fo_getinfo (struct CYG_FILE_TAG *fp, int key, void *buf, int len );
1050 static int ramfs_fo_setinfo (struct CYG_FILE_TAG *fp, int key, void *buf, int len );
1052 // Directory operations
1053 static int ramfs_fo_dirread (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
1054 static int ramfs_fo_dirlseek (struct CYG_FILE_TAG *fp, off_t *pos, int whence );
1058 We define all of the fstab entries and all of the file IO
1059 operations. We also define alternatives for the
1060 <structfield>fo_read</structfield> and
1061 <structfield>fo_lseek</structfield> file IO operations.
1065 We can now define the filesystem table entry. There is a macro,
1066 <literal>FSTAB_ENTRY</literal> to do this:
1070 <programlisting width=72>
1071 //==========================================================================
1072 // Filesystem table entries
1074 // -------------------------------------------------------------------------
1076 // This defines the entry in the filesystem table.
1077 // For simplicity we use _FILESYSTEM synchronization for all accesses since
1078 // we should never block in any filesystem operations.
1080 FSTAB_ENTRY( ramfs_fste, "ramfs", 0,
1081 CYG_SYNCMODE_FILE_FILESYSTEM|CYG_SYNCMODE_IO_FILESYSTEM,
1098 The first argument to this macro gives the fstab entry a name, the
1099 remainder are initializers for the field of the structure.
1103 We must also define the file operations table that is installed in all
1104 open file table entries:
1107 <programlisting width=72>
1108 // -------------------------------------------------------------------------
1110 // This set of file operations are used for normal open files.
1112 static cyg_fileops ramfs_fileops =
1128 These all point to functions supplied by the filesystem except the
1129 <structfield>fo_select</structfield> field which is filled with a
1130 pointer to <function>cyg_fileio_seltrue()</function>. This is provided
1131 by the FILEIO package and is a select function that always returns
1132 true to all operations.
1136 Finally, we need to define a set of file operations for use when
1137 reading directories. This table only defines the
1138 <structfield>fo_read</structfield> and
1139 <structfield>fo_lseek</structfield> operations. The rest are filled
1140 with stub functions supplied by the FILEIO package that just return an
1144 <programlisting width=72>
1145 // -------------------------------------------------------------------------
1146 // Directory file operations.
1147 // This set of operations are used for open directories. Most entries
1148 // point to error-returning stub functions. Only the read, lseek and
1149 // close entries are functional.
1151 static cyg_fileops ramfs_dirops =
1154 (cyg_fileop_write *)cyg_fileio_enosys,
1156 (cyg_fileop_ioctl *)cyg_fileio_enosys,
1158 (cyg_fileop_fsync *)cyg_fileio_enosys,
1160 (cyg_fileop_fstat *)cyg_fileio_enosys,
1161 (cyg_fileop_getinfo *)cyg_fileio_enosys,
1162 (cyg_fileop_setinfo *)cyg_fileio_enosys
1167 If the filesystem wants to have an instance automatically mounted on
1168 system startup, it must also define a mount table entry. This is done
1169 with the <literal>MTAB_ENTRY</literal> macro. This is an example from
1170 the test filesystem of how this is used:
1173 <programlisting width=72>
1174 MTAB_ENTRY( testfs_mte1,
1182 The first argument provides a name for the table entry. The following
1183 arguments provide initialization for the
1184 <structfield>name</structfield>, <structfield>fsname</structfield>,
1185 <structfield>devname</structfield> and <structfield>data</structfield>
1186 fields respectively.
1190 These definitions are adequate to let the new filesystem interact
1191 with the FILEIO package. The new filesystem now needs to be fleshed
1192 out with implementations of the functions defined above. Obviously,
1193 the exact form this takes will depend on what the filesystem is
1194 intended to do. Take a look at the RAM and ROM filesystems for
1195 examples of how this has been done.