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