Section 7.5. HBA API | Inside Windows Storage: Server Storage Technologies for Windows 2000, Windows Server 2003 and Beyond

7.5 HBA API

In a storage area network, HBAs provide extremely important functionality and provide a means of physical connectivity between a server and other elements of the storage network, including storage devices, switches, and other hosts . As storage networks grow in complexity, the need for automatic discovery and management of devices becomes increasingly important.

The Storage Networking Industry Association (SNIA) defined a C library API to allow storage management applications to manage Fibre Channel HBAs. The management applications using the API can implement a single interface, no matter what the HBA model or vendor is, as long as the vendor supports the SNIA-defined HBA API. The APIs defined include support for querying and setting HBA configuration management, as well as measuring HBA performance statistics. In particular, the HBA API can provide the following:

HBA attributes such as model, vendor name, and World Wide Name (WWN, a unique 64-bit number assigned by the vendor and registered with the IEEE; the IEEE assigns a range of numbers to each vendor).
Port attributes such as port ID (a 24-bit number that is unique for each node), type of port, current port state, and maximum frame size that the port can support.
Port Fibre Channel protocol attributes such as SCSI bus number or SCSI target ID.
Port statistics such as frames received, frames transmitted, time since last occurrence of statistics reset, and errors encountered (nature and number of occurrences).
FC-3 (Fibre Channel functional level 3) management information such as WWN or port ID; the noteworthy point here is that the API allows a storage management application to query Fibre Channel services such as name servers. The API also allows querying and setting of node information such as WWN and port ID.

Although Microsoft and SNIA members both support the HBA API, the approaches differ a little. The SNIA approach, illustrated in Figure 7.4, requires three components :

A generic HBA API DLL owned and maintained by SNIA. This DLL exposes a standard interface for the benefit of management applications; at the bottom layer, the DLL interfaces with several vendor-written DLLs.
An HBA vendor-written DLL that plugs into the generic HBA API DLL. This vendor-written DLL reveals management information and interacts with the vendor-written driver using proprietary IOCTLs.
A vendor-written device driver for the HBA.

Figure 7.4. The SNIA HBA API

graphics/07fig04.gif

Although this standardization effort has its merits, Microsoft sees some problems with this approach:

There is no clear way to manage the distribution and versioning of the proposed dynamic link libraries. This is one more example of a potential DLL problem in which various applications will install versions of the libraries and potentially overwrite libraries that other applications have installed.
The HBA vendor must not only write the device driver and private IOCTL interface to the driver, but must also write the vendor-specific DLL library, as well as potentially modify the wrapper HBA library to handle vendor-specific interfaces to the vendor DLL.
It will be extremely hard to test and certify vendor drivers that implement private IOCTLs; for example, how does one verify that the driver code will not result in a buffer overrun situation when bad parameters are passed on the IOCTL call?
The architecture appears to be extensible at first sight, but upon closer inspection, one realizes that the HBA vendors will be forever chasing the management application vendors to add code that deals with vendor-specific enhancements.
The solution does not allow communication and management in kernel modes. The SNIA approach dictates that a management application must wait until the Windows NT user mode subsystem is fully operational. For management purposes such as LUN masking, however, it is desirable that a kernel mode driver be able to take some action while the system is booting and even before the user mode subsystem has been started.

Microsoft advocates a slightly different approach, illustrated in Figure 7.5, which consists of the following components:

A generic HBA API DLL owned and maintained by Microsoft. This DLL exposes a SNIA-defined standard interface at the upper edge for the benefit of management applications. At the bottom edge, the DLL interfaces with Windows Management Instrumentation (WMI), the Microsoft implementation of the Common Information Model (CIM), which, as stated earlier, is an object-oriented systems management model adopted by both SNIA and the DMTF. This DLL also does the required translation back and forth between the SNIA HBA API and WMI.
A vendor-written device driver for the HBA; this driver implements WMI and makes the management and configuration interface available in the WMI repository. Because WMI is a two-way interface, the driver also implements WMI IRP functionality that allows a management application to set configuration parameters for the driver. Note that the vendor is required to write a driver anyway; the additional burden being imposed here is to implement WMI code in that driver.

Figure 7.5. The Microsoft HBA API

graphics/07fig05.gif

The advantages with the Microsoft approach are as follows :

All interfaces presented are standardized, whereas in the SNIA approach, the interface between the generic HBA API DLL and the vendor-written DLL is proprietary for each vendor. The Microsoft approach is consistent with the SNIA adoption of the DMTF Common Information Model.
The approach also allows for extensibility, since a vendor can easily extend an existing WMI class or define a new one and populate management information into that class. Again, this just emphasizes the extensibility of the SNIA-adopted CIM model.
The biggest advantage is that management applications can use either the SNIA HBA API or the SNIA CIM model. If applications use the SNIA HBA API, they still work unaltered, thanks to the WMI code in the driver and the Microsoft dynamic link library that maps WMI information to the SNIA HBA interface.
The architecture allows a kernel mode component to interrogate the vendor-written driver and take some management action.
The management applications do not (and should not) care about how the underlying code obtains the necessary information. As long as the management applications use the SNIA HBA API (and this is what Microsoft recommends), the underlying code may obtain the necessary information using the SNIA-advocated DLLs or the Microsoft-advocated WMI. In both approaches management applications still write to a single interface.

Note that the WMI interfaces needed to code the HBA driver shipped with Windows 2000. Therefore, if one had the Microsoft dynamic link library mapping WMI information to the SNIA, along with the SNIA HBA dynamic link library, the solution would work on Windows 2000 as well. The problem is that the Microsoft dynamic link library is indeed available with Windows Server 2003, but it remains to be seen whether Microsoft offers a version of this library for the Windows platform as well.

Top