1 /*++
2
3 Copyright (c) Microsoft Corporation. All rights reserved.
4
5 _WdfVersionBuild_
6
7 Module Name:
8
9 WdfMemory.h
10
11 Abstract:
12
13 Contains prototypes for managing memory objects in the driver frameworks.
14
15 Author:
16
17 Environment:
18
19 kernel mode only
20
21 Revision History:
22
23 --*/
24
25 //
26 // NOTE: This header is generated by stubwork. Please make any
27 // modifications to the corresponding template files
28 // (.x or .y) and use stubwork to regenerate the header
29 //
30
31 #ifndef _WDFMEMORY_H_
32 #define _WDFMEMORY_H_
33
34 #ifndef WDF_EXTERN_C
35 #ifdef __cplusplus
36 #define WDF_EXTERN_C extern "C"
37 #define WDF_EXTERN_C_START extern "C" {
38 #define WDF_EXTERN_C_END }
39 #else
40 #define WDF_EXTERN_C
41 #define WDF_EXTERN_C_START
42 #define WDF_EXTERN_C_END
43 #endif
44 #endif
45
46 WDF_EXTERN_C_START
47
48
49
50 #if (NTDDI_VERSION >= NTDDI_WIN2K)
51
52 typedef enum _WDF_MEMORY_DESCRIPTOR_TYPE {
53 WdfMemoryDescriptorTypeInvalid = 0,
54 WdfMemoryDescriptorTypeBuffer,
55 WdfMemoryDescriptorTypeMdl,
56 WdfMemoryDescriptorTypeHandle,
57 } WDF_MEMORY_DESCRIPTOR_TYPE;
58
59
60
61 typedef struct _WDFMEMORY_OFFSET {
62 //
63 // Offset into the WDFMEMORY that the operation should start at.
64 //
65 size_t BufferOffset;
66
67 //
68 // Number of bytes that the operation should access. If 0, the entire
69 // length of the WDFMEMORY buffer will be used in the operation or ignored
70 // depending on the API.
71 //
72 size_t BufferLength;
73
74 } WDFMEMORY_OFFSET, *PWDFMEMORY_OFFSET;
75
76 typedef struct _WDF_MEMORY_DESCRIPTOR {
77 WDF_MEMORY_DESCRIPTOR_TYPE Type;
78
79 union {
80 struct {
81 PVOID Buffer;
82
83 ULONG Length;
84 } BufferType;
85
86 struct {
87 PMDL Mdl;
88
89 ULONG BufferLength;
90 } MdlType;
91
92 struct {
93 WDFMEMORY Memory;
94 PWDFMEMORY_OFFSET Offsets;
95 } HandleType;
96 } u;
97
98 } WDF_MEMORY_DESCRIPTOR, *PWDF_MEMORY_DESCRIPTOR;
99
100 FORCEINLINE
101 VOID
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(_Out_ PWDF_MEMORY_DESCRIPTOR Descriptor,_In_ PVOID Buffer,_In_ ULONG BufferLength)102 WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
103 _Out_ PWDF_MEMORY_DESCRIPTOR Descriptor,
104 _In_ PVOID Buffer,
105 _In_ ULONG BufferLength
106 )
107 {
108 RtlZeroMemory(Descriptor, sizeof(WDF_MEMORY_DESCRIPTOR));
109
110 Descriptor->Type = WdfMemoryDescriptorTypeBuffer;
111 Descriptor->u.BufferType.Buffer = Buffer;
112 Descriptor->u.BufferType.Length = BufferLength;
113 }
114
115 FORCEINLINE
116 VOID
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(_Out_ PWDF_MEMORY_DESCRIPTOR Descriptor,_In_ WDFMEMORY Memory,_In_opt_ PWDFMEMORY_OFFSET Offsets)117 WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(
118 _Out_ PWDF_MEMORY_DESCRIPTOR Descriptor,
119 _In_ WDFMEMORY Memory,
120 _In_opt_ PWDFMEMORY_OFFSET Offsets
121 )
122 {
123 RtlZeroMemory(Descriptor, sizeof(WDF_MEMORY_DESCRIPTOR));
124
125 Descriptor->Type = WdfMemoryDescriptorTypeHandle;
126 Descriptor->u.HandleType.Memory = Memory;
127 Descriptor->u.HandleType.Offsets = Offsets;
128 }
129
130
131 FORCEINLINE
132 VOID
WDF_MEMORY_DESCRIPTOR_INIT_MDL(_Out_ PWDF_MEMORY_DESCRIPTOR Descriptor,_In_ PMDL Mdl,_In_ ULONG BufferLength)133 WDF_MEMORY_DESCRIPTOR_INIT_MDL(
134 _Out_ PWDF_MEMORY_DESCRIPTOR Descriptor,
135 _In_ PMDL Mdl,
136 _In_ ULONG BufferLength
137 )
138 {
139 RtlZeroMemory(Descriptor, sizeof(WDF_MEMORY_DESCRIPTOR));
140
141 Descriptor->Type = WdfMemoryDescriptorTypeMdl;
142 Descriptor->u.MdlType.Mdl = Mdl;
143 Descriptor->u.MdlType.BufferLength = BufferLength;
144 }
145
146 //
147 // WDF Function: WdfMemoryCreate
148 //
149 typedef
150 _Must_inspect_result_
151 _When_(PoolType == 1 || PoolType == 257, _IRQL_requires_max_(APC_LEVEL))
152 _When_(PoolType == 0 || PoolType == 256, _IRQL_requires_max_(DISPATCH_LEVEL))
153 WDFAPI
154 NTSTATUS
155 (STDCALL *PFN_WDFMEMORYCREATE)(
156 _In_
157 PWDF_DRIVER_GLOBALS DriverGlobals,
158 _In_opt_
159 PWDF_OBJECT_ATTRIBUTES Attributes,
160 _In_
161 _Strict_type_match_
162 POOL_TYPE PoolType,
163 _In_opt_
164 ULONG PoolTag,
165 _In_
166 _When_(BufferSize == 0, __drv_reportError(BufferSize cannot be zero))
167 size_t BufferSize,
168 _Out_
169 WDFMEMORY* Memory,
170 _Outptr_opt_result_bytebuffer_(BufferSize)
171 PVOID* Buffer
172 );
173
174 _Must_inspect_result_
175 _When_(PoolType == 1 || PoolType == 257, _IRQL_requires_max_(APC_LEVEL))
176 _When_(PoolType == 0 || PoolType == 256, _IRQL_requires_max_(DISPATCH_LEVEL))
177 FORCEINLINE
178 NTSTATUS
179 WdfMemoryCreate(
180 _In_opt_
181 PWDF_OBJECT_ATTRIBUTES Attributes,
182 _In_
183 _Strict_type_match_
184 POOL_TYPE PoolType,
185 _In_opt_
186 ULONG PoolTag,
187 _In_
188 _When_(BufferSize == 0, __drv_reportError(BufferSize cannot be zero))
189 size_t BufferSize,
190 _Out_
191 WDFMEMORY* Memory,
192 _Outptr_opt_result_bytebuffer_(BufferSize)
193 PVOID* Buffer
194 )
195 {
196 return ((PFN_WDFMEMORYCREATE) WdfFunctions[WdfMemoryCreateTableIndex])(WdfDriverGlobals, Attributes, PoolType, PoolTag, BufferSize, Memory, Buffer);
197 }
198
199 //
200 // WDF Function: WdfMemoryCreatePreallocated
201 //
202 typedef
203 _Must_inspect_result_
204 _IRQL_requires_max_(DISPATCH_LEVEL)
205 WDFAPI
206 NTSTATUS
207 (STDCALL *PFN_WDFMEMORYCREATEPREALLOCATED)(
208 _In_
209 PWDF_DRIVER_GLOBALS DriverGlobals,
210 _In_opt_
211 PWDF_OBJECT_ATTRIBUTES Attributes,
212 _In_ __drv_aliasesMem
213 PVOID Buffer,
214 _In_
215 _When_(BufferSize == 0, __drv_reportError(BufferSize cannot be zero))
216 size_t BufferSize,
217 _Out_
218 WDFMEMORY* Memory
219 );
220
221 _Must_inspect_result_
_IRQL_requires_max_(DISPATCH_LEVEL)222 _IRQL_requires_max_(DISPATCH_LEVEL)
223 FORCEINLINE
224 NTSTATUS
225 WdfMemoryCreatePreallocated(
226 _In_opt_
227 PWDF_OBJECT_ATTRIBUTES Attributes,
228 _In_ __drv_aliasesMem
229 PVOID Buffer,
230 _In_
231 _When_(BufferSize == 0, __drv_reportError(BufferSize cannot be zero))
232 size_t BufferSize,
233 _Out_
234 WDFMEMORY* Memory
235 )
236 {
237 return ((PFN_WDFMEMORYCREATEPREALLOCATED) WdfFunctions[WdfMemoryCreatePreallocatedTableIndex])(WdfDriverGlobals, Attributes, Buffer, BufferSize, Memory);
238 }
239
240 //
241 // WDF Function: WdfMemoryGetBuffer
242 //
243 typedef
244 _IRQL_requires_max_(DISPATCH_LEVEL)
245 WDFAPI
246 PVOID
247 (STDCALL *PFN_WDFMEMORYGETBUFFER)(
248 _In_
249 PWDF_DRIVER_GLOBALS DriverGlobals,
250 _In_
251 WDFMEMORY Memory,
252 _Out_opt_
253 size_t* BufferSize
254 );
255
_IRQL_requires_max_(DISPATCH_LEVEL)256 _IRQL_requires_max_(DISPATCH_LEVEL)
257 FORCEINLINE
258 PVOID
259 WdfMemoryGetBuffer(
260 _In_
261 WDFMEMORY Memory,
262 _Out_opt_
263 size_t* BufferSize
264 )
265 {
266 return ((PFN_WDFMEMORYGETBUFFER) WdfFunctions[WdfMemoryGetBufferTableIndex])(WdfDriverGlobals, Memory, BufferSize);
267 }
268
269 //
270 // WDF Function: WdfMemoryAssignBuffer
271 //
272 typedef
273 _Must_inspect_result_
274 _IRQL_requires_max_(DISPATCH_LEVEL)
275 WDFAPI
276 NTSTATUS
277 (STDCALL *PFN_WDFMEMORYASSIGNBUFFER)(
278 _In_
279 PWDF_DRIVER_GLOBALS DriverGlobals,
280 _In_
281 WDFMEMORY Memory,
282 _Pre_notnull_ _Pre_writable_byte_size_(BufferSize)
283 PVOID Buffer,
284 _In_
285 _When_(BufferSize == 0, __drv_reportError(BufferSize cannot be zero))
286 size_t BufferSize
287 );
288
289 _Must_inspect_result_
_IRQL_requires_max_(DISPATCH_LEVEL)290 _IRQL_requires_max_(DISPATCH_LEVEL)
291 FORCEINLINE
292 NTSTATUS
293 WdfMemoryAssignBuffer(
294 _In_
295 WDFMEMORY Memory,
296 _Pre_notnull_ _Pre_writable_byte_size_(BufferSize)
297 PVOID Buffer,
298 _In_
299 _When_(BufferSize == 0, __drv_reportError(BufferSize cannot be zero))
300 size_t BufferSize
301 )
302 {
303 return ((PFN_WDFMEMORYASSIGNBUFFER) WdfFunctions[WdfMemoryAssignBufferTableIndex])(WdfDriverGlobals, Memory, Buffer, BufferSize);
304 }
305
306 //
307 // WDF Function: WdfMemoryCopyToBuffer
308 //
309 typedef
310 _Must_inspect_result_
311 _IRQL_requires_max_(DISPATCH_LEVEL)
312 WDFAPI
313 NTSTATUS
314 (STDCALL *PFN_WDFMEMORYCOPYTOBUFFER)(
315 _In_
316 PWDF_DRIVER_GLOBALS DriverGlobals,
317 _In_
318 WDFMEMORY SourceMemory,
319 _In_
320 size_t SourceOffset,
321 _Out_writes_bytes_( NumBytesToCopyTo )
322 PVOID Buffer,
323 _In_
324 _When_(NumBytesToCopyTo == 0, __drv_reportError(NumBytesToCopyTo cannot be zero))
325 size_t NumBytesToCopyTo
326 );
327
328 _Must_inspect_result_
_IRQL_requires_max_(DISPATCH_LEVEL)329 _IRQL_requires_max_(DISPATCH_LEVEL)
330 FORCEINLINE
331 NTSTATUS
332 WdfMemoryCopyToBuffer(
333 _In_
334 WDFMEMORY SourceMemory,
335 _In_
336 size_t SourceOffset,
337 _Out_writes_bytes_( NumBytesToCopyTo )
338 PVOID Buffer,
339 _In_
340 _When_(NumBytesToCopyTo == 0, __drv_reportError(NumBytesToCopyTo cannot be zero))
341 size_t NumBytesToCopyTo
342 )
343 {
344 return ((PFN_WDFMEMORYCOPYTOBUFFER) WdfFunctions[WdfMemoryCopyToBufferTableIndex])(WdfDriverGlobals, SourceMemory, SourceOffset, Buffer, NumBytesToCopyTo);
345 }
346
347 //
348 // WDF Function: WdfMemoryCopyFromBuffer
349 //
350 typedef
351 _Must_inspect_result_
352 _IRQL_requires_max_(DISPATCH_LEVEL)
353 WDFAPI
354 NTSTATUS
355 (STDCALL *PFN_WDFMEMORYCOPYFROMBUFFER)(
356 _In_
357 PWDF_DRIVER_GLOBALS DriverGlobals,
358 _In_
359 WDFMEMORY DestinationMemory,
360 _In_
361 size_t DestinationOffset,
362 _In_
363 PVOID Buffer,
364 _In_
365 _When_(NumBytesToCopyFrom == 0, __drv_reportError(NumBytesToCopyFrom cannot be zero))
366 size_t NumBytesToCopyFrom
367 );
368
369 _Must_inspect_result_
_IRQL_requires_max_(DISPATCH_LEVEL)370 _IRQL_requires_max_(DISPATCH_LEVEL)
371 FORCEINLINE
372 NTSTATUS
373 WdfMemoryCopyFromBuffer(
374 _In_
375 WDFMEMORY DestinationMemory,
376 _In_
377 size_t DestinationOffset,
378 _In_
379 PVOID Buffer,
380 _In_
381 _When_(NumBytesToCopyFrom == 0, __drv_reportError(NumBytesToCopyFrom cannot be zero))
382 size_t NumBytesToCopyFrom
383 )
384 {
385 return ((PFN_WDFMEMORYCOPYFROMBUFFER) WdfFunctions[WdfMemoryCopyFromBufferTableIndex])(WdfDriverGlobals, DestinationMemory, DestinationOffset, Buffer, NumBytesToCopyFrom);
386 }
387
388 //
389 // WDF Function: WdfLookasideListCreate
390 //
391 typedef
392 _Must_inspect_result_
393 _When_(PoolType == 1 || PoolType == 257, _IRQL_requires_max_(APC_LEVEL))
394 _When_(PoolType == 0 || PoolType == 256, _IRQL_requires_max_(DISPATCH_LEVEL))
395 WDFAPI
396 NTSTATUS
397 (STDCALL *PFN_WDFLOOKASIDELISTCREATE)(
398 _In_
399 PWDF_DRIVER_GLOBALS DriverGlobals,
400 _In_opt_
401 PWDF_OBJECT_ATTRIBUTES LookasideAttributes,
402 _In_
403 _When_(BufferSize == 0, __drv_reportError(BufferSize cannot be zero))
404 size_t BufferSize,
405 _In_
406 _Strict_type_match_
407 POOL_TYPE PoolType,
408 _In_opt_
409 PWDF_OBJECT_ATTRIBUTES MemoryAttributes,
410 _In_opt_
411 ULONG PoolTag,
412 _Out_
413 WDFLOOKASIDE* Lookaside
414 );
415
416 _Must_inspect_result_
417 _When_(PoolType == 1 || PoolType == 257, _IRQL_requires_max_(APC_LEVEL))
418 _When_(PoolType == 0 || PoolType == 256, _IRQL_requires_max_(DISPATCH_LEVEL))
419 FORCEINLINE
420 NTSTATUS
421 WdfLookasideListCreate(
422 _In_opt_
423 PWDF_OBJECT_ATTRIBUTES LookasideAttributes,
424 _In_
425 _When_(BufferSize == 0, __drv_reportError(BufferSize cannot be zero))
426 size_t BufferSize,
427 _In_
428 _Strict_type_match_
429 POOL_TYPE PoolType,
430 _In_opt_
431 PWDF_OBJECT_ATTRIBUTES MemoryAttributes,
432 _In_opt_
433 ULONG PoolTag,
434 _Out_
435 WDFLOOKASIDE* Lookaside
436 )
437 {
438 return ((PFN_WDFLOOKASIDELISTCREATE) WdfFunctions[WdfLookasideListCreateTableIndex])(WdfDriverGlobals, LookasideAttributes, BufferSize, PoolType, MemoryAttributes, PoolTag, Lookaside);
439 }
440
441 //
442 // WDF Function: WdfMemoryCreateFromLookaside
443 //
444 typedef
445 _Must_inspect_result_
446 _IRQL_requires_max_(DISPATCH_LEVEL)
447 WDFAPI
448 NTSTATUS
449 (STDCALL *PFN_WDFMEMORYCREATEFROMLOOKASIDE)(
450 _In_
451 PWDF_DRIVER_GLOBALS DriverGlobals,
452 _In_
453 WDFLOOKASIDE Lookaside,
454 _Out_
455 WDFMEMORY* Memory
456 );
457
458 _Must_inspect_result_
_IRQL_requires_max_(DISPATCH_LEVEL)459 _IRQL_requires_max_(DISPATCH_LEVEL)
460 FORCEINLINE
461 NTSTATUS
462 WdfMemoryCreateFromLookaside(
463 _In_
464 WDFLOOKASIDE Lookaside,
465 _Out_
466 WDFMEMORY* Memory
467 )
468 {
469 return ((PFN_WDFMEMORYCREATEFROMLOOKASIDE) WdfFunctions[WdfMemoryCreateFromLookasideTableIndex])(WdfDriverGlobals, Lookaside, Memory);
470 }
471
472
473
474 #endif // (NTDDI_VERSION >= NTDDI_WIN2K)
475
476
477 WDF_EXTERN_C_END
478
479 #endif // _WDFMEMORY_H_
480
481