VirtualBox

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

Last change on this file since 53447 was 44529, checked in by vboxsync, 12 years ago

header (C) fixes

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.3 KB
Line 
1/** @file
2 * IPRT - S/G buffer handling.
3 */
4
5/*
6 * Copyright (C) 2010-2013 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 */
83RTDECL(void) RTSgBufInit(PRTSGBUF pSgBuf, PCRTSGSEG paSegs, size_t cSegs);
84
85/**
86 * Resets the internal buffer position of the S/G buffer to the beginning.
87 *
88 * @returns nothing.
89 * @param pSgBuf The S/G buffer to reset.
90 */
91RTDECL(void) RTSgBufReset(PRTSGBUF pSgBuf);
92
93/**
94 * Clones a given S/G buffer.
95 *
96 * @returns nothing.
97 * @param pSgBufNew The new S/G buffer to clone to.
98 * @param pSgBufOld The source S/G buffer to clone from.
99 *
100 * @note This is only a shallow copy. Both S/G buffers will point to the
101 * same segment array.
102 */
103RTDECL(void) RTSgBufClone(PRTSGBUF pSgBufNew, PCRTSGBUF pSgBufOld);
104
105/**
106 * Returns the next segment in the S/G buffer or NULL if no segment is left.
107 *
108 * @returns Pointer to the next segment in the S/G buffer.
109 * @param pSgBuf The S/G buffer.
110 * @param pcbSeg Where to store the size of the returned segment.
111 * Holds the number of bytes requested initially or 0 to
112 * indicate that the size doesn't matter.
113 * This may contain fewer bytes on success if the current segment
114 * is smaller than the amount of bytes requested.
115 *
116 * @note This operation advances the internal buffer pointer of both S/G buffers.
117 */
118RTDECL(void *) RTSgBufGetNextSegment(PRTSGBUF pSgBuf, size_t *pcbSeg);
119
120/**
121 * Copy data between two S/G buffers.
122 *
123 * @returns The number of bytes copied.
124 * @param pSgBufDst The destination S/G buffer.
125 * @param pSgBufSrc The source S/G buffer.
126 * @param cbCopy Number of bytes to copy.
127 *
128 * @note This operation advances the internal buffer pointer of both S/G buffers.
129 */
130RTDECL(size_t) RTSgBufCopy(PRTSGBUF pSgBufDst, PRTSGBUF pSgBufSrc, size_t cbCopy);
131
132/**
133 * Compares the content of two S/G buffers.
134 *
135 * @returns Whatever memcmp returns.
136 * @param pSgBuf1 First S/G buffer.
137 * @param pSgBuf2 Second S/G buffer.
138 * @param cbCmp How many bytes to compare.
139 *
140 * @note This operation doesn't change the internal position of the S/G buffers.
141 */
142RTDECL(int) RTSgBufCmp(PCRTSGBUF pSgBuf1, PCRTSGBUF pSgBuf2, size_t cbCmp);
143
144/**
145 * Compares the content of two S/G buffers - advanced version.
146 *
147 * @returns Whatever memcmp returns.
148 * @param pSgBuf1 First S/G buffer.
149 * @param pSgBuf2 Second S/G buffer.
150 * @param cbCmp How many bytes to compare.
151 * @param pcbOff Where to store the offset of the first different byte
152 * in the buffer starting from the position of the S/G
153 * buffer before this call.
154 * @param fAdvance Flag whether the internal buffer position should be advanced.
155 *
156 */
157RTDECL(int) RTSgBufCmpEx(PRTSGBUF pSgBuf1, PRTSGBUF pSgBuf2, size_t cbCmp,
158 size_t *pcbOff, bool fAdvance);
159
160/**
161 * Fills an S/G buf with a constant byte.
162 *
163 * @returns The number of actually filled bytes.
164 * Can be less than than cbSet if the end of the S/G buffer was reached.
165 * @param pSgBuf The S/G buffer.
166 * @param ubFill The byte to fill the buffer with.
167 * @param cbSet How many bytes to set.
168 *
169 * @note This operation advances the internal buffer pointer of the S/G buffer.
170 */
171RTDECL(size_t) RTSgBufSet(PRTSGBUF pSgBuf, uint8_t ubFill, size_t cbSet);
172
173/**
174 * Copies data from an S/G buffer into a given non scattered buffer.
175 *
176 * @returns Number of bytes copied.
177 * @param pSgBuf The S/G buffer to copy from.
178 * @param pvBuf Buffer to copy the data into.
179 * @param cbCopy How many bytes to copy.
180 *
181 * @note This operation advances the internal buffer pointer of the S/G buffer.
182 */
183RTDECL(size_t) RTSgBufCopyToBuf(PRTSGBUF pSgBuf, void *pvBuf, size_t cbCopy);
184
185/**
186 * Copies data from a non scattered buffer into an S/G buffer.
187 *
188 * @returns Number of bytes copied.
189 * @param pSgBuf The S/G buffer to copy to.
190 * @param pvBuf Buffer to copy the data from.
191 * @param cbCopy How many bytes to copy.
192 *
193 * @note This operation advances the internal buffer pointer of the S/G buffer.
194 */
195RTDECL(size_t) RTSgBufCopyFromBuf(PRTSGBUF pSgBuf, const void *pvBuf, size_t cbCopy);
196
197/**
198 * Advances the internal buffer pointer.
199 *
200 * @returns Number of bytes the pointer was moved forward.
201 * @param pSgBuf The S/G buffer.
202 * @param cbAdvance Number of bytes to move forward.
203 */
204RTDECL(size_t) RTSgBufAdvance(PRTSGBUF pSgBuf, size_t cbAdvance);
205
206/**
207 * Constructs a new segment array starting from the current position
208 * and describing the given number of bytes.
209 *
210 * @returns Number of bytes the array describes.
211 * @param pSgBuf The S/G buffer.
212 * @param paSeg The uninitialized segment array.
213 * If NULL pcSeg will contain the number of segments needed
214 * to describe the requested amount of data.
215 * @param pcSeg The number of segments the given array has.
216 * This will hold the actual number of entries needed upon return.
217 * @param cbData Number of bytes the new array should describe.
218 *
219 * @note This operation advances the internal buffer pointer of the S/G buffer if paSeg is not NULL.
220 */
221RTDECL(size_t) RTSgBufSegArrayCreate(PRTSGBUF pSgBuf, PRTSGSEG paSeg, unsigned *pcSeg, size_t cbData);
222
223/**
224 * Returns whether the given S/G buffer is zeroed out from the current position
225 * upto the number of bytes to check.
226 *
227 * @returns true if the buffer has only zeros
228 * false otherwise.
229 * @param pSgBuf The S/G buffer.
230 * @param cbCheck Number of bytes to check.
231 */
232RTDECL(bool) RTSgBufIsZero(PRTSGBUF pSgBuf, size_t cbCheck);
233
234/**
235 * Maps the given S/G buffer to a segment array of another type (for example to
236 * iovec on POSIX or WSABUF on Windows).
237 *
238 * @param paMapped Where to store the pointer to the start of the native
239 * array or NULL. The memory needs to be freed with
240 * RTMemTmpFree().
241 * @param pSgBuf The S/G buffer to map.
242 * @param Struct Struct used as the destination.
243 * @param pvBufField Name of the field holding the pointer to a buffer.
244 * @param TypeBufPtr Type of the buffer pointer.
245 * @param cbBufField Name of the field holding the size of the buffer.
246 * @param TypeBufSize Type of the field for the buffer size.
247 * @param cSegsMapped Where to store the number of segments the native array
248 * has.
249 *
250 * @note This operation maps the whole S/G buffer starting at the current
251 * internal position. The internal buffer position is unchanged by
252 * this operation.
253 *
254 * @remark Usage is a bit ugly but saves a few lines of duplicated code
255 * somewhere else and makes it possible to keep the S/G buffer members
256 * private without going through RTSgBufSegArrayCreate() first.
257 */
258#define RTSgBufMapToNative(paMapped, pSgBuf, Struct, pvBufField, TypeBufPtr, cbBufField, TypeBufSize, cSegsMapped) \
259 do \
260 { \
261 AssertCompileMemberSize(Struct, pvBufField, RT_SIZEOFMEMB(RTSGSEG, pvSeg)); \
262 /*AssertCompile(RT_SIZEOFMEMB(Struct, cbBufField) >= RT_SIZEOFMEMB(RTSGSEG, cbSeg));*/ \
263 (cSegsMapped) = (pSgBuf)->cSegs - (pSgBuf)->idxSeg; \
264 \
265 /* We need room for at least one segment. */ \
266 if ((pSgBuf)->cSegs == (pSgBuf)->idxSeg) \
267 (cSegsMapped)++; \
268 \
269 (paMapped) = (Struct *)RTMemTmpAllocZ((cSegsMapped) * sizeof(Struct)); \
270 if ((paMapped)) \
271 { \
272 /* The first buffer is special because we could be in the middle of a segment. */ \
273 (paMapped)[0].pvBufField = (TypeBufPtr)(pSgBuf)->pvSegCur; \
274 (paMapped)[0].cbBufField = (TypeBufSize)(pSgBuf)->cbSegLeft; \
275 \
276 for (unsigned i = 1; i < (cSegsMapped); i++) \
277 { \
278 (paMapped)[i].pvBufField = (TypeBufPtr)(pSgBuf)->paSegs[(pSgBuf)->idxSeg + i].pvSeg; \
279 (paMapped)[i].cbBufField = (TypeBufSize)(pSgBuf)->paSegs[(pSgBuf)->idxSeg + i].cbSeg; \
280 } \
281 } \
282 } while (0)
283
284RT_C_DECLS_END
285
286/** @} */
287
288#endif
289
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