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