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