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