service_runtime/nacl_desc_effector.h

   1 /*
   2  * Copyright 2008, Google Inc.
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are
   7  * met:
   8  *
   9  *     * Redistributions of source code must retain the above copyright
  10  * notice, this list of conditions and the following disclaimer.
  11  *     * Redistributions in binary form must reproduce the above
  12  * copyright notice, this list of conditions and the following disclaimer
  13  * in the documentation and/or other materials provided with the
  14  * distribution.
  15  *     * Neither the name of Google Inc. nor the names of its
  16  * contributors may be used to endorse or promote products derived from
  17  * this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  */
  31
  32
  33 #ifndef NATIVE_CLIENT_SERVICE_RUNTIME_NACL_DESC_EFFECTOR_H_
  34 #define NATIVE_CLIENT_SERVICE_RUNTIME_NACL_DESC_EFFECTOR_H_
  35
  36 /*
  37  * This file defines an interface class that the nacl_desc* routines
  38  * use to manipulate record keeping data structures (if any).  This
  39  * eliminates the need for the nrd_xfer library to directly manipulate
  40  * NaClApp or NaClAppThread contents, so trusted code that wish to use
  41  * the nrd_xfer library can provide their own NaClDescEffector
  42  * implementation to stub out, for example, recording of virtual
  43  * memory map changes, pre-mmap unmmaping of 64K allocations according
  44  * to the memory object backing the page, etc.
  45  */
  46
  47 #include "native_client/include/portability.h"  /* uintptr_t, off_t, etc */
  48
  49 #include "native_client/include/nacl_base.h"
  50
  51 EXTERN_C_BEGIN
  52
  53 struct NaClDesc;
  54 struct NaClDescEffectorVtbl;
  55
  56 /* virtual base class; no ctor, no vtbl */
  57 struct NaClDescEffector {
  58   struct NaClDescEffectorVtbl *vtbl;
  59 };
  60
  61 /*
  62  * Virtual functions use the kernel return interface: non-negative
  63  * values are success codes, (small) negative values are negated
  64  * NACL_ABI_* errno returns.
  65  */
  66
  67 struct NaClDescEffectorVtbl {
  68   void (*Dtor)(struct NaClDescEffector *vself);
  69
  70   /*
  71    * Return a constructed NaClDesc object to the calling environment
  72    * through the effector interface.  Takes ownership of the NaClDesc
  73    * object.
  74    *
  75    * For the service runtime, this insert the newly created NaClDesc
  76    * object into open-file table, returning index (descriptor).
  77    *
  78    * For trusted application code, each call returns a NaClDesc, but
  79    * in methods that may return more than one, dynamic cast style
  80    * checks are needed to determine which NaClDesc is which (assuming
  81    * that their types differ), or be determined by the order in which
  82    * they'red produced (which is fragile, since the implementation
  83    * might change the order in which the NaClDesc objects are
  84    * produced).  The returned indices are used for the return value
  85    * from the NaClDesc virtual function (or as output arguments) and
  86    * should not be negative; otherwise the value is immaterial.
  87    *
  88    * For example, NaClDescConnCapConnectAddr and NaClDescImcBoundDesc
  89    * uses this method since they are factories that produce
  90    * NaClDescImcDesc objects.
  91    */
  92   int (*ReturnCreatedDesc)(struct NaClDescEffector  *vself,
  93                            struct NaClDesc          *ndp);
  94
  95   /*
  96    * Update addrss map for NaClApp.  The address is the system (flat
  97    * 32) address, and the virtual function is responsible for
  98    * translating it back to user (segment base relative) addresses.
  99    * The sys_prot used are host OS memory protection bits, though on
 100    * windows these are just a copy of *x values since there's no mmap
 101    * interface there.  backing_desc is the NaClDesc that is providing
 102    * backing store for the virtual memory.  offset_bytes is the offset
 103    * into the backing_desc and must be a multiple of allocation size.
 104    * the size of the mapping from the backing_desc is nbytes.
 105    *
 106    * NB: the calling code will ensure that offset_bytes + nbytes will
 107    * be at most NaClRoundPage(file size).  If NaClRoundAllocPage(file
 108    * size) is greater, then additional calls to put in padding pages
 109    * -- with a NULL backing_desc (backed by system paging file) will
 110    * be made for the difference.
 111    *
 112    * If delete_mem is non-zero, then the memory range specified by
 113    * [sysaddr,sysaddr+nbytes) should be removed from the address map,
 114    * and the other arguments are irrelevant.
 115    *
 116    * For trusted application code, this can be a no-op routine (a stub
 117    * that does nothing; all method function pointers must be
 118    * non-NULL).
 119    *
 120    * Note that because windows map things in 64K granularity and in
 121    * order to allow independent overlapping allocations, we map the
 122    * object in 64K chunks at a time.  Thus, it is critical that the
 123    * unmapping is done via the corresponding unmap function using the
 124    * descriptor object that was used to create the mapping in the
 125    * first place, so some recording keeping is still needed for
 126    * trusted application code.
 127    */
 128   void (*UpdateAddrMap)(struct NaClDescEffector *vself,
 129                         uintptr_t               sysaddr,  /* flat 32 addr */
 130                         size_t                  nbytes,
 131                         int                     sysprot,
 132                         struct NaClDesc         *backing_desc,
 133                         size_t                  backing_obj_size_bytes,
 134                         off_t                   offset_bytes,
 135                         int                     delete_mem);
 136
 137   /*
 138    * For service runtime, the NaClDesc's Map virtual function will
 139    * call this to unmap any existing memory before mapping new pages
 140    * in on top.  This method should handle the necessary unmapping
 141    * (figure out the memory object that is backing the memory and call
 142    * UnmapViewOfFile or VirtualFree as appropriate).  On linux and
 143    * osx, this can be a no-op since mmap will override existing
 144    * mappings in an atomic fashion (yay!).  The sysaddr will be a
 145    * multiple of allocation size, as will be nbytes.
 146    *
 147    * For trusted applications, this can also be a no-op as long as the
 148    * application chooses a valid (not committed nor reserved) address
 149    * range.
 150    *
 151    * Note that UnmapMemory may be called without a corresponding
 152    * UpdateAddrmap (w/ delete_mem=1), since that may be deferred until
 153    * the memory hole has been populated with something else.
 154    *
 155    * This is NOT used by the NaClDesc's own Unmap method.
 156    */
 157   int (*UnmapMemory)(struct NaClDescEffector  *vself,
 158                      uintptr_t                sysaddr,
 159                      size_t                   nbytes);
 160
 161   /*
 162    * Map anonymous memory -- from paging space -- into address space
 163    * at requested sysaddr of nbytes in length.  prot may be
 164    * NACL_ABI_PROT_NONE for address space squatting purposes.
 165    */
 166   int (*MapAnonymousMemory)(struct NaClDescEffector *vself,
 167                             uintptr_t               sysaddr,
 168                             size_t                  nbytes,
 169                             int                     prot);
 170
 171   /*
 172    * The bound IMC socket to use as the sender when making a
 173    * connection.  Does not transfer ownership nor change refcount, so
 174    * returned value's lifetime should be lower-bounded by the lifetime
 175    * of the NaClDescEffector object.
 176    */
 177   struct NaClDescImcBoundDesc *(*SourceSock)(struct NaClDescEffector *vself);
 178 };
 179
 180 EXTERN_C_END
 181
 182 #endif /* NATIVE_CLIENT_SERVICE_RUNTIME_NACL_DESC_EFFECTOR_H_ */