Leaked source code of windows server 2003
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

924 lines
105 KiB

  1. ��<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  2. <html xmlns:v="urn:schemas-microsoft-com:vml"
  3. xmlns:o="urn:schemas-microsoft-com:office:office"
  4. xmlns:w="urn:schemas-microsoft-com:office:word"
  5. xmlns="http://www.w3.org/TR/REC-html40">
  6. <head>
  7. <meta http-equiv=Content-Type content="text/html; charset=unicode">
  8. <meta name=ProgId content=Word.Document>
  9. <meta name=Generator content="Microsoft Word 10">
  10. <meta name=Originator content="Microsoft Word 10">
  11. <link rel=File-List href="spti_files/filelist.xml">
  12. <!--[if gte mso 9]><xml>
  13. <w:WordDocument>
  14. <w:ActiveWritingStyle Lang="EN-US" VendorID="64" DLLVersion="131077"
  15. NLCheck="1">1</w:ActiveWritingStyle>
  16. <w:ActiveWritingStyle Lang="EN-US" VendorID="64" DLLVersion="131078"
  17. NLCheck="1">1</w:ActiveWritingStyle>
  18. <w:SpellingState>Clean</w:SpellingState>
  19. <w:GrammarState>Clean</w:GrammarState>
  20. <w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel>
  21. </w:WordDocument>
  22. </xml><![endif]-->
  23. <style>
  24. <!--
  25. /* Font Definitions */
  26. @font-face
  27. {font-family:"MS Mincho";
  28. panose-1:2 2 6 9 4 2 5 8 3 4;
  29. mso-font-alt:"-�3� fg";
  30. mso-font-charset:128;
  31. mso-generic-font-family:modern;
  32. mso-font-pitch:fixed;
  33. mso-font-signature:-1610612033 1757936891 16 0 131231 0;}
  34. @font-face
  35. {font-family:"MS Sans Serif";
  36. panose-1:0 0 0 0 0 0 0 0 0 0;
  37. mso-font-charset:0;
  38. mso-generic-font-family:swiss;
  39. mso-font-format:other;
  40. mso-font-pitch:variable;
  41. mso-font-signature:3 0 0 0 1 0;}
  42. @font-face
  43. {font-family:Verdana;
  44. panose-1:2 11 6 4 3 5 4 4 2 4;
  45. mso-font-charset:0;
  46. mso-generic-font-family:swiss;
  47. mso-font-pitch:variable;
  48. mso-font-signature:536871559 0 0 0 415 0;}
  49. @font-face
  50. {font-family:"\@MS Mincho";
  51. panose-1:2 2 6 9 4 2 5 8 3 4;
  52. mso-font-charset:128;
  53. mso-generic-font-family:modern;
  54. mso-font-pitch:fixed;
  55. mso-font-signature:-1610612033 1757936891 16 0 131231 0;}
  56. /* Style Definitions */
  57. p.MsoNormal, li.MsoNormal, div.MsoNormal
  58. {mso-style-parent:"";
  59. margin:0in;
  60. margin-bottom:.0001pt;
  61. mso-pagination:widow-orphan;
  62. font-size:12.0pt;
  63. font-family:"Times New Roman";
  64. mso-fareast-font-family:"Times New Roman";
  65. color:black;}
  66. h2
  67. {mso-margin-top-alt:auto;
  68. margin-right:0in;
  69. mso-margin-bottom-alt:auto;
  70. margin-left:0in;
  71. mso-pagination:widow-orphan;
  72. mso-outline-level:2;
  73. font-size:18.0pt;
  74. font-family:"Times New Roman";
  75. color:black;
  76. font-weight:bold;}
  77. h3
  78. {mso-margin-top-alt:auto;
  79. margin-right:0in;
  80. mso-margin-bottom-alt:auto;
  81. margin-left:0in;
  82. mso-pagination:widow-orphan;
  83. mso-outline-level:3;
  84. font-size:13.5pt;
  85. font-family:"Times New Roman";
  86. color:black;
  87. font-weight:bold;}
  88. h4
  89. {mso-margin-top-alt:auto;
  90. margin-right:0in;
  91. mso-margin-bottom-alt:auto;
  92. margin-left:0in;
  93. mso-pagination:widow-orphan;
  94. mso-outline-level:4;
  95. font-size:12.0pt;
  96. font-family:"Times New Roman";
  97. color:black;
  98. font-weight:bold;}
  99. a:link, span.MsoHyperlink
  100. {color:blue;
  101. text-decoration:underline;
  102. text-underline:single;}
  103. a:visited, span.MsoHyperlinkFollowed
  104. {color:purple;
  105. text-decoration:underline;
  106. text-underline:single;}
  107. p.MsoPlainText, li.MsoPlainText, div.MsoPlainText
  108. {margin:0in;
  109. margin-bottom:.0001pt;
  110. mso-pagination:widow-orphan;
  111. font-size:10.0pt;
  112. font-family:"Courier New";
  113. mso-fareast-font-family:"Times New Roman";
  114. mso-bidi-font-family:"Times New Roman";
  115. color:windowtext;}
  116. p
  117. {mso-margin-top-alt:auto;
  118. margin-right:0in;
  119. mso-margin-bottom-alt:auto;
  120. margin-left:0in;
  121. mso-pagination:widow-orphan;
  122. font-size:12.0pt;
  123. font-family:"Times New Roman";
  124. mso-fareast-font-family:"Times New Roman";
  125. color:black;}
  126. pre
  127. {margin:0in;
  128. margin-bottom:.0001pt;
  129. mso-pagination:widow-orphan;
  130. tab-stops:45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;
  131. font-size:10.0pt;
  132. font-family:"Courier New";
  133. mso-fareast-font-family:"Courier New";
  134. mso-bidi-font-family:"Times New Roman";
  135. color:black;}
  136. span.SpellE
  137. {mso-style-name:"";
  138. mso-spl-e:yes;}
  139. span.GramE
  140. {mso-style-name:"";
  141. mso-gram-e:yes;}
  142. @page Section1
  143. {size:8.5in 11.0in;
  144. margin:1.0in 1.25in 1.0in 1.25in;
  145. mso-header-margin:.5in;
  146. mso-footer-margin:.5in;
  147. mso-paper-source:0;}
  148. div.Section1
  149. {page:Section1;}
  150. /* List Definitions */
  151. @list l0
  152. {mso-list-id:1019158786;
  153. mso-list-type:hybrid;
  154. mso-list-template-ids:-386474800 67698689 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;}
  155. @list l0:level1
  156. {mso-level-number-format:bullet;
  157. mso-level-text:��;
  158. mso-level-tab-stop:.5in;
  159. mso-level-number-position:left;
  160. text-indent:-.25in;
  161. font-family:Symbol;}
  162. @list l0:level2
  163. {mso-level-tab-stop:1.0in;
  164. mso-level-number-position:left;
  165. text-indent:-.25in;}
  166. @list l0:level3
  167. {mso-level-tab-stop:1.5in;
  168. mso-level-number-position:left;
  169. text-indent:-.25in;}
  170. @list l0:level4
  171. {mso-level-tab-stop:2.0in;
  172. mso-level-number-position:left;
  173. text-indent:-.25in;}
  174. @list l0:level5
  175. {mso-level-tab-stop:2.5in;
  176. mso-level-number-position:left;
  177. text-indent:-.25in;}
  178. @list l0:level6
  179. {mso-level-tab-stop:3.0in;
  180. mso-level-number-position:left;
  181. text-indent:-.25in;}
  182. @list l0:level7
  183. {mso-level-tab-stop:3.5in;
  184. mso-level-number-position:left;
  185. text-indent:-.25in;}
  186. @list l0:level8
  187. {mso-level-tab-stop:4.0in;
  188. mso-level-number-position:left;
  189. text-indent:-.25in;}
  190. @list l0:level9
  191. {mso-level-tab-stop:4.5in;
  192. mso-level-number-position:left;
  193. text-indent:-.25in;}
  194. ol
  195. {margin-bottom:0in;}
  196. ul
  197. {margin-bottom:0in;}
  198. -->
  199. </style>
  200. <!--[if gte mso 10]>
  201. <style>
  202. /* Style Definitions */
  203. table.MsoNormalTable
  204. {mso-style-name:"Table Normal";
  205. mso-tstyle-rowband-size:0;
  206. mso-tstyle-colband-size:0;
  207. mso-style-noshow:yes;
  208. mso-style-parent:"";
  209. mso-padding-alt:0in 5.4pt 0in 5.4pt;
  210. mso-para-margin:0in;
  211. mso-para-margin-bottom:.0001pt;
  212. mso-pagination:widow-orphan;
  213. font-size:10.0pt;
  214. font-family:"Times New Roman";}
  215. </style>
  216. <![endif]-->
  217. <meta content="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot"
  218. name=Template>
  219. <!--[if gte mso 9]><xml>
  220. <o:shapedefaults v:ext="edit" spidmax="2050"/>
  221. </xml><![endif]--><!--[if gte mso 9]><xml>
  222. <o:shapelayout v:ext="edit">
  223. <o:idmap v:ext="edit" data="1"/>
  224. </o:shapelayout></xml><![endif]-->
  225. </head>
  226. <body bgcolor=white lang=EN-US link=blue vlink=purple style='tab-interval:.5in'
  227. leftmargin=8>
  228. <div class=Section1>
  229. <h2><a name="_Communicating_with_SCSI"></a><span style='font-family:Verdana'>Communicating
  230. with SCSI devices via Win32 application <o:p></o:p></span></h2>
  231. <p class=MsoNormal><span style='font-family:Verdana;color:red'>[This is
  232. preliminary documentation and subject to change.]</span><span style='font-family:
  233. Verdana'> <o:p></o:p></span></p>
  234. <h3><span style='font-family:Verdana'>SUMMARY<o:p></o:p></span></h3>
  235. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  236. mso-fareast-font-family:"MS Mincho"'>Win32 applications can communicate
  237. directly with SCSI devices using the Win32 API <span class=SpellE>DeviceIoControl</span>
  238. and specifying the appropriate I/O control code (IOCTL).<span
  239. style='mso-spacerun:yes'>� </span>Before <span class=SpellE>DeviceIoControl</span>
  240. can be used, a valid handle to the device must be obtained.<span
  241. style='mso-spacerun:yes'>� </span>The handle is obtained using the Win32 API <span
  242. class=SpellE>CreateFile</span>.<o:p></o:p></span></p>
  243. <p><b><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  244. mso-fareast-font-family:"MS Mincho"'>New for Windows 2000:<span
  245. style='mso-spacerun:yes'>� </span></span></b><span style='font-size:10.0pt;
  246. mso-bidi-font-size:12.0pt;font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>When
  247. using the SCSI pass through <span class=SpellE>IOCTLs</span> (described below),
  248. you must specify an access mode <span class=GramE>of<span
  249. style='mso-spacerun:yes'>� </span>(</span>GENERIC_READ | GENERIC_WRITE) in <span
  250. class=SpellE>CreateFile</span> or the <span class=SpellE>DeviceIoControl</span>
  251. call will fail with ERROR_ACCESS_DENIED (5L).<span style='mso-spacerun:yes'>�
  252. </span>The access mode is specified in the second parameter to <span
  253. class=SpellE>CreateFile</span>, <span class=SpellE>dwDesiredAccess</span>.<span
  254. style='mso-spacerun:yes'>� </span>Refer to the MSDN documentation for specific
  255. information about the Win32 APIs <span class=SpellE>CreateFile</span> and <span
  256. class=SpellE>DeviceIoControl</span>.<o:p></o:p></span></p>
  257. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  258. mso-fareast-font-family:"MS Mincho"'>There are several <span class=SpellE>IOCTLs</span>
  259. that the SCSI port driver supports.<span style='mso-spacerun:yes'>�
  260. </span>Refer to the DDK file NTDDSCSI.H for the most current information
  261. regarding the supported <span class=SpellE>IOCTLs</span>.<span
  262. style='mso-spacerun:yes'>� </span>This sample will demonstrate the following <span
  263. class=SpellE>IOCTLs</span>: <a href="#_IOCTL_STORAGE_QUERY_PROPERTY">IOCTL_STORAGE_QUERY_PROPERTY</a>,
  264. and <a href="#_IOCTL_SCSI_PASS_THROUGH_and_IOCTL_SCSI">IOCTL_SCSI_PASS_THROUGH_DIRECT</a>.<o:p></o:p></span></p>
  265. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  266. mso-fareast-font-family:"MS Mincho"'>To issue these <span class=SpellE>IOCTLs</span>,
  267. the user must have read + write access to the device.<span
  268. style='mso-spacerun:yes'>� </span><o:p></o:p></span></p>
  269. <p style='margin-left:.5in;text-indent:-.25in;mso-list:l0 level1 lfo2;
  270. tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt;
  271. mso-bidi-font-size:12.0pt;font-family:Symbol;mso-fareast-font-family:Symbol;
  272. mso-bidi-font-family:Symbol'><span style='mso-list:Ignore'>�<span
  273. style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  274. </span></span></span><![endif]><span style='font-size:10.0pt;mso-bidi-font-size:
  275. 12.0pt;font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>If <span
  276. class=SpellE>CreateFile</span> fails with ERROR_ACCESS_DENIED, the user doesn't
  277. have the correct privilege level.<span style='mso-spacerun:yes'>� </span><o:p></o:p></span></p>
  278. <p style='margin-left:.5in;text-indent:-.25in;mso-list:l0 level1 lfo2;
  279. tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt;
  280. mso-bidi-font-size:12.0pt;font-family:Symbol;mso-fareast-font-family:Symbol;
  281. mso-bidi-font-family:Symbol'><span style='mso-list:Ignore'>�<span
  282. style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  283. </span></span></span><![endif]><span style='font-size:10.0pt;mso-bidi-font-size:
  284. 12.0pt;font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>If <span
  285. class=SpellE>DeviceIoControl</span> fails with ERROR_ACCESS_DENIED, the access
  286. mode (GENERIC_READ | GENERIC_WRITE) was not specified in the <span
  287. class=SpellE>CreateFile</span> call.<o:p></o:p></span></p>
  288. <h4><a name="_IOCTL_SCSI_GET_INQUIRY_DATA"></a><a
  289. name="_IOCTL_SCSI_GET_CAPABILITIES"></a><a name="_IOCTL_STORAGE_QUERY_PROPERTY"></a><span
  290. style='font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>IOCTL_STORAGE_QUERY_PROPERTY<o:p></o:p></span></h4>
  291. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  292. mso-fareast-font-family:"MS Mincho"'>IOCTL_STORAGE_QUERY_PROPERTY returns a STORAGE_DESCRIPTOR_HEADER
  293. structure (found in NTDDSTOR.H), usually as a derived structure with more
  294. information.<span style='mso-spacerun:yes'>� </span>If the request type was for
  295. <span class=SpellE>StorageAdapterProperty</span> or <span class=SpellE>StorageDeviceProperty</span>,
  296. the returned data will be a STORAGE_ADAPTER_<span class=GramE>DESCRIPTOR<span
  297. style='mso-spacerun:yes'>� </span>or</span> STORAGE_DEVICE_DESCRIPTOR structure,
  298. respectively.<span style='mso-spacerun:yes'>� </span>These structures contain
  299. valuable information about the capabilities of the adapter and device.<span
  300. style='mso-spacerun:yes'>� </span>Three items of note are the <span
  301. class=SpellE>MaximumTransferLength</span>, which is a byte value indicating the
  302. largest data block that can be transferred in a single SRB, and the <span
  303. class=SpellE>MaximumPhysicalPages</span>, which is the maximum number of
  304. physical pages that a data buffer can span, and the <span class=SpellE>AlignmentMask</span>.
  305. <span style='mso-spacerun:yes'>�</span>The <span class=SpellE>MaximumPhysicalPages</span>
  306. indicates how many Scatter/Gather entries the SCSI miniport driver and adapter
  307. can support.<span style='mso-spacerun:yes'>� </span>Any buffer provided by the
  308. caller for <a href="#_IOCTL_SCSI_PASS_THROUGH_and_IOCTL_S">IOCTL_SCSI_PASS_THROUGH_DIRECT</a>
  309. in the <span class=SpellE>DataBuffer</span> field must have a starting address
  310. that does meets the restriction of the <span class=SpellE>AlignmentMask</span>
  311. field.<span style='mso-spacerun:yes'>� </span>A simple check is to logically
  312. AND the buffer address and the <span class=SpellE>AlignmentMask</span>; if the
  313. result is non-zero the buffer is not valid for SPTD.<o:p></o:p></span></p>
  314. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  315. mso-fareast-font-family:"MS Mincho"'>To determine the largest transfer that an
  316. adapter can handle, you have to first convert the <span class=SpellE>MaximumPhysicalPages</span>
  317. into a byte value that we ll refer to here as <span class=SpellE>MaximumPhysicalPages_in_bytes</span>.<span
  318. style='mso-spacerun:yes'>� </span>Subtract one from <span class=SpellE>MaximumPhysicalPages</span>
  319. and then multiply this value by the system PAGE_SIZE (defined in NTDDK.H) to
  320. get the <span class=SpellE>MaximumPhysicalPages_in_bytes</span>.<span
  321. style='mso-spacerun:yes'>� </span>Then the largest transfer that can be issued
  322. on an adapter is the smaller of <span class=SpellE>MaximumTransferLength</span>
  323. and <span class=SpellE>MaximumPhysicalPages_in_bytes</span>.<span
  324. style='mso-spacerun:yes'>� </span>Due to scatter-gather list limitations, there
  325. is a system limit on transfer sizes of 255 pages.<o:p></o:p></span></p>
  326. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  327. mso-fareast-font-family:"MS Mincho"'>For example, assume a system has PAGE_SIZE
  328. = 4KB, and the SCSI capabilities indicate <span class=SpellE>MaximumTransferLength</span>
  329. = 16MB and <span class=SpellE>MaximumPhysicalPages</span> = 17.<span
  330. style='mso-spacerun:yes'>� </span>Then, the largest transfer on this adapter
  331. would be 64KB based on the following calculations:<o:p></o:p></span></p>
  332. <p style='margin-left:.5in'><span class=SpellE><span style='font-size:10.0pt;
  333. mso-bidi-font-size:12.0pt;font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>MaximumPhysicalPages</span></span><span
  334. style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  335. mso-fareast-font-family:"MS Mincho"'>  1 = 17  1 = 16 * PAGE_SIZE = 16 * 4096
  336. = 64KB<o:p></o:p></span></p>
  337. <p style='margin-left:.5in'><span class=GramE><span style='font-size:10.0pt;
  338. mso-bidi-font-size:12.0pt;font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>largest</span></span><span
  339. style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  340. mso-fareast-font-family:"MS Mincho"'> transfer = min(<span class=SpellE>MaximumTransferLength</span>,
  341. <span class=SpellE>MaximumPhysicalPages_in_bytes</span>) = min(16MB, 64KB) =
  342. 64KB<o:p></o:p></span></p>
  343. <h4><a name="_IOCTL_SCSI_PASS_THROUGH_and_IOCTL_SCSI_"></a><a
  344. name="_IOCTL_SCSI_PASS_THROUGH_and_IOCTL_S"></a><span style='font-family:Verdana;
  345. mso-fareast-font-family:"MS Mincho"'>IOCTL_SCSI_PASS_THROUGH and
  346. IOCTL_SCSI_PASS_THROUGH_DIRECT<o:p></o:p></span></h4>
  347. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  348. mso-fareast-font-family:"MS Mincho"'>The two <span class=SpellE>IOCTLs</span>
  349. IOCTL_SCSI_PASS_THROUGH and IOCTL_SCSI_PASS_THROUGH_DIRECT allow SCSI <span
  350. class=SpellE>CDBs</span> (Command Descriptor Blocks) to be sent from a Win32
  351. application to a SCSI device.<span style='mso-spacerun:yes'>� </span>Depending
  352. on which IOCTL is sent<span class=GramE>,</span> a corresponding pass through
  353. structure is filled out by the Win32 application.<span
  354. style='mso-spacerun:yes'>� </span>IOCTL_SCSI_PASS_THROUGH uses the structure
  355. SCSI_PASS_THROUGH.<span style='mso-spacerun:yes'>�
  356. </span>IOCTL_SCSI_PASS_THROUGH_DIRECT uses the structure <span class=GramE>SCSI_PASS_THROUGH_DIRECT.</span><span
  357. style='mso-spacerun:yes'>� </span>See NTDDSCSI.H for more details about these
  358. structures.<o:p></o:p></span></p>
  359. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  360. mso-fareast-font-family:"MS Mincho"'>The structures SCSI_PASS_THROUGH and
  361. SCSI_PASS_THROUGH_DIRECT are virtually identical.<span
  362. style='mso-spacerun:yes'>� </span>The only difference is that the data buffer
  363. for the SCSI_PASS_THROUGH structure must be contiguous with the structure.<span
  364. style='mso-spacerun:yes'>� </span>This structure member is called <span
  365. class=SpellE>DataBufferOffset</span> and is of type ULONG.<span
  366. style='mso-spacerun:yes'>� </span>The data buffer for the
  367. SCSI_PASS_THROUGH_DIRECT structure does not have to be contiguous with the
  368. structure.<span style='mso-spacerun:yes'>� </span>This structure member is
  369. called <span class=SpellE>DataBuffer</span> and is of type PVOID.<span
  370. style='mso-spacerun:yes'>� </span>This is the only difference between the two
  371. structures.<o:p></o:p></span></p>
  372. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  373. mso-fareast-font-family:"MS Mincho"'>IOCTL_SCSI_PASS_THROUGH and
  374. IOCTL_SCSI_PASS_THROUGH_DIRECT are not substitutes for a SCSI class driver and
  375. should only be used for infrequent I/O processing.<span
  376. style='mso-spacerun:yes'>� </span>For situations in which frequent SCSI
  377. commands need to be sent to a device, with strict error processing and high
  378. performance requirements, the best solution is to write a SCSI class driver
  379. that will send these <span class=SpellE>CDBs</span> to the respective
  380. devices.<span style='mso-spacerun:yes'>� </span>SCSI pass through requests are
  381. handled synchronously by the SCSI port driver, even if the Win32 application
  382. has the proper code to handle the requests as overlapped I/O.<o:p></o:p></span></p>
  383. <h4><a name="_Obtaining_a_handle"></a><u><span style='font-family:Verdana;
  384. mso-fareast-font-family:"MS Mincho"'>Obtaining a handle to a device</span></u><u><span
  385. style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  386. mso-fareast-font-family:"MS Mincho"'><o:p></o:p></span></u></h4>
  387. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  388. mso-fareast-font-family:"MS Mincho"'>Before any <span class=SpellE>IOCTLs</span>
  389. can be sent to a SCSI device, a handle for the device must be obtained.<span
  390. style='mso-spacerun:yes'>� </span>The Win32 API <span class=SpellE>CreateFile</span>
  391. is used to obtain this handle and to define the sharing mode and the access
  392. mode.<span style='mso-spacerun:yes'>� </span>The access mode must be specified
  393. as (GENERIC_READ | GENERIC_WRITE).<span style='mso-spacerun:yes'>� </span>The
  394. key to obtaining a valid handle is to supply the proper filename for the device
  395. that is to be opened.<span style='mso-spacerun:yes'>� </span>It is possible to
  396. obtain a handle to the device via either the SCSI port driver or the
  397. appropriate SCSI class driver, depending on whether the device was claimed (see
  398. the <span class=SpellE>DeviceClaimed</span> information returned from <a
  399. href="#_IOCTL_SCSI_GET_INQUIRY_DATA">IOCTL_SCSI_GET_INQUIRY_DATA</a>).<span
  400. style='mso-spacerun:yes'>� </span><o:p></o:p></span></p>
  401. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  402. mso-fareast-font-family:"MS Mincho"'>If the device is claimed by a class
  403. driver, then you have to specify a filename that will route requests through
  404. the class driver.<span style='mso-spacerun:yes'>� </span>In the case of fixed
  405. disks and optical storage devices, the filename is typically the corresponding
  406. drive letter.<span style='mso-spacerun:yes'>� </span>&quot;\\.\I:&quot; can be
  407. used to obtain a handle to a CD-ROM drive that has been mapped to driver
  408. &quot;I:<span class=GramE>&quot;.</span><span style='mso-spacerun:yes'>�
  409. </span>In the case of SCSI printers, the filename is &quot;<span class=SpellE>LPTn</span>&quot;,
  410. where n = 1, 2, etc.<span style='mso-spacerun:yes'>� </span>For all remaining
  411. SCSI devices, the SCSI class driver defines the appropriate name.<span
  412. style='mso-spacerun:yes'>� </span>Typically the name is related to the device
  413. (e.g. - &quot;\\.\Scanner0&quot;, &quot;\\.\Tape1&quot;).<span
  414. style='mso-spacerun:yes'>� </span>Except for <span class=SpellE>COMn</span> and
  415. <span class=SpellE>LPTn</span>, all device filenames must be <span
  416. class=SpellE>prepended</span> with a \\.\ to inform the I/O Manager that this
  417. is a device and not a standard file name. <o:p></o:p></span></p>
  418. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  419. mso-fareast-font-family:"MS Mincho"'>If the device is unclaimed by a SCSI class
  420. driver, then a handle to the SCSI port driver is required.<span
  421. style='mso-spacerun:yes'>� </span>The filename in this case is &quot;\\.\<span
  422. class=SpellE>ScsiN</span>:<span class=GramE>&quot;,</span> where N = 0, 1, 2,
  423. etc.<span style='mso-spacerun:yes'>� </span>The number N corresponds to the
  424. SCSI host adapter card number that controls the desired SCSI device.<span
  425. style='mso-spacerun:yes'>� </span>When the SCSI port name is used, the Win32
  426. application must set the proper <span class=SpellE>PathId</span>, <span
  427. class=SpellE>TargetId</span>, and <span class=SpellE>Lun</span> in the SCSI
  428. pass through structure.<span style='mso-spacerun:yes'>� </span>Failure to set
  429. this SCSI address information will cause the SCSI request to fail (if directed
  430. to a target device claimed by a class driver) or possibly cause data corruption
  431. (if the unexpected target device processed the I/O request).<o:p></o:p></span></p>
  432. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  433. mso-fareast-font-family:"MS Mincho"'>If the device is claimed by a class driver
  434. but a handle to the SCSI port driver is used, the <span class=SpellE>DeviceIoControl</span>
  435. call will fail the IOCTL_SCSI_PASS_THROUGH and IOCTL_SCSI_PASS_THROUGH_DIRECT
  436. with ERROR_INVALID_PARAMETER (87L).<span style='mso-spacerun:yes'>� </span>The
  437. Win32 API <span class=SpellE>QueryDosDevice</span> can be used to display the
  438. symbolic links between the Win32 device names and their corresponding kernel
  439. mode names.<span style='mso-spacerun:yes'>� </span>If you are unsure of which
  440. device name to specify for <span class=SpellE>CreateFile</span>, one should be
  441. able to examine the output from <span class=SpellE>QueryDosDevice</span> to
  442. determine the correct name.<o:p></o:p></span></p>
  443. <p><b><u><span style='font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>Initializing
  444. the structures</span></u></b><span style='font-size:10.0pt;mso-bidi-font-size:
  445. 12.0pt;font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><o:p></o:p></span></p>
  446. <p><span style='font-size:26.0pt;font-family:Verdana;mso-fareast-font-family:
  447. "MS Mincho";color:red'>NOTE:<span style='mso-spacerun:yes'>� </span>ALL
  448. INFORMATION AFTER THIS POINT IS NOT VALID.<span style='mso-spacerun:yes'>�
  449. </span>THE NEW SPTI.EXE SAMPLE USES A LIBRARY, SPTLIB, TO SIMPLIFY THE PROCESS
  450. OF SENDING SPTD REQUESTS.<o:p></o:p></span></p>
  451. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  452. mso-fareast-font-family:"MS Mincho"'>Once a valid handle is obtained to a SCSI device,
  453. then appropriate input and output buffers for the requested IOCTL must be
  454. allocated and, in some cases, filled in correctly.<span
  455. style='mso-spacerun:yes'>� </span>This section describes general guidelines for
  456. setting up the parameters for the <span class=SpellE>DeviceIoControl</span>
  457. call.<span style='mso-spacerun:yes'>� </span><o:p></o:p></span></p>
  458. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  459. mso-fareast-font-family:"MS Mincho"'>For IOCTL_SCSI_GET_INQUIRY_DATA, no data
  460. is sent to the device - data is only read from the device.<span
  461. style='mso-spacerun:yes'>� </span>Set <span class=SpellE>lpInBuffer</span> to
  462. NULL and <span class=SpellE>nInBufferSize</span> to zero.<span
  463. style='mso-spacerun:yes'>� </span>The output buffer might be quite large, as
  464. each SCSI device on the bus will provide data that will fill three structures for
  465. each device:<span style='mso-spacerun:yes'>� </span>SCSI_ADAPTER_BUS_INFO,
  466. SCSI_BUS_DATA, and SCSI_INQUIRY_DATA.<span style='mso-spacerun:yes'>�
  467. </span>Allocate a buffer that will hold the information for all the devices on
  468. that particular SCSI adapter.<span style='mso-spacerun:yes'>� </span>Set <span
  469. class=SpellE>lpOutBuffer</span> to point to this allocated buffer and <span
  470. class=SpellE>nOutBufferSize</span> to the size of the allocated buffer.<o:p></o:p></span></p>
  471. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  472. mso-fareast-font-family:"MS Mincho"'>For IOCTL_SCSI_GET_CAPABILITIES, no data
  473. is sent to the device - data is only read from the device.<span
  474. style='mso-spacerun:yes'>� </span>Set <span class=SpellE>lpInBuffer</span> to
  475. NULL and <span class=SpellE>nInBufferSize</span> to zero.<span
  476. style='mso-spacerun:yes'>� </span>Set <span class=SpellE>lpOutBuffer</span> to
  477. a pointer to hold the IO_SCSI_CAPABILITIES structure, and <span class=SpellE>nOutBufferSize</span>
  478. to <span class=SpellE><span class=GramE>sizeof</span></span><span class=GramE>(</span>IO_SCSI_CAPABILITIES).<span
  479. style='mso-spacerun:yes'>� </span>A larger output buffer can be used, but the
  480. output buffer length must be set as described here.<o:p></o:p></span></p>
  481. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  482. mso-fareast-font-family:"MS Mincho"'>For the two SCSI pass through <span
  483. class=SpellE>IOCTLs</span>, IOCTL_SCSI_PASS_THROUGH and
  484. IOCTL_SCSI_PASS_THROUGH_DIRECT, both <span class=SpellE>lpInBuffer</span> and <span
  485. class=SpellE>lpOutBuffer</span> can vary in size depending on the Request Sense
  486. buffer size and the data buffer size.<span style='mso-spacerun:yes'>� </span>In
  487. all cases, <span class=SpellE>nInBufferSize</span> and <span class=SpellE>nOutBufferSize</span>
  488. must be at least the size of the SCSI_PASS_THROUGH (or
  489. SCSI_PASS_THROUGH_DIRECT) structure.<span style='mso-spacerun:yes'>� </span>If
  490. the SCSI port driver detects that one of the two buffers is too small, then the
  491. <span class=SpellE>DeviceIoControl</span> API will fail with
  492. ERROR_INVALID_PARAMETER.<span style='mso-spacerun:yes'>� </span><o:p></o:p></span></p>
  493. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  494. mso-fareast-font-family:"MS Mincho"'>Once the appropriate input and output
  495. buffers have been allocated, then the appropriate structure must be initialized.<span
  496. style='mso-spacerun:yes'>� </span>The SCSI_PASS_THROUGH structure is defined in
  497. NTDDSCSI.H as follows:<o:p></o:p></span></p>
  498. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  499. margin-bottom:.0001pt'><span class=SpellE><span class=GramE><span
  500. style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  501. mso-fareast-font-family:"MS Mincho"'>typedef</span></span></span><span
  502. style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  503. mso-fareast-font-family:"MS Mincho"'> <span class=SpellE>struct</span>
  504. _SCSI_PASS_THROUGH {<o:p></o:p></span></p>
  505. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  506. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  507. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  508. style='mso-spacerun:yes'>��� </span>USHORT Length;<o:p></o:p></span></p>
  509. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  510. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  511. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  512. style='mso-spacerun:yes'>��� </span>UCHAR <span class=SpellE>ScsiStatus</span>;<o:p></o:p></span></p>
  513. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  514. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  515. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  516. style='mso-spacerun:yes'>��� </span>UCHAR <span class=SpellE>PathId</span>;<o:p></o:p></span></p>
  517. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  518. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  519. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  520. style='mso-spacerun:yes'>��� </span>UCHAR <span class=SpellE>TargetId</span>;<o:p></o:p></span></p>
  521. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  522. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  523. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  524. style='mso-spacerun:yes'>��� </span>UCHAR <span class=SpellE>Lun</span>;<o:p></o:p></span></p>
  525. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  526. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  527. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  528. style='mso-spacerun:yes'>��� </span>UCHAR <span class=SpellE>CdbLength</span>;<o:p></o:p></span></p>
  529. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  530. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  531. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  532. style='mso-spacerun:yes'>��� </span>UCHAR <span class=SpellE>SenseInfoLength</span>;<o:p></o:p></span></p>
  533. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  534. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  535. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  536. style='mso-spacerun:yes'>��� </span>UCHAR <span class=SpellE>DataIn</span>;<o:p></o:p></span></p>
  537. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  538. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  539. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  540. style='mso-spacerun:yes'>��� </span>ULONG <span class=SpellE>DataTransferLength</span>;<o:p></o:p></span></p>
  541. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  542. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  543. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  544. style='mso-spacerun:yes'>��� </span>ULONG <span class=SpellE>TimeOutValue</span>;<o:p></o:p></span></p>
  545. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  546. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  547. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  548. style='mso-spacerun:yes'>��� </span>ULONG <span class=SpellE>DataBufferOffset</span>;<o:p></o:p></span></p>
  549. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  550. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  551. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  552. style='mso-spacerun:yes'>��� </span>ULONG <span class=SpellE>SenseInfoOffset</span>;<o:p></o:p></span></p>
  553. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  554. margin-bottom:.0001pt'><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  555. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><span
  556. style='mso-spacerun:yes'>��� </span>UCHAR <span class=SpellE><span class=GramE>Cdb</span></span><span
  557. class=GramE>[</span>16];<o:p></o:p></span></p>
  558. <p style='margin-top:0in;margin-right:0in;margin-bottom:0in;margin-left:.5in;
  559. margin-bottom:.0001pt'><span class=GramE><span style='font-size:10.0pt;
  560. mso-bidi-font-size:12.0pt;font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>}SCSI</span></span><span
  561. style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  562. mso-fareast-font-family:"MS Mincho"'>_PASS_THROUGH, *PSCSI_PASS_THROUGH;<o:p></o:p></span></p>
  563. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  564. mso-fareast-font-family:"MS Mincho"'>The Length is the size of the
  565. SCSI_PASS_THROUGH structure.<span style='mso-spacerun:yes'>� </span>The <span
  566. class=SpellE>ScsiStatus</span> should be initialized to 0.<span
  567. style='mso-spacerun:yes'>� </span>The SCSI status of the requested SCSI
  568. operation is returned in this structure member.<span style='mso-spacerun:yes'>�
  569. </span>The possible SCSI statuses are defined in SCSI.H and are of the form <span
  570. class=SpellE>SCSISTAT_xxx</span>. The <span class=SpellE>PathId</span> is the
  571. bus number for the SCSI host adapter that controls the SCSI device in
  572. question.<span style='mso-spacerun:yes'>� </span>Typically, this value will be
  573. 0, but there are SCSI host adapters that have more than one SCSI bus on the
  574. adapter.<span style='mso-spacerun:yes'>� </span>The <span class=SpellE>TargetId</span>
  575. and <span class=SpellE>Lun</span> are the SCSI ID number and logical unit
  576. number for the device.<span style='mso-spacerun:yes'>� </span>If the handle was
  577. obtained for a claimed device, then the <span class=SpellE>PathId</span>, <span
  578. class=SpellE>TargetId</span> and <span class=SpellE>Lun</span> as defined in
  579. this structure will be ignored and the appropriate class driver will provide
  580. this SCSI address information.<span style='mso-spacerun:yes'>� </span>If the
  581. handle was obtained for the SCSI port driver, then the <span class=SpellE>PathId</span>,
  582. <span class=SpellE>TargetId</span> and <span class=SpellE>Lun</span> must be
  583. correct for the device intended.<span style='mso-spacerun:yes'>� </span><o:p></o:p></span></p>
  584. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  585. mso-fareast-font-family:"MS Mincho"'>The <span class=SpellE>CdbLength</span> is
  586. the length of the CDB. Typical values are 6, 10, and 12 up to the maximum of
  587. 16.<span style='mso-spacerun:yes'>� </span>The <span class=SpellE>SenseInfoLength</span>
  588. is the length of the <span class=SpellE>SenseInfo</span> buffer.<span
  589. style='mso-spacerun:yes'>� </span><span class=SpellE>DataIn</span> has three
  590. possible values which are defined in NTDDSCSI.H<span class=GramE>;<span
  591. style='mso-spacerun:yes'>� </span>SCSI</span>_IOCTL_DATA_OUT,
  592. SCSI_IOCTL_DATA_IN and SCSI_IOCTL_DATA_UNSPECIFIED.<span
  593. style='mso-spacerun:yes'>� </span>SCSI_IOCTL_DATA_UNSPECIFIED should be used
  594. only if the appropriate SCSI miniport driver supports its usage.<span
  595. style='mso-spacerun:yes'>� </span>The <span class=SpellE>DataTransferLength</span>
  596. is the byte size of the data buffer.<span style='mso-spacerun:yes'>� </span>The
  597. <span class=SpellE>TimeOutValue</span> is the length of time, in seconds, until
  598. a time-out error should occur.<span style='mso-spacerun:yes'>� </span>This can
  599. range from 0 to a maximum of 30 minutes (108000 seconds).<span
  600. style='mso-spacerun:yes'>� </span><o:p></o:p></span></p>
  601. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  602. mso-fareast-font-family:"MS Mincho"'>The <span class=SpellE>DataBufferOffset</span>
  603. is the offset of the data buffer from the beginning of the pass through
  604. structure.<span style='mso-spacerun:yes'>� </span>For the
  605. SCSI_PASS_THROUGH_DIRECT structure, this value is not an offset, but rather is
  606. a pointer to a data buffer.<span style='mso-spacerun:yes'>� </span>The <span
  607. class=SpellE>SenseInfoOffset</span> is similarly an offset to the <span
  608. class=SpellE>SenseInfo</span> buffer from the beginning of the pass through structure.
  609. Finally, the sixteen remaining bytes are for the CDB data.<span
  610. style='mso-spacerun:yes'>� </span>The format of this data must conform to the
  611. SCSI-2 standard as defined by ANSI.<o:p></o:p></span></p>
  612. <p><b><u><span style='font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>Buffer
  613. Alignment</span></u></b><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  614. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><o:p></o:p></span></p>
  615. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  616. mso-fareast-font-family:"MS Mincho"'>The <span class=SpellE>AlignmentMask</span>
  617. member returned in the structure via the IOCTL_SCSI_GET_CAPABILITIES indicates
  618. the buffer alignment requirements of the SCSI adapter.<span
  619. style='mso-spacerun:yes'>� </span>Buffer alignment is handled using two methods
  620. for assuring that buffers are aligned on the appropriate boundaries.<span
  621. style='mso-spacerun:yes'>� </span><o:p></o:p></span></p>
  622. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  623. mso-fareast-font-family:"MS Mincho"'>The first method uses the compiler to
  624. align the buffer on the correct boundary.<span style='mso-spacerun:yes'>�
  625. </span>The structure SCSI_PASS_THROUGH_WITH_BUFFERS contains a member, Filler
  626. that is of type ULONG.<span style='mso-spacerun:yes'>� </span>The compiler
  627. aligns Filler on a ULONG (double word) boundary.<span
  628. style='mso-spacerun:yes'>� </span>The structure member that follows Filler, <span
  629. class=SpellE>ucSenseBuf</span>, is also aligned on a double word boundary.<span
  630. style='mso-spacerun:yes'>� </span>The <span class=SpellE>ucSenseBuf</span> <span
  631. class=GramE>array is of a size that is a multiple of a double word, and so this
  632. makes the last structure member, <span class=SpellE>ucDataBuf</span>, also
  633. begin</span> on a double word boundary. <o:p></o:p></span></p>
  634. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  635. mso-fareast-font-family:"MS Mincho"'>A second method to ensure buffer alignment
  636. is demonstrated in the <span class=SpellE>AllocateAlignedBuffer</span>
  637. procedure.<span style='mso-spacerun:yes'>� </span>This procedure depends on the
  638. fact that a buffer aligned on a certain boundary will have 0's in its least
  639. significant bits indicating the buffer alignment.<span
  640. style='mso-spacerun:yes'>� </span>A buffer allocation request is made using the
  641. C runtime call (<span class=SpellE>malloc</span>) that is the size of the
  642. requested buffer plus the <span class=SpellE>AlignmentMask</span> value as
  643. returned by IOCTL_SCSI_GET_CAPABILITIES.<span style='mso-spacerun:yes'>�
  644. </span>A pointer is manipulated so that it is pointing to the first possible
  645. address in the buffer that meets the alignment requirements.<o:p></o:p></span></p>
  646. <p><b><u><span style='font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>Direct
  647. versus Buffered<o:p></o:p></span></u></b></p>
  648. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  649. mso-fareast-font-family:"MS Mincho"'>Here's the big difference between
  650. IOCTL_SCSI_PASS_THROUGH versus IOCTL_SCSI_PASS_THROUGH_DIRECT: the SCSI data is
  651. transferred directly into the specified <span class=SpellE>ucDataBuf</span> for
  652. IOCTL_SCSI_PASS_THROUGH_DIRECT while the data will be buffered in an intermediate
  653. I/O manager allocated buffer for IOCTL_SCSI_PASS_THROUGH.<o:p></o:p></span></p>
  654. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  655. mso-fareast-font-family:"MS Mincho"'>The various <span class=SpellE>IOCTLs</span>
  656. that are demonstrated in this sample are defined by the SCSI port driver (see
  657. NTDDSCSI.H for details).<span style='mso-spacerun:yes'>� </span>The memory
  658. buffering for these <span class=SpellE>IOCTLs</span> is METHOD_BUFFERED.<span
  659. style='mso-spacerun:yes'>� </span>What this means is that the I/O manager
  660. examines the length <span class=SpellE>lpInBuffer</span> and the length of <span
  661. class=SpellE>lpOutBuffer</span> as defined by the <span class=SpellE>DeviceIoControl</span>
  662. parameters and allocates a contiguous buffer that is the size of the larger of
  663. the two buffers.<span style='mso-spacerun:yes'>� </span>On entry to the I/O
  664. manager (i.e. the call to <span class=SpellE>DeviceIoControl</span>), the
  665. contents of the Win32 application's <span class=SpellE>lpInBuffer</span> is
  666. copied to the buffer that was allocated by the I/O manager.<span
  667. style='mso-spacerun:yes'>� </span>The <span class=SpellE>nInBufferSize</span>
  668. controls the amount of data copied.<span style='mso-spacerun:yes'>� </span>The
  669. I/O manager then calls the appropriate SCSI class driver's (or port driver's) <span
  670. class=SpellE>DeviceIoControl</span> routine passing it the new buffer.<span
  671. style='mso-spacerun:yes'>� </span>On exit, the reverse process occurs and the
  672. data in the new buffer is copied back into the Win32 application's <span
  673. class=SpellE>lpOutBuffer</span>.<span style='mso-spacerun:yes'>� </span>This
  674. behavior is not user configurable.<o:p></o:p></span></p>
  675. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  676. mso-fareast-font-family:"MS Mincho"'>When using IOCTL_SCSI_PASS_THROUGH, the
  677. SCSI data buffer (<span class=SpellE>ucDataBuf</span>) is part of <span
  678. class=SpellE>lpInBuffer</span>.<span style='mso-spacerun:yes'>�
  679. </span>Therefore, the data in <span class=SpellE>ucDataBuf</span> is copied
  680. into the new buffer (allocated by the I/O manager) and presented to the SCSI
  681. port driver and the SCSI miniport driver.<span style='mso-spacerun:yes'>�
  682. </span>On completion, the new buffer is copied back to the <span class=SpellE>ucDataBuf</span>.<o:p></o:p></span></p>
  683. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  684. mso-fareast-font-family:"MS Mincho"'>When using IOCTL_SCSI_PASS_THROUGH_DIRECT,
  685. the SCSI data buffer (<span class=SpellE>ucDataBuf</span>) is not part of <span
  686. class=SpellE>lpInBuffer</span>.<span style='mso-spacerun:yes'>� </span>Recall
  687. that the SCSI_PASS_THROUGH_DIRECT has a PVOID <span class=SpellE>DataBuffer</span>
  688. member.<span style='mso-spacerun:yes'>� </span>That is, <span class=SpellE>DataBuffer</span>
  689. is a pointer to the data buffer, and the data buffer does not have to be
  690. contiguous with the SCSI_PASS_THROUGH_DIRECT structure.<span
  691. style='mso-spacerun:yes'>� </span>When the Win32 application calls <span
  692. class=SpellE>DeviceIoControl</span>, the <span class=SpellE>lpInBuffer</span>
  693. is copied into an I/O manager allocated buffer, and this new buffer is passed
  694. to the SCSI port driver.<span style='mso-spacerun:yes'>� </span>In the SCSI
  695. port driver, the SCSI_PASS_THROUGH_DIRECT structure is examined, the pointer to
  696. the <span class=SpellE>DataBuffer</span> is retrieved from the structure, and
  697. the user's buffer is probed and locked for direct access.<span
  698. style='mso-spacerun:yes'>� </span><o:p></o:p></span></p>
  699. <p><b><u><span style='font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>Running
  700. the SPTI.EXE sample</span></u></b><span style='font-size:10.0pt;mso-bidi-font-size:
  701. 12.0pt;font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><o:p></o:p></span></p>
  702. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  703. mso-fareast-font-family:"MS Mincho"'>Two command line parameters can be used
  704. with SPTI.EXE.<o:p></o:p></span></p>
  705. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  706. mso-fareast-font-family:"MS Mincho"'>The first parameter is mandatory.<span
  707. style='mso-spacerun:yes'>� </span>It is the name of the device to be
  708. opened.<span style='mso-spacerun:yes'>� </span>Typical values for this are
  709. drive letters such as &quot;C:&quot;, or device names as defined by a class
  710. driver such as Scanner0, or the SCSI port driver name, <span class=SpellE>ScsiN</span><span
  711. class=GramE>:,</span> where N = 0, 1, 2, etc.<span style='mso-spacerun:yes'>�
  712. </span>See <a href="#_Obtaining_a_handle"><span class=GramE>Obtaining</span> a
  713. handle for a device</a> for details on this first parameter.<o:p></o:p></span></p>
  714. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  715. mso-fareast-font-family:"MS Mincho"'>The second parameter is optional and is
  716. used to set the share mode (note that access mode and share mode are different
  717. things) and sector size.<span style='mso-spacerun:yes'>� </span>The default
  718. share mode is (FILE_SHARE_READ | FILE_SHARE_WRITE) and the default sector size
  719. is 512.<span style='mso-spacerun:yes'>� </span>A parameter of &quot;r&quot;
  720. changes the share mode to only FILE_SHARE_READ.<span style='mso-spacerun:yes'>�
  721. </span>A parameter of &quot;w&quot; changes the share mode to only
  722. FILE_SHARE_WRITE.<span style='mso-spacerun:yes'>� </span>A parameter of
  723. &quot;c&quot; changes the share mode to only FILE_SHARE_READ and also changes
  724. the sector size to 2048.<span style='mso-spacerun:yes'>� </span>Typically, a
  725. CD-ROM device would use the &quot;c&quot; parameter.<span
  726. style='mso-spacerun:yes'>� </span><o:p></o:p></span></p>
  727. <p><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  728. mso-fareast-font-family:"MS Mincho"'>The examples below assume that there is a
  729. system with a disk drive &quot;c:<span class=GramE>&quot;,</span> CD-ROM
  730. &quot;d:&quot;, and an unclaimed SCSI device on the second SCSI adapter
  731. (scsi1:).<o:p></o:p></span></p>
  732. <p style='margin:0in;margin-bottom:.0001pt'><span class=SpellE><span
  733. class=GramE><b><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  734. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>spti</span></b></span></span><b><span
  735. style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  736. mso-fareast-font-family:"MS Mincho"'> c:</span></b><span style='font-size:10.0pt;
  737. mso-bidi-font-size:12.0pt;font-family:Verdana;mso-fareast-font-family:"MS Mincho"'><o:p></o:p></span></p>
  738. <p style='margin:0in;margin-bottom:.0001pt'><span style='font-size:10.0pt;
  739. mso-bidi-font-size:12.0pt;font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>To
  740. send SCSI commands to the disk drive. <o:p></o:p></span></p>
  741. <p style='margin-bottom:0in;margin-bottom:.0001pt'><span class=SpellE><span
  742. class=GramE><b><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  743. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>spti</span></b></span></span><b><span
  744. style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  745. mso-fareast-font-family:"MS Mincho"'> d: c</span></b><span style='font-size:
  746. 10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;mso-fareast-font-family:
  747. "MS Mincho"'><o:p></o:p></span></p>
  748. <p style='margin:0in;margin-bottom:.0001pt'><span style='font-size:10.0pt;
  749. mso-bidi-font-size:12.0pt;font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>To
  750. send SCSI commands to the CD-ROM device.<span style='mso-spacerun:yes'>�
  751. </span>Remember that CD-ROM devices typically use 2048 sector size, so the
  752. &quot;c&quot; parameter should be used. <o:p></o:p></span></p>
  753. <p style='margin-bottom:0in;margin-bottom:.0001pt'><span class=SpellE><span
  754. class=GramE><b><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  755. font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>spti</span></b></span></span><b><span
  756. style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;
  757. mso-fareast-font-family:"MS Mincho"'> scsi1:</span></b><span style='font-size:
  758. 10.0pt;mso-bidi-font-size:12.0pt;font-family:Verdana;mso-fareast-font-family:
  759. "MS Mincho"'> <o:p></o:p></span></p>
  760. <p style='margin-top:0in'><span style='font-size:10.0pt;mso-bidi-font-size:
  761. 12.0pt;font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>To send SCSI
  762. commands to the unclaimed SCSI device.<span style='mso-spacerun:yes'>�
  763. </span>Make sure that the SCSI pass through structure has the correct <span
  764. class=SpellE>PathId</span>, <span class=SpellE>TargetId</span> and <span
  765. class=SpellE>Lun</span>, filled in.<span style='mso-spacerun:yes'>� </span>If
  766. the SCSI address information is incorrectly set, the request might fail or be
  767. directed towards the wrong device.<span style='mso-spacerun:yes'>� </span><o:p></o:p></span></p>
  768. <p><b><u>BUILDING THE SAMPLE<o:p></o:p></u></b></p>
  769. <p><span style='font-size:10.0pt;font-family:Verdana'>Click the Free Build
  770. Environment or Checked Build Environment icon under your <b>Development Kits </b>program
  771. group to set basic environment variables needed by the build utility. <o:p></o:p></span></p>
  772. <p><span style='font-size:10.0pt;font-family:Verdana'>Change to the directory
  773. containing the device source code.<o:p></o:p></span></p>
  774. <p><span style='font-size:10.0pt;font-family:Verdana'>To build the sample, run <b>build
  775. -<span class=SpellE>ceZ</span></b>, or use the macro <b>BLD</b>.<span
  776. style='mso-spacerun:yes'>� </span>The &quot;e&quot; option produces a log file
  777. (<span class=SpellE>buildXXX.log</span>), a warning file (<span class=SpellE>buildXXX.wrn</span>),
  778. and an error file (<span class=SpellE>buildXXX.err</span>) where XXX means
  779. either <span class=SpellE><b>fre</b></span> or <span class=SpellE><b>chk</b></span><b>,
  780. </b>depending on the environment chosen.<span style='mso-spacerun:yes'>�
  781. </span>If there are no warnings, then the warning file will not be built and if
  782. there are no errors, there will be no error file built.<span
  783. style='mso-spacerun:yes'>��� </span>If the build succeeds, the Win32
  784. application spti.exe will be placed in a subdirectory of either the <span
  785. class=SpellE>objfre</span> (for free build) or <span class=SpellE>objchk</span>
  786. (for checked build) directories. <o:p></o:p></span></p>
  787. <p class=MsoNormal><span style='font-size:10.0pt;mso-bidi-font-size:12.0pt;
  788. font-family:Verdana;mso-fareast-font-family:"MS Mincho";color:windowtext'>No
  789. INF file is needed to install this application. <o:p></o:p></span></p>
  790. <h3><span style='font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>CODE
  791. TOUR<o:p></o:p></span></h3>
  792. <h4><span style='font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>File
  793. Manifest<o:p></o:p></span></h4>
  794. <pre><u><span style='mso-bidi-font-family:"Courier New"'>File<span
  795. style='mso-tab-count:2'>���������� </span>Description<o:p></o:p></span></u></pre><pre><span
  796. style='mso-bidi-font-family:"Courier New"'><o:p>&nbsp;</o:p></span></pre><pre><span
  797. style='mso-bidi-font-family:"Courier New"'><o:p>&nbsp;</o:p></span></pre><pre><span
  798. class=GramE><span style='mso-bidi-font-family:"Courier New"'>spti.htm</span></span><span
  799. style='mso-bidi-font-family:"Courier New"'><span style='mso-tab-count:1'>������ </span>The documentation for these samples (this file)<o:p></o:p></span></pre><pre><span
  800. class=SpellE><span class=GramE><span style='mso-bidi-font-family:"Courier New"'>spti.c</span></span></span><span
  801. style='mso-bidi-font-family:"Courier New"'><span style='mso-spacerun:yes'>�������� </span>Implements the Win32 application to communicate with the SCSI devices.<o:p></o:p></span></pre><pre><span
  802. class=SpellE><span class=GramE><span style='mso-bidi-font-family:"Courier New"'>spti.h</span></span></span><span
  803. style='mso-bidi-font-family:"Courier New"'><span style='mso-spacerun:yes'>�������� </span>Header file for <span
  804. class=SpellE>spti.c</span><o:p></o:p></span></pre><pre><span style='mso-bidi-font-family:
  805. "Courier New"'>Sources<span style='mso-spacerun:yes'>������� </span>DDK build instructions<o:p></o:p></span></pre>
  806. <p style='margin:0in;margin-bottom:.0001pt;tab-stops:45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'><span
  807. style='font-size:10.0pt;font-family:"Courier New";mso-fareast-font-family:"Courier New"'><o:p>&nbsp;</o:p></span></p>
  808. <p style='margin:0in;margin-bottom:.0001pt;tab-stops:45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'><span
  809. style='font-size:10.0pt;font-family:"Courier New";mso-fareast-font-family:"Courier New"'><o:p>&nbsp;</o:p></span></p>
  810. <p align=center style='margin:0in;margin-bottom:.0001pt;text-align:center;
  811. tab-stops:45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'><span
  812. style='font-size:10.0pt;font-family:Verdana;mso-fareast-font-family:"Courier New";
  813. mso-bidi-font-family:"Courier New"'><a href="#_Communicating_with_SCSI">Top of
  814. page </a></span><span class=MsoHyperlink><span style='font-family:Verdana;
  815. mso-fareast-font-family:"Courier New"'><o:p></o:p></span></span></p>
  816. <pre><o:p>&nbsp;</o:p></pre>
  817. <table class=MsoNormalTable border=0 cellspacing=0 cellpadding=0 width=624
  818. style='width:6.5in;mso-cellspacing:0in;mso-padding-alt:0in 0in 0in 0in'>
  819. <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes;height:1.5pt'>
  820. <td style='background:aqua;padding:.75pt .75pt .75pt .75pt;height:1.5pt'>
  821. <p class=MsoNormal>&nbsp;</p>
  822. </td>
  823. </tr>
  824. </table>
  825. <pre><span style='mso-bidi-font-family:"Courier New"'><o:p>&nbsp;</o:p></span></pre><pre><span
  826. style='mso-bidi-font-family:"Courier New"'><o:p>&nbsp;</o:p></span></pre>
  827. <p style='margin:0in;margin-bottom:.0001pt;tab-stops:45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt'><span
  828. style='font-size:7.5pt;font-family:"MS Sans Serif";mso-fareast-font-family:
  829. "Courier New";mso-bidi-font-family:"Courier New"'>� 1999 Microsoft Corporation</span><span
  830. style='font-size:10.0pt;font-family:Verdana;mso-fareast-font-family:"Courier New";
  831. mso-bidi-font-family:"Courier New"'> <o:p></o:p></span></p>
  832. </div>
  833. </body>
  834. </html>