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 279