blob: 01df55f9e8c8da5dfd40cafa195cfa606e172fb7 [file] [log] [blame]
pbrook87ecb682007-11-17 17:14:51 +00001#ifndef QEMU_CHAR_H
2#define QEMU_CHAR_H
3
Markus Armbruster9af23982018-02-11 10:36:01 +01004#include "qapi/qapi-types-char.h"
Daniel P. Berrange0a733362016-10-07 13:18:34 +01005#include "qemu/bitmap.h"
Markus Armbrusterdb725812019-08-12 07:23:50 +02006#include "qemu/thread.h"
Marc-André Lureau777357d2016-12-07 18:39:10 +03007#include "qom/object.h"
aliguori376253e2009-03-05 23:01:23 +00008
Jing Liuae92cbd2016-09-23 08:06:11 +02009#define IAC_EOR 239
10#define IAC_SE 240
11#define IAC_NOP 241
12#define IAC_BREAK 243
13#define IAC_IP 244
14#define IAC_SB 250
15#define IAC 255
16
pbrook87ecb682007-11-17 17:14:51 +000017/* character device */
Marc-André Lureau4d43a602017-01-26 18:26:44 +040018typedef struct CharBackend CharBackend;
pbrook87ecb682007-11-17 17:14:51 +000019
Marc-André Lureau8c260cb2016-10-22 13:09:39 +030020typedef enum {
21 CHR_EVENT_BREAK, /* serial break char */
22 CHR_EVENT_OPENED, /* new connection established */
23 CHR_EVENT_MUX_IN, /* mux-focus was set to this terminal */
24 CHR_EVENT_MUX_OUT, /* mux-focus will move on */
Peter Xud8861012018-06-20 15:32:17 +080025 CHR_EVENT_CLOSED /* connection closed. NOTE: currently this event
26 * is only bound to the read port of the chardev.
27 * Normally the read port and write port of a
28 * chardev should be the same, but it can be
29 * different, e.g., for fd chardevs, when the two
30 * fds are different. So when we received the
31 * CLOSED event it's still possible that the out
32 * port is still open. TODO: we should only send
33 * the CLOSED event when both ports are closed.
34 */
Marc-André Lureau8c260cb2016-10-22 13:09:39 +030035} QEMUChrEvent;
pbrook87ecb682007-11-17 17:14:51 +000036
Marc-André Lureauf6121432016-12-12 16:39:35 +030037#define CHR_READ_BUF_LEN 4096
pbrook87ecb682007-11-17 17:14:51 +000038
Daniel P. Berrange0a733362016-10-07 13:18:34 +010039typedef enum {
40 /* Whether the chardev peer is able to close and
41 * reopen the data channel, thus requiring support
42 * for qemu_chr_wait_connected() to wait for a
43 * valid connection */
44 QEMU_CHAR_FEATURE_RECONNECTABLE,
45 /* Whether it is possible to send/recv file descriptors
46 * over the data channel */
47 QEMU_CHAR_FEATURE_FD_PASS,
Marc-André Lureau5ebd6702016-10-21 22:58:45 +030048 /* Whether replay or record mode is enabled */
49 QEMU_CHAR_FEATURE_REPLAY,
Marc-André Lureau9ac37882018-12-06 00:37:33 +040050 /* Whether the gcontext can be changed after calling
51 * qemu_chr_be_update_read_handlers() */
52 QEMU_CHAR_FEATURE_GCONTEXT,
Daniel P. Berrange0a733362016-10-07 13:18:34 +010053
54 QEMU_CHAR_FEATURE_LAST,
Marc-André Lureau279b0662016-12-14 13:27:58 +030055} ChardevFeature;
Daniel P. Berrange0a733362016-10-07 13:18:34 +010056
Marc-André Lureau4d43a602017-01-26 18:26:44 +040057#define qemu_chr_replay(chr) qemu_chr_has_feature(chr, QEMU_CHAR_FEATURE_REPLAY)
Daniel P. Berrange0a733362016-10-07 13:18:34 +010058
Marc-André Lureau0ec7b3e2016-12-07 16:20:22 +030059struct Chardev {
Marc-André Lureau777357d2016-12-07 18:39:10 +030060 Object parent_obj;
61
Paolo Bonzini9005b2a2014-06-18 08:43:58 +020062 QemuMutex chr_write_lock;
Marc-André Lureaua4afa542016-10-22 12:53:01 +030063 CharBackend *be;
aliguori5ccfae12008-10-31 17:31:29 +000064 char *label;
65 char *filename;
Daniel P. Berranged0d77082016-01-11 12:44:41 +000066 int logfd;
Hans de Goede16665b92013-03-26 11:07:53 +010067 int be_open;
Lukas Straubfeb774c2021-03-30 20:13:31 +020068 /* used to coordinate the chardev-change special-case: */
69 bool handover_yank_instance;
zhanghailiangb19456d2017-04-19 09:15:32 +080070 GSource *gsource;
Peter Xu95eeeba2017-09-21 14:35:52 +080071 GMainContext *gcontext;
Daniel P. Berrange0a733362016-10-07 13:18:34 +010072 DECLARE_BITMAP(features, QEMU_CHAR_FEATURE_LAST);
pbrook87ecb682007-11-17 17:14:51 +000073};
74
Anthony Liguori2011fe52011-08-15 11:17:41 -050075/**
Marc-André Lureau56625762018-08-24 16:22:47 +020076 * qemu_chr_new_from_opts:
77 * @opts: see qemu-config.c for a list of valid options
Paolo Bonzini4ad6f6c2019-02-13 14:18:13 +010078 * @context: the #GMainContext to be used at initialization time
Anthony Liguori2011fe52011-08-15 11:17:41 -050079 *
80 * Create a new character backend from a QemuOpts list.
81 *
Anton Nefedov0ec846b2017-07-25 13:04:41 +030082 * Returns: on success: a new character backend
83 * otherwise: NULL; @errp specifies the error
84 * or left untouched in case of help option
Anthony Liguori2011fe52011-08-15 11:17:41 -050085 */
Marc-André Lureau0ec7b3e2016-12-07 16:20:22 +030086Chardev *qemu_chr_new_from_opts(QemuOpts *opts,
Paolo Bonzini4ad6f6c2019-02-13 14:18:13 +010087 GMainContext *context,
Marc-André Lureau0ec7b3e2016-12-07 16:20:22 +030088 Error **errp);
Anthony Liguori2011fe52011-08-15 11:17:41 -050089
90/**
Marc-André Lureau56625762018-08-24 16:22:47 +020091 * qemu_chr_parse_common:
92 * @opts: the options that still need parsing
93 * @backend: a new backend
Eric Blake21a933e2016-02-19 17:19:31 -070094 *
95 * Parse the common options available to all character backends.
Eric Blake21a933e2016-02-19 17:19:31 -070096 */
97void qemu_chr_parse_common(QemuOpts *opts, ChardevCommon *backend);
98
99/**
Marc-André Lureau56625762018-08-24 16:22:47 +0200100 * qemu_chr_parse_opts:
Anton Nefedov75b60162017-07-06 15:08:57 +0300101 *
102 * Parse the options to the ChardevBackend struct.
103 *
104 * Returns: a new backend or NULL on error
105 */
106ChardevBackend *qemu_chr_parse_opts(QemuOpts *opts,
107 Error **errp);
108
109/**
Marc-André Lureau56625762018-08-24 16:22:47 +0200110 * qemu_chr_new:
111 * @label: the name of the backend
112 * @filename: the URI
Paolo Bonzini4ad6f6c2019-02-13 14:18:13 +0100113 * @context: the #GMainContext to be used at initialization time
Anthony Liguori2011fe52011-08-15 11:17:41 -0500114 *
115 * Create a new character backend from a URI.
Marc-André Lureau95e30b22018-08-22 19:19:42 +0200116 * Do not implicitly initialize a monitor if the chardev is muxed.
Anthony Liguori2011fe52011-08-15 11:17:41 -0500117 *
Anthony Liguori2011fe52011-08-15 11:17:41 -0500118 * Returns: a new character backend
119 */
Paolo Bonzini4ad6f6c2019-02-13 14:18:13 +0100120Chardev *qemu_chr_new(const char *label, const char *filename,
121 GMainContext *context);
Marc-André Lureau94a40fc2016-10-22 12:52:49 +0300122
Anthony Liguori2011fe52011-08-15 11:17:41 -0500123/**
Marc-André Lureau95e30b22018-08-22 19:19:42 +0200124 * qemu_chr_new_mux_mon:
125 * @label: the name of the backend
126 * @filename: the URI
Paolo Bonzini4ad6f6c2019-02-13 14:18:13 +0100127 * @context: the #GMainContext to be used at initialization time
Marc-André Lureau95e30b22018-08-22 19:19:42 +0200128 *
129 * Create a new character backend from a URI.
130 * Implicitly initialize a monitor if the chardev is muxed.
131 *
132 * Returns: a new character backend
133 */
Paolo Bonzini4ad6f6c2019-02-13 14:18:13 +0100134Chardev *qemu_chr_new_mux_mon(const char *label, const char *filename,
135 GMainContext *context);
Marc-André Lureau95e30b22018-08-22 19:19:42 +0200136
137/**
138* qemu_chr_change:
139* @opts: the new backend options
Anton Nefedov7bb86082017-07-06 15:08:50 +0300140 *
141 * Change an existing character backend
Anton Nefedov7bb86082017-07-06 15:08:50 +0300142 */
143void qemu_chr_change(QemuOpts *opts, Error **errp);
144
145/**
Marc-André Lureau56625762018-08-24 16:22:47 +0200146 * qemu_chr_cleanup:
Marc-André Lureauaa5cb7f2016-07-04 17:38:23 +0200147 *
148 * Delete all chardevs (when leaving qemu)
149 */
150void qemu_chr_cleanup(void);
151
152/**
Marc-André Lureau56625762018-08-24 16:22:47 +0200153 * qemu_chr_new_noreplay:
154 * @label: the name of the backend
155 * @filename: the URI
Marc-André Lureau95e30b22018-08-22 19:19:42 +0200156 * @permit_mux_mon: if chardev is muxed, initialize a monitor
Paolo Bonzini4ad6f6c2019-02-13 14:18:13 +0100157 * @context: the #GMainContext to be used at initialization time
Pavel Dovgalyuk33577b42016-03-14 10:44:36 +0300158 *
159 * Create a new character backend from a URI.
160 * Character device communications are not written
161 * into the replay log.
162 *
Pavel Dovgalyuk33577b42016-03-14 10:44:36 +0300163 * Returns: a new character backend
164 */
Marc-André Lureau95e30b22018-08-22 19:19:42 +0200165Chardev *qemu_chr_new_noreplay(const char *label, const char *filename,
Paolo Bonzini4ad6f6c2019-02-13 14:18:13 +0100166 bool permit_mux_mon, GMainContext *context);
Pavel Dovgalyuk33577b42016-03-14 10:44:36 +0300167
168/**
Marc-André Lureau56625762018-08-24 16:22:47 +0200169 * qemu_chr_be_can_write:
Anthony Liguori2011fe52011-08-15 11:17:41 -0500170 *
171 * Determine how much data the front end can currently accept. This function
172 * returns the number of bytes the front end can accept. If it returns 0, the
173 * front end cannot receive data at the moment. The function must be polled
174 * to determine when data can be received.
175 *
176 * Returns: the number of bytes the front end can receive via @qemu_chr_be_write
177 */
Marc-André Lureau0ec7b3e2016-12-07 16:20:22 +0300178int qemu_chr_be_can_write(Chardev *s);
Anthony Liguori2011fe52011-08-15 11:17:41 -0500179
180/**
Marc-André Lureau56625762018-08-24 16:22:47 +0200181 * qemu_chr_be_write:
182 * @buf: a buffer to receive data from the front end
183 * @len: the number of bytes to receive from the front end
Anthony Liguori2011fe52011-08-15 11:17:41 -0500184 *
185 * Write data from the back end to the front end. Before issuing this call,
186 * the caller should call @qemu_chr_be_can_write to determine how much data
187 * the front end can currently accept.
Anthony Liguori2011fe52011-08-15 11:17:41 -0500188 */
Arwed Meyer8f9abdf2022-09-11 20:18:37 +0200189void qemu_chr_be_write(Chardev *s, const uint8_t *buf, int len);
Anthony Liguori2011fe52011-08-15 11:17:41 -0500190
Pavel Dovgalyuk33577b42016-03-14 10:44:36 +0300191/**
Marc-André Lureau56625762018-08-24 16:22:47 +0200192 * qemu_chr_be_write_impl:
193 * @buf: a buffer to receive data from the front end
194 * @len: the number of bytes to receive from the front end
Pavel Dovgalyuk33577b42016-03-14 10:44:36 +0300195 *
196 * Implementation of back end writing. Used by replay module.
Pavel Dovgalyuk33577b42016-03-14 10:44:36 +0300197 */
Arwed Meyer8f9abdf2022-09-11 20:18:37 +0200198void qemu_chr_be_write_impl(Chardev *s, const uint8_t *buf, int len);
Hans de Goedea425d232011-11-19 10:22:43 +0100199
200/**
Marc-André Lureau56625762018-08-24 16:22:47 +0200201 * qemu_chr_be_update_read_handlers:
202 * @context: the gcontext that will be used to attach the watch sources
Peter Xu07241c22017-09-21 14:35:51 +0800203 *
204 * Invoked when frontend read handlers are setup
Peter Xu07241c22017-09-21 14:35:51 +0800205 */
206void qemu_chr_be_update_read_handlers(Chardev *s,
207 GMainContext *context);
208
209/**
Marc-André Lureau56625762018-08-24 16:22:47 +0200210 * qemu_chr_be_event:
211 * @event: the event to send
Hans de Goedea425d232011-11-19 10:22:43 +0100212 *
213 * Send an event from the back end to the front end.
Hans de Goedea425d232011-11-19 10:22:43 +0100214 */
Paolo Bonzini2fa90442020-01-08 11:14:29 +0100215void qemu_chr_be_event(Chardev *s, QEMUChrEvent event);
Hans de Goedea425d232011-11-19 10:22:43 +0100216
Marc-André Lureau0ec7b3e2016-12-07 16:20:22 +0300217int qemu_chr_add_client(Chardev *s, int fd);
218Chardev *qemu_chr_find(const char *name);
Marc-André Lureauad5c6792016-10-21 22:38:41 +0300219
Marc-André Lureau0ec7b3e2016-12-07 16:20:22 +0300220bool qemu_chr_has_feature(Chardev *chr,
Marc-André Lureau279b0662016-12-14 13:27:58 +0300221 ChardevFeature feature);
Marc-André Lureau0ec7b3e2016-12-07 16:20:22 +0300222void qemu_chr_set_feature(Chardev *chr,
Marc-André Lureau279b0662016-12-14 13:27:58 +0300223 ChardevFeature feature);
Marc-André Lureau95e30b22018-08-22 19:19:42 +0200224QemuOpts *qemu_chr_parse_compat(const char *label, const char *filename,
225 bool permit_mux_mon);
Marc-André Lureau4d43a602017-01-26 18:26:44 +0400226int qemu_chr_write(Chardev *s, const uint8_t *buf, int len, bool write_all);
227#define qemu_chr_write_all(s, buf, len) qemu_chr_write(s, buf, len, true)
Marc-André Lureaud24ca4b2016-12-12 18:41:00 +0300228int qemu_chr_wait_connected(Chardev *chr, Error **errp);
Anthony Liguori2011fe52011-08-15 11:17:41 -0500229
Marc-André Lureau777357d2016-12-07 18:39:10 +0300230#define TYPE_CHARDEV "chardev"
Eduardo Habkosta489d192020-09-16 14:25:18 -0400231OBJECT_DECLARE_TYPE(Chardev, ChardevClass, CHARDEV)
Marc-André Lureau777357d2016-12-07 18:39:10 +0300232
233#define TYPE_CHARDEV_NULL "chardev-null"
234#define TYPE_CHARDEV_MUX "chardev-mux"
235#define TYPE_CHARDEV_RINGBUF "chardev-ringbuf"
236#define TYPE_CHARDEV_PTY "chardev-pty"
237#define TYPE_CHARDEV_CONSOLE "chardev-console"
238#define TYPE_CHARDEV_STDIO "chardev-stdio"
239#define TYPE_CHARDEV_PIPE "chardev-pipe"
240#define TYPE_CHARDEV_MEMORY "chardev-memory"
241#define TYPE_CHARDEV_PARALLEL "chardev-parallel"
242#define TYPE_CHARDEV_FILE "chardev-file"
243#define TYPE_CHARDEV_SERIAL "chardev-serial"
244#define TYPE_CHARDEV_SOCKET "chardev-socket"
245#define TYPE_CHARDEV_UDP "chardev-udp"
246
Marc-André Lureau777357d2016-12-07 18:39:10 +0300247#define CHARDEV_IS_RINGBUF(chr) \
248 object_dynamic_cast(OBJECT(chr), TYPE_CHARDEV_RINGBUF)
249#define CHARDEV_IS_PTY(chr) \
250 object_dynamic_cast(OBJECT(chr), TYPE_CHARDEV_PTY)
251
Eduardo Habkostdb1015e2020-09-03 16:43:22 -0400252struct ChardevClass {
Marc-André Lureau777357d2016-12-07 18:39:10 +0300253 ObjectClass parent_class;
254
255 bool internal; /* TODO: eventually use TYPE_USER_CREATABLE */
Lukas Straubfeb774c2021-03-30 20:13:31 +0200256 bool supports_yank;
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400257
258 /* parse command line options and populate QAPI @backend */
Marc-André Lureau88cace92016-12-09 00:50:12 +0300259 void (*parse)(QemuOpts *opts, ChardevBackend *backend, Error **errp);
Marc-André Lureau777357d2016-12-07 18:39:10 +0300260
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400261 /* called after construction, open/starts the backend */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300262 void (*open)(Chardev *chr, ChardevBackend *backend,
263 bool *be_opened, Error **errp);
264
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400265 /* write buf to the backend */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300266 int (*chr_write)(Chardev *s, const uint8_t *buf, int len);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400267
268 /*
269 * Read from the backend (blocking). A typical front-end will instead rely
270 * on chr_can_read/chr_read being called when polling/looping.
271 */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300272 int (*chr_sync_read)(Chardev *s, const uint8_t *buf, int len);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400273
274 /* create a watch on the backend */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300275 GSource *(*chr_add_watch)(Chardev *s, GIOCondition cond);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400276
277 /* update the backend internal sources */
Peter Xubb86d052017-09-21 14:35:54 +0800278 void (*chr_update_read_handler)(Chardev *s);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400279
280 /* send an ioctl to the backend */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300281 int (*chr_ioctl)(Chardev *s, int cmd, void *arg);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400282
283 /* get ancillary-received fds during last read */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300284 int (*get_msgfds)(Chardev *s, int* fds, int num);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400285
286 /* set ancillary fds to be sent with next write */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300287 int (*set_msgfds)(Chardev *s, int *fds, int num);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400288
289 /* accept the given fd */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300290 int (*chr_add_client)(Chardev *chr, int fd);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400291
292 /* wait for a connection */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300293 int (*chr_wait_connected)(Chardev *chr, Error **errp);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400294
295 /* disconnect a connection */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300296 void (*chr_disconnect)(Chardev *chr);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400297
298 /* called by frontend when it can read */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300299 void (*chr_accept_input)(Chardev *chr);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400300
301 /* set terminal echo */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300302 void (*chr_set_echo)(Chardev *chr, bool echo);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400303
304 /* notify the backend of frontend open state */
Marc-André Lureau777357d2016-12-07 18:39:10 +0300305 void (*chr_set_fe_open)(Chardev *chr, int fe_open);
Marc-André Lureau78e3e1d2021-08-04 19:48:41 +0400306
307 /* handle various events */
Paolo Bonzini2fa90442020-01-08 11:14:29 +0100308 void (*chr_be_event)(Chardev *s, QEMUChrEvent event);
Eduardo Habkostdb1015e2020-09-03 16:43:22 -0400309};
Marc-André Lureau777357d2016-12-07 18:39:10 +0300310
Marc-André Lureau777357d2016-12-07 18:39:10 +0300311Chardev *qemu_chardev_new(const char *id, const char *typename,
Paolo Bonzini4ad6f6c2019-02-13 14:18:13 +0100312 ChardevBackend *backend, GMainContext *context,
313 Error **errp);
Marc-André Lureau777357d2016-12-07 18:39:10 +0300314
aliguori0e82f342008-10-31 18:44:40 +0000315extern int term_escape_char;
316
Peter Xu2c716ba2018-01-04 22:18:35 +0800317GSource *qemu_chr_timeout_add_ms(Chardev *chr, guint ms,
318 GSourceFunc func, void *private);
319
Paolo Bonzini5a1ee602020-11-30 13:44:49 -0500320void suspend_mux_open(void);
321void resume_mux_open(void);
322
pbrook87ecb682007-11-17 17:14:51 +0000323#endif