include/chardev/char-fe.h

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