1 | #ifndef QEMU_CHAR_FE_H |
2 | #define QEMU_CHAR_FE_H |
3 | |
4 | #include "chardev/char.h" |
5 | #include "qemu/main-loop.h" |
6 | |
7 | typedef void IOEventHandler(void *opaque, int event); |
8 | typedef int BackendChangeHandler(void *opaque); |
9 | |
10 | /* This is the backend as seen by frontend, the actual backend is |
11 | * Chardev */ |
12 | struct CharBackend { |
13 | Chardev *chr; |
14 | IOEventHandler *chr_event; |
15 | IOCanReadHandler *chr_can_read; |
16 | IOReadHandler *chr_read; |
17 | BackendChangeHandler *chr_be_change; |
18 | void *opaque; |
19 | int tag; |
20 | int fe_open; |
21 | }; |
22 | |
23 | /** |
24 | * qemu_chr_fe_init: |
25 | * |
26 | * Initializes a front end for the given CharBackend and |
27 | * Chardev. Call qemu_chr_fe_deinit() to remove the association and |
28 | * release the driver. |
29 | * |
30 | * Returns: false on error. |
31 | */ |
32 | bool qemu_chr_fe_init(CharBackend *b, Chardev *s, Error **errp); |
33 | |
34 | /** |
35 | * qemu_chr_fe_deinit: |
36 | * @b: a CharBackend |
37 | * @del: if true, delete the chardev backend |
38 | * |
39 | * Dissociate the CharBackend from the Chardev. |
40 | * |
41 | * Safe to call without associated Chardev. |
42 | */ |
43 | void qemu_chr_fe_deinit(CharBackend *b, bool del); |
44 | |
45 | /** |
46 | * qemu_chr_fe_get_driver: |
47 | * |
48 | * Returns: the driver associated with a CharBackend or NULL if no |
49 | * associated Chardev. |
50 | * Note: avoid this function as the driver should never be accessed directly, |
51 | * especially by the frontends that support chardevice hotswap. |
52 | * Consider qemu_chr_fe_backend_connected() to check for driver existence |
53 | */ |
54 | Chardev *qemu_chr_fe_get_driver(CharBackend *be); |
55 | |
56 | /** |
57 | * qemu_chr_fe_backend_connected: |
58 | * |
59 | * Returns: true if there is a chardevice associated with @be. |
60 | */ |
61 | bool qemu_chr_fe_backend_connected(CharBackend *be); |
62 | |
63 | /** |
64 | * qemu_chr_fe_backend_open: |
65 | * |
66 | * Returns: true if chardevice associated with @be is open. |
67 | */ |
68 | bool qemu_chr_fe_backend_open(CharBackend *be); |
69 | |
70 | /** |
71 | * qemu_chr_fe_set_handlers_full: |
72 | * @b: a CharBackend |
73 | * @fd_can_read: callback to get the amount of data the frontend may |
74 | * receive |
75 | * @fd_read: callback to receive data from char |
76 | * @fd_event: event callback |
77 | * @be_change: backend change callback; passing NULL means hot backend change |
78 | * is not supported and will not be attempted |
79 | * @opaque: an opaque pointer for the callbacks |
80 | * @context: a main loop context or NULL for the default |
81 | * @set_open: whether to call qemu_chr_fe_set_open() implicitely when |
82 | * any of the handler is non-NULL |
83 | * @sync_state: whether to issue event callback with updated state |
84 | * |
85 | * Set the front end char handlers. The front end takes the focus if |
86 | * any of the handler is non-NULL. |
87 | * |
88 | * Without associated Chardev, nothing is changed. |
89 | */ |
90 | void qemu_chr_fe_set_handlers_full(CharBackend *b, |
91 | IOCanReadHandler *fd_can_read, |
92 | IOReadHandler *fd_read, |
93 | IOEventHandler *fd_event, |
94 | BackendChangeHandler *be_change, |
95 | void *opaque, |
96 | GMainContext *context, |
97 | bool set_open, |
98 | bool sync_state); |
99 | |
100 | /** |
101 | * qemu_chr_fe_set_handlers: |
102 | * |
103 | * Version of qemu_chr_fe_set_handlers_full() with sync_state = true. |
104 | */ |
105 | void qemu_chr_fe_set_handlers(CharBackend *b, |
106 | IOCanReadHandler *fd_can_read, |
107 | IOReadHandler *fd_read, |
108 | IOEventHandler *fd_event, |
109 | BackendChangeHandler *be_change, |
110 | void *opaque, |
111 | GMainContext *context, |
112 | bool set_open); |
113 | |
114 | /** |
115 | * qemu_chr_fe_take_focus: |
116 | * |
117 | * Take the focus (if the front end is muxed). |
118 | * |
119 | * Without associated Chardev, nothing is changed. |
120 | */ |
121 | void qemu_chr_fe_take_focus(CharBackend *b); |
122 | |
123 | /** |
124 | * qemu_chr_fe_accept_input: |
125 | * |
126 | * Notify that the frontend is ready to receive data |
127 | */ |
128 | void qemu_chr_fe_accept_input(CharBackend *be); |
129 | |
130 | /** |
131 | * qemu_chr_fe_disconnect: |
132 | * |
133 | * Close a fd accepted by character backend. |
134 | * Without associated Chardev, do nothing. |
135 | */ |
136 | void qemu_chr_fe_disconnect(CharBackend *be); |
137 | |
138 | /** |
139 | * qemu_chr_fe_wait_connected: |
140 | * |
141 | * Wait for characted backend to be connected, return < 0 on error or |
142 | * if no associated Chardev. |
143 | */ |
144 | int qemu_chr_fe_wait_connected(CharBackend *be, Error **errp); |
145 | |
146 | /** |
147 | * qemu_chr_fe_set_echo: |
148 | * @echo: true to enable echo, false to disable echo |
149 | * |
150 | * Ask the backend to override its normal echo setting. This only really |
151 | * applies to the stdio backend and is used by the QMP server such that you |
152 | * can see what you type if you try to type QMP commands. |
153 | * Without associated Chardev, do nothing. |
154 | */ |
155 | void qemu_chr_fe_set_echo(CharBackend *be, bool echo); |
156 | |
157 | /** |
158 | * qemu_chr_fe_set_open: |
159 | * |
160 | * Set character frontend open status. This is an indication that the |
161 | * front end is ready (or not) to begin doing I/O. |
162 | * Without associated Chardev, do nothing. |
163 | */ |
164 | void qemu_chr_fe_set_open(CharBackend *be, int fe_open); |
165 | |
166 | /** |
167 | * qemu_chr_fe_printf: |
168 | * @fmt: see #printf |
169 | * |
170 | * Write to a character backend using a printf style interface. This |
171 | * function is thread-safe. It does nothing without associated |
172 | * Chardev. |
173 | */ |
174 | void qemu_chr_fe_printf(CharBackend *be, const char *fmt, ...) |
175 | GCC_FMT_ATTR(2, 3); |
176 | |
177 | /** |
178 | * qemu_chr_fe_add_watch: |
179 | * @cond: the condition to poll for |
180 | * @func: the function to call when the condition happens |
181 | * @user_data: the opaque pointer to pass to @func |
182 | * |
183 | * If the backend is connected, create and add a #GSource that fires |
184 | * when the given condition (typically G_IO_OUT|G_IO_HUP or G_IO_HUP) |
185 | * is active; return the #GSource's tag. If it is disconnected, |
186 | * or without associated Chardev, return 0. |
187 | * |
188 | * Note that you are responsible to update the front-end sources if |
189 | * you are switching the main context with qemu_chr_fe_set_handlers(). |
190 | * |
191 | * Returns: the source tag |
192 | */ |
193 | guint qemu_chr_fe_add_watch(CharBackend *be, GIOCondition cond, |
194 | GIOFunc func, void *user_data); |
195 | |
196 | /** |
197 | * qemu_chr_fe_write: |
198 | * @buf: the data |
199 | * @len: the number of bytes to send |
200 | * |
201 | * Write data to a character backend from the front end. This function |
202 | * will send data from the front end to the back end. This function |
203 | * is thread-safe. |
204 | * |
205 | * Returns: the number of bytes consumed (0 if no associated Chardev) |
206 | */ |
207 | int qemu_chr_fe_write(CharBackend *be, const uint8_t *buf, int len); |
208 | |
209 | /** |
210 | * qemu_chr_fe_write_all: |
211 | * @buf: the data |
212 | * @len: the number of bytes to send |
213 | * |
214 | * Write data to a character backend from the front end. This function will |
215 | * send data from the front end to the back end. Unlike @qemu_chr_fe_write, |
216 | * this function will block if the back end cannot consume all of the data |
217 | * attempted to be written. This function is thread-safe. |
218 | * |
219 | * Returns: the number of bytes consumed (0 if no associated Chardev) |
220 | */ |
221 | int qemu_chr_fe_write_all(CharBackend *be, const uint8_t *buf, int len); |
222 | |
223 | /** |
224 | * qemu_chr_fe_read_all: |
225 | * @buf: the data buffer |
226 | * @len: the number of bytes to read |
227 | * |
228 | * Read data to a buffer from the back end. |
229 | * |
230 | * Returns: the number of bytes read (0 if no associated Chardev) |
231 | */ |
232 | int qemu_chr_fe_read_all(CharBackend *be, uint8_t *buf, int len); |
233 | |
234 | /** |
235 | * qemu_chr_fe_ioctl: |
236 | * @cmd: see CHR_IOCTL_* |
237 | * @arg: the data associated with @cmd |
238 | * |
239 | * Issue a device specific ioctl to a backend. This function is thread-safe. |
240 | * |
241 | * Returns: if @cmd is not supported by the backend or there is no |
242 | * associated Chardev, -ENOTSUP, otherwise the return |
243 | * value depends on the semantics of @cmd |
244 | */ |
245 | int qemu_chr_fe_ioctl(CharBackend *be, int cmd, void *arg); |
246 | |
247 | /** |
248 | * qemu_chr_fe_get_msgfd: |
249 | * |
250 | * For backends capable of fd passing, return the latest file descriptor passed |
251 | * by a client. |
252 | * |
253 | * Returns: -1 if fd passing isn't supported or there is no pending file |
254 | * descriptor. If a file descriptor is returned, subsequent calls to |
255 | * this function will return -1 until a client sends a new file |
256 | * descriptor. |
257 | */ |
258 | int qemu_chr_fe_get_msgfd(CharBackend *be); |
259 | |
260 | /** |
261 | * qemu_chr_fe_get_msgfds: |
262 | * |
263 | * For backends capable of fd passing, return the number of file received |
264 | * descriptors and fills the fds array up to num elements |
265 | * |
266 | * Returns: -1 if fd passing isn't supported or there are no pending file |
267 | * descriptors. If file descriptors are returned, subsequent calls to |
268 | * this function will return -1 until a client sends a new set of file |
269 | * descriptors. |
270 | */ |
271 | int qemu_chr_fe_get_msgfds(CharBackend *be, int *fds, int num); |
272 | |
273 | /** |
274 | * qemu_chr_fe_set_msgfds: |
275 | * |
276 | * For backends capable of fd passing, set an array of fds to be passed with |
277 | * the next send operation. |
278 | * A subsequent call to this function before calling a write function will |
279 | * result in overwriting the fd array with the new value without being send. |
280 | * Upon writing the message the fd array is freed. |
281 | * |
282 | * Returns: -1 if fd passing isn't supported or no associated Chardev. |
283 | */ |
284 | int qemu_chr_fe_set_msgfds(CharBackend *be, int *fds, int num); |
285 | |
286 | #endif /* QEMU_CHAR_FE_H */ |
287 | |