1. How to Add WMI Interfaces to SCSIPort and Storport Miniports

2. Outline What is Windows Management Instrumentation?
Model for system management and specifying management data
Why is WMI great for MiniPorts?
Standardized interfaces for MiniPorts
Accessible through COM
Security
How does it work?
Interfaces are specified in a MOF
Provider implements and registers interfaces with WMI service
Clients use COM to enumerate instances
Great, but how do I go about it?
Define the interfaces (ie writing the MOF file)
Using scsiwmi.lib (scsiport/storport version of wmilib.lib)
Calling the interfaces from user mode
Advanced topics
Supporting standard interfaces (HBA API, iSCSI)
Handling the WMI IRP yourself
Web Links and Questions

3. What is Windows Management Instrumentation ?
A model for system management and specifying management data
Providers implement one or more instances of management objects
Management objects have properties and or methods

4. Why is WMI Great for MiniPorts ?
Standardized interfaces for MiniPorts
Standard providers for HBA API, iSCSI etc.
Generic tools can be written for standardized interfaces
Parameter checking is straight forward
Accessible through COM
Scriptable through VBS
Remote able
Security
Default ACL’s are secure (Windows XP and later, ACL’s should reset for Windows 2000)

5. How Does It Work? Interfaces and data classes are specified in a MOF
Provider implements and registers interfaces with WMI service
Clients (applications) use COM to enumerate instances

6. WMI Diagram Applications COM HbaApi iScsi WmiProv WMI Service
Provided by:
Microsoft
COM
HbaApi
iScsi
ISV
WmiProv
IHV
WMI Service
Schema
Device Class Driver
ScsiPort / Storport
ScsiWmi
Miniport

7. Great, But How Do I Go About It?
Define the interfaces (i.e., writing the MOF file)
Define the data type classes (i.e., structs)
Define Query, Method and Event classes
Generate the guids and the header
Use scsiwmi.lib (scsiport/storport version of wmilib.lib)
Initializing scsiwmi
Registering the interfaces/classes
Implementing the queries
Implementing the methods
Handling events
Call the interfaces from user mode
Wbemtest.exe (demo)
VBS example (the gotcha with dim, the clone stuff)
C/C++ example
Wmimofchk.exe generated html (demo)

8. Great, But How Do I Go About It? (con’t)
Define the interfaces (i.e., writing the MOF file)
Define the data type classes (i.e., structs)
Define Query, Method and Event classes
Generate the guids and the header

9. Define The Interfaces (Data Type)
// A simple data class (expwmi.mof)
[WMI,
guid("{5beefb8d-e604-4b d5270c46e8a}")]
class ExampleMiniport_DataType {
[WmiDataId(1)] sint32 Id;
[WmiDataId(2)] uint64 u64;
[MaxLen(16),
WmiDataId(3)] string name; };

