StdLibPrivateInternalFiles/Include/kfile.h

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