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 * `Offset' must point to the inside 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. `Offset' must point to the inside of iovec. 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 */ 76 size_t iov_memset(const struct iovec *iov, const unsigned int iov_cnt, 77 size_t offset, int fillc, size_t bytes); 78 79 /* 80 * Send/recv data from/to iovec buffers directly, with the provided 81 * socket flags. 82 * 83 * `offset' bytes in the beginning of iovec buffer are skipped and 84 * next `bytes' bytes are used, which must be within data of iovec. 85 * 86 * r = iov_send_recv_with_flags(sockfd, sockflags, iov, iovcnt, 87 * offset, bytes, true); 88 * 89 * is logically equivalent to 90 * 91 * char *buf = malloc(bytes); 92 * iov_to_buf(iov, iovcnt, offset, buf, bytes); 93 * r = send(sockfd, buf, bytes, sockflags); 94 * free(buf); 95 * 96 * For iov_send_recv_with_flags() _whole_ area being sent or received 97 * should be within the iovec, not only beginning of it. 98 */ 99 ssize_t iov_send_recv_with_flags(int sockfd, int sockflags, 100 const struct iovec *iov, 101 unsigned iov_cnt, size_t offset, 102 size_t bytes, 103 bool do_send); 104 105 /* 106 * Send/recv data from/to iovec buffers directly 107 * 108 * `offset' bytes in the beginning of iovec buffer are skipped and 109 * next `bytes' bytes are used, which must be within data of iovec. 110 * 111 * r = iov_send_recv(sockfd, iov, iovcnt, offset, bytes, true); 112 * 113 * is logically equivalent to 114 * 115 * char *buf = malloc(bytes); 116 * iov_to_buf(iov, iovcnt, offset, buf, bytes); 117 * r = send(sockfd, buf, bytes, 0); 118 * free(buf); 119 * 120 * For iov_send_recv() _whole_ area being sent or received 121 * should be within the iovec, not only beginning of it. 122 */ 123 ssize_t iov_send_recv(int sockfd, const struct iovec *iov, unsigned iov_cnt, 124 size_t offset, size_t bytes, bool do_send); 125 #define iov_recv(sockfd, iov, iov_cnt, offset, bytes) \ 126 iov_send_recv(sockfd, iov, iov_cnt, offset, bytes, false) 127 #define iov_send(sockfd, iov, iov_cnt, offset, bytes) \ 128 iov_send_recv(sockfd, iov, iov_cnt, offset, bytes, true) 129 130 /** 131 * Produce a text hexdump of iovec `iov' with `iov_cnt' number of elements 132 * in file `fp', prefixing each line with `prefix' and processing not more 133 * than `limit' data bytes. 134 */ 135 void iov_hexdump(const struct iovec *iov, const unsigned int iov_cnt, 136 FILE *fp, const char *prefix, size_t limit); 137 138 /* 139 * Partial copy of vector from iov to dst_iov (data is not copied). 140 * dst_iov overlaps iov at a specified offset. 141 * size of dst_iov is at most bytes. dst vector count is returned. 142 */ 143 unsigned iov_copy(struct iovec *dst_iov, unsigned int dst_iov_cnt, 144 const struct iovec *iov, unsigned int iov_cnt, 145 size_t offset, size_t bytes); 146 147 /* 148 * Remove a given number of bytes from the front or back of a vector. 149 * This may update iov and/or iov_cnt to exclude iovec elements that are 150 * no longer required. 151 * 152 * The number of bytes actually discarded is returned. This number may be 153 * smaller than requested if the vector is too small. 154 */ 155 size_t iov_discard_front(struct iovec **iov, unsigned int *iov_cnt, 156 size_t bytes); 157 size_t iov_discard_back(struct iovec *iov, unsigned int *iov_cnt, 158 size_t bytes); 159 160 /* Information needed to undo an iov_discard_*() operation */ 161 typedef struct { 162 struct iovec *modified_iov; 163 struct iovec orig; 164 } IOVDiscardUndo; 165 166 /* 167 * Undo an iov_discard_front_undoable() or iov_discard_back_undoable() 168 * operation. If multiple operations are made then each one needs a separate 169 * IOVDiscardUndo and iov_discard_undo() must be called in the reverse order 170 * that the operations were made. 171 */ 172 void iov_discard_undo(IOVDiscardUndo *undo); 173 174 /* 175 * Undoable versions of iov_discard_front() and iov_discard_back(). Use 176 * iov_discard_undo() to reset to the state before the discard operations. 177 */ 178 size_t iov_discard_front_undoable(struct iovec **iov, unsigned int *iov_cnt, 179 size_t bytes, IOVDiscardUndo *undo); 180 size_t iov_discard_back_undoable(struct iovec *iov, unsigned int *iov_cnt, 181 size_t bytes, IOVDiscardUndo *undo); 182 183 typedef struct QEMUIOVector { 184 struct iovec *iov; 185 int niov; 186 187 /* 188 * For external @iov (qemu_iovec_init_external()) or allocated @iov 189 * (qemu_iovec_init()), @size is the cumulative size of iovecs and 190 * @local_iov is invalid and unused. 191 * 192 * For embedded @iov (QEMU_IOVEC_INIT_BUF() or qemu_iovec_init_buf()), 193 * @iov is equal to &@local_iov, and @size is valid, as it has same 194 * offset and type as @local_iov.iov_len, which is guaranteed by 195 * static assertion below. 196 * 197 * @nalloc is always valid and is -1 both for embedded and external 198 * cases. It is included in the union only to ensure the padding prior 199 * to the @size field will not result in a 0-length array. 200 */ 201 union { 202 struct { 203 int nalloc; 204 struct iovec local_iov; 205 }; 206 struct { 207 char __pad[sizeof(int) + offsetof(struct iovec, iov_len)]; 208 size_t size; 209 }; 210 }; 211 } QEMUIOVector; 212 213 QEMU_BUILD_BUG_ON(offsetof(QEMUIOVector, size) != 214 offsetof(QEMUIOVector, local_iov.iov_len)); 215 216 #define QEMU_IOVEC_INIT_BUF(self, buf, len) \ 217 { \ 218 .iov = &(self).local_iov, \ 219 .niov = 1, \ 220 .nalloc = -1, \ 221 .local_iov = { \ 222 .iov_base = (void *)(buf), /* cast away const */ \ 223 .iov_len = (len), \ 224 }, \ 225 } 226 227 /* 228 * qemu_iovec_init_buf 229 * 230 * Initialize embedded QEMUIOVector. 231 * 232 * Note: "const" is used over @buf pointer to make it simple to pass 233 * const pointers, appearing in read functions. Then this "const" is 234 * cast away by QEMU_IOVEC_INIT_BUF(). 235 */ 236 static inline void qemu_iovec_init_buf(QEMUIOVector *qiov, 237 const void *buf, size_t len) 238 { 239 *qiov = (QEMUIOVector) QEMU_IOVEC_INIT_BUF(*qiov, buf, len); 240 } 241 242 static inline void *qemu_iovec_buf(QEMUIOVector *qiov) 243 { 244 /* Only supports embedded iov */ 245 assert(qiov->nalloc == -1 && qiov->iov == &qiov->local_iov); 246 247 return qiov->local_iov.iov_base; 248 } 249 250 void qemu_iovec_init(QEMUIOVector *qiov, int alloc_hint); 251 void qemu_iovec_init_external(QEMUIOVector *qiov, struct iovec *iov, int niov); 252 void qemu_iovec_init_slice(QEMUIOVector *qiov, QEMUIOVector *source, 253 size_t offset, size_t len); 254 struct iovec *qemu_iovec_slice(QEMUIOVector *qiov, 255 size_t offset, size_t len, 256 size_t *head, size_t *tail, int *niov); 257 int qemu_iovec_subvec_niov(QEMUIOVector *qiov, size_t offset, size_t len); 258 void qemu_iovec_add(QEMUIOVector *qiov, void *base, size_t len); 259 void qemu_iovec_concat(QEMUIOVector *dst, 260 QEMUIOVector *src, size_t soffset, size_t sbytes); 261 size_t qemu_iovec_concat_iov(QEMUIOVector *dst, 262 struct iovec *src_iov, unsigned int src_cnt, 263 size_t soffset, size_t sbytes); 264 bool qemu_iovec_is_zero(QEMUIOVector *qiov, size_t qiov_offeset, size_t bytes); 265 void qemu_iovec_destroy(QEMUIOVector *qiov); 266 void qemu_iovec_reset(QEMUIOVector *qiov); 267 size_t qemu_iovec_to_buf(QEMUIOVector *qiov, size_t offset, 268 void *buf, size_t bytes); 269 size_t qemu_iovec_from_buf(QEMUIOVector *qiov, size_t offset, 270 const void *buf, size_t bytes); 271 size_t qemu_iovec_memset(QEMUIOVector *qiov, size_t offset, 272 int fillc, size_t bytes); 273 ssize_t qemu_iovec_compare(QEMUIOVector *a, QEMUIOVector *b); 274 void qemu_iovec_clone(QEMUIOVector *dest, const QEMUIOVector *src, void *buf); 275 void qemu_iovec_discard_back(QEMUIOVector *qiov, size_t bytes); 276 277 #endif 278