doc/html/ref/fileio-writing.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Writing a New Filesystem</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="File System Support Infrastructure"
  23 HREF="fileio.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Devices"
  26 HREF="fileio-devices.html"><LINK
  27 REL="NEXT"
  28 TITLE="PCI Library"
  29 HREF="io-pci.html"></HEAD
  30 ><BODY
  31 CLASS="CHAPTER"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="fileio-devices.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="io-pci.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="CHAPTER"
  82 ><H1
  83 ><A
  84 NAME="FILEIO-WRITING">Chapter 29. Writing a New Filesystem</H1
  85 ><P
  86 >To create a new filesystem it is necessary to define the fstab entry
  87 and the file IO operations. The easiest way to do this is to copy an
  88 existing filesystem: either the test filesystem in the FILEIO package,
  89 or the RAM or ROM filesystem packages.</P
  90 ><P
  91 >To make this clearer, the following is a brief tour of the FILEIO
  92 relevant parts of the RAM filesystem.</P
  93 ><P
  94 >First, it is necessary to provide forward definitions of the functions
  95 that constitute the filesystem interface:</P
  96 ><TABLE
  97 BORDER="5"
  98 BGCOLOR="#E0E0F0"
  99 WIDTH="70%"
 100 ><TR
 101 ><TD
 102 ><PRE
 103 CLASS="PROGRAMLISTING"
 104 >//==========================================================================
 105 // Forward definitions
 106
 107 // Filesystem operations
 108 static int ramfs_mount    ( cyg_fstab_entry *fste, cyg_mtab_entry *mte );
 109 static int ramfs_umount   ( cyg_mtab_entry *mte );
 110 static int ramfs_open     ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
 111                              int mode,  cyg_file *fte );
 112 static int ramfs_unlink   ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
 113 static int ramfs_mkdir    ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
 114 static int ramfs_rmdir    ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
 115 static int ramfs_rename   ( cyg_mtab_entry *mte, cyg_dir dir1, const char *name1,
 116                              cyg_dir dir2, const char *name2 );
 117 static int ramfs_link     ( cyg_mtab_entry *mte, cyg_dir dir1, const char *name1,
 118                              cyg_dir dir2, const char *name2, int type );
 119 static int ramfs_opendir  ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
 120                              cyg_file *fte );
 121 static int ramfs_chdir    ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
 122                              cyg_dir *dir_out );
 123 static int ramfs_stat     ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
 124                              struct stat *buf);
 125 static int ramfs_getinfo  ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
 126                              int key, void *buf, int len );
 127 static int ramfs_setinfo  ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
 128                              int key, void *buf, int len );
 129
 130 // File operations
 131 static int ramfs_fo_read      (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
 132 static int ramfs_fo_write     (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
 133 static int ramfs_fo_lseek     (struct CYG_FILE_TAG *fp, off_t *pos, int whence );
 134 static int ramfs_fo_ioctl     (struct CYG_FILE_TAG *fp, CYG_ADDRWORD com,
 135                                 CYG_ADDRWORD data);
 136 static int ramfs_fo_fsync     (struct CYG_FILE_TAG *fp, int mode );
 137 static int ramfs_fo_close     (struct CYG_FILE_TAG *fp);
 138 static int ramfs_fo_fstat     (struct CYG_FILE_TAG *fp, struct stat *buf );
 139 static int ramfs_fo_getinfo   (struct CYG_FILE_TAG *fp, int key, void *buf, int len );
 140 static int ramfs_fo_setinfo   (struct CYG_FILE_TAG *fp, int key, void *buf, int len );
 141
 142 // Directory operations
 143 static int ramfs_fo_dirread      (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
 144 static int ramfs_fo_dirlseek     (struct CYG_FILE_TAG *fp, off_t *pos, int whence );</PRE
 145 ></TD
 146 ></TR
 147 ></TABLE
 148 ><P
 149 >We define all of the fstab entries and all of the file IO
 150 operations. We also define alternatives for the
 151 <TT
 152 CLASS="STRUCTFIELD"
 153 ><I
 154 >fo_read</I
 155 ></TT
 156 > and
 157 <TT
 158 CLASS="STRUCTFIELD"
 159 ><I
 160 >fo_lseek</I
 161 ></TT
 162 > file IO operations.</P
 163 ><P
 164 >We can now define the filesystem table entry. There is a macro,
 165 <TT
 166 CLASS="LITERAL"
 167 >FSTAB_ENTRY</TT
 168 > to do this:</P
 169 ><TABLE
 170 BORDER="5"
 171 BGCOLOR="#E0E0F0"
 172 WIDTH="70%"
 173 ><TR
 174 ><TD
 175 ><PRE
 176 CLASS="PROGRAMLISTING"
 177 >//==========================================================================
 178 // Filesystem table entries
 179
 180 // -------------------------------------------------------------------------
 181 // Fstab entry.
 182 // This defines the entry in the filesystem table.
 183 // For simplicity we use _FILESYSTEM synchronization for all accesses since
 184 // we should never block in any filesystem operations.
 185
 186 FSTAB_ENTRY( ramfs_fste, "ramfs", 0,
 187              CYG_SYNCMODE_FILE_FILESYSTEM|CYG_SYNCMODE_IO_FILESYSTEM,
 188              ramfs_mount,
 189              ramfs_umount,
 190              ramfs_open,
 191              ramfs_unlink,
 192              ramfs_mkdir,
 193              ramfs_rmdir,
 194              ramfs_rename,
 195              ramfs_link,
 196              ramfs_opendir,
 197              ramfs_chdir,
 198              ramfs_stat,
 199              ramfs_getinfo,
 200              ramfs_setinfo);</PRE
 201 ></TD
 202 ></TR
 203 ></TABLE
 204 ><P
 205 >The first argument to this macro gives the fstab entry a name, the
 206 remainder are initializers for the field of the structure.</P
 207 ><P
 208 >We must also define the file operations table that is installed in all
 209 open file table entries:</P
 210 ><TABLE
 211 BORDER="5"
 212 BGCOLOR="#E0E0F0"
 213 WIDTH="70%"
 214 ><TR
 215 ><TD
 216 ><PRE
 217 CLASS="PROGRAMLISTING"
 218 >// -------------------------------------------------------------------------
 219 // File operations.
 220 // This set of file operations are used for normal open files.
 221
 222 static cyg_fileops ramfs_fileops =
 223 {
 224     ramfs_fo_read,
 225     ramfs_fo_write,
 226     ramfs_fo_lseek,
 227     ramfs_fo_ioctl,
 228     cyg_fileio_seltrue,
 229     ramfs_fo_fsync,
 230     ramfs_fo_close,
 231     ramfs_fo_fstat,
 232     ramfs_fo_getinfo,
 233     ramfs_fo_setinfo
 234 };</PRE
 235 ></TD
 236 ></TR
 237 ></TABLE
 238 ><P
 239 >These all point to functions supplied by the filesystem except the
 240 <TT
 241 CLASS="STRUCTFIELD"
 242 ><I
 243 >fo_select</I
 244 ></TT
 245 > field which is filled with a
 246 pointer to <TT
 247 CLASS="FUNCTION"
 248 >cyg_fileio_seltrue()</TT
 249 >. This is provided
 250 by the FILEIO package and is a select function that always returns
 251 true to all operations.</P
 252 ><P
 253 >Finally, we need to define a set of file operations for use when
 254 reading directories. This table only defines the
 255 <TT
 256 CLASS="STRUCTFIELD"
 257 ><I
 258 >fo_read</I
 259 ></TT
 260 > and
 261 <TT
 262 CLASS="STRUCTFIELD"
 263 ><I
 264 >fo_lseek</I
 265 ></TT
 266 > operations. The rest are filled
 267 with stub functions supplied by the FILEIO package that just return an
 268 error code.</P
 269 ><TABLE
 270 BORDER="5"
 271 BGCOLOR="#E0E0F0"
 272 WIDTH="70%"
 273 ><TR
 274 ><TD
 275 ><PRE
 276 CLASS="PROGRAMLISTING"
 277 >// -------------------------------------------------------------------------
 278 // Directory file operations.
 279 // This set of operations are used for open directories. Most entries
 280 // point to error-returning stub functions. Only the read, lseek and
 281 // close entries are functional.
 282
 283 static cyg_fileops ramfs_dirops =
 284 {
 285     ramfs_fo_dirread,
 286     (cyg_fileop_write *)cyg_fileio_enosys,
 287     ramfs_fo_dirlseek,
 288     (cyg_fileop_ioctl *)cyg_fileio_enosys,
 289     cyg_fileio_seltrue,
 290     (cyg_fileop_fsync *)cyg_fileio_enosys,
 291     ramfs_fo_close,
 292     (cyg_fileop_fstat *)cyg_fileio_enosys,
 293     (cyg_fileop_getinfo *)cyg_fileio_enosys,
 294     (cyg_fileop_setinfo *)cyg_fileio_enosys
 295 };</PRE
 296 ></TD
 297 ></TR
 298 ></TABLE
 299 ><P
 300 >If the filesystem wants to have an instance automatically mounted on
 301 system startup, it must also define a mount table entry. This is done
 302 with the <TT
 303 CLASS="LITERAL"
 304 >MTAB_ENTRY</TT
 305 > macro. This is an example from
 306 the test filesystem of how this is used:</P
 307 ><TABLE
 308 BORDER="5"
 309 BGCOLOR="#E0E0F0"
 310 WIDTH="70%"
 311 ><TR
 312 ><TD
 313 ><PRE
 314 CLASS="PROGRAMLISTING"
 315 >MTAB_ENTRY( testfs_mte1,
 316                    "/",
 317                    "testfs",
 318                    "",
 319                    0);</PRE
 320 ></TD
 321 ></TR
 322 ></TABLE
 323 ><P
 324 >The first argument provides a name for the table entry. The following
 325 arguments provide initialization for the
 326 <TT
 327 CLASS="STRUCTFIELD"
 328 ><I
 329 >name</I
 330 ></TT
 331 >, <TT
 332 CLASS="STRUCTFIELD"
 333 ><I
 334 >fsname</I
 335 ></TT
 336 >,
 337 <TT
 338 CLASS="STRUCTFIELD"
 339 ><I
 340 >devname</I
 341 ></TT
 342 > and <TT
 343 CLASS="STRUCTFIELD"
 344 ><I
 345 >data</I
 346 ></TT
 347 >
 348 fields respectively.</P
 349 ><P
 350 >These definitions are adequate to let the new filesystem interact
 351 with the FILEIO package. The new filesystem now needs to be fleshed
 352 out with implementations of the functions defined above. Obviously,
 353 the exact form this takes will depend on what the filesystem is
 354 intended to do. Take a look at the RAM and ROM filesystems for
 355 examples of how this has been done.</P
 356 ></DIV
 357 ><DIV
 358 CLASS="NAVFOOTER"
 359 ><HR
 360 ALIGN="LEFT"
 361 WIDTH="100%"><TABLE
 362 SUMMARY="Footer navigation table"
 363 WIDTH="100%"
 364 BORDER="0"
 365 CELLPADDING="0"
 366 CELLSPACING="0"
 367 ><TR
 368 ><TD
 369 WIDTH="33%"
 370 ALIGN="left"
 371 VALIGN="top"
 372 ><A
 373 HREF="fileio-devices.html"
 374 ACCESSKEY="P"
 375 >Prev</A
 376 ></TD
 377 ><TD
 378 WIDTH="34%"
 379 ALIGN="center"
 380 VALIGN="top"
 381 ><A
 382 HREF="ecos-ref.html"
 383 ACCESSKEY="H"
 384 >Home</A
 385 ></TD
 386 ><TD
 387 WIDTH="33%"
 388 ALIGN="right"
 389 VALIGN="top"
 390 ><A
 391 HREF="io-pci.html"
 392 ACCESSKEY="N"
 393 >Next</A
 394 ></TD
 395 ></TR
 396 ><TR
 397 ><TD
 398 WIDTH="33%"
 399 ALIGN="left"
 400 VALIGN="top"
 401 >Devices</TD
 402 ><TD
 403 WIDTH="34%"
 404 ALIGN="center"
 405 VALIGN="top"
 406 ><A
 407 HREF="fileio.html"
 408 ACCESSKEY="U"
 409 >Up</A
 410 ></TD
 411 ><TD
 412 WIDTH="33%"
 413 ALIGN="right"
 414 VALIGN="top"
 415 >PCI Library</TD
 416 ></TR
 417 ></TABLE
 418 ></DIV
 419 ></BODY
 420 ></HTML
 421 >