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  <stdarg.h>
  52 #include  <sys/fcntl.h>
  53 #include  <sys/unistd.h>
  54
  55 struct stat;
  56 struct fileops;
  57 struct _Device_Node;
  58
  59 /* The number of "special" character stream devices.
  60    These include:
  61     stdin, stdout, stderr
  62 */
  63 #define NUM_SPECIAL   3
  64
  65 /* Organization of the f_iflags member of the __filedes structure. */
  66 #define DTYPE_MASK      0x00000007    ///< Device Type
  67 #define DTYPE_VNODE             1     /* file */
  68 #define DTYPE_SOCKET            2     /* communications endpoint */
  69 #define DTYPE_PIPE              3     /* pipe */
  70 #define DTYPE_KQUEUE            4     /* event queue */
  71 #define DTYPE_MISC              5     /* misc file descriptor type */
  72 #define DTYPE_CRYPTO            6     /* crypto */
  73 #define DTYPE_NAMES   "0", "file", "socket", "pipe", "kqueue", "misc", "crypto"
  74
  75 #define FIF_WANTCLOSE   0x10000000  /* a close is waiting for usecount */
  76 #define FIF_DELCLOSE    0x20000000  /* Delete on close. */
  77 #define FIF_LARVAL      0x80000000  /* not fully constructed; don't use */
  78
  79 /*
  80     This structure must be a multiple of 8 bytes in length.
  81 */
  82 struct __filedes {
  83   off_t                   f_offset;     /* current position in file */
  84   const struct fileops   *f_ops;
  85   void                   *devdata;      /* Device-specific data */
  86   int                     Oflags;       // From the open call
  87   int                     Omode;        // From the open call
  88   int                     RefCount;     // Reference count of opens
  89   UINT32                  f_flag;       /* see fcntl.h */
  90   UINT32                  f_iflags;     // In use if non-zero
  91   UINT16                  MyFD;         // Which FD this is.
  92   UINT16                  Reserved_1;   // Force this structure to be a multiple of 8-bytes in length
  93 };
  94
  95 struct fileops {
  96   /* These functions must always be implemented. */
  97   int     (EFIAPI *fo_close)    (struct __filedes *filp);
  98   ssize_t (EFIAPI *fo_read)     (struct __filedes *filp, off_t *Offset, size_t Len, void *Buf);
  99   ssize_t (EFIAPI *fo_write)    (struct __filedes *filp, off_t *Offset, size_t Len, const void *Buf);
 100
 101   /* Call the fnullop_* version of these functions if not implemented by the device. */
 102   int     (EFIAPI *fo_fcntl)    (struct __filedes *filp, UINT32 Cmd, void *p3, void *p4);
 103   short   (EFIAPI *fo_poll)     (struct __filedes *filp, short Events);
 104   int     (EFIAPI *fo_flush)    (struct __filedes *filp);
 105
 106   /* Call the fbadop_* version of these functions if not implemented by the device. */
 107   int     (EFIAPI *fo_stat)     (struct __filedes *filp, struct stat *StatBuf, void *Buf);
 108   int     (EFIAPI *fo_ioctl)    (struct __filedes *filp, ULONGN Cmd, va_list argp);
 109   int     (EFIAPI *fo_delete)   (struct __filedes *filp);
 110   int     (EFIAPI *fo_rmdir)    (struct __filedes *filp);
 111   int     (EFIAPI *fo_mkdir)    (const char *path, __mode_t perms);
 112   int     (EFIAPI *fo_rename)   (const char *from, const char *to);
 113
 114   /* Use a NULL if this function has not been implemented by the device. */
 115   off_t   (EFIAPI *fo_lseek)    (struct __filedes *filp, off_t, int);
 116 };
 117
 118 /*  A generic instance structure which is valid for
 119     for all device instance structures.
 120
 121     All device instance structures MUST be a multiple of 8-bytes in length.
 122 */
 123 typedef struct {
 124   UINT32                      Cookie;       ///< Special value identifying this as a valid Instance
 125   UINT32                      InstanceNum;  ///< Which instance is this?  Zero-based.
 126   EFI_HANDLE                  Dev;          ///< Pointer to either Input or Output Protocol.
 127   struct _Device_Node        *Parent;       ///< Points to the parent Device Node.
 128   struct fileops              Abstraction;  ///< Pointers to functions implementing this device's abstraction.
 129   UINTN                       Reserved_1;   // Force this to always be a multiple of 8-bytes in length
 130 } GenericInstance;
 131
 132 /* Type of all Device-specific handler's open routines. */
 133 typedef
 134   int     (EFIAPI *FO_OPEN)    (struct _Device_Node *This, struct __filedes *FD,
 135                                 int Instance, wchar_t *Path, wchar_t *MPath);
 136
 137 #define FILE_IS_USABLE(fp)  (((fp)->f_iflags &      \
 138           (FIF_WANTCLOSE|FIF_LARVAL)) == 0)
 139
 140 #define FILE_SET_MATURE(fp)       \
 141 do {                              \
 142   (fp)->f_iflags &= ~FIF_LARVAL;  \
 143 } while (/*CONSTCOND*/0)
 144
 145 /*
 146  * Flags for fo_read and fo_write.
 147  */
 148 #define FOF_UPDATE_OFFSET 0x01      /* update the file offset */
 149
 150 __BEGIN_DECLS
 151
 152 int   fdcreate    (CHAR16 *, UINT32, UINT32, BOOLEAN, VOID *, const struct fileops *);
 153
 154 /* Commonly used fileops
 155       fnullop_*   Does nothing and returns success.
 156       fbadop_*    Does nothing and returns EPERM
 157 */
 158 int     EFIAPI fnullop_fcntl (struct __filedes *filp, UINT32 Cmd, void *p3, void *p4);
 159 short   EFIAPI fnullop_poll  (struct __filedes *filp, short Events);
 160 int     EFIAPI fnullop_flush (struct __filedes *filp);
 161
 162 int     EFIAPI fbadop_stat   (struct __filedes *filp, struct stat *StatBuf, void *Buf);
 163 int     EFIAPI fbadop_ioctl  (struct __filedes *filp, ULONGN Cmd, va_list argp);
 164 int     EFIAPI fbadop_delete (struct __filedes *filp);
 165 int     EFIAPI fbadop_rmdir  (struct __filedes *filp);
 166 int     EFIAPI fbadop_mkdir  (const char *path, __mode_t perms);
 167 int     EFIAPI fbadop_rename (const char *from, const char *to);
 168
 169 __END_DECLS
 170
 171 /* From the original file... */
 172 #if 0
 173
 174 //struct proc;
 175 //struct lwp;
 176 //struct uio;
 177 //struct iovec;
 178 //struct knote;
 179
 180 //LIST_HEAD(filelist, file);
 181 //extern struct filelist  filehead;   /* head of list of open files */
 182 //extern int              maxfiles;   /* kernel limit on # of open files */
 183 //extern int              nfiles;     /* actual number of open files */
 184
 185 //extern const struct fileops vnops;  /* vnode operations for files */
 186
 187 struct fileops {
 188   int (*fo_read)      (struct file *, off_t *, struct uio *, kauth_cred_t, int);
 189   int (*fo_write)     (struct file *, off_t *, struct uio *, kauth_cred_t, int);
 190   int (*fo_ioctl)     (struct file *, u_long, void *, struct lwp *);
 191   int (*fo_fcntl)     (struct file *, u_int, void *, struct lwp *);
 192   int (*fo_poll)      (struct file *, int, struct lwp *);
 193   int (*fo_stat)      (struct file *, struct stat *, struct lwp *);
 194   int (*fo_close)     (struct file *, struct lwp *);
 195 };
 196
 197 /*
 198  * Kernel descriptor table.
 199  * One entry for each open kernel vnode and socket.
 200  */
 201 struct file {
 202   LIST_ENTRY(file)        f_list;     /* list of active files */
 203   void                   *f_data;     /* descriptor data, e.g. vnode/socket */
 204   const struct fileops   *f_ops;
 205   void                   *f_DevDesc;  /* Device Descriptor pointer */
 206   EFI_FILE_HANDLE         FileHandle;
 207   EFI_HANDLE              Handle;
 208   off_t                   f_offset;   /* current position in file */
 209   int                     f_flag;     /* see fcntl.h */
 210   UINT32                  f_iflags;   /* internal flags; FIF_* */
 211   int                     f_advice;   /* access pattern hint; UVM_ADV_* */
 212   int                     f_type;     /* descriptor type */
 213   int                     f_usecount; /* number active users */
 214   u_int                   f_count;    /* reference count */
 215   u_int                   f_msgcount; /* references from message queue */
 216 //  kauth_cred_t            f_cred;     /* creds associated with descriptor */
 217   struct simplelock       f_slock;
 218   UINT16                  MyFD;       /* Which FD this is. */
 219 };
 220
 221 #ifdef DIAGNOSTIC
 222 #define FILE_USE_CHECK(fp, str)   \
 223   do {                              \
 224   if ((fp)->f_usecount < 0)       \
 225     panic(str);                   \
 226 } while (/* CONSTCOND */ 0)
 227 #else
 228 #define FILE_USE_CHECK(fp, str)   /* nothing */
 229 #endif
 230
 231   /*
 232    * FILE_USE() must be called with the file lock held.
 233    * (Typical usage is: `fp = fd_getfile(..); FILE_USE(fp);'
 234    * and fd_getfile() returns the file locked)
 235    *
 236    * fp is a pointer to a __filedes structure.
 237    */
 238 #define FILE_USE(fp)                                \
 239     do {                                                \
 240     (fp)->f_usecount++;                               \
 241     FILE_USE_CHECK((fp), "f_usecount overflow");      \
 242     simple_unlock(&(fp)->f_slock);                    \
 243   } while (/* CONSTCOND */ 0)
 244
 245 #define FILE_UNUSE_WLOCK(fp, l, havelock)           \
 246       do {                                                \
 247       if (!(havelock))                                  \
 248         simple_lock(&(fp)->f_slock);                    \
 249         if ((fp)->f_iflags & FIF_WANTCLOSE) {             \
 250         simple_unlock(&(fp)->f_slock);                  \
 251         /* Will drop usecount */                        \
 252         (void) closef((fp), (l));                       \
 253         break;                                          \
 254         } else {                                          \
 255         (fp)->f_usecount--;                             \
 256         FILE_USE_CHECK((fp), "f_usecount underflow");   \
 257       }                                                 \
 258       simple_unlock(&(fp)->f_slock);                    \
 259     } while (/* CONSTCOND */ 0)
 260
 261 #define FILE_UNUSE(fp, l)           FILE_UNUSE_WLOCK(fp, l, 0)
 262 #define FILE_UNUSE_HAVELOCK(fp, l)  FILE_UNUSE_WLOCK(fp, l, 1)
 263
 264 __BEGIN_DECLS
 265 //int   dofileread  (struct lwp *, int, struct file *, void *, size_t, off_t *, int, register_t *);
 266 //int   dofilewrite (struct lwp *, int, struct file *, const void *, size_t, off_t *, int, register_t *);
 267
 268 //int   dofilereadv (struct lwp *, int, struct file *, const struct iovec *, int, off_t *, int, register_t *);
 269 //int   dofilewritev(struct lwp *, int, struct file *, const struct iovec *, int, off_t *, int, register_t *);
 270
 271 //int   fsetown     (struct proc *, pid_t *, int, const void *);
 272 //int   fgetown     (struct proc *, pid_t, int, void *);
 273 //void  fownsignal  (pid_t, int, int, int, void *);
 274
 275 //int   fdclone     (struct lwp *, struct file *, int, int, const struct fileops *, void *);
 276
 277 /* Commonly used fileops
 278       fnullop_*   Does nothing and returns success.
 279       fbadop_*    Does nothing and returns EPERM
 280 */
 281 //int   fnullop_fcntl   (struct file *, u_int, void *, struct lwp *);
 282 //int   fnullop_poll    (struct file *, int, struct lwp *);
 283 //int   fnullop_kqfilter(struct file *, struct knote *);
 284 //int   fbadop_stat     (struct file *, struct stat *, struct lwp *);
 285 //int   fbadop_ioctl    (struct file *, u_long, void *, struct lwp *);
 286 __END_DECLS
 287
 288 #endif
 289
 290 #endif /* _PIF_KFILE_H_ */