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 = (1 << 0), 44 QIO_CHANNEL_FEATURE_SHUTDOWN = (1 << 1), 45 QIO_CHANNEL_FEATURE_LISTEN = (1 << 2), 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_readv_full: 153 * @ioc: the channel object 154 * @iov: the array of memory regions to read data into 155 * @niov: the length of the @iov array 156 * @fds: pointer to an array that will received file handles 157 * @nfds: pointer filled with number of elements in @fds on return 158 * @errp: pointer to a NULL-initialized error object 159 * 160 * Read data from the IO channel, storing it in the 161 * memory regions referenced by @iov. Each element 162 * in the @iov will be fully populated with data 163 * before the next one is used. The @niov parameter 164 * specifies the total number of elements in @iov. 165 * 166 * It is not required for all @iov to be filled with 167 * data. If the channel is in blocking mode, at least 168 * one byte of data will be read, but no more is 169 * guaranteed. If the channel is non-blocking and no 170 * data is available, it will return QIO_CHANNEL_ERR_BLOCK 171 * 172 * If the channel has passed any file descriptors, 173 * the @fds array pointer will be allocated and 174 * the elements filled with the received file 175 * descriptors. The @nfds pointer will be updated 176 * to indicate the size of the @fds array that 177 * was allocated. It is the callers responsibility 178 * to call close() on each file descriptor and to 179 * call g_free() on the array pointer in @fds. 180 * 181 * It is an error to pass a non-NULL @fds parameter 182 * unless qio_channel_has_feature() returns a true 183 * value for the QIO_CHANNEL_FEATURE_FD_PASS constant. 184 * 185 * Returns: the number of bytes read, or -1 on error, 186 * or QIO_CHANNEL_ERR_BLOCK if no data is available 187 * and the channel is non-blocking 188 */ 189 ssize_t qio_channel_readv_full(QIOChannel *ioc, 190 const struct iovec *iov, 191 size_t niov, 192 int **fds, 193 size_t *nfds, 194 Error **errp); 195 196 197 /** 198 * qio_channel_writev_full: 199 * @ioc: the channel object 200 * @iov: the array of memory regions to write data from 201 * @niov: the length of the @iov array 202 * @fds: an array of file handles to send 203 * @nfds: number of file handles in @fds 204 * @errp: pointer to a NULL-initialized error object 205 * 206 * Write data to the IO channel, reading it from the 207 * memory regions referenced by @iov. Each element 208 * in the @iov will be fully sent, before the next 209 * one is used. The @niov parameter specifies the 210 * total number of elements in @iov. 211 * 212 * It is not required for all @iov data to be fully 213 * sent. If the channel is in blocking mode, at least 214 * one byte of data will be sent, but no more is 215 * guaranteed. If the channel is non-blocking and no 216 * data can be sent, it will return QIO_CHANNEL_ERR_BLOCK 217 * 218 * If there are file descriptors to send, the @fds 219 * array should be non-NULL and provide the handles. 220 * All file descriptors will be sent if at least one 221 * byte of data was sent. 222 * 223 * It is an error to pass a non-NULL @fds parameter 224 * unless qio_channel_has_feature() returns a true 225 * value for the QIO_CHANNEL_FEATURE_FD_PASS constant. 226 * 227 * Returns: the number of bytes sent, or -1 on error, 228 * or QIO_CHANNEL_ERR_BLOCK if no data is can be sent 229 * and the channel is non-blocking 230 */ 231 ssize_t qio_channel_writev_full(QIOChannel *ioc, 232 const struct iovec *iov, 233 size_t niov, 234 int *fds, 235 size_t nfds, 236 Error **errp); 237 238 /** 239 * qio_channel_readv: 240 * @ioc: the channel object 241 * @iov: the array of memory regions to read data into 242 * @niov: the length of the @iov array 243 * @errp: pointer to a NULL-initialized error object 244 * 245 * Behaves as qio_channel_readv_full() but does not support 246 * receiving of file handles. 247 */ 248 ssize_t qio_channel_readv(QIOChannel *ioc, 249 const struct iovec *iov, 250 size_t niov, 251 Error **errp); 252 253 /** 254 * qio_channel_writev: 255 * @ioc: the channel object 256 * @iov: the array of memory regions to write data from 257 * @niov: the length of the @iov array 258 * @errp: pointer to a NULL-initialized error object 259 * 260 * Behaves as qio_channel_writev_full() but does not support 261 * sending of file handles. 262 */ 263 ssize_t qio_channel_writev(QIOChannel *ioc, 264 const struct iovec *iov, 265 size_t niov, 266 Error **errp); 267 268 /** 269 * qio_channel_readv: 270 * @ioc: the channel object 271 * @buf: the memory region to read data into 272 * @buflen: the length of @buf 273 * @errp: pointer to a NULL-initialized error object 274 * 275 * Behaves as qio_channel_readv_full() but does not support 276 * receiving of file handles, and only supports reading into 277 * a single memory region. 278 */ 279 ssize_t qio_channel_read(QIOChannel *ioc, 280 char *buf, 281 size_t buflen, 282 Error **errp); 283 284 /** 285 * qio_channel_writev: 286 * @ioc: the channel object 287 * @buf: the memory regions to send data from 288 * @buflen: the length of @buf 289 * @errp: pointer to a NULL-initialized error object 290 * 291 * Behaves as qio_channel_writev_full() but does not support 292 * sending of file handles, and only supports writing from a 293 * single memory region. 294 */ 295 ssize_t qio_channel_write(QIOChannel *ioc, 296 const char *buf, 297 size_t buflen, 298 Error **errp); 299 300 /** 301 * qio_channel_set_blocking: 302 * @ioc: the channel object 303 * @enabled: the blocking flag state 304 * @errp: pointer to a NULL-initialized error object 305 * 306 * If @enabled is true, then the channel is put into 307 * blocking mode, otherwise it will be non-blocking. 308 * 309 * In non-blocking mode, read/write operations may 310 * return QIO_CHANNEL_ERR_BLOCK if they would otherwise 311 * block on I/O 312 */ 313 int qio_channel_set_blocking(QIOChannel *ioc, 314 bool enabled, 315 Error **errp); 316 317 /** 318 * qio_channel_close: 319 * @ioc: the channel object 320 * @errp: pointer to a NULL-initialized error object 321 * 322 * Close the channel, flushing any pending I/O 323 * 324 * Returns: 0 on success, -1 on error 325 */ 326 int qio_channel_close(QIOChannel *ioc, 327 Error **errp); 328 329 /** 330 * qio_channel_shutdown: 331 * @ioc: the channel object 332 * @how: the direction to shutdown 333 * @errp: pointer to a NULL-initialized error object 334 * 335 * Shutdowns transmission and/or receiving of data 336 * without closing the underlying transport. 337 * 338 * Not all implementations will support this facility, 339 * so may report an error. To avoid errors, the 340 * caller may check for the feature flag 341 * QIO_CHANNEL_FEATURE_SHUTDOWN prior to calling 342 * this method. 343 * 344 * Returns: 0 on success, -1 on error 345 */ 346 int qio_channel_shutdown(QIOChannel *ioc, 347 QIOChannelShutdown how, 348 Error **errp); 349 350 /** 351 * qio_channel_set_delay: 352 * @ioc: the channel object 353 * @enabled: the new flag state 354 * 355 * Controls whether the underlying transport is 356 * permitted to delay writes in order to merge 357 * small packets. If @enabled is true, then the 358 * writes may be delayed in order to opportunistically 359 * merge small packets into larger ones. If @enabled 360 * is false, writes are dispatched immediately with 361 * no delay. 362 * 363 * When @enabled is false, applications may wish to 364 * use the qio_channel_set_cork() method to explicitly 365 * control write merging. 366 * 367 * On channels which are backed by a socket, this 368 * API corresponds to the inverse of TCP_NODELAY flag, 369 * controlling whether the Nagle algorithm is active. 370 * 371 * This setting is merely a hint, so implementations are 372 * free to ignore this without it being considered an 373 * error. 374 */ 375 void qio_channel_set_delay(QIOChannel *ioc, 376 bool enabled); 377 378 /** 379 * qio_channel_set_cork: 380 * @ioc: the channel object 381 * @enabled: the new flag state 382 * 383 * Controls whether the underlying transport is 384 * permitted to dispatch data that is written. 385 * If @enabled is true, then any data written will 386 * be queued in local buffers until @enabled is 387 * set to false once again. 388 * 389 * This feature is typically used when the automatic 390 * write coalescing facility is disabled via the 391 * qio_channel_set_delay() method. 392 * 393 * On channels which are backed by a socket, this 394 * API corresponds to the TCP_CORK flag. 395 * 396 * This setting is merely a hint, so implementations are 397 * free to ignore this without it being considered an 398 * error. 399 */ 400 void qio_channel_set_cork(QIOChannel *ioc, 401 bool enabled); 402 403 404 /** 405 * qio_channel_seek: 406 * @ioc: the channel object 407 * @offset: the position to seek to, relative to @whence 408 * @whence: one of the (POSIX) SEEK_* constants listed below 409 * @errp: pointer to a NULL-initialized error object 410 * 411 * Moves the current I/O position within the channel 412 * @ioc, to be @offset. The value of @offset is 413 * interpreted relative to @whence: 414 * 415 * SEEK_SET - the position is set to @offset bytes 416 * SEEK_CUR - the position is moved by @offset bytes 417 * SEEK_END - the position is set to end of the file plus @offset bytes 418 * 419 * Not all implementations will support this facility, 420 * so may report an error. 421 * 422 * Returns: the new position on success, (off_t)-1 on failure 423 */ 424 off_t qio_channel_io_seek(QIOChannel *ioc, 425 off_t offset, 426 int whence, 427 Error **errp); 428 429 430 /** 431 * qio_channel_create_watch: 432 * @ioc: the channel object 433 * @condition: the I/O condition to monitor 434 * 435 * Create a new main loop source that is used to watch 436 * for the I/O condition @condition. Typically the 437 * qio_channel_add_watch() method would be used instead 438 * of this, since it directly attaches a callback to 439 * the source 440 * 441 * Returns: the new main loop source. 442 */ 443 GSource *qio_channel_create_watch(QIOChannel *ioc, 444 GIOCondition condition); 445 446 /** 447 * qio_channel_add_watch: 448 * @ioc: the channel object 449 * @condition: the I/O condition to monitor 450 * @func: callback to invoke when the source becomes ready 451 * @user_data: opaque data to pass to @func 452 * @notify: callback to free @user_data 453 * 454 * Create a new main loop source that is used to watch 455 * for the I/O condition @condition. The callback @func 456 * will be registered against the source, to be invoked 457 * when the source becomes ready. The optional @user_data 458 * will be passed to @func when it is invoked. The @notify 459 * callback will be used to free @user_data when the 460 * watch is deleted 461 * 462 * The returned source ID can be used with g_source_remove() 463 * to remove and free the source when no longer required. 464 * Alternatively the @func callback can return a FALSE 465 * value. 466 * 467 * Returns: the source ID 468 */ 469 guint qio_channel_add_watch(QIOChannel *ioc, 470 GIOCondition condition, 471 QIOChannelFunc func, 472 gpointer user_data, 473 GDestroyNotify notify); 474 475 476 /** 477 * qio_channel_yield: 478 * @ioc: the channel object 479 * @condition: the I/O condition to wait for 480 * 481 * Yields execution from the current coroutine until 482 * the condition indicated by @condition becomes 483 * available. 484 * 485 * This must only be called from coroutine context 486 */ 487 void qio_channel_yield(QIOChannel *ioc, 488 GIOCondition condition); 489 490 /** 491 * qio_channel_wait: 492 * @ioc: the channel object 493 * @condition: the I/O condition to wait for 494 * 495 * Block execution from the current thread until 496 * the condition indicated by @condition becomes 497 * available. 498 * 499 * This will enter a nested event loop to perform 500 * the wait. 501 */ 502 void qio_channel_wait(QIOChannel *ioc, 503 GIOCondition condition); 504 505 #endif /* QIO_CHANNEL_H */ 506