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