]>
git.proxmox.com Git - mirror_qemu.git/blob - include/chardev/char-fe.h
4 #include "chardev/char.h"
5 #include "qemu/main-loop.h"
7 typedef void IOEventHandler(void *opaque
, QEMUChrEvent event
);
8 typedef int BackendChangeHandler(void *opaque
);
11 * struct CharBackend - back end as seen by front end
12 * @fe_is_open: the front end is ready for IO
14 * The actual backend is Chardev
18 IOEventHandler
*chr_event
;
19 IOCanReadHandler
*chr_can_read
;
20 IOReadHandler
*chr_read
;
21 BackendChangeHandler
*chr_be_change
;
30 * Initializes a front end for the given CharBackend and
31 * Chardev. Call qemu_chr_fe_deinit() to remove the association and
34 * Returns: false on error.
36 bool qemu_chr_fe_init(CharBackend
*b
, Chardev
*s
, Error
**errp
);
41 * @del: if true, delete the chardev backend
43 * Dissociate the CharBackend from the Chardev.
45 * Safe to call without associated Chardev.
47 void qemu_chr_fe_deinit(CharBackend
*b
, bool del
);
50 * qemu_chr_fe_get_driver:
52 * Returns: the driver associated with a CharBackend or NULL if no
54 * Note: avoid this function as the driver should never be accessed directly,
55 * especially by the frontends that support chardevice hotswap.
56 * Consider qemu_chr_fe_backend_connected() to check for driver existence
58 Chardev
*qemu_chr_fe_get_driver(CharBackend
*be
);
61 * qemu_chr_fe_backend_connected:
63 * Returns: true if there is a chardevice associated with @be.
65 bool qemu_chr_fe_backend_connected(CharBackend
*be
);
68 * qemu_chr_fe_backend_open:
70 * Returns: true if chardevice associated with @be is open.
72 bool qemu_chr_fe_backend_open(CharBackend
*be
);
75 * qemu_chr_fe_set_handlers_full:
77 * @fd_can_read: callback to get the amount of data the frontend may
79 * @fd_read: callback to receive data from char
80 * @fd_event: event callback
81 * @be_change: backend change callback; passing NULL means hot backend change
82 * is not supported and will not be attempted
83 * @opaque: an opaque pointer for the callbacks
84 * @context: a main loop context or NULL for the default
85 * @set_open: whether to call qemu_chr_fe_set_open() implicitly when
86 * any of the handler is non-NULL
87 * @sync_state: whether to issue event callback with updated state
89 * Set the front end char handlers. The front end takes the focus if
90 * any of the handler is non-NULL.
92 * Without associated Chardev, nothing is changed.
94 void qemu_chr_fe_set_handlers_full(CharBackend
*b
,
95 IOCanReadHandler
*fd_can_read
,
96 IOReadHandler
*fd_read
,
97 IOEventHandler
*fd_event
,
98 BackendChangeHandler
*be_change
,
100 GMainContext
*context
,
105 * qemu_chr_fe_set_handlers:
107 * Version of qemu_chr_fe_set_handlers_full() with sync_state = true.
109 void qemu_chr_fe_set_handlers(CharBackend
*b
,
110 IOCanReadHandler
*fd_can_read
,
111 IOReadHandler
*fd_read
,
112 IOEventHandler
*fd_event
,
113 BackendChangeHandler
*be_change
,
115 GMainContext
*context
,
119 * qemu_chr_fe_take_focus:
121 * Take the focus (if the front end is muxed).
123 * Without associated Chardev, nothing is changed.
125 void qemu_chr_fe_take_focus(CharBackend
*b
);
128 * qemu_chr_fe_accept_input:
130 * Notify that the frontend is ready to receive data
132 void qemu_chr_fe_accept_input(CharBackend
*be
);
135 * qemu_chr_fe_disconnect:
137 * Close a fd accepted by character backend.
138 * Without associated Chardev, do nothing.
140 void qemu_chr_fe_disconnect(CharBackend
*be
);
143 * qemu_chr_fe_wait_connected:
145 * Wait for character backend to be connected, return < 0 on error or
146 * if no associated Chardev.
148 int qemu_chr_fe_wait_connected(CharBackend
*be
, Error
**errp
);
151 * qemu_chr_fe_set_echo:
152 * @echo: true to enable echo, false to disable echo
154 * Ask the backend to override its normal echo setting. This only really
155 * applies to the stdio backend and is used by the QMP server such that you
156 * can see what you type if you try to type QMP commands.
157 * Without associated Chardev, do nothing.
159 void qemu_chr_fe_set_echo(CharBackend
*be
, bool echo
);
162 * qemu_chr_fe_set_open:
164 * @is_open: the front end open status
166 * This is an indication that the front end is ready (or not) to begin
167 * doing I/O. Without associated Chardev, do nothing.
169 void qemu_chr_fe_set_open(CharBackend
*be
, bool is_open
);
172 * qemu_chr_fe_printf:
175 * Write to a character backend using a printf style interface. This
176 * function is thread-safe. It does nothing without associated
179 void qemu_chr_fe_printf(CharBackend
*be
, const char *fmt
, ...)
184 * FEWatchFunc: a #GSourceFunc called when any conditions requested by
185 * qemu_chr_fe_add_watch() is satisfied.
186 * @do_not_use: depending on the underlying chardev, a GIOChannel or a
187 * QIOChannel. DO NOT USE!
188 * @cond: bitwise combination of conditions watched and satisfied
189 * before calling this callback.
190 * @data: user data passed at creation to qemu_chr_fe_add_watch(). Can
193 * Returns: G_SOURCE_REMOVE if the GSource should be removed from the
194 * main loop, or G_SOURCE_CONTINUE to leave the GSource in
197 typedef gboolean (*FEWatchFunc
)(void *do_not_use
, GIOCondition condition
, void *data
);
200 * qemu_chr_fe_add_watch:
201 * @cond: the condition to poll for
202 * @func: the function to call when the condition happens
203 * @user_data: the opaque pointer to pass to @func
205 * If the backend is connected, create and add a #GSource that fires
206 * when the given condition (typically G_IO_OUT|G_IO_HUP or G_IO_HUP)
207 * is active; return the #GSource's tag. If it is disconnected,
208 * or without associated Chardev, return 0.
210 * Note that you are responsible to update the front-end sources if
211 * you are switching the main context with qemu_chr_fe_set_handlers().
213 * Warning: DO NOT use the first callback argument (it may be either
214 * a GIOChannel or a QIOChannel, depending on the underlying chardev)
216 * Returns: the source tag
218 guint
qemu_chr_fe_add_watch(CharBackend
*be
, GIOCondition cond
,
219 FEWatchFunc func
, void *user_data
);
224 * @len: the number of bytes to send
226 * Write data to a character backend from the front end. This function
227 * will send data from the front end to the back end. This function
230 * Returns: the number of bytes consumed (0 if no associated Chardev)
232 int qemu_chr_fe_write(CharBackend
*be
, const uint8_t *buf
, int len
);
235 * qemu_chr_fe_write_all:
237 * @len: the number of bytes to send
239 * Write data to a character backend from the front end. This function will
240 * send data from the front end to the back end. Unlike @qemu_chr_fe_write,
241 * this function will block if the back end cannot consume all of the data
242 * attempted to be written. This function is thread-safe.
244 * Returns: the number of bytes consumed (0 if no associated Chardev)
246 int qemu_chr_fe_write_all(CharBackend
*be
, const uint8_t *buf
, int len
);
249 * qemu_chr_fe_read_all:
250 * @buf: the data buffer
251 * @len: the number of bytes to read
253 * Read data to a buffer from the back end.
255 * Returns: the number of bytes read (0 if no associated Chardev)
257 int qemu_chr_fe_read_all(CharBackend
*be
, uint8_t *buf
, int len
);
261 * @cmd: see CHR_IOCTL_*
262 * @arg: the data associated with @cmd
264 * Issue a device specific ioctl to a backend. This function is thread-safe.
266 * Returns: if @cmd is not supported by the backend or there is no
267 * associated Chardev, -ENOTSUP, otherwise the return
268 * value depends on the semantics of @cmd
270 int qemu_chr_fe_ioctl(CharBackend
*be
, int cmd
, void *arg
);
273 * qemu_chr_fe_get_msgfd:
275 * For backends capable of fd passing, return the latest file descriptor passed
278 * Returns: -1 if fd passing isn't supported or there is no pending file
279 * descriptor. If a file descriptor is returned, subsequent calls to
280 * this function will return -1 until a client sends a new file
283 int qemu_chr_fe_get_msgfd(CharBackend
*be
);
286 * qemu_chr_fe_get_msgfds:
288 * For backends capable of fd passing, return the number of file received
289 * descriptors and fills the fds array up to num elements
291 * Returns: -1 if fd passing isn't supported or there are no pending file
292 * descriptors. If file descriptors are returned, subsequent calls to
293 * this function will return -1 until a client sends a new set of file
296 int qemu_chr_fe_get_msgfds(CharBackend
*be
, int *fds
, int num
);
299 * qemu_chr_fe_set_msgfds:
301 * For backends capable of fd passing, set an array of fds to be passed with
302 * the next send operation.
303 * A subsequent call to this function before calling a write function will
304 * result in overwriting the fd array with the new value without being send.
305 * Upon writing the message the fd array is freed.
307 * Returns: -1 if fd passing isn't supported or no associated Chardev.
309 int qemu_chr_fe_set_msgfds(CharBackend
*be
, int *fds
, int num
);
311 #endif /* QEMU_CHAR_FE_H */