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     GCC_FMT_ATTR(2, 3);
 176
 177 /**
 178  * qemu_chr_fe_add_watch:
 179  * @cond: the condition to poll for
 180  * @func: the function to call when the condition happens
 181  * @user_data: the opaque pointer to pass to @func
 182  *
 183  * If the backend is connected, create and add a #GSource that fires
 184  * when the given condition (typically G_IO_OUT|G_IO_HUP or G_IO_HUP)
 185  * is active; return the #GSource's tag.  If it is disconnected,
 186  * or without associated Chardev, return 0.
 187  *
 188  * Note that you are responsible to update the front-end sources if
 189  * you are switching the main context with qemu_chr_fe_set_handlers().
 190  *
 191  * Returns: the source tag
 192  */
 193 guint qemu_chr_fe_add_watch(CharBackend *be, GIOCondition cond,
 194                             GIOFunc func, void *user_data);
 195
 196 /**
 197  * qemu_chr_fe_write:
 198  * @buf: the data
 199  * @len: the number of bytes to send
 200  *
 201  * Write data to a character backend from the front end.  This function
 202  * will send data from the front end to the back end.  This function
 203  * is thread-safe.
 204  *
 205  * Returns: the number of bytes consumed (0 if no associated Chardev)
 206  */
 207 int qemu_chr_fe_write(CharBackend *be, const uint8_t *buf, int len);
 208
 209 /**
 210  * qemu_chr_fe_write_all:
 211  * @buf: the data
 212  * @len: the number of bytes to send
 213  *
 214  * Write data to a character backend from the front end.  This function will
 215  * send data from the front end to the back end.  Unlike @qemu_chr_fe_write,
 216  * this function will block if the back end cannot consume all of the data
 217  * attempted to be written.  This function is thread-safe.
 218  *
 219  * Returns: the number of bytes consumed (0 if no associated Chardev)
 220  */
 221 int qemu_chr_fe_write_all(CharBackend *be, const uint8_t *buf, int len);
 222
 223 /**
 224  * qemu_chr_fe_read_all:
 225  * @buf: the data buffer
 226  * @len: the number of bytes to read
 227  *
 228  * Read data to a buffer from the back end.
 229  *
 230  * Returns: the number of bytes read (0 if no associated Chardev)
 231  */
 232 int qemu_chr_fe_read_all(CharBackend *be, uint8_t *buf, int len);
 233
 234 /**
 235  * qemu_chr_fe_ioctl:
 236  * @cmd: see CHR_IOCTL_*
 237  * @arg: the data associated with @cmd
 238  *
 239  * Issue a device specific ioctl to a backend.  This function is thread-safe.
 240  *
 241  * Returns: if @cmd is not supported by the backend or there is no
 242  *          associated Chardev, -ENOTSUP, otherwise the return
 243  *          value depends on the semantics of @cmd
 244  */
 245 int qemu_chr_fe_ioctl(CharBackend *be, int cmd, void *arg);
 246
 247 /**
 248  * qemu_chr_fe_get_msgfd:
 249  *
 250  * For backends capable of fd passing, return the latest file descriptor passed
 251  * by a client.
 252  *
 253  * Returns: -1 if fd passing isn't supported or there is no pending file
 254  *          descriptor.  If a file descriptor is returned, subsequent calls to
 255  *          this function will return -1 until a client sends a new file
 256  *          descriptor.
 257  */
 258 int qemu_chr_fe_get_msgfd(CharBackend *be);
 259
 260 /**
 261  * qemu_chr_fe_get_msgfds:
 262  *
 263  * For backends capable of fd passing, return the number of file received
 264  * descriptors and fills the fds array up to num elements
 265  *
 266  * Returns: -1 if fd passing isn't supported or there are no pending file
 267  *          descriptors.  If file descriptors are returned, subsequent calls to
 268  *          this function will return -1 until a client sends a new set of file
 269  *          descriptors.
 270  */
 271 int qemu_chr_fe_get_msgfds(CharBackend *be, int *fds, int num);
 272
 273 /**
 274  * qemu_chr_fe_set_msgfds:
 275  *
 276  * For backends capable of fd passing, set an array of fds to be passed with
 277  * the next send operation.
 278  * A subsequent call to this function before calling a write function will
 279  * result in overwriting the fd array with the new value without being send.
 280  * Upon writing the message the fd array is freed.
 281  *
 282  * Returns: -1 if fd passing isn't supported or no associated Chardev.
 283  */
 284 int qemu_chr_fe_set_msgfds(CharBackend *be, int *fds, int num);
 285
 286 #endif /* QEMU_CHAR_FE_H */