vl: Table-based select_vgahw()
[qemu.git] / contrib / ivshmem-client / ivshmem-client.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_CLIENT_H_
10 #define _IVSHMEM_CLIENT_H_
11
12 /**
13 * This file provides helper to implement an ivshmem client. It is used
14 * on the host to ask QEMU to send an interrupt to an ivshmem PCI device in a
15 * guest. QEMU also implements an ivshmem client similar to this one, they both
16 * connect to an ivshmem server.
17 *
18 * A standalone ivshmem client based on this file is provided for debug/test
19 * purposes.
20 */
21
22 #include <sys/select.h>
23
24 #include "qemu/queue.h"
25 #include "hw/misc/ivshmem.h"
26
27 /**
28 * Maximum number of notification vectors supported by the client
29 */
30 #define IVSHMEM_CLIENT_MAX_VECTORS 64
31
32 /**
33 * Structure storing a peer
34 *
35 * Each time a client connects to an ivshmem server, it is advertised to
36 * all connected clients through the unix socket. When our ivshmem
37 * client receives a notification, it creates a IvshmemClientPeer
38 * structure to store the infos of this peer.
39 *
40 * This structure is also used to store the information of our own
41 * client in (IvshmemClient)->local.
42 */
43 typedef struct IvshmemClientPeer {
44 QTAILQ_ENTRY(IvshmemClientPeer) next; /**< next in list*/
45 int64_t id; /**< the id of the peer */
46 int vectors[IVSHMEM_CLIENT_MAX_VECTORS]; /**< one fd per vector */
47 unsigned vectors_count; /**< number of vectors */
48 } IvshmemClientPeer;
49 QTAILQ_HEAD(IvshmemClientPeerList, IvshmemClientPeer);
50
51 typedef struct IvshmemClientPeerList IvshmemClientPeerList;
52 typedef struct IvshmemClient IvshmemClient;
53
54 /**
55 * Typedef of callback function used when our IvshmemClient receives a
56 * notification from a peer.
57 */
58 typedef void (*IvshmemClientNotifCb)(
59 const IvshmemClient *client,
60 const IvshmemClientPeer *peer,
61 unsigned vect, void *arg);
62
63 /**
64 * Structure describing an ivshmem client
65 *
66 * This structure stores all information related to our client: the name
67 * of the server unix socket, the list of peers advertised by the
68 * server, our own client information, and a pointer the notification
69 * callback function used when we receive a notification from a peer.
70 */
71 struct IvshmemClient {
72 char unix_sock_path[PATH_MAX]; /**< path to unix sock */
73 int sock_fd; /**< unix sock filedesc */
74 int shm_fd; /**< shm file descriptor */
75
76 IvshmemClientPeerList peer_list; /**< list of peers */
77 IvshmemClientPeer local; /**< our own infos */
78
79 IvshmemClientNotifCb notif_cb; /**< notification callback */
80 void *notif_arg; /**< notification argument */
81
82 bool verbose; /**< true to enable debug */
83 };
84
85 /**
86 * Initialize an ivshmem client
87 *
88 * @client: A pointer to an uninitialized IvshmemClient structure
89 * @unix_sock_path: The pointer to the unix socket file name
90 * @notif_cb: If not NULL, the pointer to the function to be called when
91 * our IvshmemClient receives a notification from a peer
92 * @notif_arg: Opaque pointer given as-is to the notification callback
93 * function
94 * @verbose: True to enable debug
95 *
96 * Returns: 0 on success, or a negative value on error
97 */
98 int ivshmem_client_init(IvshmemClient *client, const char *unix_sock_path,
99 IvshmemClientNotifCb notif_cb, void *notif_arg,
100 bool verbose);
101
102 /**
103 * Connect to the server
104 *
105 * Connect to the server unix socket, and read the first initial
106 * messages sent by the server, giving the ID of the client and the file
107 * descriptor of the shared memory.
108 *
109 * @client: The ivshmem client
110 *
111 * Returns: 0 on success, or a negative value on error
112 */
113 int ivshmem_client_connect(IvshmemClient *client);
114
115 /**
116 * Close connection to the server and free all peer structures
117 *
118 * @client: The ivshmem client
119 */
120 void ivshmem_client_close(IvshmemClient *client);
121
122 /**
123 * Fill a fd_set with file descriptors to be monitored
124 *
125 * This function will fill a fd_set with all file descriptors
126 * that must be polled (unix server socket and peers eventfd). The
127 * function will not initialize the fd_set, it is up to the caller
128 * to do this.
129 *
130 * @client: The ivshmem client
131 * @fds: The fd_set to be updated
132 * @maxfd: Must be set to the max file descriptor + 1 in fd_set. This value is
133 * updated if this function adds a greater fd in fd_set.
134 */
135 void ivshmem_client_get_fds(const IvshmemClient *client, fd_set *fds,
136 int *maxfd);
137
138 /**
139 * Read and handle new messages
140 *
141 * Given a fd_set filled by select(), handle incoming messages from
142 * server or peers.
143 *
144 * @client: The ivshmem client
145 * @fds: The fd_set containing the file descriptors to be checked. Note
146 * that file descriptors that are not related to our client are
147 * ignored.
148 * @maxfd: The maximum fd in fd_set, plus one.
149 *
150 * Returns: 0 on success, or a negative value on error
151 */
152 int ivshmem_client_handle_fds(IvshmemClient *client, fd_set *fds, int maxfd);
153
154 /**
155 * Send a notification to a vector of a peer
156 *
157 * @client: The ivshmem client
158 * @peer: The peer to be notified
159 * @vector: The number of the vector
160 *
161 * Returns: 0 on success, or a negative value on error
162 */
163 int ivshmem_client_notify(const IvshmemClient *client,
164 const IvshmemClientPeer *peer, unsigned vector);
165
166 /**
167 * Send a notification to all vectors of a peer
168 *
169 * @client: The ivshmem client
170 * @peer: The peer to be notified
171 *
172 * Returns: 0 on success, or a negative value on error (at least one
173 * notification failed)
174 */
175 int ivshmem_client_notify_all_vects(const IvshmemClient *client,
176 const IvshmemClientPeer *peer);
177
178 /**
179 * Broadcat a notification to all vectors of all peers
180 *
181 * @client: The ivshmem client
182 *
183 * Returns: 0 on success, or a negative value on error (at least one
184 * notification failed)
185 */
186 int ivshmem_client_notify_broadcast(const IvshmemClient *client);
187
188 /**
189 * Search a peer from its identifier
190 *
191 * Return the peer structure from its peer_id. If the given peer_id is
192 * the local id, the function returns the local peer structure.
193 *
194 * @client: The ivshmem client
195 * @peer_id: The identifier of the peer structure
196 *
197 * Returns: The peer structure, or NULL if not found
198 */
199 IvshmemClientPeer *
200 ivshmem_client_search_peer(IvshmemClient *client, int64_t peer_id);
201
202 /**
203 * Dump information of this ivshmem client on stdout
204 *
205 * Dump the id and the vectors of the given ivshmem client and the list
206 * of its peers and their vectors on stdout.
207 *
208 * @client: The ivshmem client
209 */
210 void ivshmem_client_dump(const IvshmemClient *client);
211
212 #endif /* _IVSHMEM_CLIENT_H_ */