contrib/ivshmem-server/ivshmem-server.h

   1 /*
   2  * Copyright 6WIND S.A., 2014
   3  *
   4  * This work is licensed under the terms of the GNU GPL, version 2 or
   5  * (at your option) any later version.  See the COPYING file in the
   6  * top-level directory.
   7  */
   8
   9 #ifndef _IVSHMEM_SERVER_H_
  10 #define _IVSHMEM_SERVER_H_
  11
  12 /**
  13  * The ivshmem server is a daemon that creates a unix socket in listen
  14  * mode. The ivshmem clients (qemu or ivshmem-client) connect to this
  15  * unix socket. For each client, the server will create some eventfd
  16  * (see EVENTFD(2)), one per vector. These fd are transmitted to all
  17  * clients using the SCM_RIGHTS cmsg message. Therefore, each client is
  18  * able to send a notification to another client without beeing
  19  * "profixied" by the server.
  20  *
  21  * We use this mechanism to send interruptions between guests.
  22  * qemu is able to transform an event on a eventfd into a PCI MSI-x
  23  * interruption in the guest.
  24  *
  25  * The ivshmem server is also able to share the file descriptor
  26  * associated to the ivshmem shared memory.
  27  */
  28
  29 #include <limits.h>
  30 #include <sys/select.h>
  31 #include <stdint.h>
  32 #include <stdbool.h>
  33
  34 #include "qemu/event_notifier.h"
  35 #include "qemu/queue.h"
  36 #include "hw/misc/ivshmem.h"
  37
  38 /**
  39  * Maximum number of notification vectors supported by the server
  40  */
  41 #define IVSHMEM_SERVER_MAX_VECTORS 64
  42
  43 /**
  44  * Structure storing a peer
  45  *
  46  * Each time a client connects to an ivshmem server, a new
  47  * IvshmemServerPeer structure is created. This peer and all its
  48  * vectors are advertised to all connected clients through the connected
  49  * unix sockets.
  50  */
  51 typedef struct IvshmemServerPeer {
  52     QTAILQ_ENTRY(IvshmemServerPeer) next;    /**< next in list*/
  53     int sock_fd;                             /**< connected unix sock */
  54     int64_t id;                              /**< the id of the peer */
  55     EventNotifier vectors[IVSHMEM_SERVER_MAX_VECTORS]; /**< one per vector */
  56     unsigned vectors_count;                  /**< number of vectors */
  57 } IvshmemServerPeer;
  58 QTAILQ_HEAD(IvshmemServerPeerList, IvshmemServerPeer);
  59
  60 typedef struct IvshmemServerPeerList IvshmemServerPeerList;
  61
  62 /**
  63  * Structure describing an ivshmem server
  64  *
  65  * This structure stores all information related to our server: the name
  66  * of the server unix socket and the list of connected peers.
  67  */
  68 typedef struct IvshmemServer {
  69     char unix_sock_path[PATH_MAX];   /**< path to unix socket */
  70     int sock_fd;                     /**< unix sock file descriptor */
  71     char shm_path[PATH_MAX];         /**< path to shm */
  72     size_t shm_size;                 /**< size of shm */
  73     int shm_fd;                      /**< shm file descriptor */
  74     unsigned n_vectors;              /**< number of vectors */
  75     uint16_t cur_id;                 /**< id to be given to next client */
  76     bool verbose;                    /**< true in verbose mode */
  77     IvshmemServerPeerList peer_list; /**< list of peers */
  78 } IvshmemServer;
  79
  80 /**
  81  * Initialize an ivshmem server
  82  *
  83  * @server:         A pointer to an uninitialized IvshmemServer structure
  84  * @unix_sock_path: The pointer to the unix socket file name
  85  * @shm_path:       Path to the shared memory. The path corresponds to a POSIX
  86  *                  shm name or a hugetlbfs mount point.
  87  * @shm_size:       Size of shared memory
  88  * @n_vectors:      Number of interrupt vectors per client
  89  * @verbose:        True to enable verbose mode
  90  *
  91  * Returns:         0 on success, or a negative value on error
  92  */
  93 int
  94 ivshmem_server_init(IvshmemServer *server, const char *unix_sock_path,
  95                     const char *shm_path, size_t shm_size, unsigned n_vectors,
  96                     bool verbose);
  97
  98 /**
  99  * Open the shm, then create and bind to the unix socket
 100  *
 101  * @server: The pointer to the initialized IvshmemServer structure
 102  *
 103  * Returns: 0 on success, or a negative value on error
 104  */
 105 int ivshmem_server_start(IvshmemServer *server);
 106
 107 /**
 108  * Close the server
 109  *
 110  * Close connections to all clients, close the unix socket and the
 111  * shared memory file descriptor. The structure remains initialized, so
 112  * it is possible to call ivshmem_server_start() again after a call to
 113  * ivshmem_server_close().
 114  *
 115  * @server: The ivshmem server
 116  */
 117 void ivshmem_server_close(IvshmemServer *server);
 118
 119 /**
 120  * Fill a fd_set with file descriptors to be monitored
 121  *
 122  * This function will fill a fd_set with all file descriptors that must
 123  * be polled (unix server socket and peers unix socket). The function
 124  * will not initialize the fd_set, it is up to the caller to do it.
 125  *
 126  * @server: The ivshmem server
 127  * @fds:    The fd_set to be updated
 128  * @maxfd:  Must be set to the max file descriptor + 1 in fd_set. This value is
 129  *          updated if this function adds a greater fd in fd_set.
 130  */
 131 void
 132 ivshmem_server_get_fds(const IvshmemServer *server, fd_set *fds, int *maxfd);
 133
 134 /**
 135  * Read and handle new messages
 136  *
 137  * Given a fd_set (for instance filled by a call to select()), handle
 138  * incoming messages from peers.
 139  *
 140  * @server: The ivshmem server
 141  * @fds:    The fd_set containing the file descriptors to be checked. Note that
 142  *          file descriptors that are not related to our server are ignored.
 143  * @maxfd:  The maximum fd in fd_set, plus one.
 144  *
 145  * Returns: 0 on success, or a negative value on error
 146  */
 147 int ivshmem_server_handle_fds(IvshmemServer *server, fd_set *fds, int maxfd);
 148
 149 /**
 150  * Search a peer from its identifier
 151  *
 152  * @server:  The ivshmem server
 153  * @peer_id: The identifier of the peer structure
 154  *
 155  * Returns:  The peer structure, or NULL if not found
 156  */
 157 IvshmemServerPeer *
 158 ivshmem_server_search_peer(IvshmemServer *server, int64_t peer_id);
 159
 160 /**
 161  * Dump information of this ivshmem server and its peers on stdout
 162  *
 163  * @server: The ivshmem server
 164  */
 165 void ivshmem_server_dump(const IvshmemServer *server);
 166
 167 #endif /* _IVSHMEM_SERVER_H_ */