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