Fibre Channel SNIA HBA API Programmer's Guide HP Part Number: J2635-91000 Published: November 2009
©Copyright 1999, 2009 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license. The information contained herein is subject to change without notice.
Table of Contents 1 FC SNIA HBA API Overview.........................................................................................7 Introduction............................................................................................................................................7 Disclaimer...............................................................................................................................................7 Common Library Source and Readme Files..............................
A Call Order Sequence..................................................................................................39 Call Order Sequence.............................................................................................................................39 Reading HP's Vendor Library Call Order (Figure A-2)...................................................................39 Common Library Call Order ................................................................................................
List of Tables 1-1 2-1 3-1 Acronyms in this Guide..................................................................................................................8 Definitions of the API Portions .....................................................................................................11 Sample Programs...........................................................................................................................
1 FC SNIA HBA API Overview Chapter 1 introduces the Fibre Channel Storage Network Industry Association Host Bus Adapter Application Programming Interface (FC SNIA HBA API) and its features. Introduction This guide is for programmers creating applications using the SNIA API. The following is a list of additional resources you can use with this guide: • • Fibre Channel - Methodologies for Interconnects (FC-MI) Revision 1.6, Annex A SNIA HBA API specifications at www.snia.
hbaapilib.c - Implements the common HBA API library as of FC HBA API Specifications Version 1.0 from the SNIA. This code has been modified and enhanced for HP-UX from original open source code obtained from http://www.snia.org. Author Benjamin F. Kuo, Troika Networks, Inc. Code contributors: Tuan Lam, QLogic Corp.; Dan Willie, Emulex Corp.; Hari Hara Kumar M., Hewlett-Packard Co. Date: September 21, 2001.Copyright (c) 2001 Hewlett-Packard Co. All Rights Reserved. Hewlett-Packard Co.
FC SNIA HBA API Overview Software applications managing SANs require information from HBAs to operate. Every vendor, operating system, and platform provides HBA information differently. Sometimes information is not available at all. Hewlett-Packard created the FC SNIA HBA API to provide the following: • • a common HBA API library for all HP-UX Fibre Channel HBA vendors a vendor specific API library for HP supported Fibre Channel adapters The FC SNIA HBA API is a C library interface.
2 HBA Common Library APIs Chapter 2 introduces the HBA common library APIs. Introduction - How to Read Each API HBA common library APIs are classified by the functionality each provides. The following table defines each segment of the APIs: Table 2-1 Definitions of the API Portions Segment Definition Function Function prototype Input Parameters Function arguments strictly for the function being called. Input parameters are passed by value and do not change upon call return.
Output Parameters: None. Return Values HBA_STATUS_OK Returned after a successful execution of the call. A log is made in a log file (/opt/snia/snia.log) for every invalid hba.conf entry encountered. When none of the entries in hba.conf are valid, HBA_STATUS_ERROR is returned. HBA_STATUS_ERROR Returned when an internal library or system error is detected. HBA_STATUS_ERROR_BUSY Returned when the library is busy and cannot currently process this call. Call order sequence: See Appendix A.
HBA_STATUS status; status = HBA_FreeLibrary(); if (status == HBA_STATUS_OK) { printf("Successfully freed HBA library.\n"); } HBA_GetNumberOfAdapters Function: HBA_UINT32 HBA_GetNumberOfAdapters(); Purpose: Returns the total number of adapters in the system. This function is allowed to be called multiple times to handle OLAR. Input Parameters: None. Output Parameters: None. Return Values: 32-bit unsigned integer value of total number of Fibre Channel adapters claimed in the system.
Return Values: HBA_STATUS_OK Returned after a successful execution of the call. HBA_STATUS_ERROR Returned when an internal library or system error is detected. HBA_STATUS_ERROR_ARG Returned when the pointer passed to this function is NULL. HBA_STATUS_ERROR_BUSY Returned when the library is busy and cannot currently process this call. HBA_STATUS_ERROR_UNAVAILABLE Returned when the adapter to the corresponding handle is not available.
• • Call order sequence: EACCES = there has been a file open error EIO = there is an internal error See Appendix A. Example code: HBA_HANDLE adapter_handle; adapter_handle = HBA_OpenAdapter(adapter_name); if (adapter_handle != 0) { printf ("Successfully opened %s\n", adapter_name); } HBA_CloseAdapter Function: void HBA_CloseAdapter( HBA_HANDLE handle ); Purpose: Closes the adapter corresponding to the input handle.
HBA_ADAPTERATTRIBUTES *hba_attributes ); Purpose: Returns the attributes for an adapter port. Input Parameters handle - Handle to an adapter already opened by a call to HBA_OpenAdapter(). Output Parameters: hba_attributes - Pointer to a structure for returning the adapter attributes. Return Values: HBA_STATUS_OK Returned after a successful execution of the call. HBA_STATUS_ERROR Returned when an internal library or system error is detected.
Output Parameters: port_attributes - Pointer to a structure for returning the adapter port attributes. Return Values: HBA_STATUS_OK Returned after a successful execution of the call. HBA_STATUS_ERROR Returned when an internal library or system error is detected. HBA_STATUS_ERROR_BUSY Returned when the library is busy and cannot currently process this call. HBA_STATUS_ERROR_INVALID_HANDLE Returned when the handle passed to this function is invalid.
Input Parameters handle - Handle to an adapter already opened by a call to HBA_ OpenAdapter(). port_index - Index of the port. Output Parameters: port_statistics - Pointer to a structure for returning the port statistics. Return Values: HBA_STATUS_OK Returned after a successful execution of the call. HBA_STATUS_ERROR Returned when an internal library or system error is detected. HBA_STATUS_ERROR_BUSY Returned when the library is busy and cannot currently process this call.
NOTE: HP's vendor library returns HBA_PORTSPEED_UNKNOWN as the supported and current port speed attributes for all remote ports. Input Parameters: handle - Handle to an adapter already opened by a call to HBA_OpenAdapter(). port_index - Index of the port. discovered_port_index - Index of the discovered port for which port attributes are desired. Output Parameters: port_attributes - Pointer to a structure for returning the remote port attributes.
HBA_GetPortAttributesByWWN Function: HBA_STATUS HBA_GetPortAttributesByWWN( HBA_HANDLE handle, HBA_WWN port_wwn, HBA_PORTATTRIBUTES *port_attributes ); Purpose: Returns the port attributes of a remote port when its WWN is specified. NOTE: HP's vendor library returns HBA_PORTSPEED_UNKNOWN as the supported and current port speed attributes for all remote ports. Input Parameters: handle - Handle to an adapter already opened by a call to HBA_OpenAdapter().
status = HBA GetPortAttributesByWWN(adapter_handle, wwn, &port_attributes); if (status == HBA_STATUS_OK) { printf("Discovered port type is %u\n", port_attributes.PortType); } FC-3 Management Functions Call the following functions for FC-3 management: HBA_ SendCTPassThru NOTE: This function only applies for an HBA connected in a public loop or fabric topology.
HBA_STATUS_ERROR_UNAVAILABLE Returned when the corresponding handle's adapter is not available. Call order sequence: See Appendix A.
Input Parameters: handle - Handle to an adapter already opened by a call to HBA_OpenAdapter(). event_buffer - Pointer to a buffer to receive events. Set to size (in event records) of the buffer for receiving events on call. event_count - Number of event records in the buffer to receive events. Returned as the number of events actually delivered. Output Parameters: event_count - Number of event records in the buffer to receive events that have been filled.
HBA_SetRNIDMgmtInfo NOTE: HP's vendor library does not support this function. The application calling this API will get HBA_STATUS_ERROR_NOT_SUPPORTED when all the arguments passed are valid. Function: HBA_STATUS HBA_SetRNIDMgmtInfo( HBA_HANDLE handle, HBA_MGMTINFO *p_info ); Purpose: Sets the RNID returned from the HBA. Input Parameters: handle - Handle to an adapter already opened by a call to HBA_OpenAdapter(). p_info - Pointer to structure containing management information.
HBA_GetRNIDMgmtInfo NOTE: HP's vendor library does not support this function. The application calling this API will get HBA_STATUS_ERROR_NOT_SUPPORTED when all the arguments passed are valid. Function: HBA_STATUS HBA_GetRNIDMgmtInfo( HBA_HANDLE handle, HBA_MGMTINFO *p_info ); Purpose: Returns the RNID from the HBA. Input Parameters: handle - Handle to an adapter already opened by a call to HBA_OpenAdapter().
HBA_SendRNID NOTE: HP's vendor library does not support this function. The application calling this API will get HBA_STATUS_ERROR_NOT_SUPPORTED when all the arguments passed are valid. Function: HBA_STATUS HBA_SendRNID( HBA_HANDLE handle, HBA_WWN wwn, HBA_WWNTYPE wwn_type, void * p_rsp_buffer, HBA_UINT32 *rsp_buffer_size ); Purpose: Issues an RNID ELS to another node in 0xDF format (Topology Discovery Specific Node Identification Data).
if ((status = HBA_SendRNID(adapter_handle, wwn, wwn_type, resp_buffer, sizeof(resp_buffer))) == HBA_STATUS_OK) { printf("Success in HBA_SendRNID\n"); } else { printf("Error in HBA_SendRNID\n"); } FCP Information Functions Call the following functions to obtain FCP information for SCSI devices behind Fibre Channel interfaces: HBA_GetFcpTargetMapping NOTE: This function is meant to be called only by an application having an effective user id as that of the super user (that is, effective user id = 0).
HBA_STATUS_ERROR_UNAVAILABLE Returned when the adapter to which the handle corresponds is not available. HBA_STATUS_ERROR_MORE_DATA Returned when the allocated buffer is insufficient. Call order sequence: See Appendix A. Example Code: HBA_STATUS status; HBA_HANDLE adapterhandle; HBA_FCPTARGETMAPPING single_mapping; PHBA_FCPTARGETMAPPING map_list; memset(&single_mapping, 0, sizeof(single_mapping)); single_mapping.
HBA_GetFcpPersistentBinding NOTE: This function is meant to be called only by an application having an effective user id as that of the super user (that is, effective user id = 0). Function: HBA_STATUS HBA_GetFcpPersistentBinding( HBA_HANDLE handle, PHBA_FCPBINDING binding ); Purpose: Gets persistent bindings between an FCP target and SCSI ID. Input Parameters: handle - Handle to an adapter already opened by call to HBA_OpenAdapter().binding - Pointer to an HBA_FCPBINDING structure.
" time with single entry buffer\n"); if ((status =HBA_GetFcpPersistentBinding(adapterhandle, &single_mapping)) == HBA_STATUS_ERROR_MROE_DATA) { printf("HBA_GetFcpPersistentBinding %d targets\n", single_mapping.NumberOfEntries); if (single_mapping.NumberOfEntries; > 0) { map_list = (PHBA_FCPBINDING) malloc ((single_mapping.NumberOfEntries;) * sizeof(HBA_FCPBINDING) ); if (map_list) { map_list->NumberOfEntries = single_mapping.
HBA_UINT32 sense_buffer_size ); Purpose: Sends a SCSI Inquiry command to a remote WWN. Input Parameters: handle - Handle to an adapter already opened by call to HBA_OpenAdapter(). port_wwn - Port WWN of a remote port. fc_lun - Specific FC LUN to send inquiry to. evpd- Set to 0 to return standard SCSI INQUIRY data. Set to 1 to return the vital product data specified by the page code. page_code - If evpd is 1, the vital product data page code to request.
Example Code: memset (resp_buffer, 0, sizeof(resp_buffer)); memset (sense_buffer, 0, sizeof(sense_buffer)); if ((status = HBA_SendScsiInquiry(adapter_handle, wwn, fc_lun, evpd_reqd, page_code, resp_buffer, sizeof(resp_buffer), sense_buffer, sizeof(sense_buffer))) != HBA_STATUS_OK) { printf ("HBA_SendScsiInquiry error %d\n", status); } else { printf("HBA_SendScsiInquiry succeeded\n"); } HBA_SendReportLUNs NOTE: This function is meant to be called only by an application having an effective user id as that of
HBA_STATUS_ERROR_ILLEGAL_WWN Returned when the WWN given as input does not match the WWN of any discovered port. HBA_STATUS_ERROR_MORE_DATA Returned when any of the allocated buffers is insufficient. HBA_STATUS_SCSI_CHECK_CONDITION Returned when a SCSI check condition occurs and there is valid sense data in the SenseBuffer. Call order sequence: See Appendix A.
HBA_STATUS_ERROR Returned when a internal library or system error is detected. HBA_STATUS_ERROR_BUSY Returned when the library is busy and cannot currently process this call. HBA_STATUS_ERROR_INVALID_HANDLE Returned when the handle passed to this function is invalid. HBA_STATUS_ERROR_ARG Returned when any of the pointers passed to this function are NULL. HBA_STATUS_ERROR_UNAVAILABLE Returned when the adapter to which the handle corresponds is not available.
HBA_RefreshInformation Function: void HBA_RefreshInformation( HBA_HANDLE handle ); Purpose: Refreshes adapter information. Input Parameters: handle - Handle to an adapter already opened by call to HBA_OpenAdapter(). Output Parameters: None. Return Values: None. Call order sequence: See Appendix A. Example code: HBA_RefreshInformation(adapterhandle); HBA_ResetStatistics NOTE: This function was deprecated as of FC-MI Revision 1.6.
3 Creating a Vendor Library for HP's HBA SNIA API Chapter 3 introduces compiling and setting-up a third party vendor library with HP's common HBA API. The /etc/hba.conf File The /etc/hba.conf file has entries for each vendor library to be loaded during a HBA_LoadLibrary() call in the common API library. Invalid entries in this file are ignored by the common API library. Comment lines in this file must begin with a # in the first column. Example of entries in this file are: # # # # # /etc/hba.
A Call Order Sequence Appendix A explains the call order sequence for FC SNIA HBA API functions. Call Order Sequence The following are pictorial representations of the call sequence order that should be followed by applications using HP's implementation of the FC SNIA HBA API. Before a call is made to any of the functions, a call to all the previous functions above it must be made at least once for the corresponding library, adapter, port, discovered-port functions.
NOTE: * Call to HBA_GetAdapterName() before HBA_OpenAdapter() is not enforced.
Index Symbols M /etc/hba.
