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