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 being
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 <sys/select.h>
30
31#include "qemu/event_notifier.h"
32#include "qemu/queue.h"
33#include "hw/misc/ivshmem.h"
34
35/**
36 * Maximum number of notification vectors supported by the server
37 */
38#define IVSHMEM_SERVER_MAX_VECTORS 64
39
40/**
41 * Structure storing a peer
42 *
43 * Each time a client connects to an ivshmem server, a new
44 * IvshmemServerPeer structure is created. This peer and all its
45 * vectors are advertised to all connected clients through the connected
46 * unix sockets.
47 */
48typedef struct IvshmemServerPeer {
49 QTAILQ_ENTRY(IvshmemServerPeer) next; /**< next in list*/
50 int sock_fd; /**< connected unix sock */
51 int64_t id; /**< the id of the peer */
52 EventNotifier vectors[IVSHMEM_SERVER_MAX_VECTORS]; /**< one per vector */
53 unsigned vectors_count; /**< number of vectors */
54} IvshmemServerPeer;
55
56/**
57 * Structure describing an ivshmem server
58 *
59 * This structure stores all information related to our server: the name
60 * of the server unix socket and the list of connected peers.
61 */
62typedef struct IvshmemServer {
63 char unix_sock_path[PATH_MAX]; /**< path to unix socket */
64 int sock_fd; /**< unix sock file descriptor */
65 char shm_path[PATH_MAX]; /**< path to shm */
66 bool use_shm_open;
67 size_t shm_size; /**< size of shm */
68 int shm_fd; /**< shm file descriptor */
69 unsigned n_vectors; /**< number of vectors */
70 uint16_t cur_id; /**< id to be given to next client */
71 bool verbose; /**< true in verbose mode */
72 QTAILQ_HEAD(, IvshmemServerPeer) peer_list; /**< list of peers */
73} IvshmemServer;
74
75/**
76 * Initialize an ivshmem server
77 *
78 * @server: A pointer to an uninitialized IvshmemServer structure
79 * @unix_sock_path: The pointer to the unix socket file name
80 * @shm_path: Path to the shared memory. The path corresponds to a POSIX
81 * shm name or a hugetlbfs mount point.
82 * @shm_size: Size of shared memory
83 * @n_vectors: Number of interrupt vectors per client
84 * @verbose: True to enable verbose mode
85 *
86 * Returns: 0 on success, or a negative value on error
87 */
88int
89ivshmem_server_init(IvshmemServer *server, const char *unix_sock_path,
90 const char *shm_path, bool use_shm_open,
91 size_t shm_size, unsigned n_vectors,
92 bool verbose);
93
94/**
95 * Open the shm, then create and bind to the unix socket
96 *
97 * @server: The pointer to the initialized IvshmemServer structure
98 *
99 * Returns: 0 on success, or a negative value on error
100 */
101int ivshmem_server_start(IvshmemServer *server);
102
103/**
104 * Close the server
105 *
106 * Close connections to all clients, close the unix socket and the
107 * shared memory file descriptor. The structure remains initialized, so
108 * it is possible to call ivshmem_server_start() again after a call to
109 * ivshmem_server_close().
110 *
111 * @server: The ivshmem server
112 */
113void ivshmem_server_close(IvshmemServer *server);
114
115/**
116 * Fill a fd_set with file descriptors to be monitored
117 *
118 * This function will fill a fd_set with all file descriptors that must
119 * be polled (unix server socket and peers unix socket). The function
120 * will not initialize the fd_set, it is up to the caller to do it.
121 *
122 * @server: The ivshmem server
123 * @fds: The fd_set to be updated
124 * @maxfd: Must be set to the max file descriptor + 1 in fd_set. This value is
125 * updated if this function adds a greater fd in fd_set.
126 */
127void
128ivshmem_server_get_fds(const IvshmemServer *server, fd_set *fds, int *maxfd);
129
130/**
131 * Read and handle new messages
132 *
133 * Given a fd_set (for instance filled by a call to select()), handle
134 * incoming messages from peers.
135 *
136 * @server: The ivshmem server
137 * @fds: The fd_set containing the file descriptors to be checked. Note that
138 * file descriptors that are not related to our server are ignored.
139 * @maxfd: The maximum fd in fd_set, plus one.
140 *
141 * Returns: 0 on success, or a negative value on error
142 */
143int ivshmem_server_handle_fds(IvshmemServer *server, fd_set *fds, int maxfd);
144
145/**
146 * Search a peer from its identifier
147 *
148 * @server: The ivshmem server
149 * @peer_id: The identifier of the peer structure
150 *
151 * Returns: The peer structure, or NULL if not found
152 */
153IvshmemServerPeer *
154ivshmem_server_search_peer(IvshmemServer *server, int64_t peer_id);
155
156/**
157 * Dump information of this ivshmem server and its peers on stdout
158 *
159 * @server: The ivshmem server
160 */
161void ivshmem_server_dump(const IvshmemServer *server);
162
163#endif /* IVSHMEM_SERVER_H */
164