[28053] | 1 | /** @file
|
---|
[101690] | 2 | * IPRT - Scatter / Gather Buffers.
|
---|
[28053] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[98103] | 6 | * Copyright (C) 2010-2023 Oracle and/or its affiliates.
|
---|
[28053] | 7 | *
|
---|
[96407] | 8 | * This file is part of VirtualBox base platform packages, as
|
---|
| 9 | * available from https://www.virtualbox.org.
|
---|
[28053] | 10 | *
|
---|
[96407] | 11 | * This program is free software; you can redistribute it and/or
|
---|
| 12 | * modify it under the terms of the GNU General Public License
|
---|
| 13 | * as published by the Free Software Foundation, in version 3 of the
|
---|
| 14 | * License.
|
---|
| 15 | *
|
---|
| 16 | * This program is distributed in the hope that it will be useful, but
|
---|
| 17 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
| 18 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
---|
| 19 | * General Public License for more details.
|
---|
| 20 | *
|
---|
| 21 | * You should have received a copy of the GNU General Public License
|
---|
| 22 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
---|
| 23 | *
|
---|
[28053] | 24 | * The contents of this file may alternatively be used under the terms
|
---|
| 25 | * of the Common Development and Distribution License Version 1.0
|
---|
[96407] | 26 | * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
---|
| 27 | * in the VirtualBox distribution, in which case the provisions of the
|
---|
[28053] | 28 | * CDDL are applicable instead of those of the GPL.
|
---|
| 29 | *
|
---|
| 30 | * You may elect to license modified versions of this file under the
|
---|
| 31 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[96407] | 32 | *
|
---|
| 33 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
---|
[28053] | 34 | */
|
---|
| 35 |
|
---|
[76557] | 36 | #ifndef IPRT_INCLUDED_sg_h
|
---|
| 37 | #define IPRT_INCLUDED_sg_h
|
---|
[76507] | 38 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 39 | # pragma once
|
---|
| 40 | #endif
|
---|
[28053] | 41 |
|
---|
| 42 | #include <iprt/types.h>
|
---|
| 43 |
|
---|
| 44 | RT_C_DECLS_BEGIN
|
---|
| 45 |
|
---|
[77236] | 46 | /** @defgroup grp_rt_sgbuf RTSgBuf - Scatter / Gather Buffers
|
---|
| 47 | * @ingroup grp_rt
|
---|
| 48 | * @{
|
---|
| 49 | */
|
---|
| 50 |
|
---|
[89264] | 51 | /** Pointer to a const S/G entry. */
|
---|
| 52 | typedef const struct RTSGBUF *PCRTSGBUF;
|
---|
| 53 |
|
---|
[28053] | 54 | /**
|
---|
[89264] | 55 | * Callback for RTSgBufCopyToFn() called on every segment of the given S/G buffer.
|
---|
| 56 | *
|
---|
| 57 | * @returns Number of bytes copied for this segment, a value smaller than cbSrc will stop the copy operation.
|
---|
| 58 | * @param pSgBuf The S/G buffer for reference.
|
---|
| 59 | * @param pvSrc Where to copy from.
|
---|
| 60 | * @param cbSrc The number of bytes in the source buffer.
|
---|
| 61 | * @param pvUser Opaque user data passed in RTSgBufCopyToFn().
|
---|
| 62 | */
|
---|
| 63 | typedef DECLCALLBACKTYPE(size_t, FNRTSGBUFCOPYTO, (PCRTSGBUF pSgBuf, const void *pvSrc, size_t cbSrc, void *pvUser));
|
---|
| 64 | /** Pointer to a FNRTSGBUFCOPYTO. */
|
---|
| 65 | typedef FNRTSGBUFCOPYTO *PFNRTSGBUFCOPYTO;
|
---|
| 66 |
|
---|
| 67 | /**
|
---|
| 68 | * Callback for RTSgBufCopyFromFn() called on every segment of the given S/G buffer.
|
---|
| 69 | *
|
---|
| 70 | * @returns Number of bytes copied for this segment, a value smaller than cbDst will stop the copy operation.
|
---|
| 71 | * @param pSgBuf The S/G buffer for reference.
|
---|
| 72 | * @param pvDst Where to copy to.
|
---|
| 73 | * @param cbDst The number of bytes in the destination buffer.
|
---|
| 74 | * @param pvUser Opaque user data passed in RTSgBufCopyFromFn().
|
---|
| 75 | */
|
---|
| 76 | typedef DECLCALLBACKTYPE(size_t, FNRTSGBUFCOPYFROM, (PCRTSGBUF pSgBuf, void *pvDst, size_t cbDst, void *pvUser));
|
---|
| 77 | /** Pointer to a FNRTSGBUFCOPYFROM. */
|
---|
| 78 | typedef FNRTSGBUFCOPYFROM *PFNRTSGBUFCOPYFROM;
|
---|
| 79 |
|
---|
| 80 | /**
|
---|
[28053] | 81 | * A S/G entry.
|
---|
| 82 | */
|
---|
| 83 | typedef struct RTSGSEG
|
---|
| 84 | {
|
---|
| 85 | /** Pointer to the segment buffer. */
|
---|
| 86 | void *pvSeg;
|
---|
| 87 | /** Size of the segment buffer. */
|
---|
| 88 | size_t cbSeg;
|
---|
| 89 | } RTSGSEG;
|
---|
| 90 | /** Pointer to a S/G entry. */
|
---|
| 91 | typedef RTSGSEG *PRTSGSEG;
|
---|
| 92 | /** Pointer to a const S/G entry. */
|
---|
| 93 | typedef const RTSGSEG *PCRTSGSEG;
|
---|
| 94 | /** Pointer to a S/G entry pointer. */
|
---|
| 95 | typedef PRTSGSEG *PPRTSGSEG;
|
---|
| 96 |
|
---|
| 97 | /**
|
---|
| 98 | * A S/G buffer.
|
---|
| 99 | *
|
---|
| 100 | * The members should be treated as private.
|
---|
[77236] | 101 | *
|
---|
| 102 | * @warning There is a lot of code, especially in the VFS area of IPRT, that
|
---|
| 103 | * totally ignores the idxSeg, pvSegCur and cbSegLeft members! So,
|
---|
| 104 | * it is not recommended to pass buffers that aren't fully reset or
|
---|
| 105 | * where cbSegLeft is shorter than what paSegs describes.
|
---|
[28053] | 106 | */
|
---|
| 107 | typedef struct RTSGBUF
|
---|
| 108 | {
|
---|
| 109 | /** Pointer to the scatter/gather array. */
|
---|
[30468] | 110 | PCRTSGSEG paSegs;
|
---|
[28053] | 111 | /** Number of segments. */
|
---|
[30468] | 112 | unsigned cSegs;
|
---|
[77236] | 113 |
|
---|
[28053] | 114 | /** Current segment we are in. */
|
---|
| 115 | unsigned idxSeg;
|
---|
[80410] | 116 | /** Pointer to current byte within the current segment. */
|
---|
[30468] | 117 | void *pvSegCur;
|
---|
[80410] | 118 | /** Number of bytes left in the current segment. */
|
---|
[28053] | 119 | size_t cbSegLeft;
|
---|
| 120 | } RTSGBUF;
|
---|
| 121 | /** Pointer to a S/G entry. */
|
---|
| 122 | typedef RTSGBUF *PRTSGBUF;
|
---|
| 123 | /** Pointer to a S/G entry pointer. */
|
---|
| 124 | typedef PRTSGBUF *PPRTSGBUF;
|
---|
| 125 |
|
---|
[77236] | 126 |
|
---|
[28053] | 127 | /**
|
---|
[77236] | 128 | * Sums up the length of all the segments.
|
---|
| 129 | *
|
---|
| 130 | * @returns The complete segment length.
|
---|
| 131 | * @param pSgBuf The S/G buffer to check out.
|
---|
| 132 | */
|
---|
| 133 | DECLINLINE(size_t) RTSgBufCalcTotalLength(PCRTSGBUF pSgBuf)
|
---|
| 134 | {
|
---|
| 135 | size_t cb = 0;
|
---|
| 136 | unsigned i = pSgBuf->cSegs;
|
---|
| 137 | while (i-- > 0)
|
---|
| 138 | cb += pSgBuf->paSegs[i].cbSeg;
|
---|
| 139 | return cb;
|
---|
| 140 | }
|
---|
| 141 |
|
---|
| 142 | /**
|
---|
| 143 | * Sums up the number of bytes left from the current position.
|
---|
| 144 | *
|
---|
| 145 | * @returns Number of bytes left.
|
---|
| 146 | * @param pSgBuf The S/G buffer to check out.
|
---|
| 147 | */
|
---|
| 148 | DECLINLINE(size_t) RTSgBufCalcLengthLeft(PCRTSGBUF pSgBuf)
|
---|
| 149 | {
|
---|
| 150 | size_t cb = pSgBuf->cbSegLeft;
|
---|
| 151 | unsigned i = pSgBuf->cSegs;
|
---|
| 152 | while (i-- > pSgBuf->idxSeg + 1)
|
---|
| 153 | cb += pSgBuf->paSegs[i].cbSeg;
|
---|
| 154 | return cb;
|
---|
| 155 | }
|
---|
| 156 |
|
---|
| 157 | /**
|
---|
| 158 | * Checks if the current buffer position is at the start of the first segment.
|
---|
| 159 | *
|
---|
| 160 | * @returns true / false.
|
---|
| 161 | * @param pSgBuf The S/G buffer to check out.
|
---|
| 162 | */
|
---|
| 163 | DECLINLINE(bool) RTSgBufIsAtStart(PCRTSGBUF pSgBuf)
|
---|
| 164 | {
|
---|
| 165 | return pSgBuf->idxSeg == 0
|
---|
| 166 | && ( pSgBuf->cSegs == 0
|
---|
| 167 | || pSgBuf->pvSegCur == pSgBuf->paSegs[0].pvSeg);
|
---|
| 168 | }
|
---|
| 169 |
|
---|
| 170 | /**
|
---|
| 171 | * Checks if the current buffer position is at the end of all the segments.
|
---|
| 172 | *
|
---|
| 173 | * @returns true / false.
|
---|
| 174 | * @param pSgBuf The S/G buffer to check out.
|
---|
| 175 | */
|
---|
| 176 | DECLINLINE(bool) RTSgBufIsAtEnd(PCRTSGBUF pSgBuf)
|
---|
| 177 | {
|
---|
[99960] | 178 | return pSgBuf->idxSeg >= pSgBuf->cSegs
|
---|
| 179 | || ( pSgBuf->cbSegLeft == 0 /* sg.cpp doesn't create this situation, but just in case someone does. */
|
---|
| 180 | && pSgBuf->idxSeg + 1 == pSgBuf->cSegs);
|
---|
[77236] | 181 | }
|
---|
| 182 |
|
---|
| 183 | /**
|
---|
| 184 | * Checks if the current buffer position is at the start of the current segment.
|
---|
| 185 | *
|
---|
| 186 | * @returns true / false.
|
---|
| 187 | * @param pSgBuf The S/G buffer to check out.
|
---|
| 188 | */
|
---|
| 189 | DECLINLINE(bool) RTSgBufIsAtStartOfSegment(PCRTSGBUF pSgBuf)
|
---|
| 190 | {
|
---|
| 191 | return pSgBuf->idxSeg < pSgBuf->cSegs
|
---|
| 192 | && pSgBuf->paSegs[pSgBuf->idxSeg].pvSeg == pSgBuf->pvSegCur;
|
---|
| 193 | }
|
---|
| 194 |
|
---|
| 195 | /**
|
---|
[28053] | 196 | * Initialize a S/G buffer structure.
|
---|
| 197 | *
|
---|
| 198 | * @param pSgBuf Pointer to the S/G buffer to initialize.
|
---|
[30468] | 199 | * @param paSegs Pointer to the start of the segment array.
|
---|
| 200 | * @param cSegs Number of segments in the array.
|
---|
[60346] | 201 | *
|
---|
[99960] | 202 | * @note paSegs and cSegs can be NULL and 0 respectively to indicate an empty
|
---|
| 203 | * S/G buffer. Operations on the S/G buffer will not do anything in
|
---|
| 204 | * this case.
|
---|
[28053] | 205 | */
|
---|
[30470] | 206 | RTDECL(void) RTSgBufInit(PRTSGBUF pSgBuf, PCRTSGSEG paSegs, size_t cSegs);
|
---|
[28053] | 207 |
|
---|
| 208 | /**
|
---|
| 209 | * Resets the internal buffer position of the S/G buffer to the beginning.
|
---|
| 210 | *
|
---|
| 211 | * @param pSgBuf The S/G buffer to reset.
|
---|
| 212 | */
|
---|
| 213 | RTDECL(void) RTSgBufReset(PRTSGBUF pSgBuf);
|
---|
| 214 |
|
---|
| 215 | /**
|
---|
| 216 | * Clones a given S/G buffer.
|
---|
[99961] | 217 | *
|
---|
[99960] | 218 | * This is only a shallow copy. Both S/G buffers will point to the same segment
|
---|
[99961] | 219 | * array.
|
---|
| 220 | *
|
---|
[99960] | 221 | * The buffer position will be preserved.
|
---|
[99961] | 222 | *
|
---|
[28053] | 223 | * @param pSgBufNew The new S/G buffer to clone to.
|
---|
| 224 | * @param pSgBufOld The source S/G buffer to clone from.
|
---|
| 225 | */
|
---|
| 226 | RTDECL(void) RTSgBufClone(PRTSGBUF pSgBufNew, PCRTSGBUF pSgBufOld);
|
---|
| 227 |
|
---|
| 228 | /**
|
---|
[77236] | 229 | * Returns the next segment in the S/G buffer or NULL if no segments left.
|
---|
| 230 | *
|
---|
| 231 | * @returns Pointer to the next segment in the S/G buffer.
|
---|
| 232 | * @param pSgBuf The S/G buffer.
|
---|
| 233 | * @param cbDesired The max number of bytes to get.
|
---|
| 234 | * @param pcbSeg Where to store the size of the returned segment, this is
|
---|
| 235 | * equal or smaller than @a cbDesired.
|
---|
| 236 | *
|
---|
| 237 | * @note Use RTSgBufAdvance() to advance after read/writing into the buffer.
|
---|
| 238 | */
|
---|
| 239 | DECLINLINE(void *) RTSgBufGetCurrentSegment(PRTSGBUF pSgBuf, size_t cbDesired, size_t *pcbSeg)
|
---|
| 240 | {
|
---|
| 241 | if (!RTSgBufIsAtEnd(pSgBuf))
|
---|
| 242 | {
|
---|
| 243 | *pcbSeg = RT_MIN(cbDesired, pSgBuf->cbSegLeft);
|
---|
| 244 | return pSgBuf->pvSegCur;
|
---|
| 245 | }
|
---|
| 246 | *pcbSeg = 0;
|
---|
| 247 | return NULL;
|
---|
| 248 | }
|
---|
| 249 |
|
---|
| 250 | /**
|
---|
[38539] | 251 | * Returns the next segment in the S/G buffer or NULL if no segment is left.
|
---|
| 252 | *
|
---|
| 253 | * @returns Pointer to the next segment in the S/G buffer.
|
---|
| 254 | * @param pSgBuf The S/G buffer.
|
---|
| 255 | * @param pcbSeg Where to store the size of the returned segment.
|
---|
| 256 | * Holds the number of bytes requested initially or 0 to
|
---|
| 257 | * indicate that the size doesn't matter.
|
---|
| 258 | * This may contain fewer bytes on success if the current segment
|
---|
| 259 | * is smaller than the amount of bytes requested.
|
---|
| 260 | *
|
---|
[99960] | 261 | * @note This operation advances the internal buffer pointer of both S/G buffers.
|
---|
[38539] | 262 | */
|
---|
| 263 | RTDECL(void *) RTSgBufGetNextSegment(PRTSGBUF pSgBuf, size_t *pcbSeg);
|
---|
| 264 |
|
---|
| 265 | /**
|
---|
[28053] | 266 | * Copy data between two S/G buffers.
|
---|
| 267 | *
|
---|
| 268 | * @returns The number of bytes copied.
|
---|
| 269 | * @param pSgBufDst The destination S/G buffer.
|
---|
| 270 | * @param pSgBufSrc The source S/G buffer.
|
---|
| 271 | * @param cbCopy Number of bytes to copy.
|
---|
| 272 | *
|
---|
[99960] | 273 | * @note This operation advances the internal buffer pointer of both S/G buffers.
|
---|
[28053] | 274 | */
|
---|
| 275 | RTDECL(size_t) RTSgBufCopy(PRTSGBUF pSgBufDst, PRTSGBUF pSgBufSrc, size_t cbCopy);
|
---|
| 276 |
|
---|
| 277 | /**
|
---|
| 278 | * Compares the content of two S/G buffers.
|
---|
| 279 | *
|
---|
| 280 | * @returns Whatever memcmp returns.
|
---|
| 281 | * @param pSgBuf1 First S/G buffer.
|
---|
| 282 | * @param pSgBuf2 Second S/G buffer.
|
---|
| 283 | * @param cbCmp How many bytes to compare.
|
---|
| 284 | *
|
---|
[99960] | 285 | * @note This operation doesn't change the internal position of the S/G buffers.
|
---|
[28053] | 286 | */
|
---|
| 287 | RTDECL(int) RTSgBufCmp(PCRTSGBUF pSgBuf1, PCRTSGBUF pSgBuf2, size_t cbCmp);
|
---|
| 288 |
|
---|
| 289 | /**
|
---|
[28117] | 290 | * Compares the content of two S/G buffers - advanced version.
|
---|
| 291 | *
|
---|
| 292 | * @returns Whatever memcmp returns.
|
---|
| 293 | * @param pSgBuf1 First S/G buffer.
|
---|
| 294 | * @param pSgBuf2 Second S/G buffer.
|
---|
| 295 | * @param cbCmp How many bytes to compare.
|
---|
[59745] | 296 | * @param poffDiff Where to store the offset of the first different byte
|
---|
[28117] | 297 | * in the buffer starting from the position of the S/G
|
---|
| 298 | * buffer before this call.
|
---|
| 299 | * @param fAdvance Flag whether the internal buffer position should be advanced.
|
---|
| 300 | *
|
---|
| 301 | */
|
---|
[59746] | 302 | RTDECL(int) RTSgBufCmpEx(PRTSGBUF pSgBuf1, PRTSGBUF pSgBuf2, size_t cbCmp, size_t *poffDiff, bool fAdvance);
|
---|
[28117] | 303 |
|
---|
| 304 | /**
|
---|
[28053] | 305 | * Fills an S/G buf with a constant byte.
|
---|
| 306 | *
|
---|
| 307 | * @returns The number of actually filled bytes.
|
---|
| 308 | * Can be less than than cbSet if the end of the S/G buffer was reached.
|
---|
| 309 | * @param pSgBuf The S/G buffer.
|
---|
[99960] | 310 | * @param bFill The byte to fill the buffer with.
|
---|
| 311 | * @param cbToSet How many bytes to set.
|
---|
[28053] | 312 | *
|
---|
[99960] | 313 | * @note This operation advances the internal buffer pointer of the S/G buffer.
|
---|
[28053] | 314 | */
|
---|
[99960] | 315 | RTDECL(size_t) RTSgBufSet(PRTSGBUF pSgBuf, uint8_t bFill, size_t cbToSet);
|
---|
[28053] | 316 |
|
---|
| 317 | /**
|
---|
| 318 | * Copies data from an S/G buffer into a given non scattered buffer.
|
---|
| 319 | *
|
---|
| 320 | * @returns Number of bytes copied.
|
---|
| 321 | * @param pSgBuf The S/G buffer to copy from.
|
---|
| 322 | * @param pvBuf Buffer to copy the data into.
|
---|
| 323 | * @param cbCopy How many bytes to copy.
|
---|
| 324 | *
|
---|
[99960] | 325 | * @note This operation advances the internal buffer pointer of the S/G buffer.
|
---|
[28053] | 326 | */
|
---|
| 327 | RTDECL(size_t) RTSgBufCopyToBuf(PRTSGBUF pSgBuf, void *pvBuf, size_t cbCopy);
|
---|
| 328 |
|
---|
| 329 | /**
|
---|
| 330 | * Copies data from a non scattered buffer into an S/G buffer.
|
---|
| 331 | *
|
---|
| 332 | * @returns Number of bytes copied.
|
---|
| 333 | * @param pSgBuf The S/G buffer to copy to.
|
---|
[44250] | 334 | * @param pvBuf Buffer to copy the data from.
|
---|
[28053] | 335 | * @param cbCopy How many bytes to copy.
|
---|
| 336 | *
|
---|
[99960] | 337 | * @note This operation advances the internal buffer pointer of the S/G buffer.
|
---|
[28053] | 338 | */
|
---|
[44250] | 339 | RTDECL(size_t) RTSgBufCopyFromBuf(PRTSGBUF pSgBuf, const void *pvBuf, size_t cbCopy);
|
---|
[28053] | 340 |
|
---|
| 341 | /**
|
---|
[89264] | 342 | * Copies data from the given S/G buffer to a destination handled by the given callback.
|
---|
| 343 | *
|
---|
| 344 | * @returns Number of bytes copied.
|
---|
| 345 | * @param pSgBuf The S/G buffer to copy from.
|
---|
| 346 | * @param cbCopy How many bytes to copy.
|
---|
| 347 | * @param pfnCopyTo The callback to call on every S/G buffer segment until the operation finished.
|
---|
| 348 | * @param pvUser Opaque user data to pass in the given callback.
|
---|
| 349 | *
|
---|
[99960] | 350 | * @note This operation advances the internal buffer pointer of the S/G buffer.
|
---|
[89264] | 351 | */
|
---|
| 352 | RTDECL(size_t) RTSgBufCopyToFn(PRTSGBUF pSgBuf, size_t cbCopy, PFNRTSGBUFCOPYTO pfnCopyTo, void *pvUser);
|
---|
| 353 |
|
---|
| 354 | /**
|
---|
| 355 | * Copies data to the given S/G buffer from a destination handled by the given callback.
|
---|
| 356 | *
|
---|
| 357 | * @returns Number of bytes copied.
|
---|
| 358 | * @param pSgBuf The S/G buffer to copy to.
|
---|
| 359 | * @param cbCopy How many bytes to copy.
|
---|
| 360 | * @param pfnCopyFrom The callback to call on every S/G buffer segment until the operation finished.
|
---|
| 361 | * @param pvUser Opaque user data to pass in the given callback.
|
---|
| 362 | *
|
---|
[99960] | 363 | * @note This operation advances the internal buffer pointer of the S/G buffer.
|
---|
[89264] | 364 | */
|
---|
| 365 | RTDECL(size_t) RTSgBufCopyFromFn(PRTSGBUF pSgBuf, size_t cbCopy, PFNRTSGBUFCOPYFROM pfnCopyFrom, void *pvUser);
|
---|
| 366 |
|
---|
| 367 | /**
|
---|
[28113] | 368 | * Advances the internal buffer pointer.
|
---|
| 369 | *
|
---|
| 370 | * @returns Number of bytes the pointer was moved forward.
|
---|
| 371 | * @param pSgBuf The S/G buffer.
|
---|
| 372 | * @param cbAdvance Number of bytes to move forward.
|
---|
| 373 | */
|
---|
| 374 | RTDECL(size_t) RTSgBufAdvance(PRTSGBUF pSgBuf, size_t cbAdvance);
|
---|
| 375 |
|
---|
| 376 | /**
|
---|
[28053] | 377 | * Constructs a new segment array starting from the current position
|
---|
| 378 | * and describing the given number of bytes.
|
---|
| 379 | *
|
---|
| 380 | * @returns Number of bytes the array describes.
|
---|
| 381 | * @param pSgBuf The S/G buffer.
|
---|
[31583] | 382 | * @param paSeg The uninitialized segment array.
|
---|
| 383 | * If NULL pcSeg will contain the number of segments needed
|
---|
| 384 | * to describe the requested amount of data.
|
---|
[28053] | 385 | * @param pcSeg The number of segments the given array has.
|
---|
| 386 | * This will hold the actual number of entries needed upon return.
|
---|
| 387 | * @param cbData Number of bytes the new array should describe.
|
---|
| 388 | *
|
---|
[31583] | 389 | * @note This operation advances the internal buffer pointer of the S/G buffer if paSeg is not NULL.
|
---|
[28053] | 390 | */
|
---|
| 391 | RTDECL(size_t) RTSgBufSegArrayCreate(PRTSGBUF pSgBuf, PRTSGSEG paSeg, unsigned *pcSeg, size_t cbData);
|
---|
| 392 |
|
---|
[31448] | 393 | /**
|
---|
[44241] | 394 | * Returns whether the given S/G buffer is zeroed out from the current position
|
---|
| 395 | * upto the number of bytes to check.
|
---|
[99961] | 396 | *
|
---|
[99960] | 397 | * @retval true if the buffer has only zeros
|
---|
| 398 | * @retval false otherwise.
|
---|
[44241] | 399 | * @param pSgBuf The S/G buffer.
|
---|
[99961] | 400 | * @param cbCheck Number of bytes to check.
|
---|
| 401 | *
|
---|
[99960] | 402 | * @note This operation advances the internal buffer pointer of the S/G buffer.
|
---|
[44241] | 403 | */
|
---|
| 404 | RTDECL(bool) RTSgBufIsZero(PRTSGBUF pSgBuf, size_t cbCheck);
|
---|
| 405 |
|
---|
| 406 | /**
|
---|
[31526] | 407 | * Maps the given S/G buffer to a segment array of another type (for example to
|
---|
| 408 | * iovec on POSIX or WSABUF on Windows).
|
---|
[31448] | 409 | *
|
---|
[31526] | 410 | * @param paMapped Where to store the pointer to the start of the native
|
---|
| 411 | * array or NULL. The memory needs to be freed with
|
---|
| 412 | * RTMemTmpFree().
|
---|
[31448] | 413 | * @param pSgBuf The S/G buffer to map.
|
---|
| 414 | * @param Struct Struct used as the destination.
|
---|
[31526] | 415 | * @param pvBufField Name of the field holding the pointer to a buffer.
|
---|
[31448] | 416 | * @param TypeBufPtr Type of the buffer pointer.
|
---|
[31526] | 417 | * @param cbBufField Name of the field holding the size of the buffer.
|
---|
[31448] | 418 | * @param TypeBufSize Type of the field for the buffer size.
|
---|
[31526] | 419 | * @param cSegsMapped Where to store the number of segments the native array
|
---|
| 420 | * has.
|
---|
[31448] | 421 | *
|
---|
[31526] | 422 | * @note This operation maps the whole S/G buffer starting at the current
|
---|
| 423 | * internal position. The internal buffer position is unchanged by
|
---|
| 424 | * this operation.
|
---|
[31448] | 425 | *
|
---|
[31526] | 426 | * @remark Usage is a bit ugly but saves a few lines of duplicated code
|
---|
| 427 | * somewhere else and makes it possible to keep the S/G buffer members
|
---|
| 428 | * private without going through RTSgBufSegArrayCreate() first.
|
---|
[31448] | 429 | */
|
---|
[31526] | 430 | #define RTSgBufMapToNative(paMapped, pSgBuf, Struct, pvBufField, TypeBufPtr, cbBufField, TypeBufSize, cSegsMapped) \
|
---|
| 431 | do \
|
---|
| 432 | { \
|
---|
| 433 | AssertCompileMemberSize(Struct, pvBufField, RT_SIZEOFMEMB(RTSGSEG, pvSeg)); \
|
---|
| 434 | /*AssertCompile(RT_SIZEOFMEMB(Struct, cbBufField) >= RT_SIZEOFMEMB(RTSGSEG, cbSeg));*/ \
|
---|
| 435 | (cSegsMapped) = (pSgBuf)->cSegs - (pSgBuf)->idxSeg; \
|
---|
| 436 | \
|
---|
| 437 | /* We need room for at least one segment. */ \
|
---|
| 438 | if ((pSgBuf)->cSegs == (pSgBuf)->idxSeg) \
|
---|
| 439 | (cSegsMapped)++; \
|
---|
| 440 | \
|
---|
| 441 | (paMapped) = (Struct *)RTMemTmpAllocZ((cSegsMapped) * sizeof(Struct)); \
|
---|
| 442 | if ((paMapped)) \
|
---|
| 443 | { \
|
---|
[31448] | 444 | /* The first buffer is special because we could be in the middle of a segment. */ \
|
---|
[31526] | 445 | (paMapped)[0].pvBufField = (TypeBufPtr)(pSgBuf)->pvSegCur; \
|
---|
| 446 | (paMapped)[0].cbBufField = (TypeBufSize)(pSgBuf)->cbSegLeft; \
|
---|
| 447 | \
|
---|
| 448 | for (unsigned i = 1; i < (cSegsMapped); i++) \
|
---|
| 449 | { \
|
---|
| 450 | (paMapped)[i].pvBufField = (TypeBufPtr)(pSgBuf)->paSegs[(pSgBuf)->idxSeg + i].pvSeg; \
|
---|
| 451 | (paMapped)[i].cbBufField = (TypeBufSize)(pSgBuf)->paSegs[(pSgBuf)->idxSeg + i].cbSeg; \
|
---|
| 452 | } \
|
---|
| 453 | } \
|
---|
| 454 | } while (0)
|
---|
[31448] | 455 |
|
---|
[28053] | 456 | RT_C_DECLS_END
|
---|
| 457 |
|
---|
| 458 | /** @} */
|
---|
| 459 |
|
---|
[76585] | 460 | #endif /* !IPRT_INCLUDED_sg_h */
|
---|
[28053] | 461 |
|
---|