StdLibPrivateInternalFiles/Include/kfile.h

   1 /** @file
   2   The EFI kernel's interpretation of a "file".
   3
   4   Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials are licensed and made available
   6   under the terms and conditions of the BSD License which accompanies this
   7   distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php.
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13  * Copyright (c) 1982, 1986, 1989, 1993
  14  *  The Regents of the University of California.  All rights reserved.
  15  *
  16  * Redistribution and use in source and binary forms, with or without
  17  * modification, are permitted provided that the following conditions
  18  * are met:
  19  * 1. Redistributions of source code must retain the above copyright
  20  *    notice, this list of conditions and the following disclaimer.
  21  * 2. Redistributions in binary form must reproduce the above copyright
  22  *    notice, this list of conditions and the following disclaimer in the
  23  *    documentation and/or other materials provided with the distribution.
  24  * 3. Neither the name of the University nor the names of its contributors
  25  *    may be used to endorse or promote products derived from this software
  26  *    without specific prior written permission.
  27  *
  28  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  29  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  30  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  31  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  32  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  33  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  34  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  36  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  37  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  38  * SUCH DAMAGE.
  39  *
  40  *  file.h  8.3 (Berkeley) 1/9/95
  41     NetBSD: file.h,v 1.56 2006/05/14 21:38:18 elad Exp
  42 **/
  43 #ifndef _PIF_KFILE_H_
  44 #define _PIF_KFILE_H_
  45
  46 #include  <Uefi.h>
  47 #include  <Protocol/SimpleTextOut.h>
  48 #include  <Protocol/SimpleFileSystem.h>
  49
  50 #include  <wchar.h>
  51 #include  <sys/fcntl.h>
  52 #include  <sys/unistd.h>
  53
  54 struct stat;
  55 struct fileops;
  56 struct _Device_Node;
  57
  58 /* The number of "special" character stream devices.
  59    These include:
  60     stdin, stdout, stderr
  61 */
  62 #define NUM_SPECIAL   3
  63
  64 /* Organization of the f_iflags member of the __filedes structure. */
  65 #define DTYPE_MASK      0x00000007    ///< Device Type
  66 #define DTYPE_VNODE             1     /* file */
  67 #define DTYPE_SOCKET            2     /* communications endpoint */
  68 #define DTYPE_PIPE              3     /* pipe */
  69 #define DTYPE_KQUEUE            4     /* event queue */
  70 #define DTYPE_MISC              5     /* misc file descriptor type */
  71 #define DTYPE_CRYPTO            6     /* crypto */
  72 #define DTYPE_NAMES   "0", "file", "socket", "pipe", "kqueue", "misc", "crypto"
  73
  74 #define FIF_WANTCLOSE   0x10000000  /* a close is waiting for usecount */
  75 #define FIF_DELCLOSE    0x20000000  /* Delete on close. */
  76 #define FIF_LARVAL      0x80000000  /* not fully constructed; don't use */
  77
  78 /*
  79     This structure must be a multiple of 8 bytes in length.
  80 */
  81 struct __filedes {
  82   const struct fileops   *f_ops;
  83   void                   *devdata;      /* Device-specific data */
  84   off_t                   f_offset;     /* current position in file */
  85   UINT32                  f_flag;       /* see fcntl.h */
  86   UINT32                  f_iflags;     // In use if non-zero
  87   int                     Oflags;       // From the open call
  88   int                     Omode;        // From the open call
  89   int                     RefCount;     // Reference count of opens
  90   UINT16                  MyFD;         // Which FD this is.
  91   UINT16                  Reserved_1;   // Force this structure to be a multiple of 8-bytes in length
  92 };
  93
  94 struct fileops {
  95   /* These functions must always be implemented. */
  96   int     (EFIAPI *fo_close)    (struct __filedes *filp);
  97   ssize_t (EFIAPI *fo_read)     (struct __filedes *filp, off_t *Offset, size_t Len, void *Buf);
  98   ssize_t (EFIAPI *fo_write)    (struct __filedes *filp, off_t *Offset, size_t Len, const void *Buf);
  99
 100   /* Call the fnullop_* version of these functions if not implemented by the device. */
 101   int     (EFIAPI *fo_fcntl)    (struct __filedes *filp, UINT32 Cmd, void *p3, void *p4);
 102   short   (EFIAPI *fo_poll)     (struct __filedes *filp, short Events);
 103   int     (EFIAPI *fo_flush)    (struct __filedes *filp);
 104
 105   /* Call the fbadop_* version of these functions if not implemented by the device. */
 106   int     (EFIAPI *fo_stat)     (struct __filedes *filp, struct stat *StatBuf, void *Buf);
 107   int     (EFIAPI *fo_ioctl)    (struct __filedes *filp, ULONGN Cmd, void *argp);
 108   int     (EFIAPI *fo_delete)   (struct __filedes *filp);
 109   int     (EFIAPI *fo_rmdir)    (struct __filedes *filp);
 110   int     (EFIAPI *fo_mkdir)    (const char *path, __mode_t perms);
 111   int     (EFIAPI *fo_rename)   (const char *from, const char *to);
 112
 113   /* Use a NULL if this function has not been implemented by the device. */
 114   off_t   (EFIAPI *fo_lseek)    (struct __filedes *filp, off_t, int);
 115 };
 116
 117 /*  A generic instance structure which is valid for
 118     for all device instance structures.
 119
 120     All device instance structures MUST be a multiple of 8-bytes in length.
 121 */
 122 typedef struct {
 123   UINT32                      Cookie;       ///< Special value identifying this as a valid Instance
 124   UINT32                      InstanceNum;  ///< Which instance is this?  Zero-based.
 125   EFI_HANDLE                  Dev;          ///< Pointer to either Input or Output Protocol.
 126   struct _Device_Node        *Parent;       ///< Points to the parent Device Node.
 127   struct fileops              Abstraction;  ///< Pointers to functions implementing this device's abstraction.
 128   UINTN                       Reserved_1;   // Force this to always be a multiple of 8-bytes in length
 129 } GenericInstance;
 130
 131 /* Type of all Device-specific handler's open routines. */
 132 typedef
 133   int     (EFIAPI *FO_OPEN)    (struct __filedes *FD, void *IP, wchar_t *Path, wchar_t *Flags);
 134
 135 #define FILE_IS_USABLE(fp)  (((fp)->f_iflags &      \
 136           (FIF_WANTCLOSE|FIF_LARVAL)) == 0)
 137
 138 #define FILE_SET_MATURE(fp)       \
 139 do {                              \
 140   (fp)->f_iflags &= ~FIF_LARVAL;  \
 141 } while (/*CONSTCOND*/0)
 142
 143 /*
 144  * Flags for fo_read and fo_write.
 145  */
 146 #define FOF_UPDATE_OFFSET 0x01      /* update the file offset */
 147
 148 __BEGIN_DECLS
 149
 150 int   fdcreate    (CHAR16 *, UINT32, UINT32, BOOLEAN, VOID *, const struct fileops *);
 151
 152 /* Commonly used fileops
 153       fnullop_*   Does nothing and returns success.
 154       fbadop_*    Does nothing and returns EPERM
 155 */
 156 int     fnullop_fcntl (struct __filedes *filp, UINT32 Cmd, void *p3, void *p4);
 157 short   fnullop_poll  (struct __filedes *filp, short Events);
 158 int     fnullop_flush (struct __filedes *filp);
 159
 160 int     fbadop_stat   (struct __filedes *filp, struct stat *StatBuf, void *Buf);
 161 int     fbadop_ioctl  (struct __filedes *filp, ULONGN Cmd, void *argp);
 162 int     fbadop_delete (struct __filedes *filp);
 163 int     fbadop_rmdir  (struct __filedes *filp);
 164 int     fbadop_mkdir  (const char *path, __mode_t perms);
 165 int     fbadop_rename (const char *from, const char *to);
 166
 167 __END_DECLS
 168
 169 /* From the original file... */
 170 #if 0
 171
 172 //struct proc;
 173 //struct lwp;
 174 //struct uio;
 175 //struct iovec;
 176 //struct knote;
 177
 178 //LIST_HEAD(filelist, file);
 179 //extern struct filelist  filehead;   /* head of list of open files */
 180 //extern int              maxfiles;   /* kernel limit on # of open files */
 181 //extern int              nfiles;     /* actual number of open files */
 182
 183 //extern const struct fileops vnops;  /* vnode operations for files */
 184
 185 struct fileops {
 186   int (*fo_read)      (struct file *, off_t *, struct uio *, kauth_cred_t, int);
 187   int (*fo_write)     (struct file *, off_t *, struct uio *, kauth_cred_t, int);
 188   int (*fo_ioctl)     (struct file *, u_long, void *, struct lwp *);
 189   int (*fo_fcntl)     (struct file *, u_int, void *, struct lwp *);
 190   int (*fo_poll)      (struct file *, int, struct lwp *);
 191   int (*fo_stat)      (struct file *, struct stat *, struct lwp *);
 192   int (*fo_close)     (struct file *, struct lwp *);
 193 };
 194
 195 /*
 196  * Kernel descriptor table.
 197  * One entry for each open kernel vnode and socket.
 198  */
 199 struct file {
 200   LIST_ENTRY(file)        f_list;     /* list of active files */
 201   void                   *f_data;     /* descriptor data, e.g. vnode/socket */
 202   const struct fileops   *f_ops;
 203   void                   *f_DevDesc;  /* Device Descriptor pointer */
 204   EFI_FILE_HANDLE         FileHandle;
 205   EFI_HANDLE              Handle;
 206   off_t                   f_offset;   /* current position in file */
 207   int                     f_flag;     /* see fcntl.h */
 208   UINT32                  f_iflags;   /* internal flags; FIF_* */
 209   int                     f_advice;   /* access pattern hint; UVM_ADV_* */
 210   int                     f_type;     /* descriptor type */
 211   int                     f_usecount; /* number active users */
 212   u_int                   f_count;    /* reference count */
 213   u_int                   f_msgcount; /* references from message queue */
 214 //  kauth_cred_t            f_cred;     /* creds associated with descriptor */
 215   struct simplelock       f_slock;
 216   UINT16                  MyFD;       /* Which FD this is. */
 217 };
 218
 219 #ifdef DIAGNOSTIC
 220 #define FILE_USE_CHECK(fp, str)   \
 221   do {                              \
 222   if ((fp)->f_usecount < 0)       \
 223     panic(str);                   \
 224 } while (/* CONSTCOND */ 0)
 225 #else
 226 #define FILE_USE_CHECK(fp, str)   /* nothing */
 227 #endif
 228
 229   /*
 230    * FILE_USE() must be called with the file lock held.
 231    * (Typical usage is: `fp = fd_getfile(..); FILE_USE(fp);'
 232    * and fd_getfile() returns the file locked)
 233    *
 234    * fp is a pointer to a __filedes structure.
 235    */
 236 #define FILE_USE(fp)                                \
 237     do {                                                \
 238     (fp)->f_usecount++;                               \
 239     FILE_USE_CHECK((fp), "f_usecount overflow");      \
 240     simple_unlock(&(fp)->f_slock);                    \
 241   } while (/* CONSTCOND */ 0)
 242
 243 #define FILE_UNUSE_WLOCK(fp, l, havelock)           \
 244       do {                                                \
 245       if (!(havelock))                                  \
 246         simple_lock(&(fp)->f_slock);                    \
 247         if ((fp)->f_iflags & FIF_WANTCLOSE) {             \
 248         simple_unlock(&(fp)->f_slock);                  \
 249         /* Will drop usecount */                        \
 250         (void) closef((fp), (l));                       \
 251         break;                                          \
 252         } else {                                          \
 253         (fp)->f_usecount--;                             \
 254         FILE_USE_CHECK((fp), "f_usecount underflow");   \
 255       }                                                 \
 256       simple_unlock(&(fp)->f_slock);                    \
 257     } while (/* CONSTCOND */ 0)
 258
 259 #define FILE_UNUSE(fp, l)           FILE_UNUSE_WLOCK(fp, l, 0)
 260 #define FILE_UNUSE_HAVELOCK(fp, l)  FILE_UNUSE_WLOCK(fp, l, 1)
 261
 262 __BEGIN_DECLS
 263 //int   dofileread  (struct lwp *, int, struct file *, void *, size_t, off_t *, int, register_t *);
 264 //int   dofilewrite (struct lwp *, int, struct file *, const void *, size_t, off_t *, int, register_t *);
 265
 266 //int   dofilereadv (struct lwp *, int, struct file *, const struct iovec *, int, off_t *, int, register_t *);
 267 //int   dofilewritev(struct lwp *, int, struct file *, const struct iovec *, int, off_t *, int, register_t *);
 268
 269 //int   fsetown     (struct proc *, pid_t *, int, const void *);
 270 //int   fgetown     (struct proc *, pid_t, int, void *);
 271 //void  fownsignal  (pid_t, int, int, int, void *);
 272
 273 //int   fdclone     (struct lwp *, struct file *, int, int, const struct fileops *, void *);
 274
 275 /* Commonly used fileops
 276       fnullop_*   Does nothing and returns success.
 277       fbadop_*    Does nothing and returns EPERM
 278 */
 279 //int   fnullop_fcntl   (struct file *, u_int, void *, struct lwp *);
 280 //int   fnullop_poll    (struct file *, int, struct lwp *);
 281 //int   fnullop_kqfilter(struct file *, struct knote *);
 282 //int   fbadop_stat     (struct file *, struct stat *, struct lwp *);
 283 //int   fbadop_ioctl    (struct file *, u_long, void *, struct lwp *);
 284 __END_DECLS
 285
 286 #endif
 287
 288 #endif /* _PIF_KFILE_H_ */