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 accpeted 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 assicated Chardev. 126 */ 127 int qemu_chr_fe_wait_connected(CharBackend *be, Error **errp); 128 129 /** 130 * @qemu_chr_fe_set_echo: 131 * 132 * Ask the backend to override its normal echo setting. This only really 133 * applies to the stdio backend and is used by the QMP server such that you 134 * can see what you type if you try to type QMP commands. 135 * Without associated Chardev, do nothing. 136 * 137 * @echo true to enable echo, false to disable echo 138 */ 139 void qemu_chr_fe_set_echo(CharBackend *be, bool echo); 140 141 /** 142 * @qemu_chr_fe_set_open: 143 * 144 * Set character frontend open status. This is an indication that the 145 * front end is ready (or not) to begin doing I/O. 146 * Without associated Chardev, do nothing. 147 */ 148 void qemu_chr_fe_set_open(CharBackend *be, int fe_open); 149 150 /** 151 * @qemu_chr_fe_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 * @fmt see #printf 158 */ 159 void qemu_chr_fe_printf(CharBackend *be, const char *fmt, ...) 160 GCC_FMT_ATTR(2, 3); 161 162 /** 163 * @qemu_chr_fe_add_watch: 164 * 165 * If the backend is connected, create and add a #GSource that fires 166 * when the given condition (typically G_IO_OUT|G_IO_HUP or G_IO_HUP) 167 * is active; return the #GSource's tag. If it is disconnected, 168 * or without associated Chardev, return 0. 169 * 170 * @cond the condition to poll for 171 * @func the function to call when the condition happens 172 * @user_data the opaque pointer to pass to @func 173 * 174 * Returns: the source tag 175 */ 176 guint qemu_chr_fe_add_watch(CharBackend *be, GIOCondition cond, 177 GIOFunc func, void *user_data); 178 179 /** 180 * @qemu_chr_fe_write: 181 * 182 * Write data to a character backend from the front end. This function 183 * will send data from the front end to the back end. This function 184 * is thread-safe. 185 * 186 * @buf the data 187 * @len the number of bytes to send 188 * 189 * Returns: the number of bytes consumed (0 if no assicated Chardev) 190 */ 191 int qemu_chr_fe_write(CharBackend *be, const uint8_t *buf, int len); 192 193 /** 194 * @qemu_chr_fe_write_all: 195 * 196 * Write data to a character backend from the front end. This function will 197 * send data from the front end to the back end. Unlike @qemu_chr_fe_write, 198 * this function will block if the back end cannot consume all of the data 199 * attempted to be written. This function is thread-safe. 200 * 201 * @buf the data 202 * @len the number of bytes to send 203 * 204 * Returns: the number of bytes consumed (0 if no assicated Chardev) 205 */ 206 int qemu_chr_fe_write_all(CharBackend *be, const uint8_t *buf, int len); 207 208 /** 209 * @qemu_chr_fe_read_all: 210 * 211 * Read data to a buffer from the back end. 212 * 213 * @buf the data buffer 214 * @len the number of bytes to read 215 * 216 * Returns: the number of bytes read (0 if no assicated Chardev) 217 */ 218 int qemu_chr_fe_read_all(CharBackend *be, uint8_t *buf, int len); 219 220 /** 221 * @qemu_chr_fe_ioctl: 222 * 223 * Issue a device specific ioctl to a backend. This function is thread-safe. 224 * 225 * @cmd see CHR_IOCTL_* 226 * @arg the data associated with @cmd 227 * 228 * Returns: if @cmd is not supported by the backend or there is no 229 * associated Chardev, -ENOTSUP, otherwise the return 230 * value depends on the semantics of @cmd 231 */ 232 int qemu_chr_fe_ioctl(CharBackend *be, int cmd, void *arg); 233 234 /** 235 * @qemu_chr_fe_get_msgfd: 236 * 237 * For backends capable of fd passing, return the latest file descriptor passed 238 * by a client. 239 * 240 * Returns: -1 if fd passing isn't supported or there is no pending file 241 * descriptor. If a file descriptor is returned, subsequent calls to 242 * this function will return -1 until a client sends a new file 243 * descriptor. 244 */ 245 int qemu_chr_fe_get_msgfd(CharBackend *be); 246 247 /** 248 * @qemu_chr_fe_get_msgfds: 249 * 250 * For backends capable of fd passing, return the number of file received 251 * descriptors and fills the fds array up to num elements 252 * 253 * Returns: -1 if fd passing isn't supported or there are no pending file 254 * descriptors. If file descriptors are returned, subsequent calls to 255 * this function will return -1 until a client sends a new set of file 256 * descriptors. 257 */ 258 int qemu_chr_fe_get_msgfds(CharBackend *be, int *fds, int num); 259 260 /** 261 * @qemu_chr_fe_set_msgfds: 262 * 263 * For backends capable of fd passing, set an array of fds to be passed with 264 * the next send operation. 265 * A subsequent call to this function before calling a write function will 266 * result in overwriting the fd array with the new value without being send. 267 * Upon writing the message the fd array is freed. 268 * 269 * Returns: -1 if fd passing isn't supported or no associated Chardev. 270 */ 271 int qemu_chr_fe_set_msgfds(CharBackend *be, int *fds, int num); 272 273 #endif /* QEMU_CHAR_FE_H */ 274