ReactOS  0.4.15-dev-3324-gda4e15f
fxdmaenabler.hpp
Go to the documentation of this file.
1 /*++
2 
3 Copyright (c) Microsoft Corporation
4 
5 Module Name:
6 
7  FxDmaEnabler.hpp
8 
9 Abstract:
10 
11  WDF DMA Enabler support
12 
13 Environment:
14 
15  Kernel mode only.
16 
17 Notes:
18 
19 
20 Revision History:
21 
22 --*/
23 
24 #ifndef __FX_DMA_ENABLER_HPP__
25 #define __FX_DMA_ENABLER_HPP__
26 
28 
29 //
30 // Dma Description structure
31 //
32 typedef struct _FxDmaDescription {
33 
35 
37 
38  //
39  // The size of a preallocated lookaside list for this DMA adapter
40  //
42 
44 
46 
48 
53 };
54 
55 //
56 // Make sure the two enums which match to the channels in the enabler match
57 // corresponding values.
58 //
59 
62 
63 //
64 // Declare the FxDmaEnabler class
65 //
67 
68  friend class FxDmaTransactionBase;
69  friend class FxDmaPacketTransaction;
71  friend class FxDmaSystemTransaction;
72 
73 public:
74 
76  __in PFX_DRIVER_GLOBALS FxDriverGlobals
77  );
78 
79  ~FxDmaEnabler();
80 
81  virtual
82  BOOLEAN
83  Dispose(
84  VOID
85  );
86 
88  NTSTATUS
89  Initialize(
92  );
93 
95  NTSTATUS
99  );
100 
101  VOID
103  __in size_t Length,
104  __deref_out_opt PVOID * BufferVA,
105  __out PHYSICAL_ADDRESS * BufferPA
106  );
107 
108  VOID
110  __in size_t Length,
111  __in PVOID BufferVA,
112  __in PHYSICAL_ADDRESS BufferPA
113  );
114 
116  NTSTATUS
117  PowerUp(
118  VOID
119  );
120 
122  NTSTATUS
123  PowerDown(
124  VOID
125  );
126 
127  VOID
129  VOID
130  );
131 
132  VOID
136  );
137 
138  __inline
139  size_t
141  VOID
142  )
143  {
144  //
145  // This value is same for all the channels and equal to the value
146  // provided in the DMA_ENABLER_CONFIG.
147  //
149  }
150 
151  __inline
152  size_t
154  VOID
155  )
156  {
158  }
159 
160  __inline
161  WDFDMAENABLER
163  VOID
164  )
165  {
166  return (WDFDMAENABLER) GetObjectHandle();
167  }
168 
169  __inline
170  WDFDEVICE
172  VOID
173  )
174  {
175 
176  return m_DeviceBase->GetHandle();
177  }
178 
179  __inline
180  size_t
182  VOID
183  )
184  {
185  return m_MaxSGElements;
186  }
187 
188  __inline
189  VOID
191  __in size_t MaximumSGElements
192  )
193  {
194  m_MaxSGElements = (ULONG) MaximumSGElements;
195  }
196 
197  __inline
200  VOID
201  )
202  {
203  return m_Profile;
204  }
205 
206  __inline
207  BOOLEAN
209  VOID
210  )
211  {
212  //
213  // The only case where we don't support chained MDLS is DMAV2
214  // with packet mode.
215  //
216 
217  if ((UsesDmaV3() == false) &&
218  (m_IsBusMaster == TRUE) &&
219  (m_IsScatterGather == FALSE)) {
220  return false;
221  } else {
222  return true;
223  }
224  }
225 
226  __inline
227  BOOLEAN
229  VOID
230  )
231  {
232  return m_IsBusMaster;
233  }
234 
235  __inline
236  BOOLEAN
238  )
239  {
240  return m_IsScatterGather ? FALSE : TRUE ;
241  }
242 
243  __inline
247  )
248  {
249  if (m_IsDuplexTransfer) {
251  }
252  else {
253  return &m_SimplexAdapterInfo;
254  }
255  }
256 
257 
258  __inline
261  VOID
262  )
263  {
264  if (m_IsDuplexTransfer) {
266  } else {
267  return &m_SimplexAdapterInfo;
268  }
269  }
270 
271  __inline
274  VOID
275  )
276  {
277  if (m_IsDuplexTransfer) {
279  } else {
280  return &m_SimplexAdapterInfo;
281  }
282  }
283 
284  BOOLEAN
286  VOID
287  )
288  {
290 
291  //
292  // It doesn't matter which direction we use below. Direction is
293  // ignored for the simplex enabler, and will be the same for both
294  // channels in a duplex enabler.
295  //
296 
298 
299  return description->DeviceDescription.Version == DEVICE_DESCRIPTION_VERSION3;
300  }
301 
302  USHORT
304  VOID
305  )
306  {
308  }
309 
310 public:
311  //
312  // Link into list of FxDmaEnabler pointers maintained by the pnp package.
313  //
315 
316 protected:
317 
319 
321 
322  union {
323  //
324  // Used if the dma profile is not duplex. Common for both read & write.
325  // All the information specific to the channel are stored in the struct.
326  //
328 
329  //
330  // Used if the dma profile is duplex.
331  //
333  };
334 
335  //
336  // The profile of the DMA enabler.
337  //
339 
340  //
341  // Whether the enabler object is added to the device enabler list.
342  //
344 
345  //
346  // Whether the DMA enabler has been configured with DMA resources & has its
347  // adapters.
348  //
350 
351  //
352  // The DMA profile broken out into individual flags.
353  //
355 
357 
359 
360  //
361  // Has the preallocated scatter gather list (single list or lookaside,
362  // depending on profile) been allocated. Indicates initialization state
363  // of m_SGList below.
364  //
366 
367  //
368  // This value is larger of aligment value returned by HAL(which is always 1)
369  // and the alignment value set on the device by WdfDeviceSetAlignmentRequirement.
370  //
372 
373  //
374  // The maximum DMA transfer the enabler should support (saved from the enabler
375  // config)
376  //
378 
380 
381  //
382  // The size of the preallocated SGList entries, in bytes. This is for entries
383  // on the lookaside list or the single entry list.
384  //
385  size_t m_SGListSize;
386 
387  //
388  // Storage for scatter gather lists. Whether the lookaside or the single entry
389  // the size in bytes is described by m_SGListSize
390  //
391  // The m_IsSGListAllocated bit above indicates whether we've
392  // initialized this structure or not.
393  //
394  union {
395 
396  //
397  // For the scatter gather profile we have a lookaside list of SGLists
398  // We allocate these dynamically because (a) we can be mapping
399  // multiple transactions in parallel and (b) the number of map registers
400  // for SG DMA may be very large and we don't necessarily need one per
401  // transaction at all times
402  //
403  // For duplex channels, the entry size is larger of read & write channels.
404  //
405  struct {
408 
409  //
410  // A single SGList for use with system DMA transfers. We can use a single
411  // list because (a) there is only one system DMA transaction being mapped
412  // at any given time (for this adapter) and (b) we don't use the physical
413  // addresses or give them to the driver so they don't need to be preserved
414  // very long (the list is only so the HAL has enough scratch space to tell
415  // the HAL DMA extension which PA's comprise the transfer)
416  //
417  struct {
419  } SystemProfile;
420 
421  //
422  // NOTE: there is no preallocated entry for packet based bus mastering DMA
423  // because we could be mapping multiple transactions in parallel but
424  // the size of the SGList is static and can be allocated on the stack
425  //
426 
427  } m_SGList;
428 
429 private:
430  //
431  // Power-related callbacks.
432  //
439 
440  //
441  // Note that these fields form an informal state engine.
442  //
446 
448  NTSTATUS
452  );
453 
455  NTSTATUS
459  );
460 
462  NTSTATUS
464  __inout FxDmaDescription *AdapterInfo
465  );
466 
467  VOID
469  VOID
470  );
471 
472  VOID
474  __inout FxDmaDescription *AdapterInfo
475  );
476 
477 }; // end of class
478 
479 #endif // _FXDMAENABLER_HPP_
__inline FxDmaDescription * GetReadDmaDescription(VOID)
__inline FxDmaDescription * GetDmaDescription(__in WDF_DMA_DIRECTION Direction)
__inline VOID SetMaxSGElements(__in size_t MaximumSGElements)
_Must_inspect_result_ NTSTATUS InitializeResources(__inout FxDmaDescription *AdapterInfo)
struct FxDmaEnabler::@4584::@4586 SystemProfile
FxTransactionedEntry m_TransactionLink
struct LOOKASIDE_ALIGN _NPAGED_LOOKASIDE_LIST NPAGED_LOOKASIDE_LIST
_In_ ULONG _In_ ULONG _In_ ULONG Length
Definition: ntddpcm.h:101
WDF_EXTERN_C_START typedef _In_ WDFDEVICE _In_ WDFCONTEXT _In_ WDF_DMA_DIRECTION Direction
__inline WDF_DMA_PROFILE GetProfile(VOID)
#define TRUE
Definition: types.h:120
WDFDEVICE __inline GetHandle(VOID)
Definition: fxdevice.hpp:237
BOOLEAN m_DmaEnablerFillFailed
BOOLEAN UsesDmaV3(VOID)
BOOLEAN m_IsConfigured
__inline BOOLEAN IsPacketBased()
VOID RevokeResources(VOID)
ULONG m_MaxSGElements
LONG NTSTATUS
Definition: precomp.h:26
_Must_inspect_result_ NTSTATUS ConfigureSystemAdapter(__in PWDF_DMA_SYSTEM_PROFILE_CONFIG Config, __in WDF_DMA_DIRECTION ConfigDirection)
FxEvtDmaEnablerSelfManagedIoStopCallback m_EvtDmaEnablerSelfManagedIoStop
size_t PreallocatedSGListSize
BOOLEAN m_IsScatterGather
#define DMA_TRANSFER_CONTEXT_SIZE_V1
Definition: iotypes.h:2148
FxDuplexDmaDescriptionType
FxEvtDmaEnablerEnableCallback m_EvtDmaEnablerEnable
const char * description
Definition: directx.c:2497
WDF_DMA_PROFILE m_Profile
FxDmaEnabler(__in PFX_DRIVER_GLOBALS FxDriverGlobals)
#define DEVICE_DESCRIPTION_VERSION3
Definition: iotypes.h:2066
BOOLEAN m_IsSGListAllocated
size_t MaximumFragmentLength
ULONG m_CommonBufferAlignment
union FxDmaEnabler::@4584 m_SGList
FxEvtDmaEnablerFillCallback m_EvtDmaEnablerFill
WDF_EXTERN_C_START enum _WDF_DMA_PROFILE WDF_DMA_PROFILE
_Must_inspect_result_ NTSTATUS Initialize(__in PWDF_DMA_ENABLER_CONFIG Config, __inout FxDeviceBase *Device)
__inline WDFDEVICE GetDeviceHandle(VOID)
_Must_inspect_result_ _In_ PWDFDEVICE_INIT _In_ PCUNICODE_STRING DeviceDescription
Definition: wdfpdo.h:430
#define FALSE
Definition: types.h:117
PDEVICE_OBJECT m_PDO
__inline WDFDMAENABLER GetHandle(VOID)
C_ASSERT(((ULONG) FxDuplexDmaDescriptionTypeRead)==((ULONG) WdfDmaDirectionReadFromDevice))
PVOID __inline GetObjectHandle(VOID)
Definition: fxobject.hpp:603
#define __out
Definition: dbghelp.h:62
__inline size_t GetAlignment(VOID)
unsigned char BOOLEAN
VOID ReleaseResources(VOID)
USHORT GetTransferContextSize(VOID)
__inline size_t GetMaximumLength(VOID)
PDEVICE_OBJECT m_FDO
BOOLEAN m_DmaEnablerEnableFailed
VOID AllocateCommonBuffer(__in size_t Length, __deref_out_opt PVOID *BufferVA, __out PHYSICAL_ADDRESS *BufferPA)
VOID FreeCommonBuffer(__in size_t Length, __in PVOID BufferVA, __in PHYSICAL_ADDRESS BufferPA)
BOOLEAN m_DmaEnablerSelfManagedIoStartFailed
size_t m_SGListSize
FxEvtDmaEnablerSelfManagedIoStartCallback m_EvtDmaEnablerSelfManagedIoStart
__inline size_t GetMaxSGElements(VOID)
_Must_inspect_result_ NTSTATUS PowerUp(VOID)
_Must_inspect_result_ NTSTATUS ConfigureBusMasterAdapters(__in PDEVICE_DESCRIPTION DeviceDescription, __in PWDF_DMA_ENABLER_CONFIG Config)
ULONG m_MaximumLength
__inline FxDmaDescription * GetWriteDmaDescription(VOID)
NPAGED_LOOKASIDE_LIST Lookaside
BOOLEAN m_IsBusMaster
__inline BOOLEAN SupportsChainedMdls(VOID)
FxEvtDmaEnablerDisableCallback m_EvtDmaEnablerDisable
CfxDeviceBase * m_DeviceBase
Definition: fxobject.hpp:328
DEVICE_DESCRIPTION DeviceDescription
#define __inout
Definition: dbghelp.h:50
#define _Must_inspect_result_
Definition: ms_sal.h:558
_Must_inspect_result_ _In_ WDFDEVICE Device
Definition: wdfchildlist.h:474
_Must_inspect_result_ _In_ WDFDEVICE _In_ PWDF_CHILD_LIST_CONFIG Config
Definition: wdfchildlist.h:474
__inline BOOLEAN IsBusMaster(VOID)
PSCATTER_GATHER_LIST List
FxEvtDmaEnablerFlushCallback m_EvtDmaEnablerFlush
_Must_inspect_result_ _In_ WDFDMAENABLER _In_ PWDF_DMA_SYSTEM_PROFILE_CONFIG _In_ WDF_DMA_DIRECTION ConfigDirection
PDMA_ADAPTER AdapterObject
BOOLEAN m_IsAdded
unsigned short USHORT
Definition: pedump.c:61
FxDmaDescription m_DuplexAdapterInfo[FxDuplexDmaDescriptionTypeMax]
_Must_inspect_result_ NTSTATUS ConfigureDmaAdapter(__in PDEVICE_DESCRIPTION DeviceDescription, __in WDF_DMA_DIRECTION ConfigDirection)
VOID InitializeTransferContext(__out PVOID Context, __in WDF_DMA_DIRECTION Direction)
_Must_inspect_result_ NTSTATUS PowerDown(VOID)
BOOLEAN m_IsDuplexTransfer
virtual BOOLEAN Dispose(VOID)
#define __deref_out_opt
Definition: dbghelp.h:29
struct _SCATTER_GATHER_LIST * PSCATTER_GATHER_LIST
Definition: iotypes.h:2204
enum _WDF_DMA_DIRECTION WDF_DMA_DIRECTION
unsigned int ULONG
Definition: retypes.h:1
struct FxDmaEnabler::@4584::@4585 ScatterGatherProfile
struct _FxDmaDescription FxDmaDescription
VOID FreeResources(__inout FxDmaDescription *AdapterInfo)
#define __in
Definition: dbghelp.h:35
FxDmaDescription m_SimplexAdapterInfo