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