10. Define The Interfaces (Query Interface)
[WMI,
Dynamic,
Description(“The first data blob for this instance"),
Provider("WmiProv"),
guid("{5e973a98-8edc-4856-acb1-b9345f084340}")]
class ExampleMiniport_Query {
[key] // providers always need these 3 fields
string InstanceName;
boolean Active;
[WmiDataId(1)] uint32 Count;
[WmiDataId(2)] ExampleMiniport_DataType Data; };

11. Define The Interfaces (Method Interface)
[WMI,
Dynamic,
Provider("WmiProv"),
guid("{7c01153f-58bb-4c56-bc9c-7f f73}")]
class ExampleMiniport_Method {
[key]
string InstanceName;
boolean Active;
[Implemented, WmiMethodId(1)]
void GetCount(
[out] uint32 Count );

12. Define The Interfaces (Method, con’t)
[Implemented, WmiMethodId(2)]
void GetOneThing(
[in] uint32 Id,
[out] uint32 Status,
[out] ExampleMiniport_DataType Data );
[Implemented, WmiMethodId(3)]
void GetManyThing(
[in] uint32 InCount, // num asked for
[out] uint32 OutCount,
[out, WmiSizeIs("OutCount")] ExampleMiniport_DataType Data[ ]

13. Define The Interfaces (Method, con’t)
[Implemented, WmiMethodId(4)]
void PutOneThing(
[in] ExampleMiniport_DataType Data,
[out] uint32 Status ); };

14. Define The Interfaces (Event Data)
[WMI,
Dynamic,
Provider("WmiProv"),
guid("{26d51a2b-b7d8-42df-bb53-33b730ccee18}")]
class ExampleMiniport_Event : WmiEvent {
[key, read]
string InstanceName;
[read] boolean Active;
[WmiDataId(1)] uint32 EventType;
[WmiDataId(2)] uint32 Id; };

15. Define The Interfaces (Event Method)
[WMI,
Dynamic,
Provider("WmiProv"),
guid("{2729cdcf-0bff c5e0532d4a43}") ]
class ExampleMiniport_EventMethod {
[key]
string InstanceName;
boolean Active;
[Implemented, WmiMethodId(1) ]
void Monitor( [in] uint32 Id, [out] uint32 Status ); };

16. Define The Interfaces (GUIDS and Headers)
For GUIDS use uuidgen.exe
Available in SDK or Visual Studio
Generate resource binary using mofcomp.exe
Available in DDK (also on system)
*.bmf used in resource file and to generate header
Generate the header file using wmimofck.exe
Available in DDK
Example:
mofcomp /b:expwmi.bmf expwmi.mof
wmimofck -hexpwmi.h -m -u expwmi.bmf

17. Great, But How Do I Go About It? (con’t)
Use scsiwmi.lib (scsiport/storport version of wmilib.lib)
Initializing scsiwmi
Registering the interfaces/classes
Implementing the queries
Implementing the methods
Handling events

18. Use scsiwmi.lib Link against scsiwmi.lib
Add WibLibContext (SCSI_WMILIB_CONTEXT) to HwDeviceExtension
Add custom data to HwDeviceExtension
In HwFindAdapter routine
Set WmiDataProvider to TRUE in PORT_CONFIGURATION_INFORMATION
Initialize WibLibContext in HwDeviceExtension (See ExpWmiInitialize)
In HwStartIo routine
Process Srb->Function == SRB_FUNCTION_WMI (see ExpWmiSrb)

19. Use scsiwmi.lib (HwFindAdapter)
ULONG
HwFindAdapter(
IN PVOID HwDeviceExtension,
IN PVOID HwContext,
IN PVOID BusInformation,
IN PCHAR ArgumentString,
IN OUT PPORT_CONFIGURATION_INFORMATION PortConfigInfo,
OUT PBOOLEAN Again ) {
// do other stuff
PortConfigInfo->WmiDataProvider = TRUE;
ExpWmiInitialize(HwDeviceExtension);
return SP_RETURN_FOUND; }

20. Use scsiwmi.lib (ExpWmiInitialize)//
// GUIDs are from generated expwmi.h (expwmi.c)
SCSIWMIGUIDREGINFO gGuidList[ ] = {
{&ExampleMiniport_Query_GUID, , 0},
{&ExampleMiniport_Method_GUID, , 0},
{&ExampleMiniport_EventMethod_GUID, 1, 0},
{&ExampleMiniport_Event_GUID, ,
WMIREG_FLAG_EVENT_ONLY_GUID}
// keep the order the same as the gGuidList (these are the GuidIndexes)
enum {
ExampleMiniport_Query_INDEX = 0,
ExampleMiniport_Method_INDEX = 1,
ExampleMiniport_EventMethod_INDEX = 2,
ExampleMiniport_Event_INDEX = 3 };

21. Use scsiwmi.lib (ExpWmiInitialize, con’t)
void
ExpWmiInitialize(
PDEVICE_EXTENSION Extension ) {
PSCSI_WMILIB_CONTEXT pWmiLibContext =
&Extension->WmiLibContext;
pWmiLibContext->GuidCount = ExampleMiniport_NUM_GUIDS;
pWmiLibContext->GuidList = gGuidList;
pWmiLibContext->QueryWmiRegInfo = ExpWmiQueryRegInfo;
pWmiLibContext->QueryWmiDataBlock = ExpWmiQueryDataBlock;
pWmiLibContext->SetWmiDataBlock = NULL; // not implemented
pWmiLibContext->SetWmiDataItem = NULL;
pWmiLibContext->ExecuteWmiMethod = ExpWmiExecuteMethod;
pWmiLibContext->WmiFunctionControl = ExpWmiFunctionControl; }

22. Use scsiwmi.lib (HwStartIo)
BOOLEAN
HwStartIo(
IN PVOID HwDeviceExtension,
IN PSCSI_REQUEST_BLOCK Srb ) {
if (Srb->Function == SRB_FUNCTION_WMI) { //
// Process the WMI request and return.
return ExpWmiSrb(
HwDeviceExtension,
(PSCSI_WMI_REQUEST_BLOCK) Srb ); }
// do other stuff

23. Use scsiwmi.lib (ExpWmiSrb)
Call ScsiPortWmiDispatchFunction with
WmiLibContext
Srb->WMIFlags with
SRB_WMI_FLAGS_ADAPTER_REQUEST indicates
adapter is target
Call ScsiPortWmiGetReturnSize to get
DataTransferLength when request completes
Call ScsiPortWmiGetReturnStatus to get status
when request completes

24. Use scsiwmi.lib (ExpWmiQueryRegInfo)
Register the Schema
#define Exp_MofResourceName L”MofResource”
UCHAR
ExpWmiQueryRegInfo(
IN PVOID Context,
IN PSCSIWMI_REQUEST_CONTEXT RequestContext,
OUT PWCHAR *MofResourceName ) {
*MofResourceName = Exp_MofResourceName;
return SRB_STATUS_SUCCESS; }

25. Use scsiwmi.lib (ExpWmiQueryDataBlock)
Data blocks must be aligned on 8 byte boundaries
InstanceLengthArray must be initialized if not
NULL and SRB_STATUS_SUCCESS
GuidIndex of methods should be handled for enumeration
Generated header contains types, Data_SIZE defines
Call ScsiPortWmiPostProcess to complete request
Complete with SRB_STATUS_OVERRUN if output buffer too small (size should be completed with required size)
Failures complete with SRB_STATUS_ERROR and size of zero
SRB_STATUS_SUCCESS completes with size <= required size

26. Use scsiwmi.lib (ExpWmiExecuteMethod)
Non-method GuidIndex should be failed
In buffer and out buffer are the same address
Generated Header contains
Method ids
PMethod_IN and PMethod_OUT types
Method_IN_SIZE Method_OUT_SIZE defines
Call ScsiPortWmiPostProcess to complete request
Complete with SRB_STATUS_OVERRUN if output buffer too small (size should be completed with required size)
Failures complete with SRB_STATUS_ERROR and size of zero (in buffer too small is a failure)
SRB_STATUS_SUCCESS completes with size <= required size

27. Use scsiwmi.lib (ExpWmiFunctionControl)
Used to Enable/Disable event notfications
Should verify ScsiWmiEventControl Function
Call ScsiPortWmiPostProcess to complete request
Failures complete with SRB_STATUS_ERROR
Success complete with SRB_STATUS_SUCCESS
Call ScsiPortWmiFireAdapterEvent and/or ScsiPortWmiFireLogicalUnitEvent to send notifications

28. Great, But How Do I Go About It? (con’t)
Calling the interfaces from user mode
Wbemtest.exe
VBS example
C/C++ example
Wmimofchk.exe generated html

29. Advanced Topics Supporting standard interfaces (HBA API, iSCSI)
Handling the WMI IRP yourself

30. Additional Resources Search MSDN: http://msdn.microsoft.com WMI
ScsiPortWmiPostProcess (scsiwmi.lib api)
HBA API
SNIA spec also available at:

31. © 2005 Microsoft Corporation. All rights reserved.
This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.