<html>

<head>
<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
<meta NAME="GENERATOR" CONTENT="Microsoft FrontPage 3.0">
<title>DummyDMA</title>
</head>

<body TEXT="#000000" LINK="#0000ff" VLINK="#800080" BGCOLOR="#ffffff" leftmargin="8">
<font face="Verdana" size="2">

<h2><a NAME="MYSAMPLE">DummyDMA</a> </h2>
<span style="color:#FF0000">

<p>[This is preliminary documentation and subject to change.]</span> </p>

<h3>SUMMARY</h3>

<p>This sample demonstrates how to correctly set up a packet-based busmaster DMA operation
using system manage queue. This sample supports Plug and Play. In addition, this sample
uses the new DMA interface available under Windows 2000. These new DMA interfaces include
the following. 

<ul>
  <li>GetScatterGatherList</li>
  <li>PutScatterGatherList</li>
  <li>PutDmaAdapter</li>
</ul>

<p>This sample does not support Power Management and Windows Management Instrumentation
(WMI). This sample just passes the Irps to the next driver in the stack. </p>

<p>The sample is accompanied by a simple console application to stress-test the driver's
DMA capabilities. The driver is written for a hypothetical PCI busmaster-capable device.
When a user request reaches the driver (in the form of a Device I/O Control IRP), the IRP
is queued. Upon completion of any previously outstanding requests, the driver calls
IoStartNextPacket to start another I/O request. The StartIo routine calls the
GetScatterGatherList function to build the Scatter Gather block for our virtual device.
The transfer is completed when our Pseudo ISR (a simple timer callback routine) is called.
The timer DPC is queued every time we program a transfer operation.</p>

<p>The IOCTL is defined as of type METHOD_IN_DIRECT. The output buffer (output buffer
pointer in the call to DeviceIOControl) is described by the MDL present at
IRP-&gt;MdlAddress when the request reaches the driver. This is the buffer that we will
generate the scatter gather block that our &quot;hypothetical&quot; PCI device driver will
perform a DMA read operation on.</p>

<p>If you wish to use this driver as a foundation for your driver, you need to add support
for Power Management and WMI.</p>

<p>The build and installation instructions given here apply to Windows 2000 systems.
This sample works on both x86 and Alpha.</p>

<p><b>Note</b>: This driver provides an example of a minimal driver. Neither the driver
nor the sample program is production-environment ready. Rather, they are intended for
educational purposes and as a skeleton driver. </font></p>

<h3>BUILDING THE SAMPLE</h3>

<ol>
  <li>Click the <b>Free Build Environment</b> or <b>Checked Build Environment</b> icon under
    your Windows 2000 DDK program's group to set basic environment variables needed by Windows
    2000.</li>
  <li>Change to the directory containing the device source code, such as cd
    Src\General\Dummydma.</li>
  <li>Run <b>BUILD -cef</b> or use the macro <b>BLD</b>. This behavior invokes the Microsoft
    make routines that produce log files called Build.log, Build.wrn, and Build.err. The .wrn
    file will contain warnings.</li>
</ol>

<p>If the build succeeds, the driver will be named Dummydma.sys and it will be saved in
the Alpha subdirectory (depending on whether you are building on a x86 or an Alpha
machine) of the &lt;TARGETPATH&gt; directory specified in the Sources file. The executable
Dmademo.exe will also be placed in the Alpha subdirectory (depending on whether you are
building on a x86 or an Alpha machine) of the &lt;TARGETPATH&gt; directory specified in
the Sources file for exe. </p>
<b>

<h4>Driver Installation</b></h4>

<p>Copy both Dummydma.sys and Dummydma.inf files from the &lt;TARGETPATH&gt;\Lib\&lt;I386
or ALPHA&gt;\&lt;Free or checked build&gt; subdirectory created by BUILD to a floppy
diskette or to the target system. </p>

<p>To install the DummyDma driver, perform the following steps. 

<ol>
  <li>Right click on My Computer.</li>
  <li>Select Hardware.</li>
  <li>Select Hardware Wizard.</li>
  <li>Click Next.</li>
  <li>Select Add/Troubleshoot a device and click Next.</li>
  <li>Select Add a new device and click Next.</li>
  <li>Select No, I want to select the hardware from a list and click Next.</li>
  <li>Select Other devices and click Next.</li>
  <li>Select Have Disk.</li>
  <li>Enter the path where you copied Dummydma.inf or browse for Dummydma.inf.</li>
  <li>Select Finish when the system finish installing the driver.</li>
</ol>

<ol>
  <b><p>Note</b>: This adds a DUMMYDMA driver key to the
  HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services tree in the registry. You can verify
  this by running REGEDT32.EXE and looking in this mentioned location.</p>
</ol>

<h3>TOOLS</h3>

<p>When the system installs the driver, the driver will start. To test this driver, run
Dmademo.exe, a simple Win32 console mode application.</p>

<p>Usage: dmademo &lt;StartingBufferSize&gt;</p>

<p>Dmademo accepts one command-line parameter&#151;the starting buffer size. The
application will step the buffer size up 1024 bytes every time it makes a request to the
driver to perform DMA on the buffer. It loops infinitely until any one of the following
occurs: The user presses a key. The request for a buffer cannot be satisfied by the OS.
The driver returns an error status (return value of DeviceIOControl). </p>

<h3>RESOURCES</h3>

<p><a HREF="http://support.microsoft.com/support/ddk/ntddk/">http://support.microsoft.com/support/ddk/ntddk/</a>
</p>

<p><a HREF="http://www.microsoft.com/hwdev/">http://www.microsoft.com/hwdev/</a></p>

<h3>CODE TOUR</h3>

<h4>File Manifest</h4>

<pre><u>Files             Description</u>
DummyDMA.HTM      The documentation for this sample (this file)
Sys\Dummydma.c    Source file for this driver
Sys\Dummydma.h    Header file for this driver.
Sys\Dummydma.inf  The .inf file for installing this driver
Sys\Dummydma.rc   The resource file for this driver.
Sys\Power.c       Power management related code.
Sys\Wmi.c         WMI related code.
Sys\Sources       Generic file that lists source files and all the build options
Sys\Makefile      This file merely indirects to the real makefile that is shared by all the driver components of the Windows 2000 DDK
Exe\Dmademo.c     Source file of the test application
Exe\Dmademo.h     Header file defining the IOCTL
Exe\Sources       Generic file that lists source files and all the build options
Exe\Makefile      This file merely indirects to the real makefile that is shared by all the driver components of the Windows 2000 DDK


</pre>

<p ALIGN="CENTER"><font face="Verdana" size="2"><a HREF="#top">Top of page</a> </p>
</font>

<table CELLSPACING="0" BORDER="0" WIDTH="624">
  <tr>
    <td VALIGN="MIDDLE" BGCOLOR="#00ffff" HEIGHT="2"></td>
  </tr>
</table>
<font FACE="MS Sans Serif" SIZE="1">

<p> 1999 Microsoft Corporation</font><font face="Verdana" size="2"> </p>
</font>
</body>
</html>
