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 }; 46 47 48 typedef enum QIOChannelShutdown QIOChannelShutdown; 49 50 enum QIOChannelShutdown { 51 QIO_CHANNEL_SHUTDOWN_BOTH, 52 QIO_CHANNEL_SHUTDOWN_READ, 53 QIO_CHANNEL_SHUTDOWN_WRITE, 54 }; 55 56 typedef 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 78 struct 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 */ 97 struct 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 */ 147 bool 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 */ 188 ssize_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 */ 230 ssize_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 */ 247 ssize_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 */ 262 ssize_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 */ 278 ssize_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 */ 294 ssize_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 */ 312 int 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 */ 325 int 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 */ 345 int 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 */ 374 void 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 */ 399 void 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 */ 423 off_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 */ 442 GSource *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 */ 468 guint 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 */ 486 void 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 */ 501 void qio_channel_wait(QIOChannel *ioc, 502 GIOCondition condition); 503 504 #endif /* QIO_CHANNEL_H__ */ 505