char-fe.h (9287B)
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, QEMUChrEvent 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 G_GNUC_PRINTF(2, 3); 176 177 178 typedef gboolean (*FEWatchFunc)(void *do_not_use, GIOCondition condition, void *data); 179 180 /** 181 * qemu_chr_fe_add_watch: 182 * @cond: the condition to poll for 183 * @func: the function to call when the condition happens 184 * @user_data: the opaque pointer to pass to @func 185 * 186 * If the backend is connected, create and add a #GSource that fires 187 * when the given condition (typically G_IO_OUT|G_IO_HUP or G_IO_HUP) 188 * is active; return the #GSource's tag. If it is disconnected, 189 * or without associated Chardev, return 0. 190 * 191 * Note that you are responsible to update the front-end sources if 192 * you are switching the main context with qemu_chr_fe_set_handlers(). 193 * 194 * Warning: DO NOT use the first callback argument (it may be either 195 * a GIOChannel or a QIOChannel, depending on the underlying chardev) 196 * 197 * Returns: the source tag 198 */ 199 guint qemu_chr_fe_add_watch(CharBackend *be, GIOCondition cond, 200 FEWatchFunc func, void *user_data); 201 202 /** 203 * qemu_chr_fe_write: 204 * @buf: the data 205 * @len: the number of bytes to send 206 * 207 * Write data to a character backend from the front end. This function 208 * will send data from the front end to the back end. This function 209 * is thread-safe. 210 * 211 * Returns: the number of bytes consumed (0 if no associated Chardev) 212 */ 213 int qemu_chr_fe_write(CharBackend *be, const uint8_t *buf, int len); 214 215 /** 216 * qemu_chr_fe_write_all: 217 * @buf: the data 218 * @len: the number of bytes to send 219 * 220 * Write data to a character backend from the front end. This function will 221 * send data from the front end to the back end. Unlike @qemu_chr_fe_write, 222 * this function will block if the back end cannot consume all of the data 223 * attempted to be written. This function is thread-safe. 224 * 225 * Returns: the number of bytes consumed (0 if no associated Chardev) 226 */ 227 int qemu_chr_fe_write_all(CharBackend *be, const uint8_t *buf, int len); 228 229 /** 230 * qemu_chr_fe_read_all: 231 * @buf: the data buffer 232 * @len: the number of bytes to read 233 * 234 * Read data to a buffer from the back end. 235 * 236 * Returns: the number of bytes read (0 if no associated Chardev) 237 */ 238 int qemu_chr_fe_read_all(CharBackend *be, uint8_t *buf, int len); 239 240 /** 241 * qemu_chr_fe_ioctl: 242 * @cmd: see CHR_IOCTL_* 243 * @arg: the data associated with @cmd 244 * 245 * Issue a device specific ioctl to a backend. This function is thread-safe. 246 * 247 * Returns: if @cmd is not supported by the backend or there is no 248 * associated Chardev, -ENOTSUP, otherwise the return 249 * value depends on the semantics of @cmd 250 */ 251 int qemu_chr_fe_ioctl(CharBackend *be, int cmd, void *arg); 252 253 /** 254 * qemu_chr_fe_get_msgfd: 255 * 256 * For backends capable of fd passing, return the latest file descriptor passed 257 * by a client. 258 * 259 * Returns: -1 if fd passing isn't supported or there is no pending file 260 * descriptor. If a file descriptor is returned, subsequent calls to 261 * this function will return -1 until a client sends a new file 262 * descriptor. 263 */ 264 int qemu_chr_fe_get_msgfd(CharBackend *be); 265 266 /** 267 * qemu_chr_fe_get_msgfds: 268 * 269 * For backends capable of fd passing, return the number of file received 270 * descriptors and fills the fds array up to num elements 271 * 272 * Returns: -1 if fd passing isn't supported or there are no pending file 273 * descriptors. If file descriptors are returned, subsequent calls to 274 * this function will return -1 until a client sends a new set of file 275 * descriptors. 276 */ 277 int qemu_chr_fe_get_msgfds(CharBackend *be, int *fds, int num); 278 279 /** 280 * qemu_chr_fe_set_msgfds: 281 * 282 * For backends capable of fd passing, set an array of fds to be passed with 283 * the next send operation. 284 * A subsequent call to this function before calling a write function will 285 * result in overwriting the fd array with the new value without being send. 286 * Upon writing the message the fd array is freed. 287 * 288 * Returns: -1 if fd passing isn't supported or no associated Chardev. 289 */ 290 int qemu_chr_fe_set_msgfds(CharBackend *be, int *fds, int num); 291 292 #endif /* QEMU_CHAR_FE_H */