ipc/glue/Shmem.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_ipc_Shmem_h
   8 #define mozilla_ipc_Shmem_h
   9
  10 #include "mozilla/Attributes.h"
  11
  12 #include "base/basictypes.h"
  13 #include "base/process.h"
  14
  15 #include "nscore.h"
  16 #include "nsDebug.h"
  17
  18 #include "ipc/IPCMessageUtils.h"
  19 #include "mozilla/ipc/SharedMemory.h"
  20 #include "mozilla/ipc/IPDLParamTraits.h"
  21 #include "mozilla/UniquePtr.h"
  22
  23 /**
  24  * |Shmem| is one agent in the IPDL shared memory scheme.  The way it
  25     works is essentially
  26  *
  27  *  (1) C++ code calls, say, |parentActor->AllocShmem(size)|
  28
  29  *  (2) IPDL-generated code creates a |mozilla::ipc::SharedMemory|
  30  *  wrapping the bare OS shmem primitives.  The code then adds the new
  31  *  SharedMemory to the set of shmem segments being managed by IPDL.
  32  *
  33  *  (3) IPDL-generated code "shares" the new SharedMemory to the child
  34  *  process, and then sends a special asynchronous IPC message to the
  35  *  child notifying it of the creation of the segment.  (What this
  36  *  means is OS specific.)
  37  *
  38  *  (4a) The child receives the special IPC message, and using the
  39  *  |SharedMemory{Basic}::Handle| it was passed, creates a
  40  *  |mozilla::ipc::SharedMemory| in the child
  41  *  process.
  42  *
  43  *  (4b) After sending the "shmem-created" IPC message, IPDL-generated
  44  *  code in the parent returns a |mozilla::ipc::Shmem| back to the C++
  45  *  caller of |parentActor->AllocShmem()|.  The |Shmem| is a "weak
  46  *  reference" to the underlying |SharedMemory|, which is managed by
  47  *  IPDL-generated code.  C++ consumers of |Shmem| can't get at the
  48  *  underlying |SharedMemory|.
  49  *
  50  * If parent code wants to give access rights to the Shmem to the
  51  * child, it does so by sending its |Shmem| to the child, in an IPDL
  52  * message.  The parent's |Shmem| then "dies", i.e. becomes
  53  * inaccessible.  This process could be compared to passing a
  54  * "shmem-access baton" between parent and child.
  55  */
  56
  57 namespace mozilla {
  58 namespace layers {
  59 class ShadowLayerForwarder;
  60 }  // namespace layers
  61
  62 namespace ipc {
  63
  64 class Shmem final {
  65   friend struct IPDLParamTraits<mozilla::ipc::Shmem>;
  66 #ifdef DEBUG
  67   // For ShadowLayerForwarder::CheckSurfaceDescriptor
  68   friend class mozilla::layers::ShadowLayerForwarder;
  69 #endif
  70
  71  public:
  72   typedef int32_t id_t;
  73   // Low-level wrapper around platform shmem primitives.
  74   typedef mozilla::ipc::SharedMemory SharedMemory;
  75   typedef SharedMemory::SharedMemoryType SharedMemoryType;
  76   // Shmem objects should only be constructed directly from SharedMemory
  77   // objects by the Shmem implementation itself, or by a select few functions
  78   // in ProtocolUtils.{h,cpp}.  You should not need to add new instances of
  79   // this token.
  80   struct PrivateIPDLCaller {};
  81
  82   Shmem() : mSegment(nullptr), mData(nullptr), mSize(0), mId(0) {}
  83
  84   Shmem(const Shmem& aOther) = default;
  85
  86 #if !defined(DEBUG)
  87   Shmem(PrivateIPDLCaller, SharedMemory* aSegment, id_t aId)
  88       : mSegment(aSegment), mData(aSegment->memory()), mSize(0), mId(aId) {
  89     mSize = static_cast<size_t>(*PtrToSize(mSegment));
  90   }
  91 #else
  92   Shmem(PrivateIPDLCaller, SharedMemory* aSegment, id_t aId);
  93 #endif
  94
  95   ~Shmem() {
  96     // Shmem only holds a "weak ref" to the actual segment, which is
  97     // owned by IPDL. So there's nothing interesting to be done here
  98     forget(PrivateIPDLCaller());
  99   }
 100
 101   Shmem& operator=(const Shmem& aRhs) = default;
 102
 103   bool operator==(const Shmem& aRhs) const { return mSegment == aRhs.mSegment; }
 104
 105   // Returns whether this Shmem is writable by you, and thus whether you can
 106   // transfer writability to another actor.
 107   bool IsWritable() const { return mSegment != nullptr; }
 108
 109   // Returns whether this Shmem is readable by you, and thus whether you can
 110   // transfer readability to another actor.
 111   bool IsReadable() const { return mSegment != nullptr; }
 112
 113   // Return a pointer to the user-visible data segment.
 114   template <typename T>
 115   T* get() const {
 116     AssertInvariants();
 117     AssertAligned<T>();
 118
 119     return reinterpret_cast<T*>(mData);
 120   }
 121
 122   // Return the size of the segment as requested when this shmem
 123   // segment was allocated, in units of T.  The underlying mapping may
 124   // actually be larger because of page alignment and private data,
 125   // but this isn't exposed to clients.
 126   template <typename T>
 127   size_t Size() const {
 128     AssertInvariants();
 129     AssertAligned<T>();
 130
 131     return mSize / sizeof(T);
 132   }
 133
 134   // These shouldn't be used directly, use the IPDL interface instead.
 135   id_t Id(PrivateIPDLCaller) const { return mId; }
 136
 137   SharedMemory* Segment(PrivateIPDLCaller) const { return mSegment; }
 138
 139 #ifndef DEBUG
 140   void RevokeRights(PrivateIPDLCaller) {}
 141 #else
 142   void RevokeRights(PrivateIPDLCaller);
 143 #endif
 144
 145   void forget(PrivateIPDLCaller) {
 146     mSegment = nullptr;
 147     mData = nullptr;
 148     mSize = 0;
 149     mId = 0;
 150   }
 151
 152   static already_AddRefed<Shmem::SharedMemory> Alloc(PrivateIPDLCaller,
 153                                                      size_t aNBytes,
 154                                                      SharedMemoryType aType,
 155                                                      bool aUnsafe,
 156                                                      bool aProtect = false);
 157
 158   // Prepare this to be shared with |aProcess|.  Return an IPC message
 159   // that contains enough information for the other process to map
 160   // this segment in OpenExisting() below.  Return a new message if
 161   // successful (owned by the caller), nullptr if not.
 162   UniquePtr<IPC::Message> ShareTo(PrivateIPDLCaller, base::ProcessId aTargetPid,
 163                                   int32_t routingId);
 164
 165   // Stop sharing this with |aTargetPid|.  Return an IPC message that
 166   // contains enough information for the other process to unmap this
 167   // segment.  Return a new message if successful (owned by the
 168   // caller), nullptr if not.
 169   UniquePtr<IPC::Message> UnshareFrom(PrivateIPDLCaller, int32_t routingId);
 170
 171   // Return a SharedMemory instance in this process using the
 172   // descriptor shared to us by the process that created the
 173   // underlying OS shmem resource.  The contents of the descriptor
 174   // depend on the type of SharedMemory that was passed to us.
 175   static already_AddRefed<SharedMemory> OpenExisting(
 176       PrivateIPDLCaller, const IPC::Message& aDescriptor, id_t* aId,
 177       bool aProtect = false);
 178
 179   static void Dealloc(PrivateIPDLCaller, SharedMemory* aSegment);
 180
 181  private:
 182   template <typename T>
 183   void AssertAligned() const {
 184     if (0 != (mSize % sizeof(T))) MOZ_CRASH("shmem is not T-aligned");
 185   }
 186
 187 #if !defined(DEBUG)
 188   void AssertInvariants() const {}
 189
 190   static uint32_t* PtrToSize(SharedMemory* aSegment) {
 191     char* endOfSegment =
 192         reinterpret_cast<char*>(aSegment->memory()) + aSegment->Size();
 193     return reinterpret_cast<uint32_t*>(endOfSegment - sizeof(uint32_t));
 194   }
 195
 196 #else
 197   void AssertInvariants() const;
 198 #endif
 199
 200   RefPtr<SharedMemory> mSegment;
 201   void* mData;
 202   size_t mSize;
 203   id_t mId;
 204 };
 205
 206 template <>
 207 struct IPDLParamTraits<Shmem> {
 208   typedef Shmem paramType;
 209
 210   static void Write(IPC::Message* aMsg, IProtocol* aActor, paramType&& aParam);
 211   static bool Read(const IPC::Message* aMsg, PickleIterator* aIter,
 212                    IProtocol* aActor, paramType* aResult);
 213
 214   static void Log(const paramType& aParam, std::wstring* aLog) {
 215     aLog->append(L"(shmem segment)");
 216   }
 217 };
 218
 219 }  // namespace ipc
 220 }  // namespace mozilla
 221
 222 #endif  // ifndef mozilla_ipc_Shmem_h