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 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 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 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_ 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 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_ 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_ 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_ 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_ 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