intermodule_comm/nacl_imc.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 // NaCl inter-module communication primitives.
  34
  35 #ifndef NATIVE_CLIENT_INTERMODULE_COMM_NACL_IMC_H_
  36 #define NATIVE_CLIENT_INTERMODULE_COMM_NACL_IMC_H_
  37
  38 /**
  39  * @file
  40  * Defines primitive NaCl socket and shared memory functions that provide a
  41  * portable inter-module communication mechanism between processes on Windows,
  42  * Mac OS X, and Linux. On Linux, these functions are simple wrapper functions
  43  * for the AF_UNIX domain socket API.
  44  *
  45  * @addtogroup IMC
  46  * @{
  47  */
  48
  49 #if NACL_WINDOWS
  50 #include <windows.h>
  51 #endif
  52 #include <sys/types.h>
  53
  54 /**
  55  * Contains primitive NaCl socket and shared memory functions.
  56  */
  57 namespace nacl {
  58
  59 /**
  60  *  @nacl
  61  *  Gets the last error message string.
  62  *  @param buffer Pointer to the buffer in which the error message is written.
  63  *  @param length The size of buffer.
  64  *  @return 0 on success and -1 on failure.
  65  */
  66 int GetLastErrorString(char* buffer, size_t length);
  67
  68
  69 /**
  70  *  @nacl
  71  *  NaCl resource descriptor type
  72  */
  73 #if NACL_WINDOWS
  74 typedef HANDLE Handle;
  75 const Handle kInvalidHandle(INVALID_HANDLE_VALUE);
  76 #else
  77 typedef int Handle; /** < PENDING: doc */
  78 const Handle kInvalidHandle(-1); /** < PENDING: doc */
  79 #endif
  80
  81 /**
  82  *  @nacl
  83  *  The maximum length of the zero-terminated pathname for SocketAddress
  84  */
  85 const int kPathMax = 28;            // TBD
  86
  87 /**
  88  *  @nacl
  89  *  A NaCl socket address is defined as a pathname. The pathname must be a zero-
  90  *  terminated character string starting from a character within the ranges A -
  91  *  Z or a - z. The pathname is not case sensitive on Windows.
  92  */
  93 struct SocketAddress {
  94   char path[kPathMax];
  95 };
  96
  97 /**
  98  *  @nacl
  99  *  I/O vector for the scatter/gather operation used by SendDatagram() and
 100  *  ReceiveDatagram()
 101  */
 102 struct IOVec {
 103   void*   base;
 104   size_t  length;
 105 };
 106
 107 /**
 108  *  @nacl
 109  *  The maximum number of handles to be passed by SendDatagram()
 110  */
 111 const size_t kHandleCountMax = 8;   // TBD
 112
 113 /**
 114  *  @nacl
 115  *  MessageHeader flags set by ReceiveDatagram()
 116  */
 117 const int kMessageTruncated = 0x1;  /**< The trailing portion of a message was
 118                                      *   discarded. */
 119 const int kHandlesTruncated = 0x2;  /**< Not all the handles were received. */
 120
 121 /**
 122  *  @nacl
 123  *  Message header used by SendDatagram() and ReceiveDatagram()
 124  */
 125 struct MessageHeader {
 126   IOVec*  iov;            /**< scatter/gather array */
 127   size_t  iov_length;     /**< number of elements in iov */
 128   Handle* handles;        /**< array of handles to be transferred */
 129   size_t  handle_count;   /**< number of handles in handles */
 130   int     flags;
 131 };
 132
 133 /**
 134  *  @nacl
 135  *  Creates a NaCl socket associated with the local address.
 136  *  @param address Pointer to the SocketAddress to bind.
 137  *  @return A handle of the newly created bound socket on success, and
 138  *          kInvalidHandle on failure.
 139  */
 140 Handle BoundSocket(const SocketAddress* address);
 141
 142 /**
 143  *  @nacl
 144  *  Creates an unnamed pair of connected sockets.
 145  *  @param pair Pointer to an array of two Handles in which connected socket
 146  *              descriptors are returned.
 147  *  @return 0 on success, and -1 on failure.
 148  */
 149 int SocketPair(Handle pair[2]);
 150
 151 /**
 152  *  @nacl
 153  *  Closes a NaCl descriptor created by the NaCl IMC primitives.
 154  *  Note NaCl descriptors must be explicitly closed by Close(). Otherwise,
 155  *  the resources of the underlining operating system will not be released
 156  *  correctly.
 157  *  @param handle The NaCl descriptor to close.
 158  *  @return 0 on success, and -1 on failure.
 159  */
 160 int Close(Handle handle);
 161
 162 /**
 163  *  @nacl
 164  *  SendDatagram()/ReceiveDatagram() flags
 165  */
 166 const int kDontWait = 0x1;  /**< Enables non-blocking operation */
 167
 168 /**
 169  *  @nacl
 170  *  Checks whether the last non-blocking operation failed because no message
 171  *  was available in the queue.
 172  *  @return true if the previous non-blocking send or receive operation failure
 173  *          was because it would block if kDontWait was not specified.
 174  */
 175 bool WouldBlock();
 176
 177 /**
 178  *  @nacl
 179  *  Sends the message to the remote peer of the connection created by
 180  *  SocketPair().
 181  *
 182  *  If kDontWait flag is specified with the call and the other peer of the
 183  *  socket is unable to receive more data, the function returns -1 without
 184  *  waiting, and the subsequent WouldBlock() will return true.
 185  *
 186  *  Note it is not safe to send messages from the same socket handle by
 187  *  multiple threads simultaneously.
 188  *  @param socket The socket descriptor.
 189  *  @param message Pointer to MessageHeader to send.
 190  *  @param flags Either 0 or kDontWait.
 191  *  @return The number of bytes sent, or -1 upon failure
 192  */
 193 int SendDatagram(Handle socket, const MessageHeader* message, int flags);
 194
 195 /**
 196  *  @nacl
 197  *  Sends the message to the socket specified by the name. The socket parameter
 198  *  should be a socket created by BoundSocket().
 199  *  @param socket The socket descriptor.
 200  *  @param message Pointer to MessageHeader to send.
 201  *  @param flags Either 0 or kDontWait.
 202  *  @param name The target socket address to which the message is sent.
 203  *  @return The number of bytes sent, or -1 upon failure
 204  *  @see SendDatagram()
 205  */
 206 int SendDatagramTo(Handle socket, const MessageHeader* message, int flags,
 207                    const SocketAddress* name);
 208
 209 /**
 210  *  @nacl
 211  *  Sends the message to the remote peer of the connection created by
 212  *  SocketPair().
 213  *
 214  *  Note it is not safe to send messages from the same socket handle by
 215  *  multiple threads simultaneously.
 216  *  @param socket The socket descriptor.
 217  *  @param buffer Pointer to the data to send.
 218  *  @param length The length of the data to send.
 219  *  @param flags Either 0 or kDontWait.
 220  *  @return The number of bytes sent, or -1 upon failure
 221  *  @see SendDatagram()
 222  */
 223 int Send(Handle socket, const void* buffer, size_t length, int flags);
 224
 225 /**
 226  *  @nacl
 227  *  Sends the message to the socket specified by the name. The socket parameter
 228  *  should be a socket created by BoundSocket().
 229  *  @param socket The socket descriptor.
 230  *  @param buffer Pointer to the data to send.
 231  *  @param length The length of the data to send.
 232  *  @param flags Either 0 or kDontWait.
 233  *  @param name The target socket address to which the message is sent.
 234  *  @return The number of bytes sent, or -1 upon failure.
 235  *  @see SendDatagram()
 236  */
 237 int SendTo(Handle socket, const void* buffer, size_t length, int flags,
 238            const SocketAddress* name);
 239
 240 /**
 241  *  @nacl
 242  *  Receives a message from a socket.
 243  *
 244  *  If kDontWait flag is specified with the call and no messages are available
 245  *  in the queue, the function returns -1 and the subsequent WouldBlock() will
 246  *  return true.
 247  *
 248  *  Note it is not safe to receive messages from the same socket handle
 249  *  by multiple threads simultaneously unless the socket handle is created
 250  *  by BoundSocket().
 251  *  @param socket The socket descriptor.
 252  *  @param message Pointer to MessageHeader to receive a message.
 253  *  @param flags Either 0 or kDontWait.
 254  *  @return The number of bytes received, or -1 upon failure.
 255  */
 256 int ReceiveDatagram(Handle socket, MessageHeader* message, int flags);
 257
 258 /**
 259  *  @nacl
 260  *  Receives a message from a socket.
 261  *
 262  *  Note it is not safe to receive messages from the same socket handle
 263  *  by multiple threads simultaneously unless the socket handle is created
 264  *  by BoundSocket().
 265  *  @param socket The socket descriptor.
 266  *  @param buffer Pointer to the buffer to receive data.
 267  *  @param length The length of the buffer to receive data.
 268  *  @param flags Either 0 or kDontWait.
 269  *  @return The number of bytes received, or -1 upon failure.
 270  *  @see ReceiveDatagram()
 271  */
 272 int Receive(Handle socket, void* buffer, size_t length, int flags);
 273
 274 /**
 275  *  @nacl
 276  *  Map allocation granularity
 277  */
 278 const size_t kMapPageSize = 64 * 1024;
 279
 280 /**
 281  *  @nacl
 282  *  Creates a memory object of length bytes.
 283  *  @param length The size of the memory object to create. It must be a multiple
 284  *                of allocation granularity given by kMapPageSize.
 285  *  @return A handle of the newly created memory object on success, and
 286  *          kInvalidHandle on failure.
 287  */
 288 Handle CreateMemoryObject(size_t length);
 289
 290 /**
 291  *  @nacl
 292  *  Map() prot bits
 293  */
 294 const int kProtRead = 0x1;    /**< Mapped area can be read */
 295 const int kProtWrite = 0x2;   /**< Mapped area can be written */
 296
 297 /**
 298  *  @nacl
 299  *  Map() flags
 300  */
 301 const int kMapShared = 0x1;   /**< Create a sharable mapping with other
 302                                *   processes */
 303 const int kMapPrivate = 0x2;  /**< Create a private copy-on-write mapping */
 304 const int kMapFixed = 0x4;    /**< Try to create a mapping at the specified
 305                                *   address */
 306
 307 void* const kMapFailed = reinterpret_cast<void*>(-1);
 308
 309 /**
 310  *  @nacl
 311  *  Maps the specified memory object in the process address space.
 312  *  @param start The preferred start address of the space range to map if
 313  *               kMapFixed is set to flags.
 314  *  @param length The size of the space range to map.
 315  *  @param prot The bitwise OR of the kProt* bits must be specified.
 316  *  @param flags Either kMapShared or kMapPrivate must be specified. If
 317  *               kMapFixed is also set, Map() tries to map the memory object at
 318  *               the address specified by start.
 319  *  @param memory The memory object descriptor to map.
 320  *  @param offset The offset in the memory object from which the memory object
 321  *                will be mapped.
 322  *  @return A pointer to the mapped area, and kMapFailed upon error.
 323  */
 324 void* Map(void* start, size_t length, int prot, int flags,
 325           Handle memory, off_t offset);
 326
 327 /**
 328  *  @nacl
 329  *  Unmaps the memory objects mapped within the specified process address space
 330  *  range.
 331  *  @param start The start address of the space range to unmap.
 332  *  @param length The size of the space range to unmap.
 333  *  @return 0 on success, and -1 on failure.
 334  */
 335 int Unmap(void* start, size_t length);
 336
 337 }  // namespace nacl
 338
 339 /**
 340  * @} End of IMC group
 341  */
 342
 343 #endif  // NATIVE_CLIENT_INTERMODULE_COMM_NACL_IMC_H_