| 1 | /* |
| 2 | * Helpers for using (partial) iovecs. |
| 3 | * |
| 4 | * Copyright (c) 2024 Seagate Technology LLC and/or its Affiliates |
| 5 | * Copyright (C) 2010 Red Hat, Inc. |
| 6 | * |
| 7 | * Author(s): |
| 8 | * Amit Shah <amit.shah@redhat.com> |
| 9 | * Michael Tokarev <mjt@tls.msk.ru> |
| 10 | * |
| 11 | * This work is licensed under the terms of the GNU GPL, version 2. See |
| 12 | * the COPYING file in the top-level directory. |
| 13 | */ |
| 14 | |
| 15 | #ifndef IOV_H |
| 16 | #define IOV_H |
| 17 | |
| 18 | /** |
| 19 | * count and return data size, in bytes, of an iovec |
| 20 | * starting at `iov' of `iov_cnt' number of elements. |
| 21 | */ |
| 22 | size_t iov_size(const struct iovec *iov, const unsigned int iov_cnt); |
| 23 | |
| 24 | /** |
| 25 | * Copy from single continuous buffer to scatter-gather vector of buffers |
| 26 | * (iovec) and back like memcpy() between two continuous memory regions. |
| 27 | * Data in single continuous buffer starting at address `buf' and |
| 28 | * `bytes' bytes long will be copied to/from an iovec `iov' with |
| 29 | * `iov_cnt' number of elements, starting at byte position `offset' |
| 30 | * within the iovec. If the iovec does not contain enough space, |
| 31 | * only part of data will be copied, up to the end of the iovec. |
| 32 | * Number of bytes actually copied will be returned, which is |
| 33 | * min(bytes, iov_size(iov)-offset) |
| 34 | * Returns 0 when `offset' points to the outside of iovec. |
| 35 | */ |
| 36 | size_t iov_from_buf_full(const struct iovec *iov, unsigned int iov_cnt, |
| 37 | size_t offset, const void *buf, size_t bytes); |
| 38 | size_t iov_to_buf_full(const struct iovec *iov, const unsigned int iov_cnt, |
| 39 | size_t offset, void *buf, size_t bytes); |
| 40 | |
| 41 | static inline size_t |
| 42 | iov_from_buf(const struct iovec *iov, unsigned int iov_cnt, |
| 43 | size_t offset, const void *buf, size_t bytes) |
| 44 | { |
| 45 | if (__builtin_constant_p(bytes) && iov_cnt && |
| 46 | offset <= iov[0].iov_len && bytes <= iov[0].iov_len - offset) { |
| 47 | memcpy(iov[0].iov_base + offset, buf, bytes); |
| 48 | return bytes; |
| 49 | } else { |
| 50 | return iov_from_buf_full(iov, iov_cnt, offset, buf, bytes); |
| 51 | } |
| 52 | } |
| 53 | |
| 54 | static inline size_t |
| 55 | iov_to_buf(const struct iovec *iov, const unsigned int iov_cnt, |
| 56 | size_t offset, void *buf, size_t bytes) |
| 57 | { |
| 58 | if (__builtin_constant_p(bytes) && iov_cnt && |
| 59 | offset <= iov[0].iov_len && bytes <= iov[0].iov_len - offset) { |
| 60 | memcpy(buf, iov[0].iov_base + offset, bytes); |
| 61 | return bytes; |
| 62 | } else { |
| 63 | return iov_to_buf_full(iov, iov_cnt, offset, buf, bytes); |
| 64 | } |
| 65 | } |
| 66 | |
| 67 | /** |
| 68 | * Set data bytes pointed out by iovec `iov' of size `iov_cnt' elements, |
| 69 | * starting at byte offset `start', to value `fillc', repeating it |
| 70 | * `bytes' number of times. |
| 71 | * If `bytes' is large enough, only last bytes portion of iovec, |
| 72 | * up to the end of it, will be filled with the specified value. |
| 73 | * Function return actual number of bytes processed, which is |
| 74 | * min(size, iov_size(iov) - offset). |
| 75 | * Returns 0 when `offset' points to the outside of iovec. |
| 76 | */ |
| 77 | size_t iov_memset(const struct iovec *iov, const unsigned int iov_cnt, |
| 78 | size_t offset, int fillc, size_t bytes); |
| 79 | |
| 80 | /* |
| 81 | * Send/recv data from/to iovec buffers directly, with the provided |
| 82 | * socket flags. |
| 83 | * |
| 84 | * `offset' bytes in the beginning of iovec buffer are skipped and |
| 85 | * next `bytes' bytes are used, which must be within data of iovec. |
| 86 | * |
| 87 | * r = iov_send_recv_with_flags(sockfd, sockflags, iov, iovcnt, |
| 88 | * offset, bytes, true); |
| 89 | * |
| 90 | * is logically equivalent to |
| 91 | * |
| 92 | * char *buf = malloc(bytes); |
| 93 | * iov_to_buf(iov, iovcnt, offset, buf, bytes); |
| 94 | * r = send(sockfd, buf, bytes, sockflags); |
| 95 | * free(buf); |
| 96 | * |
| 97 | * For iov_send_recv_with_flags() _whole_ area being sent or received |
| 98 | * should be within the iovec, not only beginning of it. |
| 99 | */ |
| 100 | ssize_t iov_send_recv_with_flags(int sockfd, int sockflags, |
| 101 | const struct iovec *iov, |
| 102 | unsigned iov_cnt, size_t offset, |
| 103 | size_t bytes, |
| 104 | bool do_send); |
| 105 | |
| 106 | /* |
| 107 | * Send/recv data from/to iovec buffers directly |
| 108 | * |
| 109 | * `offset' bytes in the beginning of iovec buffer are skipped and |
| 110 | * next `bytes' bytes are used, which must be within data of iovec. |
| 111 | * |
| 112 | * r = iov_send_recv(sockfd, iov, iovcnt, offset, bytes, true); |
| 113 | * |
| 114 | * is logically equivalent to |
| 115 | * |
| 116 | * char *buf = malloc(bytes); |
| 117 | * iov_to_buf(iov, iovcnt, offset, buf, bytes); |
| 118 | * r = send(sockfd, buf, bytes, 0); |
| 119 | * free(buf); |
| 120 | * |
| 121 | * For iov_send_recv() _whole_ area being sent or received |
| 122 | * should be within the iovec, not only beginning of it. |
| 123 | */ |
| 124 | ssize_t iov_send_recv(int sockfd, const struct iovec *iov, unsigned iov_cnt, |
| 125 | size_t offset, size_t bytes, bool do_send); |
| 126 | #define iov_recv(sockfd, iov, iov_cnt, offset, bytes) \ |
| 127 | iov_send_recv(sockfd, iov, iov_cnt, offset, bytes, false) |
| 128 | #define iov_send(sockfd, iov, iov_cnt, offset, bytes) \ |
| 129 | iov_send_recv(sockfd, iov, iov_cnt, offset, bytes, true) |
| 130 | |
| 131 | /** |
| 132 | * Produce a text hexdump of iovec `iov' with `iov_cnt' number of elements |
| 133 | * in file `fp', prefixing each line with `prefix' and processing not more |
| 134 | * than `limit' data bytes. |
| 135 | */ |
| 136 | void iov_hexdump(const struct iovec *iov, const unsigned int iov_cnt, |
| 137 | FILE *fp, const char *prefix, size_t limit); |
| 138 | |
| 139 | /* |
| 140 | * Partial copy of vector from iov to dst_iov (data is not copied). |
| 141 | * dst_iov overlaps iov at a specified offset. |
| 142 | * size of dst_iov is at most bytes. dst vector count is returned. |
| 143 | */ |
| 144 | unsigned iov_copy(struct iovec *dst_iov, unsigned int dst_iov_cnt, |
| 145 | const struct iovec *iov, unsigned int iov_cnt, |
| 146 | size_t offset, size_t bytes); |
| 147 | |
| 148 | /* |
| 149 | * Remove a given number of bytes from the front or back of a vector. |
| 150 | * This may update iov and/or iov_cnt to exclude iovec elements that are |
| 151 | * no longer required. |
| 152 | * |
| 153 | * The number of bytes actually discarded is returned. This number may be |
| 154 | * smaller than requested if the vector is too small. |
| 155 | */ |
| 156 | size_t iov_discard_front(struct iovec **iov, unsigned int *iov_cnt, |
| 157 | size_t bytes); |
| 158 | size_t iov_discard_back(struct iovec *iov, unsigned int *iov_cnt, |
| 159 | size_t bytes); |
| 160 | |
| 161 | /* Information needed to undo an iov_discard_*() operation */ |
| 162 | typedef struct { |
| 163 | struct iovec *modified_iov; |
| 164 | struct iovec orig; |
| 165 | } IOVDiscardUndo; |
| 166 | |
| 167 | /* |
| 168 | * Undo an iov_discard_front_undoable() or iov_discard_back_undoable() |
| 169 | * operation. If multiple operations are made then each one needs a separate |
| 170 | * IOVDiscardUndo and iov_discard_undo() must be called in the reverse order |
| 171 | * that the operations were made. |
| 172 | */ |
| 173 | void iov_discard_undo(IOVDiscardUndo *undo); |
| 174 | |
| 175 | /* |
| 176 | * Undoable versions of iov_discard_front() and iov_discard_back(). Use |
| 177 | * iov_discard_undo() to reset to the state before the discard operations. |
| 178 | */ |
| 179 | size_t iov_discard_front_undoable(struct iovec **iov, unsigned int *iov_cnt, |
| 180 | size_t bytes, IOVDiscardUndo *undo); |
| 181 | size_t iov_discard_back_undoable(struct iovec *iov, unsigned int *iov_cnt, |
| 182 | size_t bytes, IOVDiscardUndo *undo); |
| 183 | |
| 184 | typedef struct QEMUIOVector { |
| 185 | struct iovec *iov; |
| 186 | int niov; |
| 187 | |
| 188 | /* |
| 189 | * For external @iov (qemu_iovec_init_external()) or allocated @iov |
| 190 | * (qemu_iovec_init()), @size is the cumulative size of iovecs and |
| 191 | * @local_iov is invalid and unused. |
| 192 | * |
| 193 | * For embedded @iov (QEMU_IOVEC_INIT_BUF() or qemu_iovec_init_buf()), |
| 194 | * @iov is equal to &@local_iov, and @size is valid, as it has same |
| 195 | * offset and type as @local_iov.iov_len, which is guaranteed by |
| 196 | * static assertion below. |
| 197 | * |
| 198 | * @nalloc is always valid and is -1 both for embedded and external |
| 199 | * cases. It is included in the union only to ensure the padding prior |
| 200 | * to the @size field will not result in a 0-length array. |
| 201 | */ |
| 202 | union { |
| 203 | struct { |
| 204 | int nalloc; |
| 205 | struct iovec local_iov; |
| 206 | }; |
| 207 | struct { |
| 208 | char __pad[sizeof(int) + offsetof(struct iovec, iov_len)]; |
| 209 | size_t size; |
| 210 | }; |
| 211 | }; |
| 212 | } QEMUIOVector; |
| 213 | |
| 214 | QEMU_BUILD_BUG_ON(offsetof(QEMUIOVector, size) != |
| 215 | offsetof(QEMUIOVector, local_iov.iov_len)); |
| 216 | |
| 217 | #define QEMU_IOVEC_INIT_BUF(self, buf, len) \ |
| 218 | { \ |
| 219 | .iov = &(self).local_iov, \ |
| 220 | .niov = 1, \ |
| 221 | .nalloc = -1, \ |
| 222 | .local_iov = { \ |
| 223 | .iov_base = (void *)(buf), /* cast away const */ \ |
| 224 | .iov_len = (len), \ |
| 225 | }, \ |
| 226 | } |
| 227 | |
| 228 | /* |
| 229 | * qemu_iovec_init_buf |
| 230 | * |
| 231 | * Initialize embedded QEMUIOVector. |
| 232 | * |
| 233 | * Note: "const" is used over @buf pointer to make it simple to pass |
| 234 | * const pointers, appearing in read functions. Then this "const" is |
| 235 | * cast away by QEMU_IOVEC_INIT_BUF(). |
| 236 | */ |
| 237 | static inline void qemu_iovec_init_buf(QEMUIOVector *qiov, |
| 238 | const void *buf, size_t len) |
| 239 | { |
| 240 | *qiov = (QEMUIOVector) QEMU_IOVEC_INIT_BUF(*qiov, buf, len); |
| 241 | } |
| 242 | |
| 243 | static inline void *qemu_iovec_buf(QEMUIOVector *qiov) |
| 244 | { |
| 245 | /* Only supports embedded iov */ |
| 246 | assert(qiov->nalloc == -1 && qiov->iov == &qiov->local_iov); |
| 247 | |
| 248 | return qiov->local_iov.iov_base; |
| 249 | } |
| 250 | |
| 251 | void qemu_iovec_init(QEMUIOVector *qiov, int alloc_hint); |
| 252 | void qemu_iovec_init_external(QEMUIOVector *qiov, struct iovec *iov, int niov); |
| 253 | void qemu_iovec_init_slice(QEMUIOVector *qiov, QEMUIOVector *source, |
| 254 | size_t offset, size_t len); |
| 255 | struct iovec *qemu_iovec_slice(QEMUIOVector *qiov, |
| 256 | size_t offset, size_t len, |
| 257 | size_t *head, size_t *tail, int *niov); |
| 258 | int qemu_iovec_subvec_niov(QEMUIOVector *qiov, size_t offset, size_t len); |
| 259 | void qemu_iovec_add(QEMUIOVector *qiov, void *base, size_t len); |
| 260 | void qemu_iovec_concat(QEMUIOVector *dst, |
| 261 | QEMUIOVector *src, size_t soffset, size_t sbytes); |
| 262 | size_t qemu_iovec_concat_iov(QEMUIOVector *dst, |
| 263 | struct iovec *src_iov, unsigned int src_cnt, |
| 264 | size_t soffset, size_t sbytes); |
| 265 | bool qemu_iovec_is_zero(QEMUIOVector *qiov, size_t qiov_offeset, size_t bytes); |
| 266 | void qemu_iovec_destroy(QEMUIOVector *qiov); |
| 267 | void qemu_iovec_reset(QEMUIOVector *qiov); |
| 268 | size_t qemu_iovec_to_buf(QEMUIOVector *qiov, size_t offset, |
| 269 | void *buf, size_t bytes); |
| 270 | size_t qemu_iovec_from_buf(QEMUIOVector *qiov, size_t offset, |
| 271 | const void *buf, size_t bytes); |
| 272 | size_t qemu_iovec_memset(QEMUIOVector *qiov, size_t offset, |
| 273 | int fillc, size_t bytes); |
| 274 | ssize_t qemu_iovec_compare(QEMUIOVector *a, QEMUIOVector *b); |
| 275 | void qemu_iovec_clone(QEMUIOVector *dest, const QEMUIOVector *src, void *buf); |
| 276 | void qemu_iovec_discard_back(QEMUIOVector *qiov, size_t bytes); |
| 277 | |
| 278 | #endif |