1 /*++
2 
3 Copyright (c) Microsoft Corporation
4 
5 Module Name:
6 
7     FxMemoryObject.hpp
8 
9 Abstract:
10     This is the base class for a whole host of memory objects which serve
11     different purposes:  The hierarchy is this
12 
13     FxMemoryObject : public FxObject, public IFxMemory
14         FxMemoryBuffer
15         FxMemoryBufferFromPool
16             FxMemoryPagedBufferFromPool
17         FxMemoryBufferFromLookaside
18             FxMemoryBufferFromPoolLookaside
19                 FxMemoryPagedBufferFromPoolLookaside
20         FxMemoryBufferPreallocated
21             FxRequestMemory
22 
23     Here is quick overview of what each object does/brings to the table:
24 
25     FxMemoryObject:  provides an implementation for almost all of IFxMemory's
26         abstract functions.  It also provides a static _Create function which
27         can create non lookaside based memory objects
28 
29     FxMemoryBuffer:  memory object which can hold the external buffer within its
30         own object allocation.  This means that the sizeof(FxMemoryBuffer) +
31         external bufer size + extra computations < PAGE_SIZE
32 
33     FxMemoryBufferFromPool:  memory object whose external buffer is a separate
34         allocation.  The external buffer can be either paged or non paged.
35 
36     FxMemoryPagedBufferFromPool:  same as FxMemoryBufferFromPool.  In addition,
37         it has a back pointer to the owning FxDeviceBase so that the object
38         can be disposed on the correct dispose list.
39 
40     FxMemoryBufferFromLookaside:  same as FxMemoryBuffer. In addition, the
41         object knows how to return itself to the lookaside which created it.
42 
43     FxMemoryBufferFromPoolLookaside:  same as FxMemoryBufferFromPool.  In
44         addtion, the object knows how to return itself to the lookaside which
45         created it.
46 
47     FxMemoryPagedBufferFromPoolLookaside:  same as
48         FxMemoryBufferFromPoolLookaside.  In addtion, it has a back pointer to
49         the owning FxDeviceBase so that the object can be disposed on the
50         correct dispose list.
51 
52     FxMemoryBufferPreallocated:  a memory object which does not own the external
53         buffer's lifetime.  It is a wrapper object to allow existing buffers to
54         be used as a WDFMEMORY.
55 
56     FxRequestMemory:  same as FxMemoryBufferPreallocated.  In addtion, it knows
57         about PMDLs and is tied to the lifetime of a WDFREQUEST.
58 
59 Author:
60 
61 Environment:
62 
63     kernel mode only
64 
65 Revision History:
66 
67 --*/
68 
69 #ifndef _FXMEMORYOBJECT_H_
70 #define _FXMEMORYOBJECT_H_
71 
72 class FxMemoryObject : public FxObject, public IFxMemory {
73 public:
74     static
75     _Must_inspect_result_
76     NTSTATUS
77     _Create(
78         __in PFX_DRIVER_GLOBALS DriverGlobals,
79         __in_opt PWDF_OBJECT_ATTRIBUTES Attributes,
80         __in POOL_TYPE PoolType,
81         __in ULONG PoolTag,
82         __in size_t BufferSize,
83         __out FxMemoryObject** Object
84         );
85 
86     // begin IFxMemory derivations
87     virtual
88     size_t
89     GetBufferSize(
90         VOID
91         )
92     {
93         return m_BufferSize;
94     }
95 
96     virtual
97     PMDL
98     GetMdl(
99         VOID
100         )
101     {
102         //
103         // This function or its derivatives do not allocate the PMDL, they just
104         // return one if there is one in the object already.
105         //
106         return NULL;
107     }
108 
109     virtual
110     WDFMEMORY
111     GetHandle(
112         VOID
113         )
114     {
115         return (WDFMEMORY) GetObjectHandle();
116     }
117 
118     virtual
119     PFX_DRIVER_GLOBALS
120     GetDriverGlobals(
121         VOID
122         )
123     {
124         return FxObject::GetDriverGlobals();
125     }
126 
127     virtual
128     ULONG
129     AddRef(
130         __in PVOID Tag,
131         __in LONG Line,
132         __in_opt PSTR File
133         )
134     {
135         return FxObject::AddRef(Tag, Line, File);
136     }
137 
138     virtual
139     ULONG
140     Release(
141         __in PVOID Tag,
142         __in LONG Line,
143         __in_opt PSTR File
144         )
145     {
146         return FxObject::Release(Tag, Line, File);
147     }
148 
149     virtual
150     VOID
151     Delete(
152         VOID
153         )
154     {
155         DeleteObject();
156     }
157 
158     virtual
159     USHORT
160     GetFlags(
161         VOID
162         )
163     {
164         //
165         // By default, memory is readable and writable
166         return 0;
167     }
168     // end IFxMemory derivations
169 
170 protected:
171 
172     FxMemoryObject(
173         __in PFX_DRIVER_GLOBALS FxDriverGlobals,
174         __in USHORT ObjectSize,
175         __in size_t BufferSize
176         );
177 
178     virtual
179     _Must_inspect_result_
180     NTSTATUS
181     QueryInterface(
182         __inout FxQueryInterfaceParams* Params
183         )
184     {
185         switch (Params->Type) {
186         case IFX_TYPE_MEMORY:
187             // cast is necessary for necessary this pointer offset to be computed
188             *Params->Object = (IFxMemory*) this;
189             return STATUS_SUCCESS;
190 
191         default:
192             return __super::QueryInterface(Params);
193         }
194     }
195 
196     size_t m_BufferSize;
197 };
198 
199 #endif // _FXMEMORYOBJECT_H_
200