HBA API FAQ
Benjamin F. Kuo <benk@troikanetworks.com>
TROIKA Networks, Inc.
Dixon Hutchinson <dhutchin@legato.com>
Legato Systems, Inc.
DRAFT VERSION 1.0.7, January 30, 2002
CONTENTS
1. Introduction
2. What's New
3. General Questions
3.1 What is the HBA API?
3.2 What is the history of the HBA API?
3.3 Where can I get some general high level information on the HBA API?
3.4 How real is this standard? Specifically, when can I see this working?
3.5 How can I get a copy of the HBA API specification?
3.6 What development resources are available for the HBA API?
3.7 Is the HBA API an in-band or out-of-band mechanism?
3.8 How can I get involved in developing the HBA API?
3.9 Does the HBA API support SCSI adapters?
3.10 Does the HBA API support iSCSI adapters?
3.11 How secure is the HBA API? Can a rogue program disrupt my SAN through the HBAAPI?
4.1 Where is the latest version of the HBA API code examples?
4.2 What files are installed to use the HBA API?
4.3 Where does the HBA API common library get installed?
4.4 Can I issue any arbitrary SCSI command with the HBA API?
4.5 What's the difference between a platform WWN and a node WWN?
4.6 What is persistent binding?
5.1 What is the common HBA library?
5.2 What operating systems are supported by the HBA API common library?
5.3 Does the HBA API support asynchronous event notification?
5.4 What is the maximum buffer size that can be passed to the common HBA function
HBA_SendCTPassThru?
5.5 Why was the HBA_ResetStatistics call removed?
5.6 Where do I get more information about the low level CT commands I can send through the HBA API?
5.7 What permissions should be given to the HBA API in unix?
5.8 What is an ELS, and how is it used in the HBA_SendRNID call?
5.9 Where does HBA_GetRNIDMgmtInfo get its information from? The HBA or a switch?
5.10 I can't get HBA_SendScsiInquiry working with the libraries I have because it can't find the symbol? How can I fix this?
6.1 What is CIM?
6.2 How is CIM supported by the HBA API?
6.3 I heard that there is a translation layer between the HBA API and CIM, where can I get more information?
7.1 Who is behind the HBA API standard?
7.2 What HBA vendors support the HBA API?
7.3 Which HBA manufacturers/models have HBA API libraries available?
7.4 Which management vendors are using the HBA API?
7.5 Are there any test or validation suites available to test by HBA API implementation?
7.6 Is there an equivalent of an Internet News (NNTP) server for HBA API discussions?
This FAQ is intended to address frequently asked questions about the HBA API. This FAQ is maintained by Benjamin F. Kuo at TROIKA Networks, Inc. <benk@troikanetworks.com> and Dixon Hutchinson at Legato Systems, Inc. <dhutchin@legato.com> and is not endorsed or sponsored by the Storage Networking Industry Association (SNIA).
A little more information on iSCSI API's and the support Matrix.
Version history:
| Version | Date | Description |
| DRAFT Version 1.0.0 | June 29, 2001 | Initial draft. |
| DRAFT Version 1.0.1 | July 10, 2001 | Resolved initial comments, added support matrix. |
| DRAFT Version 1.0.2 | August 16, 2001 | Reformat, remove copyright. |
| DRAFT Version 1.0.3 - 1.0.7 | 9/15/2001 - 1/30/2002 | Update vendor support matrix. |
The SNIA Common HBA API is an industry standard, programming interface for accessing
management information in Fibre Channel Host Bus Adapters (HBA). Developed through the
Storage Networking Industry Association (SNIA), the HBA API has been overwhelmingly adopted
by Storage Area Network vendors to help manage, monitor, and deploy storage area networks in
an interoperable way.
The HBA API is implemented as a set of 'C' level APIs, which allow access to low level, Fibre
Channel HBA information in a platform- and vendor- independent way. The API
depends on vendor supplied, vendor specific code for the vendor's HBAs.
The API does not support any vendor's HBA without a vendor specific library.
The HBA API effort began in March of 2000 in the SNIA Fibre Channel working group. In May of 2000, the HBA API subgroup was formed. In July of 2000 the 1.0 feature set was frozen and the initial draft submitted to the T11 FC-MI standards group. Version 1.0 was approved by the SNIA Fibre Channel working group in September of 2000 and is currently undergoing review as part of the T11 FC-MI Letter Ballot process.
Version 2.0 efforts have been ongoing since December of 2000, with version 2.0 expected by Q2 2002.
The following papers may be useful in understanding the HBA API.
Development of an API Standard in Interoperable Storage Networking Presentation (PowerPoint)
SNW Fall 2000 Technical Tutorial
Benjamin F. Kuo, Troika Networks, Inc.
http://hbaapi.sourceforge.net/HBA_SNW_Fall2000.ppt
Common HBA API White Paper (PDF)
SNIA FC Working Group
Mark Woithe, JNI Corp.
http://hbaapi.sourceforge.net/Common%20HBA%20API%20White%20Paper%20v012801.pdf
The HBA API is in deployment today, and was first demonstrated at the Fall 2000 Storage Networking World in Orlando.
The most current version of the HBA API 1.0 specification is part of the T11 FC-MI.
T11/01-004v2 dpANS - Fibre Channel- Methodologies for Interconnects Technical Report (Annex A)
This can be found on the T11 web site at http://www.t11.org under "Drafts".
The latest version of the HBA API 2.0 specification is still in development. The latest version of this document will be added to the Fibre Channel working group FTP site shortly.
You should work directly with your HBA vendor for development support for the HBA API. However, most questions about the HBA API specification can be answered by getting involved in the SNIA Fibre Channel working group or by sending your questions to the group at large through the email reflector at snia-snmwg-fc@snia.org.
The HBA API is neither. Information from the HBA API can be usually found through an out-of-band mechanism for management, however can also be accessed in-band through a IP over Fibre Channel connection.
You should join the SNIA Fibre Channel working groups, which hold in-face meetings, conference calls, and discusses issues over the email reflector. More information about the SNIA can be found at http://www.snia.org.
If you are already a member of the SNIA, you can get the browse the current mail archives of the Fibre Channel working group at:
http://www.snia.org/mo/mail/?l=snmwg-fc&r=1&w=2
No, the HBA API is limited to supporting Fibre Channel HBAs.
Not yet, however there has been discussion on adding iSCSI support in the future. There is a separate working group (IPS TWG) within SNIA working on an API for iSCSI
There are no calls in the current HBA API which are able to read or write
data from storage, or otherwise affect SAN operation. All current SCSI calls in
the HBA API are informational (read-only) calls. However, the CT passthrough
command does allow read and write of information from a switch, if allowed.
The HBA API is implemented as a common library which depends on vendor-specific libraries for specific HBA model support.
The latest version of the common library and example code is dated January 9, 2001 and can be found at:
http://prdownloads.sourceforge.net/hbaapi/hbaapi-src-2001JAN09.zip
The HBA API consists of three major parts (vendor library, common library, and registration) that are installed on a system to operate.
On Windows systems:
On Unix systems:
On Windows systems:
On Unix systems:
No. The scope of the HBA API is limited to discovery of Fibre Channel components. Generic SCSI pass through has been discussed but has been deemed generally dangerous, as it bypasses the operating system protections and also causes several SCSI-related issues (including problems with breaking reservations, potentially corrupting data, or interrupting I/O). As such it is not included in the API.
platform WWN - unique world-wide identifier for a computer system, used to tie together in software the association between many components within that system
node WWN - unique world-wide identifier used to associate many port world wide names within a system. This is used currently in two ways: first, to specify the relationship between ports on a common device (one node WWN and several port WWNs on a HBA), secondly to identify ports on a system (one node WWN and many port WWNs on a system with many HBAs). Unfortunately the use of this is not consistent within currently deployed hardware.
Persistent binding is a feature of HBAs which remembers the last SCSI address a particular Fibre Channel target has been mapped to. For example, that a port on a physical disk (world wide name 01:02:03:04:05:06:07, LUN 0) was last seen at SCSI address (bus=0,target=3,lun=0) on the operating system. Persistent binding ensures that this is consistent from reboot to reboot unless changed by the user.
Some HBA vendors automatically persistently bind devices, while others require manual configuration. Persistent binding is most important in the case of operating systems which remember devices by SCSI address, or in the case of raw volumes used by databases.
The common library is a component of the HBA API, typically called HBAAPI.DLL
or libHBAAPI.so which loads vendor specific library support for HBAs.
The initial work on the HBA API was done on Windows NT, Windows 2000, and Solaris 2.6, 2.7, and 2.8. Other operating systems are also planned for support.
Version 1.0 of the spec does not support asynchronous event notification, however this capability is a central part of Version 2.0 of the spec (currently in development.)
This is a vendor specific limitation and depends on the vendor of your HBA.
The HBA_ResetStatistics call was removed because it was decided that
resetting statistics counters is an undesirable function. Because any
application accessing the HBA API could reset statistics, this could potentially
confuse other software monitoring statistics counters.
More information about CT commands can be found in the T11 specifications for FC-GS-3.
This depends on your application. It is recommended that permissions be limited to trusted logins only or root access.
An ELS is a low level Fibre Channel primitive. It is used by the HBA_SendRNID call to send an RNID request across the Fibre Channel network and retrieve the response.
The information returned by HBA_GetRNIDMgmtInfo is obtained from the HBA, and does not trigger any network activity.
This was a bug in the original version of the HBA API libraries made available to the public. The latest version fixed this and is dated January 9, 2001.
CIM stands for Common Information Model, and is a high level management standard used to manage computer systems and components. CIM is being developed by the DMTF (Desktop Management Task Force) and regularly worked on by the Fibre Channel community through the SNIA.
The HBA API does not directly support CIM. However, the HBA API exposes information which can be exported to CIM providers.
As part of the SNIA Interoperability labs, a Java Native Interface (JNI) provider and corresponding CIM provider modeling the Fibre Channel adapter CIM model was created. This can be found as part of the SNIA CIM efforts. This can be found on the SourceForge site at http://sourceforge.net/projects/hbaprovider/
During the first Storage Networking World conference with the HBA API demo the following vendors endorsed the HBA API Interoperability Theme: Adaptec, Agilent, BMC Software, Brocade, Connex, EMC, Emulex, FCIA, FibreAlliance, HP, Highground, Hitachi Data Systems, Interphase, InterSAN, JNI, Legato, McData, NCITS, Prisa, Qlogic, StorageNetworks, SNIA, Tivoli, TROIKA Networks, Veritas, and Vixel. Other vendors also have announced their support since that time.
Agilent, Emulex, Interphase, JNI, and Qlogic, TROIKA Networks have all publicly announced their support for the HBA API. You should check with your individual vendor if they are not listed here.
You'll need to contact the vendors directory to get the specific information about
which models are available. You can reach HBA vendors at:
Vendor Support Matrix
| Vendor Name | HBA | Supported OS | Status | Contact |
| Emulex Corp. http://www.emulex.com/ts/dds.html |
Windows NT Windows 2000 Solaris Linux |
Fully available. | Bill Bostick (Bill.Bostick@Emulex.com) | |
| JNI Corp.
http://www.jni.com/Drivers |
Long List | Solaris | Fully available |
Tim Lustig tlustig@jni.com |
|
LSI Logic http://adapters.lsilogic.com |
LSI44929O LSI44929LO LSI44929H LSI44929LH LSI40919O LSI40919LO LSI40919H LSI40919LH ITI7004G2-LC LSI7202CP-LC |
Windows NT Windows 2000 Linux Solaris |
Fully Available |
JoLyn Reith (jolyn.Reith@lsil.com) |
|
TROIKA Networks, Inc. http://www.troikanetworks.com |
Zentai Z-2400 |
Windows NT Windows 2000 |
Fully available. |
Peter Jones (peterj@troikanetworks.com) |
| Qlogic Corp. | QLA-22XX |
Solaris Windows 2000 Linux (Redhat) |
Fully Available |
Arun Mittal arun.mittal@qlogic.com |
|
ATTO Techology http://www.attotech.com/software |
ExpressPCI FC 3300 ExpressPCI FC 3305 ExpressPCI FC 2600 ExpressPCI FCSW |
Windows NT Windows 2000 |
Fully Available | Peter Donnelly (pdonnelly@attotech.com) |
| Agilent Technologies |
HHBA-5101C HHBA-5121A HHBA-5221A HHBA-5220A |
Windows NT Windows 2000 |
Fully Available | Jerry Wong (jerry_wong@agilent.com) |
|
Hewlett-Packard http://docs.hp.com/hpux/onlinedocs |
All Tachyon HBAs, rev B.11.00.10 or higher (except A3591B, A3404A, A3636A, A3740A) | HPUX 11.00, 11i and newer | Fully Available | Brian Lee (brian_lee4@hp.com) |
CA Unicenter, Highground, InterSAN, Legato, Tivoli, SANavigator, Sun Microsystems, Prisa Networks,
Veritas, and
others.
No tests are currently publicly available, although test and validation efforts are underway in the SNIA Interoperability committee with intent to add these as part of the FCIA SANmark process. In addition, test programs may be available from your HBA vendor.
Not yet.