include/chardev/char-fe.h

   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 */