1/* 2 * QEMU I/O channels 3 * 4 * Copyright (c) 2015 Red Hat, Inc. 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with this library; if not, see <http://www.gnu.org/licenses/>. 18 * 19 */ 20 21#ifndef QIO_CHANNEL_H__ 22#define QIO_CHANNEL_H__ 23 24#include "qemu-common.h" 25#include "qom/object.h" 26 27#define TYPE_QIO_CHANNEL "qio-channel" 28#define QIO_CHANNEL(obj) \ 29 OBJECT_CHECK(QIOChannel, (obj), TYPE_QIO_CHANNEL) 30#define QIO_CHANNEL_CLASS(klass) \ 31 OBJECT_CLASS_CHECK(QIOChannelClass, klass, TYPE_QIO_CHANNEL) 32#define QIO_CHANNEL_GET_CLASS(obj) \ 33 OBJECT_GET_CLASS(QIOChannelClass, obj, TYPE_QIO_CHANNEL) 34 35typedef struct QIOChannel QIOChannel; 36typedef struct QIOChannelClass QIOChannelClass; 37 38#define QIO_CHANNEL_ERR_BLOCK -2 39 40typedef enum QIOChannelFeature QIOChannelFeature; 41 42enum QIOChannelFeature { 43 QIO_CHANNEL_FEATURE_FD_PASS = (1 << 0), 44 QIO_CHANNEL_FEATURE_SHUTDOWN = (1 << 1), 45}; 46 47 48typedef enum QIOChannelShutdown QIOChannelShutdown; 49 50enum QIOChannelShutdown { 51 QIO_CHANNEL_SHUTDOWN_BOTH, 52 QIO_CHANNEL_SHUTDOWN_READ, 53 QIO_CHANNEL_SHUTDOWN_WRITE, 54}; 55 56typedef gboolean (*QIOChannelFunc)(QIOChannel *ioc, 57 GIOCondition condition, 58 gpointer data); 59 60/** 61 * QIOChannel: 62 * 63 * The QIOChannel defines the core API for a generic I/O channel 64 * class hierarchy. It is inspired by GIOChannel, but has the 65 * following differences 66 * 67 * - Use QOM to properly support arbitrary subclassing 68 * - Support use of iovecs for efficient I/O with multiple blocks 69 * - None of the character set translation, binary data exclusively 70 * - Direct support for QEMU Error object reporting 71 * - File descriptor passing 72 * 73 * This base class is abstract so cannot be instantiated. There 74 * will be subclasses for dealing with sockets, files, and higher 75 * level protocols such as TLS, WebSocket, etc. 76 */ 77 78struct QIOChannel { 79 Object parent; 80 unsigned int features; /* bitmask of QIOChannelFeatures */ 81#ifdef _WIN32 82 HANDLE event; /* For use with GSource on Win32 */ 83#endif 84}; 85 86/** 87 * QIOChannelClass: 88 * 89 * This class defines the contract that all subclasses 90 * must follow to provide specific channel implementations. 91 * The first five callbacks are mandatory to support, others 92 * provide additional optional features. 93 * 94 * Consult the corresponding public API docs for a description 95 * of the semantics of each callback 96 */ 97struct QIOChannelClass { 98 ObjectClass parent; 99 100 /* Mandatory callbacks */ 101 ssize_t (*io_writev)(QIOChannel *ioc, 102 const struct iovec *iov, 103 size_t niov, 104 int *fds, 105 size_t nfds, 106 Error **errp); 107 ssize_t (*io_readv)(QIOChannel *ioc, 108 const struct iovec *iov, 109 size_t niov, 110 int **fds, 111 size_t *nfds, 112 Error **errp); 113 int (*io_close)(QIOChannel *ioc, 114 Error **errp); 115 GSource * (*io_create_watch)(QIOChannel *ioc, 116 GIOCondition condition); 117 int (*io_set_blocking)(QIOChannel *ioc, 118 bool enabled, 119 Error **errp); 120 121 /* Optional callbacks */ 122 int (*io_shutdown)(QIOChannel *ioc, 123 QIOChannelShutdown how, 124 Error **errp); 125 void (*io_set_cork)(QIOChannel *ioc, 126 bool enabled); 127 void (*io_set_delay)(QIOChannel *ioc, 128 bool enabled); 129 off_t (*io_seek)(QIOChannel *ioc, 130 off_t offset, 131 int whence, 132 Error **errp); 133}; 134 135/* General I/O handling functions */ 136 137/** 138 * qio_channel_has_feature: 139 * @ioc: the channel object 140 * @feature: the feature to check support of 141 * 142 * Determine whether the channel implementation supports 143 * the optional feature named in @feature. 144 * 145 * Returns: true if supported, false otherwise. 146 */ 147bool qio_channel_has_feature(QIOChannel *ioc, 148 QIOChannelFeature feature); 149 150/** 151 * qio_channel_readv_full: 152 * @ioc: the channel object 153 * @iov: the array of memory regions to read data into 154 * @niov: the length of the @iov array 155 * @fds: pointer to an array that will received file handles 156 * @nfds: pointer filled with number of elements in @fds on return 157 * @errp: pointer to a NULL-initialized error object 158 * 159 * Read data from the IO channel, storing it in the 160 * memory regions referenced by @iov. Each element 161 * in the @iov will be fully populated with data 162 * before the next one is used. The @niov parameter 163 * specifies the total number of elements in @iov. 164 * 165 * It is not required for all @iov to be filled with 166 * data. If the channel is in blocking mode, at least 167 * one byte of data will be read, but no more is 168 * guaranteed. If the channel is non-blocking and no 169 * data is available, it will return QIO_CHANNEL_ERR_BLOCK 170 * 171 * If the channel has passed any file descriptors, 172 * the @fds array pointer will be allocated and 173 * the elements filled with the received file 174 * descriptors. The @nfds pointer will be updated 175 * to indicate the size of the @fds array that 176 * was allocated. It is the callers responsibility 177 * to call close() on each file descriptor and to 178 * call g_free() on the array pointer in @fds. 179 * 180 * It is an error to pass a non-NULL @fds parameter 181 * unless qio_channel_has_feature() returns a true 182 * value for the QIO_CHANNEL_FEATURE_FD_PASS constant. 183 * 184 * Returns: the number of bytes read, or -1 on error, 185 * or QIO_CHANNEL_ERR_BLOCK if no data is available 186 * and the channel is non-blocking 187 */ 188ssize_t qio_channel_readv_full(QIOChannel *ioc, 189 const struct iovec *iov, 190 size_t niov, 191 int **fds, 192 size_t *nfds, 193 Error **errp); 194 195 196/** 197 * qio_channel_writev_full: 198 * @ioc: the channel object 199 * @iov: the array of memory regions to write data from 200 * @niov: the length of the @iov array 201 * @fds: an array of file handles to send 202 * @nfds: number of file handles in @fds 203 * @errp: pointer to a NULL-initialized error object 204 * 205 * Write data to the IO channel, reading it from the 206 * memory regions referenced by @iov. Each element 207 * in the @iov will be fully sent, before the next 208 * one is used. The @niov parameter specifies the 209 * total number of elements in @iov. 210 * 211 * It is not required for all @iov data to be fully 212 * sent. If the channel is in blocking mode, at least 213 * one byte of data will be sent, but no more is 214 * guaranteed. If the channel is non-blocking and no 215 * data can be sent, it will return QIO_CHANNEL_ERR_BLOCK 216 * 217 * If there are file descriptors to send, the @fds 218 * array should be non-NULL and provide the handles. 219 * All file descriptors will be sent if at least one 220 * byte of data was sent. 221 * 222 * It is an error to pass a non-NULL @fds parameter 223 * unless qio_channel_has_feature() returns a true 224 * value for the QIO_CHANNEL_FEATURE_FD_PASS constant. 225 * 226 * Returns: the number of bytes sent, or -1 on error, 227 * or QIO_CHANNEL_ERR_BLOCK if no data is can be sent 228 * and the channel is non-blocking 229 */ 230ssize_t qio_channel_writev_full(QIOChannel *ioc, 231 const struct iovec *iov, 232 size_t niov, 233 int *fds, 234 size_t nfds, 235 Error **errp); 236 237/** 238 * qio_channel_readv: 239 * @ioc: the channel object 240 * @iov: the array of memory regions to read data into 241 * @niov: the length of the @iov array 242 * @errp: pointer to a NULL-initialized error object 243 * 244 * Behaves as qio_channel_readv_full() but does not support 245 * receiving of file handles. 246 */ 247ssize_t qio_channel_readv(QIOChannel *ioc, 248 const struct iovec *iov, 249 size_t niov, 250 Error **errp); 251 252/** 253 * qio_channel_writev: 254 * @ioc: the channel object 255 * @iov: the array of memory regions to write data from 256 * @niov: the length of the @iov array 257 * @errp: pointer to a NULL-initialized error object 258 * 259 * Behaves as qio_channel_writev_full() but does not support 260 * sending of file handles. 261 */ 262ssize_t qio_channel_writev(QIOChannel *ioc, 263 const struct iovec *iov, 264 size_t niov, 265 Error **errp); 266 267/** 268 * qio_channel_readv: 269 * @ioc: the channel object 270 * @buf: the memory region to read data into 271 * @buflen: the length of @buf 272 * @errp: pointer to a NULL-initialized error object 273 * 274 * Behaves as qio_channel_readv_full() but does not support 275 * receiving of file handles, and only supports reading into 276 * a single memory region. 277 */ 278ssize_t qio_channel_read(QIOChannel *ioc, 279 char *buf, 280 size_t buflen, 281 Error **errp); 282 283/** 284 * qio_channel_writev: 285 * @ioc: the channel object 286 * @buf: the memory regions to send data from 287 * @buflen: the length of @buf 288 * @errp: pointer to a NULL-initialized error object 289 * 290 * Behaves as qio_channel_writev_full() but does not support 291 * sending of file handles, and only supports writing from a 292 * single memory region. 293 */ 294ssize_t qio_channel_write(QIOChannel *ioc, 295 const char *buf, 296 size_t buflen, 297 Error **errp); 298 299/** 300 * qio_channel_set_blocking: 301 * @ioc: the channel object 302 * @enabled: the blocking flag state 303 * @errp: pointer to a NULL-initialized error object 304 * 305 * If @enabled is true, then the channel is put into 306 * blocking mode, otherwise it will be non-blocking. 307 * 308 * In non-blocking mode, read/write operations may 309 * return QIO_CHANNEL_ERR_BLOCK if they would otherwise 310 * block on I/O 311 */ 312int qio_channel_set_blocking(QIOChannel *ioc, 313 bool enabled, 314 Error **errp); 315 316/** 317 * qio_channel_close: 318 * @ioc: the channel object 319 * @errp: pointer to a NULL-initialized error object 320 * 321 * Close the channel, flushing any pending I/O 322 * 323 * Returns: 0 on success, -1 on error 324 */ 325int qio_channel_close(QIOChannel *ioc, 326 Error **errp); 327 328/** 329 * qio_channel_shutdown: 330 * @ioc: the channel object 331 * @how: the direction to shutdown 332 * @errp: pointer to a NULL-initialized error object 333 * 334 * Shutdowns transmission and/or receiving of data 335 * without closing the underlying transport. 336 * 337 * Not all implementations will support this facility, 338 * so may report an error. To avoid errors, the 339 * caller may check for the feature flag 340 * QIO_CHANNEL_FEATURE_SHUTDOWN prior to calling 341 * this method. 342 * 343 * Returns: 0 on success, -1 on error 344 */ 345int qio_channel_shutdown(QIOChannel *ioc, 346 QIOChannelShutdown how, 347 Error **errp); 348 349/** 350 * qio_channel_set_delay: 351 * @ioc: the channel object 352 * @enabled: the new flag state 353 * 354 * Controls whether the underlying transport is 355 * permitted to delay writes in order to merge 356 * small packets. If @enabled is true, then the 357 * writes may be delayed in order to opportunistically 358 * merge small packets into larger ones. If @enabled 359 * is false, writes are dispatched immediately with 360 * no delay. 361 * 362 * When @enabled is false, applications may wish to 363 * use the qio_channel_set_cork() method to explicitly 364 * control write merging. 365 * 366 * On channels which are backed by a socket, this 367 * API corresponds to the inverse of TCP_NODELAY flag, 368 * controlling whether the Nagle algorithm is active. 369 * 370 * This setting is merely a hint, so implementations are 371 * free to ignore this without it being considered an 372 * error. 373 */ 374void qio_channel_set_delay(QIOChannel *ioc, 375 bool enabled); 376 377/** 378 * qio_channel_set_cork: 379 * @ioc: the channel object 380 * @enabled: the new flag state 381 * 382 * Controls whether the underlying transport is 383 * permitted to dispatch data that is written. 384 * If @enabled is true, then any data written will 385 * be queued in local buffers until @enabled is 386 * set to false once again. 387 * 388 * This feature is typically used when the automatic 389 * write coalescing facility is disabled via the 390 * qio_channel_set_delay() method. 391 * 392 * On channels which are backed by a socket, this 393 * API corresponds to the TCP_CORK flag. 394 * 395 * This setting is merely a hint, so implementations are 396 * free to ignore this without it being considered an 397 * error. 398 */ 399void qio_channel_set_cork(QIOChannel *ioc, 400 bool enabled); 401 402 403/** 404 * qio_channel_seek: 405 * @ioc: the channel object 406 * @offset: the position to seek to, relative to @whence 407 * @whence: one of the (POSIX) SEEK_* constants listed below 408 * @errp: pointer to a NULL-initialized error object 409 * 410 * Moves the current I/O position within the channel 411 * @ioc, to be @offset. The value of @offset is 412 * interpreted relative to @whence: 413 * 414 * SEEK_SET - the position is set to @offset bytes 415 * SEEK_CUR - the position is moved by @offset bytes 416 * SEEK_END - the position is set to end of the file plus @offset bytes 417 * 418 * Not all implementations will support this facility, 419 * so may report an error. 420 * 421 * Returns: the new position on success, (off_t)-1 on failure 422 */ 423off_t qio_channel_io_seek(QIOChannel *ioc, 424 off_t offset, 425 int whence, 426 Error **errp); 427 428 429/** 430 * qio_channel_create_watch: 431 * @ioc: the channel object 432 * @condition: the I/O condition to monitor 433 * 434 * Create a new main loop source that is used to watch 435 * for the I/O condition @condition. Typically the 436 * qio_channel_add_watch() method would be used instead 437 * of this, since it directly attaches a callback to 438 * the source 439 * 440 * Returns: the new main loop source. 441 */ 442GSource *qio_channel_create_watch(QIOChannel *ioc, 443 GIOCondition condition); 444 445/** 446 * qio_channel_add_watch: 447 * @ioc: the channel object 448 * @condition: the I/O condition to monitor 449 * @func: callback to invoke when the source becomes ready 450 * @user_data: opaque data to pass to @func 451 * @notify: callback to free @user_data 452 * 453 * Create a new main loop source that is used to watch 454 * for the I/O condition @condition. The callback @func 455 * will be registered against the source, to be invoked 456 * when the source becomes ready. The optional @user_data 457 * will be passed to @func when it is invoked. The @notify 458 * callback will be used to free @user_data when the 459 * watch is deleted 460 * 461 * The returned source ID can be used with g_source_remove() 462 * to remove and free the source when no longer required. 463 * Alternatively the @func callback can return a FALSE 464 * value. 465 * 466 * Returns: the source ID 467 */ 468guint qio_channel_add_watch(QIOChannel *ioc, 469 GIOCondition condition, 470 QIOChannelFunc func, 471 gpointer user_data, 472 GDestroyNotify notify); 473 474 475/** 476 * qio_channel_yield: 477 * @ioc: the channel object 478 * @condition: the I/O condition to wait for 479 * 480 * Yields execution from the current coroutine until 481 * the condition indicated by @condition becomes 482 * available. 483 * 484 * This must only be called from coroutine context 485 */ 486void qio_channel_yield(QIOChannel *ioc, 487 GIOCondition condition); 488 489/** 490 * qio_channel_wait: 491 * @ioc: the channel object 492 * @condition: the I/O condition to wait for 493 * 494 * Block execution from the current thread until 495 * the condition indicated by @condition becomes 496 * available. 497 * 498 * This will enter a nested event loop to perform 499 * the wait. 500 */ 501void qio_channel_wait(QIOChannel *ioc, 502 GIOCondition condition); 503 504#endif /* QIO_CHANNEL_H__ */ 505