packages/io/fileio/v2_0/include/fileio.h

   1 #ifndef CYGONCE_FILEIO_H
   2 #define CYGONCE_FILEIO_H
   3 //=============================================================================
   4 //
   5 //      fileio.h
   6 //
   7 //      Fileio header
   8 //
   9 //=============================================================================
  10 //####ECOSGPLCOPYRIGHTBEGIN####
  11 // -------------------------------------------
  12 // This file is part of eCos, the Embedded Configurable Operating System.
  13 // Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.
  14 //
  15 // eCos is free software; you can redistribute it and/or modify it under
  16 // the terms of the GNU General Public License as published by the Free
  17 // Software Foundation; either version 2 or (at your option) any later version.
  18 //
  19 // eCos is distributed in the hope that it will be useful, but WITHOUT ANY
  20 // WARRANTY; without even the implied warranty of MERCHANTABILITY or
  21 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  22 // for more details.
  23 //
  24 // You should have received a copy of the GNU General Public License along
  25 // with eCos; if not, write to the Free Software Foundation, Inc.,
  26 // 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
  27 //
  28 // As a special exception, if other files instantiate templates or use macros
  29 // or inline functions from this file, or you compile this file and link it
  30 // with other works to produce a work based on this file, this file does not
  31 // by itself cause the resulting work to be covered by the GNU General Public
  32 // License. However the source code for this file must still be made available
  33 // in accordance with section (3) of the GNU General Public License.
  34 //
  35 // This exception does not invalidate any other reasons why a work based on
  36 // this file might be covered by the GNU General Public License.
  37 //
  38 // Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.
  39 // at http://sources.redhat.com/ecos/ecos-license/
  40 // -------------------------------------------
  41 //####ECOSGPLCOPYRIGHTEND####
  42 //=============================================================================
  43 //#####DESCRIPTIONBEGIN####
  44 //
  45 // Author(s):     nickg
  46 // Contributors:  nickg
  47 // Date:          2000-05-25
  48 // Purpose:       Fileio header
  49 // Description:   This header contains the external definitions of the general file
  50 //                IO subsystem for POSIX and EL/IX compatability.
  51 //
  52 // Usage:
  53 //              #include <fileio.h>
  54 //              ...
  55 //
  56 //
  57 //####DESCRIPTIONEND####
  58 //
  59 //=============================================================================
  60
  61 #include <pkgconf/hal.h>
  62 #include <pkgconf/io_fileio.h>
  63
  64 #include <cyg/infra/cyg_type.h>
  65 #include <cyg/hal/hal_tables.h>
  66 #ifdef CYGFUN_IO_FILEIO_SELECT
  67 #include <cyg/kernel/kapi.h>
  68 #endif
  69
  70 #include <stddef.h>             // NULL, size_t
  71 #include <limits.h>
  72 #include <sys/types.h>
  73 #include <fcntl.h>
  74 #include <sys/stat.h>
  75
  76 //=============================================================================
  77 // forward definitions
  78
  79 struct cyg_mtab_entry;
  80 typedef struct cyg_mtab_entry cyg_mtab_entry;
  81
  82 struct  cyg_fstab_entry;
  83 typedef struct  cyg_fstab_entry  cyg_fstab_entry;
  84
  85 struct CYG_FILEOPS_TAG;
  86 typedef struct CYG_FILEOPS_TAG cyg_fileops;
  87
  88 struct CYG_FILE_TAG;
  89 typedef struct CYG_FILE_TAG cyg_file;
  90
  91 struct CYG_IOVEC_TAG;
  92 typedef struct CYG_IOVEC_TAG cyg_iovec;
  93
  94 struct CYG_UIO_TAG;
  95 typedef struct CYG_UIO_TAG cyg_uio;
  96
  97 struct CYG_SELINFO_TAG;
  98 typedef struct CYG_SELINFO_TAG cyg_selinfo;
  99
 100 //=============================================================================
 101 // Directory pointer
 102
 103 typedef CYG_ADDRWORD cyg_dir;
 104
 105 #define CYG_DIR_NULL 0
 106
 107 //=============================================================================
 108 // Filesystem table entry
 109
 110 typedef int     cyg_fsop_mount    ( cyg_fstab_entry *fste, cyg_mtab_entry *mte );
 111 typedef int     cyg_fsop_umount   ( cyg_mtab_entry *mte );
 112 typedef int     cyg_fsop_open     ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
 113                                     int mode,  cyg_file *fte );
 114 typedef int     cyg_fsop_unlink   ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
 115 typedef int     cyg_fsop_mkdir    ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
 116 typedef int     cyg_fsop_rmdir    ( cyg_mtab_entry *mte, cyg_dir dir, const char *name );
 117 typedef int     cyg_fsop_rename   ( cyg_mtab_entry *mte, cyg_dir dir1, const char *name1,
 118                                     cyg_dir dir2, const char *name2 );
 119 typedef int     cyg_fsop_link     ( cyg_mtab_entry *mte, cyg_dir dir1, const char *name1,
 120                                     cyg_dir dir2, const char *name2, int type );
 121 typedef int     cyg_fsop_opendir  ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
 122                                     cyg_file *fte );
 123 typedef int     cyg_fsop_chdir    ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
 124                                     cyg_dir *dir_out );
 125 typedef int     cyg_fsop_stat     ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
 126                                     struct stat *buf);
 127 typedef int     cyg_fsop_getinfo  ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
 128                                     int key, void *buf, int len );
 129 typedef int     cyg_fsop_setinfo  ( cyg_mtab_entry *mte, cyg_dir dir, const char *name,
 130                                     int key, void *buf, int len );
 131
 132
 133 struct cyg_fstab_entry
 134 {
 135     const char          *name;          // filesystem name
 136     CYG_ADDRWORD        data;           // private data value
 137     cyg_uint32          syncmode;       // synchronization mode
 138
 139     cyg_fsop_mount      *mount;
 140     cyg_fsop_umount     *umount;
 141     cyg_fsop_open       *open;
 142     cyg_fsop_unlink     *unlink;
 143     cyg_fsop_mkdir      *mkdir;
 144     cyg_fsop_rmdir      *rmdir;
 145     cyg_fsop_rename     *rename;
 146     cyg_fsop_link       *link;
 147     cyg_fsop_opendir    *opendir;
 148     cyg_fsop_chdir      *chdir;
 149     cyg_fsop_stat       *stat;
 150     cyg_fsop_getinfo    *getinfo;
 151     cyg_fsop_setinfo    *setinfo;
 152 } CYG_HAL_TABLE_TYPE;
 153
 154 //-----------------------------------------------------------------------------
 155 // Keys for getinfo() and setinfo()
 156
 157 #define FS_INFO_CONF            1       /* pathconf() */
 158 #define FS_INFO_ACCESS          2       /* access() */
 159 #define FS_INFO_GETCWD          3       /* getcwd() */
 160 #define FS_INFO_SYNC            4       /* cyg_fs_fssync() */
 161 #define FS_INFO_ATTRIB          5       /* cyg_fs_(get|set)_attrib() */
 162 #ifdef  CYGSEM_FILEIO_INFO_DISK_USAGE
 163 #define FS_INFO_DISK_USAGE      6       /* get_disk_usage()    */
 164 #endif
 165 //-----------------------------------------------------------------------------
 166 // Types for link()
 167
 168 #define CYG_FSLINK_HARD         1       /* form a hard link */
 169 #define CYG_FSLINK_SOFT         2       /* form a soft link */
 170
 171 //-----------------------------------------------------------------------------
 172 // getinfo() and setinfo() buffers structures.
 173
 174 struct cyg_getcwd_info
 175 {
 176     char        *buf;           /* buffer for cwd string */
 177     size_t      size;           /* size of buffer */
 178 };
 179
 180 struct cyg_fs_disk_usage{
 181   cyg_uint64 total_blocks;
 182   cyg_uint64 free_blocks;
 183   cyg_uint32 block_size;
 184 };
 185
 186 typedef cyg_uint32 cyg_fs_attrib_t;
 187
 188 //-----------------------------------------------------------------------------
 189 // Macro to define an initialized fstab entry
 190
 191 #define FSTAB_ENTRY( _l, _name, _data, _syncmode, _mount, _umount,      \
 192                      _open, _unlink,  _mkdir, _rmdir, _rename, _link,   \
 193                      _opendir, _chdir, _stat, _getinfo, _setinfo)       \
 194 struct cyg_fstab_entry _l CYG_HAL_TABLE_ENTRY(fstab) =                  \
 195 {                                                                       \
 196     _name,                                                              \
 197     _data,                                                              \
 198     _syncmode,                                                          \
 199     _mount,                                                             \
 200     _umount,                                                            \
 201     _open,                                                              \
 202     _unlink,                                                            \
 203     _mkdir,                                                             \
 204     _rmdir,                                                             \
 205     _rename,                                                            \
 206     _link,                                                              \
 207     _opendir,                                                           \
 208     _chdir,                                                             \
 209     _stat,                                                              \
 210     _getinfo,                                                           \
 211     _setinfo                                                            \
 212 };
 213
 214 //=============================================================================
 215 // Mount table entry
 216
 217 struct cyg_mtab_entry
 218 {
 219     const char          *name;          // name of mount point
 220     const char          *fsname;        // name of implementing filesystem
 221     const char          *devname;       // name of hardware device
 222     CYG_ADDRWORD        data;           // private data value
 223
 224     // The following are filled in after a successful mount operation
 225     cyg_bool            valid;          // Valid entry?
 226     cyg_fstab_entry     *fs;            // pointer to fstab entry
 227     cyg_dir             root;           // root directory pointer
 228 } CYG_HAL_TABLE_TYPE;
 229
 230
 231 // This macro defines an initialized mtab entry
 232
 233 #define MTAB_ENTRY( _l, _name, _fsname, _devname, _data )       \
 234 struct cyg_mtab_entry _l CYG_HAL_TABLE_ENTRY(mtab) =            \
 235 {                                                               \
 236     _name,                                                      \
 237     _fsname,                                                    \
 238     _devname,                                                   \
 239     _data,                                                      \
 240     false,                                                      \
 241     NULL,                                                       \
 242     CYG_DIR_NULL                                                \
 243 };
 244
 245 //=============================================================================
 246 // IO vector descriptors
 247
 248 struct CYG_IOVEC_TAG
 249 {
 250     void           *iov_base;           /* Base address. */
 251     ssize_t        iov_len;             /* Length. */
 252 };
 253
 254 enum    cyg_uio_rw { UIO_READ, UIO_WRITE };
 255
 256 /* Segment flag values. */
 257 enum cyg_uio_seg
 258 {
 259     UIO_USERSPACE,                      /* from user data space */
 260     UIO_SYSSPACE                        /* from system space */
 261 };
 262
 263 struct CYG_UIO_TAG
 264 {
 265     struct CYG_IOVEC_TAG *uio_iov;      /* pointer to array of iovecs */
 266     int                  uio_iovcnt;    /* number of iovecs in array */
 267     off_t                uio_offset;    /* offset into file this uio corresponds to */
 268     ssize_t              uio_resid;     /* residual i/o count */
 269     enum cyg_uio_seg     uio_segflg;    /* see above */
 270     enum cyg_uio_rw      uio_rw;        /* see above */
 271 };
 272
 273 // Limits
 274 #define UIO_SMALLIOV    8               /* 8 on stack, else malloc */
 275
 276 //=============================================================================
 277 // Description of open file
 278
 279 typedef int cyg_fileop_readwrite (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
 280 typedef cyg_fileop_readwrite cyg_fileop_read;
 281 typedef cyg_fileop_readwrite cyg_fileop_write;
 282 typedef int cyg_fileop_lseek   (struct CYG_FILE_TAG *fp, off_t *pos, int whence );
 283 typedef int cyg_fileop_ioctl   (struct CYG_FILE_TAG *fp, CYG_ADDRWORD com,
 284                                 CYG_ADDRWORD data);
 285 typedef cyg_bool cyg_fileop_select  (struct CYG_FILE_TAG *fp, int which, CYG_ADDRWORD info);
 286 typedef int cyg_fileop_fsync   (struct CYG_FILE_TAG *fp, int mode );
 287 typedef int cyg_fileop_close   (struct CYG_FILE_TAG *fp);
 288 typedef int cyg_fileop_fstat   (struct CYG_FILE_TAG *fp, struct stat *buf );
 289 typedef int cyg_fileop_getinfo (struct CYG_FILE_TAG *fp, int key, void *buf, int len );
 290 typedef int cyg_fileop_setinfo (struct CYG_FILE_TAG *fp, int key, void *buf, int len );
 291
 292 struct CYG_FILEOPS_TAG
 293 {
 294     cyg_fileop_read     *fo_read;
 295     cyg_fileop_write    *fo_write;
 296     cyg_fileop_lseek    *fo_lseek;
 297     cyg_fileop_ioctl    *fo_ioctl;
 298     cyg_fileop_select   *fo_select;
 299     cyg_fileop_fsync    *fo_fsync;
 300     cyg_fileop_close    *fo_close;
 301     cyg_fileop_fstat    *fo_fstat;
 302     cyg_fileop_getinfo  *fo_getinfo;
 303     cyg_fileop_setinfo  *fo_setinfo;
 304 };
 305
 306 struct CYG_FILE_TAG
 307 {
 308     cyg_uint32                  f_flag;         /* file state                   */
 309     cyg_uint16                  f_ucount;       /* use count                    */
 310     cyg_uint16                  f_type;         /* descriptor type              */
 311     cyg_uint32                  f_syncmode;     /* synchronization protocol     */
 312     struct CYG_FILEOPS_TAG      *f_ops;         /* file operations              */
 313     off_t                       f_offset;       /* current offset               */
 314     CYG_ADDRWORD                f_data;         /* file or socket               */
 315     CYG_ADDRWORD                f_xops;         /* extra type specific ops      */
 316     cyg_mtab_entry              *f_mte;         /* mount table entry            */
 317 };
 318
 319 //-----------------------------------------------------------------------------
 320 // File flags
 321
 322 // Allocation here is that bits 0..15 are copies of bits from the open
 323 // flags, bits 16..23 are extra bits that are visible to filesystems but
 324 // are not derived from the open call, and bits 24..31 are reserved for
 325 // the fileio infrastructure.
 326 #define CYG_FREAD       O_RDONLY
 327 #define CYG_FWRITE      O_WRONLY
 328 #define CYG_FNONBLOCK   O_NONBLOCK
 329 #define CYG_FAPPEND     O_APPEND
 330 #define CYG_FASYNC      0x00010000
 331 #define CYG_FDIR        0x00020000
 332
 333 #define CYG_FLOCKED     0x01000000  // Set if file is locked
 334 #define CYG_FLOCK       0x02000000  // Lock during file ops
 335 #define CYG_FALLOC      0x80000000  // File is "busy", i.e. allocated
 336
 337 // Mask for open mode bits stored in file object
 338 #define CYG_FILE_MODE_MASK (CYG_FREAD|CYG_FWRITE|CYG_FNONBLOCK|CYG_FAPPEND)
 339
 340 //-----------------------------------------------------------------------------
 341 // Type of file
 342
 343 #define CYG_FILE_TYPE_FILE      1       /* file */
 344 #define CYG_FILE_TYPE_SOCKET    2       /* communications endpoint */
 345 #define CYG_FILE_TYPE_DEVICE    3       /* device */
 346
 347 //-----------------------------------------------------------------------------
 348 // Keys for getinfo() and setinfo()
 349
 350 #define FILE_INFO_CONF          1       /* fpathconf() */
 351
 352 //-----------------------------------------------------------------------------
 353 // Modes for fsync()
 354
 355 #define CYG_FSYNC              1
 356 #define CYG_FDATASYNC          2
 357
 358 //-----------------------------------------------------------------------------
 359 // Get/set info buffer structures
 360
 361 // This is used for pathconf() and fpathconf()
 362 struct cyg_pathconf_info
 363 {
 364     int         name;           // POSIX defined variable name
 365     long        value;          // Returned variable value
 366 };
 367
 368 //=============================================================================
 369 // Synchronization modes
 370 // These values are filled into the syncmode fields of the above structures
 371 // and define the synchronization protocol used when accessing the object in
 372 // question.
 373
 374 #define CYG_SYNCMODE_NONE               (0)     // no locking required
 375
 376 #define CYG_SYNCMODE_FILE_FILESYSTEM    0x0002  // lock fs during file ops
 377 #define CYG_SYNCMODE_FILE_MOUNTPOINT    0x0004  // lock mte during file ops
 378 #define CYG_SYNCMODE_IO_FILE            0x0010  // lock file during io ops
 379 #define CYG_SYNCMODE_IO_FILESYSTEM      0x0020  // lock fs during io ops
 380 #define CYG_SYNCMODE_IO_MOUNTPOINT      0x0040  // lock mte during io ops
 381 #define CYG_SYNCMODE_SOCK_FILE          0x0100  // lock socket during socket ops
 382 #define CYG_SYNCMODE_SOCK_NETSTACK      0x0800  // lock netstack during socket ops
 383
 384 #define CYG_SYNCMODE_IO_SHIFT           (4)     // shift for IO to file bits
 385 #define CYG_SYNCMODE_SOCK_SHIFT         (8)     // shift for sock to file bits
 386
 387 //=============================================================================
 388 // Mount and umount functions
 389
 390 __externC int mount( const char *devname,
 391                      const char *dir,
 392                      const char *fsname);
 393
 394 __externC int umount( const char *name);
 395
 396 //=============================================================================
 397 // Get/Set info functions
 398
 399 __externC int cyg_fs_getinfo( const char *path, int key, void *buf, int len );
 400 __externC int cyg_fs_setinfo( const char *path, int key, void *buf, int len );
 401 __externC int cyg_fs_fgetinfo( int fd, int key, void *buf, int len );
 402 __externC int cyg_fs_fsetinfo( int fd, int key, void *buf, int len );
 403
 404 #ifdef CYGFUN_IO_FILEIO_SELECT
 405 //=============================================================================
 406 // Select support
 407
 408 //-----------------------------------------------------------------------------
 409 // Data structure for embedding in client data structures. A pointer to this
 410 // must be passed to cyg_selrecord() and cyg_selwakeup().
 411
 412 struct CYG_SELINFO_TAG
 413 {
 414     CYG_ADDRWORD        si_info;        // info passed through from fo_select()
 415     cyg_flag_value_t    si_waitFlag;    // select wait flags
 416 };
 417
 418 //-----------------------------------------------------------------------------
 419 // Select support functions.
 420
 421 // cyg_selinit() is used to initialize a selinfo structure.
 422 __externC void cyg_selinit( struct CYG_SELINFO_TAG *sip );
 423
 424 // cyg_selrecord() is called when a client device needs to register
 425 // the current thread for selection.
 426 __externC void cyg_selrecord( CYG_ADDRWORD info, struct CYG_SELINFO_TAG *sip );
 427
 428 // cyg_selwakeup() is called when the client device matches the select
 429 // criterion, and needs to wake up a selector.
 430 __externC void cyg_selwakeup( struct CYG_SELINFO_TAG *sip );
 431 #endif
 432 //=============================================================================
 433 // Timestamp support
 434
 435 // Provides the current time as a time_t timestamp for use in filesystem
 436 // data strucures.
 437
 438 __externC time_t cyg_timestamp(void);
 439
 440 //=============================================================================
 441 // Miscellaneous functions.
 442
 443 // Provide a function to synchronize an individual file system. (ie write
 444 // file and directory information to disk)
 445 __externC int cyg_fs_fssync(const char *path);
 446
 447 // Functions to set and get attributes of a file, eg FAT attributes
 448 // like hidden and system.
 449 __externC int cyg_fs_set_attrib( const char *fname,
 450                                  const cyg_fs_attrib_t new_attrib );
 451 __externC int cyg_fs_get_attrib( const char *fname,
 452                                  cyg_fs_attrib_t * const file_attrib );
 453
 454 // Functions to lock and unlock a filesystem. These are normally used
 455 // internally by the fileio layer, but the file system might need to
 456 // use them when it needs to lock itself, eg when performing garbage
 457 // collect.
 458 __externC void cyg_fs_lock( cyg_mtab_entry *mte, cyg_uint32 syncmode );
 459
 460 __externC void cyg_fs_unlock( cyg_mtab_entry *mte, cyg_uint32 syncmode );
 461
 462 // To be able to lock the filesystem you need the mte. This function
 463 // allows the table of mounted filesystems to be searched to find an
 464 // mte which uses the give filesystem root.
 465
 466 __externC cyg_mtab_entry * cyg_fs_root_lookup( cyg_dir *root );
 467
 468 //=============================================================================
 469 // Default functions.
 470 // Cast to the appropriate type, these functions can be put into any of
 471 // the operation table slots to provide the defined error code.
 472
 473 __externC int cyg_fileio_enosys(void);
 474 __externC int cyg_fileio_erofs(void);
 475 __externC int cyg_fileio_enoerr(void);
 476 __externC int cyg_fileio_enotdir(void);
 477 __externC cyg_fileop_select cyg_fileio_seltrue;
 478
 479 //-----------------------------------------------------------------------------
 480 #endif // ifndef CYGONCE_FILEIO_H
 481 // End of fileio.h