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   off_t                   f_offset;     /* current position in file */
  83   const struct fileops   *f_ops;
  84   void                   *devdata;      /* Device-specific data */
  85   int                     Oflags;       // From the open call
  86   int                     Omode;        // From the open call
  87   int                     RefCount;     // Reference count of opens
  88   UINT32                  f_flag;       /* see fcntl.h */
  89   UINT32                  f_iflags;     // In use if non-zero
  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 _Device_Node *This, struct __filedes *FD,
 134                                 int Instance, wchar_t *Path, wchar_t *MPath);
 135
 136 #define FILE_IS_USABLE(fp)  (((fp)->f_iflags &      \
 137           (FIF_WANTCLOSE|FIF_LARVAL)) == 0)
 138
 139 #define FILE_SET_MATURE(fp)       \
 140 do {                              \
 141   (fp)->f_iflags &= ~FIF_LARVAL;  \
 142 } while (/*CONSTCOND*/0)
 143
 144 /*
 145  * Flags for fo_read and fo_write.
 146  */
 147 #define FOF_UPDATE_OFFSET 0x01      /* update the file offset */
 148
 149 __BEGIN_DECLS
 150
 151 int   fdcreate    (CHAR16 *, UINT32, UINT32, BOOLEAN, VOID *, const struct fileops *);
 152
 153 /* Commonly used fileops
 154       fnullop_*   Does nothing and returns success.
 155       fbadop_*    Does nothing and returns EPERM
 156 */
 157 int     EFIAPI fnullop_fcntl (struct __filedes *filp, UINT32 Cmd, void *p3, void *p4);
 158 short   EFIAPI fnullop_poll  (struct __filedes *filp, short Events);
 159 int     EFIAPI fnullop_flush (struct __filedes *filp);
 160
 161 int     EFIAPI fbadop_stat   (struct __filedes *filp, struct stat *StatBuf, void *Buf);
 162 int     EFIAPI fbadop_ioctl  (struct __filedes *filp, ULONGN Cmd, void *argp);
 163 int     EFIAPI fbadop_delete (struct __filedes *filp);
 164 int     EFIAPI fbadop_rmdir  (struct __filedes *filp);
 165 int     EFIAPI fbadop_mkdir  (const char *path, __mode_t perms);
 166 int     EFIAPI fbadop_rename (const char *from, const char *to);
 167
 168 __END_DECLS
 169
 170 /* From the original file... */
 171 #if 0
 172
 173 //struct proc;
 174 //struct lwp;
 175 //struct uio;
 176 //struct iovec;
 177 //struct knote;
 178
 179 //LIST_HEAD(filelist, file);
 180 //extern struct filelist  filehead;   /* head of list of open files */
 181 //extern int              maxfiles;   /* kernel limit on # of open files */
 182 //extern int              nfiles;     /* actual number of open files */
 183
 184 //extern const struct fileops vnops;  /* vnode operations for files */
 185
 186 struct fileops {
 187   int (*fo_read)      (struct file *, off_t *, struct uio *, kauth_cred_t, int);
 188   int (*fo_write)     (struct file *, off_t *, struct uio *, kauth_cred_t, int);
 189   int (*fo_ioctl)     (struct file *, u_long, void *, struct lwp *);
 190   int (*fo_fcntl)     (struct file *, u_int, void *, struct lwp *);
 191   int (*fo_poll)      (struct file *, int, struct lwp *);
 192   int (*fo_stat)      (struct file *, struct stat *, struct lwp *);
 193   int (*fo_close)     (struct file *, struct lwp *);
 194 };
 195
 196 /*
 197  * Kernel descriptor table.
 198  * One entry for each open kernel vnode and socket.
 199  */
 200 struct file {
 201   LIST_ENTRY(file)        f_list;     /* list of active files */
 202   void                   *f_data;     /* descriptor data, e.g. vnode/socket */
 203   const struct fileops   *f_ops;
 204   void                   *f_DevDesc;  /* Device Descriptor pointer */
 205   EFI_FILE_HANDLE         FileHandle;
 206   EFI_HANDLE              Handle;
 207   off_t                   f_offset;   /* current position in file */
 208   int                     f_flag;     /* see fcntl.h */
 209   UINT32                  f_iflags;   /* internal flags; FIF_* */
 210   int                     f_advice;   /* access pattern hint; UVM_ADV_* */
 211   int                     f_type;     /* descriptor type */
 212   int                     f_usecount; /* number active users */
 213   u_int                   f_count;    /* reference count */
 214   u_int                   f_msgcount; /* references from message queue */
 215 //  kauth_cred_t            f_cred;     /* creds associated with descriptor */
 216   struct simplelock       f_slock;
 217   UINT16                  MyFD;       /* Which FD this is. */
 218 };
 219
 220 #ifdef DIAGNOSTIC
 221 #define FILE_USE_CHECK(fp, str)   \
 222   do {                              \
 223   if ((fp)->f_usecount < 0)       \
 224     panic(str);                   \
 225 } while (/* CONSTCOND */ 0)
 226 #else
 227 #define FILE_USE_CHECK(fp, str)   /* nothing */
 228 #endif
 229
 230   /*
 231    * FILE_USE() must be called with the file lock held.
 232    * (Typical usage is: `fp = fd_getfile(..); FILE_USE(fp);'
 233    * and fd_getfile() returns the file locked)
 234    *
 235    * fp is a pointer to a __filedes structure.
 236    */
 237 #define FILE_USE(fp)                                \
 238     do {                                                \
 239     (fp)->f_usecount++;                               \
 240     FILE_USE_CHECK((fp), "f_usecount overflow");      \
 241     simple_unlock(&(fp)->f_slock);                    \
 242   } while (/* CONSTCOND */ 0)
 243
 244 #define FILE_UNUSE_WLOCK(fp, l, havelock)           \
 245       do {                                                \
 246       if (!(havelock))                                  \
 247         simple_lock(&(fp)->f_slock);                    \
 248         if ((fp)->f_iflags & FIF_WANTCLOSE) {             \
 249         simple_unlock(&(fp)->f_slock);                  \
 250         /* Will drop usecount */                        \
 251         (void) closef((fp), (l));                       \
 252         break;                                          \
 253         } else {                                          \
 254         (fp)->f_usecount--;                             \
 255         FILE_USE_CHECK((fp), "f_usecount underflow");   \
 256       }                                                 \
 257       simple_unlock(&(fp)->f_slock);                    \
 258     } while (/* CONSTCOND */ 0)
 259
 260 #define FILE_UNUSE(fp, l)           FILE_UNUSE_WLOCK(fp, l, 0)
 261 #define FILE_UNUSE_HAVELOCK(fp, l)  FILE_UNUSE_WLOCK(fp, l, 1)
 262
 263 __BEGIN_DECLS
 264 //int   dofileread  (struct lwp *, int, struct file *, void *, size_t, off_t *, int, register_t *);
 265 //int   dofilewrite (struct lwp *, int, struct file *, const void *, size_t, off_t *, int, register_t *);
 266
 267 //int   dofilereadv (struct lwp *, int, struct file *, const struct iovec *, int, off_t *, int, register_t *);
 268 //int   dofilewritev(struct lwp *, int, struct file *, const struct iovec *, int, off_t *, int, register_t *);
 269
 270 //int   fsetown     (struct proc *, pid_t *, int, const void *);
 271 //int   fgetown     (struct proc *, pid_t, int, void *);
 272 //void  fownsignal  (pid_t, int, int, int, void *);
 273
 274 //int   fdclone     (struct lwp *, struct file *, int, int, const struct fileops *, void *);
 275
 276 /* Commonly used fileops
 277       fnullop_*   Does nothing and returns success.
 278       fbadop_*    Does nothing and returns EPERM
 279 */
 280 //int   fnullop_fcntl   (struct file *, u_int, void *, struct lwp *);
 281 //int   fnullop_poll    (struct file *, int, struct lwp *);
 282 //int   fnullop_kqfilter(struct file *, struct knote *);
 283 //int   fbadop_stat     (struct file *, struct stat *, struct lwp *);
 284 //int   fbadop_ioctl    (struct file *, u_long, void *, struct lwp *);
 285 __END_DECLS
 286
 287 #endif
 288
 289 #endif /* _PIF_KFILE_H_ */