VirtualBox

source: vbox/trunk/include/iprt/sg.h@ 68661

Last change on this file since 68661 was 62473, checked in by vboxsync, 8 years ago

(C) 2016

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.5 KB
Line 
1/** @file
2 * IPRT - S/G buffer handling.
3 */
4
5/*
6 * Copyright (C) 2010-2016 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_sg_h
27#define ___iprt_sg_h
28
29#include <iprt/types.h>
30
31RT_C_DECLS_BEGIN
32
33/**
34 * A S/G entry.
35 */
36typedef struct RTSGSEG
37{
38 /** Pointer to the segment buffer. */
39 void *pvSeg;
40 /** Size of the segment buffer. */
41 size_t cbSeg;
42} RTSGSEG;
43/** Pointer to a S/G entry. */
44typedef RTSGSEG *PRTSGSEG;
45/** Pointer to a const S/G entry. */
46typedef const RTSGSEG *PCRTSGSEG;
47/** Pointer to a S/G entry pointer. */
48typedef PRTSGSEG *PPRTSGSEG;
49
50/**
51 * A S/G buffer.
52 *
53 * The members should be treated as private.
54 */
55typedef struct RTSGBUF
56{
57 /** Pointer to the scatter/gather array. */
58 PCRTSGSEG paSegs;
59 /** Number of segments. */
60 unsigned cSegs;
61 /** Current segment we are in. */
62 unsigned idxSeg;
63 /** Pointer to the current segment start. */
64 void *pvSegCur;
65 /** Number of bytes left in the current buffer. */
66 size_t cbSegLeft;
67} RTSGBUF;
68/** Pointer to a S/G entry. */
69typedef RTSGBUF *PRTSGBUF;
70/** Pointer to a const S/G entry. */
71typedef const RTSGBUF *PCRTSGBUF;
72/** Pointer to a S/G entry pointer. */
73typedef PRTSGBUF *PPRTSGBUF;
74
75/**
76 * Initialize a S/G buffer structure.
77 *
78 * @returns nothing.
79 * @param pSgBuf Pointer to the S/G buffer to initialize.
80 * @param paSegs Pointer to the start of the segment array.
81 * @param cSegs Number of segments in the array.
82 *
83 * @note paSegs and cSegs can be NULL and 0 respectively to indicate
84 * an empty S/G buffer. All operations on the S/G buffer will
85 * not do anything in this case.
86 */
87RTDECL(void) RTSgBufInit(PRTSGBUF pSgBuf, PCRTSGSEG paSegs, size_t cSegs);
88
89/**
90 * Resets the internal buffer position of the S/G buffer to the beginning.
91 *
92 * @returns nothing.
93 * @param pSgBuf The S/G buffer to reset.
94 */
95RTDECL(void) RTSgBufReset(PRTSGBUF pSgBuf);
96
97/**
98 * Clones a given S/G buffer.
99 *
100 * @returns nothing.
101 * @param pSgBufNew The new S/G buffer to clone to.
102 * @param pSgBufOld The source S/G buffer to clone from.
103 *
104 * @note This is only a shallow copy. Both S/G buffers will point to the
105 * same segment array.
106 */
107RTDECL(void) RTSgBufClone(PRTSGBUF pSgBufNew, PCRTSGBUF pSgBufOld);
108
109/**
110 * Returns the next segment in the S/G buffer or NULL if no segment is left.
111 *
112 * @returns Pointer to the next segment in the S/G buffer.
113 * @param pSgBuf The S/G buffer.
114 * @param pcbSeg Where to store the size of the returned segment.
115 * Holds the number of bytes requested initially or 0 to
116 * indicate that the size doesn't matter.
117 * This may contain fewer bytes on success if the current segment
118 * is smaller than the amount of bytes requested.
119 *
120 * @note This operation advances the internal buffer pointer of both S/G buffers.
121 */
122RTDECL(void *) RTSgBufGetNextSegment(PRTSGBUF pSgBuf, size_t *pcbSeg);
123
124/**
125 * Copy data between two S/G buffers.
126 *
127 * @returns The number of bytes copied.
128 * @param pSgBufDst The destination S/G buffer.
129 * @param pSgBufSrc The source S/G buffer.
130 * @param cbCopy Number of bytes to copy.
131 *
132 * @note This operation advances the internal buffer pointer of both S/G buffers.
133 */
134RTDECL(size_t) RTSgBufCopy(PRTSGBUF pSgBufDst, PRTSGBUF pSgBufSrc, size_t cbCopy);
135
136/**
137 * Compares the content of two S/G buffers.
138 *
139 * @returns Whatever memcmp returns.
140 * @param pSgBuf1 First S/G buffer.
141 * @param pSgBuf2 Second S/G buffer.
142 * @param cbCmp How many bytes to compare.
143 *
144 * @note This operation doesn't change the internal position of the S/G buffers.
145 */
146RTDECL(int) RTSgBufCmp(PCRTSGBUF pSgBuf1, PCRTSGBUF pSgBuf2, size_t cbCmp);
147
148/**
149 * Compares the content of two S/G buffers - advanced version.
150 *
151 * @returns Whatever memcmp returns.
152 * @param pSgBuf1 First S/G buffer.
153 * @param pSgBuf2 Second S/G buffer.
154 * @param cbCmp How many bytes to compare.
155 * @param poffDiff Where to store the offset of the first different byte
156 * in the buffer starting from the position of the S/G
157 * buffer before this call.
158 * @param fAdvance Flag whether the internal buffer position should be advanced.
159 *
160 */
161RTDECL(int) RTSgBufCmpEx(PRTSGBUF pSgBuf1, PRTSGBUF pSgBuf2, size_t cbCmp, size_t *poffDiff, bool fAdvance);
162
163/**
164 * Fills an S/G buf with a constant byte.
165 *
166 * @returns The number of actually filled bytes.
167 * Can be less than than cbSet if the end of the S/G buffer was reached.
168 * @param pSgBuf The S/G buffer.
169 * @param ubFill The byte to fill the buffer with.
170 * @param cbSet How many bytes to set.
171 *
172 * @note This operation advances the internal buffer pointer of the S/G buffer.
173 */
174RTDECL(size_t) RTSgBufSet(PRTSGBUF pSgBuf, uint8_t ubFill, size_t cbSet);
175
176/**
177 * Copies data from an S/G buffer into a given non scattered buffer.
178 *
179 * @returns Number of bytes copied.
180 * @param pSgBuf The S/G buffer to copy from.
181 * @param pvBuf Buffer to copy the data into.
182 * @param cbCopy How many bytes to copy.
183 *
184 * @note This operation advances the internal buffer pointer of the S/G buffer.
185 */
186RTDECL(size_t) RTSgBufCopyToBuf(PRTSGBUF pSgBuf, void *pvBuf, size_t cbCopy);
187
188/**
189 * Copies data from a non scattered buffer into an S/G buffer.
190 *
191 * @returns Number of bytes copied.
192 * @param pSgBuf The S/G buffer to copy to.
193 * @param pvBuf Buffer to copy the data from.
194 * @param cbCopy How many bytes to copy.
195 *
196 * @note This operation advances the internal buffer pointer of the S/G buffer.
197 */
198RTDECL(size_t) RTSgBufCopyFromBuf(PRTSGBUF pSgBuf, const void *pvBuf, size_t cbCopy);
199
200/**
201 * Advances the internal buffer pointer.
202 *
203 * @returns Number of bytes the pointer was moved forward.
204 * @param pSgBuf The S/G buffer.
205 * @param cbAdvance Number of bytes to move forward.
206 */
207RTDECL(size_t) RTSgBufAdvance(PRTSGBUF pSgBuf, size_t cbAdvance);
208
209/**
210 * Constructs a new segment array starting from the current position
211 * and describing the given number of bytes.
212 *
213 * @returns Number of bytes the array describes.
214 * @param pSgBuf The S/G buffer.
215 * @param paSeg The uninitialized segment array.
216 * If NULL pcSeg will contain the number of segments needed
217 * to describe the requested amount of data.
218 * @param pcSeg The number of segments the given array has.
219 * This will hold the actual number of entries needed upon return.
220 * @param cbData Number of bytes the new array should describe.
221 *
222 * @note This operation advances the internal buffer pointer of the S/G buffer if paSeg is not NULL.
223 */
224RTDECL(size_t) RTSgBufSegArrayCreate(PRTSGBUF pSgBuf, PRTSGSEG paSeg, unsigned *pcSeg, size_t cbData);
225
226/**
227 * Returns whether the given S/G buffer is zeroed out from the current position
228 * upto the number of bytes to check.
229 *
230 * @returns true if the buffer has only zeros
231 * false otherwise.
232 * @param pSgBuf The S/G buffer.
233 * @param cbCheck Number of bytes to check.
234 */
235RTDECL(bool) RTSgBufIsZero(PRTSGBUF pSgBuf, size_t cbCheck);
236
237/**
238 * Maps the given S/G buffer to a segment array of another type (for example to
239 * iovec on POSIX or WSABUF on Windows).
240 *
241 * @param paMapped Where to store the pointer to the start of the native
242 * array or NULL. The memory needs to be freed with
243 * RTMemTmpFree().
244 * @param pSgBuf The S/G buffer to map.
245 * @param Struct Struct used as the destination.
246 * @param pvBufField Name of the field holding the pointer to a buffer.
247 * @param TypeBufPtr Type of the buffer pointer.
248 * @param cbBufField Name of the field holding the size of the buffer.
249 * @param TypeBufSize Type of the field for the buffer size.
250 * @param cSegsMapped Where to store the number of segments the native array
251 * has.
252 *
253 * @note This operation maps the whole S/G buffer starting at the current
254 * internal position. The internal buffer position is unchanged by
255 * this operation.
256 *
257 * @remark Usage is a bit ugly but saves a few lines of duplicated code
258 * somewhere else and makes it possible to keep the S/G buffer members
259 * private without going through RTSgBufSegArrayCreate() first.
260 */
261#define RTSgBufMapToNative(paMapped, pSgBuf, Struct, pvBufField, TypeBufPtr, cbBufField, TypeBufSize, cSegsMapped) \
262 do \
263 { \
264 AssertCompileMemberSize(Struct, pvBufField, RT_SIZEOFMEMB(RTSGSEG, pvSeg)); \
265 /*AssertCompile(RT_SIZEOFMEMB(Struct, cbBufField) >= RT_SIZEOFMEMB(RTSGSEG, cbSeg));*/ \
266 (cSegsMapped) = (pSgBuf)->cSegs - (pSgBuf)->idxSeg; \
267 \
268 /* We need room for at least one segment. */ \
269 if ((pSgBuf)->cSegs == (pSgBuf)->idxSeg) \
270 (cSegsMapped)++; \
271 \
272 (paMapped) = (Struct *)RTMemTmpAllocZ((cSegsMapped) * sizeof(Struct)); \
273 if ((paMapped)) \
274 { \
275 /* The first buffer is special because we could be in the middle of a segment. */ \
276 (paMapped)[0].pvBufField = (TypeBufPtr)(pSgBuf)->pvSegCur; \
277 (paMapped)[0].cbBufField = (TypeBufSize)(pSgBuf)->cbSegLeft; \
278 \
279 for (unsigned i = 1; i < (cSegsMapped); i++) \
280 { \
281 (paMapped)[i].pvBufField = (TypeBufPtr)(pSgBuf)->paSegs[(pSgBuf)->idxSeg + i].pvSeg; \
282 (paMapped)[i].cbBufField = (TypeBufSize)(pSgBuf)->paSegs[(pSgBuf)->idxSeg + i].cbSeg; \
283 } \
284 } \
285 } while (0)
286
287RT_C_DECLS_END
288
289/** @} */
290
291#endif
292
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette