sys/xen/interface/io/libxenvchan.h

   1 /**
   2  * @file
   3  * @section AUTHORS
   4  *
   5  * Copyright (C) 2010  Rafal Wojtczuk  <rafal@invisiblethingslab.com>
   6  *
   7  *  Authors:
   8  *       Rafal Wojtczuk  <rafal@invisiblethingslab.com>
   9  *       Daniel De Graaf <dgdegra@tycho.nsa.gov>
  10  *
  11  * @section LICENSE
  12  *
  13  *  This library is free software; you can redistribute it and/or
  14  *  modify it under the terms of the GNU Lesser General Public
  15  *  License as published by the Free Software Foundation; either
  16  *  version 2.1 of the License, or (at your option) any later version.
  17  *
  18  *  This library is distributed in the hope that it will be useful,
  19  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21  *  Lesser General Public License for more details.
  22  *
  23  *  You should have received a copy of the GNU Lesser General Public
  24  *  License along with this library; if not, write to the Free Software
  25  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
  26  *
  27  * @section DESCRIPTION
  28  *
  29  *  Originally borrowed from the Qubes OS Project, http://www.qubes-os.org,
  30  *  this code has been substantially rewritten to use the gntdev and gntalloc
  31  *  devices instead of raw MFNs and map_foreign_range.
  32  *
  33  *  This is a library for inter-domain communication.  A standard Xen ring
  34  *  buffer is used, with a datagram-based interface built on top.  The grant
  35  *  reference and event channels are shared in XenStore under a user-specified
  36  *  path.
  37  *
  38  *  The ring.h macros define an asymmetric interface to a shared data structure
  39  *  that assumes all rings reside in a single contiguous memory space. This is
  40  *  not suitable for vchan because the interface to the ring is symmetric except
  41  *  for the setup. Unlike the producer-consumer rings defined in ring.h, the
  42  *  size of the rings used in vchan are determined at execution time instead of
  43  *  compile time, so the macros in ring.h cannot be used to access the rings.
  44  */
  45
  46 #include <stdint.h>
  47 #include <sys/types.h>
  48
  49 struct ring_shared {
  50         uint32_t cons, prod;
  51 };
  52
  53 #define VCHAN_NOTIFY_WRITE 0x1
  54 #define VCHAN_NOTIFY_READ 0x2
  55
  56 /**
  57  * vchan_interface: primary shared data structure
  58  */
  59 struct vchan_interface {
  60         /**
  61          * Standard consumer/producer interface, one pair per buffer
  62          * left is client write, server read
  63          * right is client read, server write
  64          */
  65         struct ring_shared left, right;
  66         /**
  67          * size of the rings, which determines their location
  68          * 10   - at offset 1024 in ring's page
  69          * 11   - at offset 2048 in ring's page
  70          * 12+  - uses 2^(N-12) grants to describe the multi-page ring
  71          * These should remain constant once the page is shared.
  72          * Only one of the two orders can be 10 (or 11).
  73          */
  74         uint16_t left_order, right_order;
  75         /**
  76          * Shutdown detection:
  77          *  0: client (or server) has exited
  78          *  1: client (or server) is connected
  79          *  2: client has not yet connected
  80          */
  81         uint8_t cli_live, srv_live;
  82         /**
  83          * Notification bits:
  84          *  VCHAN_NOTIFY_WRITE: send notify when data is written
  85          *  VCHAN_NOTIFY_READ: send notify when data is read (consumed)
  86          * cli_notify is used for the client to inform the server of its action
  87          */
  88         uint8_t cli_notify, srv_notify;
  89         /**
  90          * Grant list: ordering is left, right. Must not extend into actual ring
  91          * or grow beyond the end of the initial shared page.
  92          * These should remain constant once the page is shared, to allow
  93          * for possible remapping by a client that restarts.
  94          */
  95         uint32_t grants[0];
  96 };
  97