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 accepted 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 associated Chardev.
 126  */
 127 int qemu_chr_fe_wait_connected(CharBackend *be, Error **errp);
 128
 129 /**
 130  * qemu_chr_fe_set_echo:
 131  * @echo: true to enable echo, false to disable echo
 132  *
 133  * Ask the backend to override its normal echo setting.  This only really
 134  * applies to the stdio backend and is used by the QMP server such that you
 135  * can see what you type if you try to type QMP commands.
 136  * Without associated Chardev, do nothing.
 137  */
 138 void qemu_chr_fe_set_echo(CharBackend *be, bool echo);
 139
 140 /**
 141  * qemu_chr_fe_set_open:
 142  *
 143  * Set character frontend open status.  This is an indication that the
 144  * front end is ready (or not) to begin doing I/O.
 145  * Without associated Chardev, do nothing.
 146  */
 147 void qemu_chr_fe_set_open(CharBackend *be, int fe_open);
 148
 149 /**
 150  * qemu_chr_fe_printf:
 151  * @fmt: see #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 void qemu_chr_fe_printf(CharBackend *be, const char *fmt, ...)
 158     GCC_FMT_ATTR(2, 3);
 159
 160 /**
 161  * qemu_chr_fe_add_watch:
 162  * @cond: the condition to poll for
 163  * @func: the function to call when the condition happens
 164  * @user_data: the opaque pointer to pass to @func
 165  *
 166  * If the backend is connected, create and add a #GSource that fires
 167  * when the given condition (typically G_IO_OUT|G_IO_HUP or G_IO_HUP)
 168  * is active; return the #GSource's tag.  If it is disconnected,
 169  * or without associated Chardev, return 0.
 170  *
 171  * Returns: the source tag
 172  */
 173 guint qemu_chr_fe_add_watch(CharBackend *be, GIOCondition cond,
 174                             GIOFunc func, void *user_data);
 175
 176 /**
 177  * qemu_chr_fe_write:
 178  * @buf: the data
 179  * @len: the number of bytes to send
 180  *
 181  * Write data to a character backend from the front end.  This function
 182  * will send data from the front end to the back end.  This function
 183  * is thread-safe.
 184  *
 185  * Returns: the number of bytes consumed (0 if no associated Chardev)
 186  */
 187 int qemu_chr_fe_write(CharBackend *be, const uint8_t *buf, int len);
 188
 189 /**
 190  * qemu_chr_fe_write_all:
 191  * @buf: the data
 192  * @len: the number of bytes to send
 193  *
 194  * Write data to a character backend from the front end.  This function will
 195  * send data from the front end to the back end.  Unlike @qemu_chr_fe_write,
 196  * this function will block if the back end cannot consume all of the data
 197  * attempted to be written.  This function is thread-safe.
 198  *
 199  * Returns: the number of bytes consumed (0 if no associated Chardev)
 200  */
 201 int qemu_chr_fe_write_all(CharBackend *be, const uint8_t *buf, int len);
 202
 203 /**
 204  * qemu_chr_fe_read_all:
 205  * @buf: the data buffer
 206  * @len: the number of bytes to read
 207  *
 208  * Read data to a buffer from the back end.
 209  *
 210  * Returns: the number of bytes read (0 if no associated Chardev)
 211  */
 212 int qemu_chr_fe_read_all(CharBackend *be, uint8_t *buf, int len);
 213
 214 /**
 215  * qemu_chr_fe_ioctl:
 216  * @cmd: see CHR_IOCTL_*
 217  * @arg: the data associated with @cmd
 218  *
 219  * Issue a device specific ioctl to a backend.  This function is thread-safe.
 220  *
 221  * Returns: if @cmd is not supported by the backend or there is no
 222  *          associated Chardev, -ENOTSUP, otherwise the return
 223  *          value depends on the semantics of @cmd
 224  */
 225 int qemu_chr_fe_ioctl(CharBackend *be, int cmd, void *arg);
 226
 227 /**
 228  * qemu_chr_fe_get_msgfd:
 229  *
 230  * For backends capable of fd passing, return the latest file descriptor passed
 231  * by a client.
 232  *
 233  * Returns: -1 if fd passing isn't supported or there is no pending file
 234  *          descriptor.  If a file descriptor is returned, subsequent calls to
 235  *          this function will return -1 until a client sends a new file
 236  *          descriptor.
 237  */
 238 int qemu_chr_fe_get_msgfd(CharBackend *be);
 239
 240 /**
 241  * qemu_chr_fe_get_msgfds:
 242  *
 243  * For backends capable of fd passing, return the number of file received
 244  * descriptors and fills the fds array up to num elements
 245  *
 246  * Returns: -1 if fd passing isn't supported or there are no pending file
 247  *          descriptors.  If file descriptors are returned, subsequent calls to
 248  *          this function will return -1 until a client sends a new set of file
 249  *          descriptors.
 250  */
 251 int qemu_chr_fe_get_msgfds(CharBackend *be, int *fds, int num);
 252
 253 /**
 254  * qemu_chr_fe_set_msgfds:
 255  *
 256  * For backends capable of fd passing, set an array of fds to be passed with
 257  * the next send operation.
 258  * A subsequent call to this function before calling a write function will
 259  * result in overwriting the fd array with the new value without being send.
 260  * Upon writing the message the fd array is freed.
 261  *
 262  * Returns: -1 if fd passing isn't supported or no associated Chardev.
 263  */
 264 int qemu_chr_fe_set_msgfds(CharBackend *be, int *fds, int num);
 265
 266 #endif /* QEMU_CHAR_FE_H */