qemu/include/chardev/char-fe.h
<<
>>
Prefs
   1#ifndef QEMU_CHAR_FE_H
   2#define QEMU_CHAR_FE_H
   3
   4#include "chardev/char.h"
   5
   6typedef void IOEventHandler(void *opaque, int event);
   7typedef int BackendChangeHandler(void *opaque);
   8
   9/* This is the backend as seen by frontend, the actual backend is
  10 * Chardev */
  11struct 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 */
  31bool 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 */
  42void 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 */
  53Chardev *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 */
  60bool 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 */
  67bool 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 */
  89void 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 */
 104void 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 */
 120void 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 */
 127void 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 */
 135void 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 */
 143int 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 */
 154void 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 */
 163void 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 */
 173void 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 * Note that you are responsible to update the front-end sources if
 188 * you are switching the main context with qemu_chr_fe_set_handlers().
 189 *
 190 * Returns: the source tag
 191 */
 192guint qemu_chr_fe_add_watch(CharBackend *be, GIOCondition cond,
 193                            GIOFunc func, void *user_data);
 194
 195/**
 196 * qemu_chr_fe_write:
 197 * @buf: the data
 198 * @len: the number of bytes to send
 199 *
 200 * Write data to a character backend from the front end.  This function
 201 * will send data from the front end to the back end.  This function
 202 * is thread-safe.
 203 *
 204 * Returns: the number of bytes consumed (0 if no associated Chardev)
 205 */
 206int qemu_chr_fe_write(CharBackend *be, const uint8_t *buf, int len);
 207
 208/**
 209 * qemu_chr_fe_write_all:
 210 * @buf: the data
 211 * @len: the number of bytes to send
 212 *
 213 * Write data to a character backend from the front end.  This function will
 214 * send data from the front end to the back end.  Unlike @qemu_chr_fe_write,
 215 * this function will block if the back end cannot consume all of the data
 216 * attempted to be written.  This function is thread-safe.
 217 *
 218 * Returns: the number of bytes consumed (0 if no associated Chardev)
 219 */
 220int qemu_chr_fe_write_all(CharBackend *be, const uint8_t *buf, int len);
 221
 222/**
 223 * qemu_chr_fe_read_all:
 224 * @buf: the data buffer
 225 * @len: the number of bytes to read
 226 *
 227 * Read data to a buffer from the back end.
 228 *
 229 * Returns: the number of bytes read (0 if no associated Chardev)
 230 */
 231int qemu_chr_fe_read_all(CharBackend *be, uint8_t *buf, int len);
 232
 233/**
 234 * qemu_chr_fe_ioctl:
 235 * @cmd: see CHR_IOCTL_*
 236 * @arg: the data associated with @cmd
 237 *
 238 * Issue a device specific ioctl to a backend.  This function is thread-safe.
 239 *
 240 * Returns: if @cmd is not supported by the backend or there is no
 241 *          associated Chardev, -ENOTSUP, otherwise the return
 242 *          value depends on the semantics of @cmd
 243 */
 244int qemu_chr_fe_ioctl(CharBackend *be, int cmd, void *arg);
 245
 246/**
 247 * qemu_chr_fe_get_msgfd:
 248 *
 249 * For backends capable of fd passing, return the latest file descriptor passed
 250 * by a client.
 251 *
 252 * Returns: -1 if fd passing isn't supported or there is no pending file
 253 *          descriptor.  If a file descriptor is returned, subsequent calls to
 254 *          this function will return -1 until a client sends a new file
 255 *          descriptor.
 256 */
 257int qemu_chr_fe_get_msgfd(CharBackend *be);
 258
 259/**
 260 * qemu_chr_fe_get_msgfds:
 261 *
 262 * For backends capable of fd passing, return the number of file received
 263 * descriptors and fills the fds array up to num elements
 264 *
 265 * Returns: -1 if fd passing isn't supported or there are no pending file
 266 *          descriptors.  If file descriptors are returned, subsequent calls to
 267 *          this function will return -1 until a client sends a new set of file
 268 *          descriptors.
 269 */
 270int qemu_chr_fe_get_msgfds(CharBackend *be, int *fds, int num);
 271
 272/**
 273 * qemu_chr_fe_set_msgfds:
 274 *
 275 * For backends capable of fd passing, set an array of fds to be passed with
 276 * the next send operation.
 277 * A subsequent call to this function before calling a write function will
 278 * result in overwriting the fd array with the new value without being send.
 279 * Upon writing the message the fd array is freed.
 280 *
 281 * Returns: -1 if fd passing isn't supported or no associated Chardev.
 282 */
 283int qemu_chr_fe_set_msgfds(CharBackend *be, int *fds, int num);
 284
 285#endif /* QEMU_CHAR_FE_H */
 286