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: 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 * 83 * Set the front end char handlers. The front end takes the focus if 84 * any of the handler is non-NULL. 85 * 86 * Without associated Chardev, nothing is changed. 87 */ 88 void qemu_chr_fe_set_handlers(CharBackend *b, 89 IOCanReadHandler *fd_can_read, 90 IOReadHandler *fd_read, 91 IOEventHandler *fd_event, 92 BackendChangeHandler *be_change, 93 void *opaque, 94 GMainContext *context, 95 bool set_open); 96 97 /** 98 * qemu_chr_fe_take_focus: 99 * 100 * Take the focus (if the front end is muxed). 101 * 102 * Without associated Chardev, nothing is changed. 103 */ 104 void qemu_chr_fe_take_focus(CharBackend *b); 105 106 /** 107 * qemu_chr_fe_accept_input: 108 * 109 * Notify that the frontend is ready to receive data 110 */ 111 void qemu_chr_fe_accept_input(CharBackend *be); 112 113 /** 114 * qemu_chr_fe_disconnect: 115 * 116 * Close a fd accepted by character backend. 117 * Without associated Chardev, do nothing. 118 */ 119 void qemu_chr_fe_disconnect(CharBackend *be); 120 121 /** 122 * qemu_chr_fe_wait_connected: 123 * 124 * Wait for characted backend to be connected, return < 0 on error or 125 * if no associated Chardev. 126 */ 127 int qemu_chr_fe_wait_connected(CharBackend *be, Error **errp); 128 129 /** 130 * qemu_chr_fe_set_echo: 131 * @echo: true to enable echo, false to disable echo 132 * 133 * Ask the backend to override its normal echo setting. This only really 134 * applies to the stdio backend and is used by the QMP server such that you 135 * can see what you type if you try to type QMP commands. 136 * Without associated Chardev, do nothing. 137 */ 138 void qemu_chr_fe_set_echo(CharBackend *be, bool echo); 139 140 /** 141 * qemu_chr_fe_set_open: 142 * 143 * Set character frontend open status. This is an indication that the 144 * front end is ready (or not) to begin doing I/O. 145 * Without associated Chardev, do nothing. 146 */ 147 void qemu_chr_fe_set_open(CharBackend *be, int fe_open); 148 149 /** 150 * qemu_chr_fe_printf: 151 * @fmt: see #printf 152 * 153 * Write to a character backend using a printf style interface. This 154 * function is thread-safe. It does nothing without associated 155 * Chardev. 156 */ 157 void qemu_chr_fe_printf(CharBackend *be, const char *fmt, ...) 158 GCC_FMT_ATTR(2, 3); 159 160 /** 161 * qemu_chr_fe_add_watch: 162 * @cond: the condition to poll for 163 * @func: the function to call when the condition happens 164 * @user_data: the opaque pointer to pass to @func 165 * 166 * If the backend is connected, create and add a #GSource that fires 167 * when the given condition (typically G_IO_OUT|G_IO_HUP or G_IO_HUP) 168 * is active; return the #GSource's tag. If it is disconnected, 169 * or without associated Chardev, return 0. 170 * 171 * Returns: the source tag 172 */ 173 guint qemu_chr_fe_add_watch(CharBackend *be, GIOCondition cond, 174 GIOFunc func, void *user_data); 175 176 /** 177 * qemu_chr_fe_write: 178 * @buf: the data 179 * @len: the number of bytes to send 180 * 181 * Write data to a character backend from the front end. This function 182 * will send data from the front end to the back end. This function 183 * is thread-safe. 184 * 185 * Returns: the number of bytes consumed (0 if no associated Chardev) 186 */ 187 int qemu_chr_fe_write(CharBackend *be, const uint8_t *buf, int len); 188 189 /** 190 * qemu_chr_fe_write_all: 191 * @buf: the data 192 * @len: the number of bytes to send 193 * 194 * Write data to a character backend from the front end. This function will 195 * send data from the front end to the back end. Unlike @qemu_chr_fe_write, 196 * this function will block if the back end cannot consume all of the data 197 * attempted to be written. This function is thread-safe. 198 * 199 * Returns: the number of bytes consumed (0 if no associated Chardev) 200 */ 201 int qemu_chr_fe_write_all(CharBackend *be, const uint8_t *buf, int len); 202 203 /** 204 * qemu_chr_fe_read_all: 205 * @buf: the data buffer 206 * @len: the number of bytes to read 207 * 208 * Read data to a buffer from the back end. 209 * 210 * Returns: the number of bytes read (0 if no associated Chardev) 211 */ 212 int qemu_chr_fe_read_all(CharBackend *be, uint8_t *buf, int len); 213 214 /** 215 * qemu_chr_fe_ioctl: 216 * @cmd: see CHR_IOCTL_* 217 * @arg: the data associated with @cmd 218 * 219 * Issue a device specific ioctl to a backend. This function is thread-safe. 220 * 221 * Returns: if @cmd is not supported by the backend or there is no 222 * associated Chardev, -ENOTSUP, otherwise the return 223 * value depends on the semantics of @cmd 224 */ 225 int qemu_chr_fe_ioctl(CharBackend *be, int cmd, void *arg); 226 227 /** 228 * qemu_chr_fe_get_msgfd: 229 * 230 * For backends capable of fd passing, return the latest file descriptor passed 231 * by a client. 232 * 233 * Returns: -1 if fd passing isn't supported or there is no pending file 234 * descriptor. If a file descriptor is returned, subsequent calls to 235 * this function will return -1 until a client sends a new file 236 * descriptor. 237 */ 238 int qemu_chr_fe_get_msgfd(CharBackend *be); 239 240 /** 241 * qemu_chr_fe_get_msgfds: 242 * 243 * For backends capable of fd passing, return the number of file received 244 * descriptors and fills the fds array up to num elements 245 * 246 * Returns: -1 if fd passing isn't supported or there are no pending file 247 * descriptors. If file descriptors are returned, subsequent calls to 248 * this function will return -1 until a client sends a new set of file 249 * descriptors. 250 */ 251 int qemu_chr_fe_get_msgfds(CharBackend *be, int *fds, int num); 252 253 /** 254 * qemu_chr_fe_set_msgfds: 255 * 256 * For backends capable of fd passing, set an array of fds to be passed with 257 * the next send operation. 258 * A subsequent call to this function before calling a write function will 259 * result in overwriting the fd array with the new value without being send. 260 * Upon writing the message the fd array is freed. 261 * 262 * Returns: -1 if fd passing isn't supported or no associated Chardev. 263 */ 264 int qemu_chr_fe_set_msgfds(CharBackend *be, int *fds, int num); 265 266 #endif /* QEMU_CHAR_FE_H */ 267