
         QLogic Linux Common HBA API Shared Library
                           Readme File

      This software license applies only to QLogic customers.
                     Marvell Semiconductor, Inc.
                     All rights reserved.


Table of Contents

1. Package Contents
2. Using the HBA API Libraries
   2.1 Installing the HBA API Libraries
   2.2 Removing the HBA API Libraries
   2.3 Testing the Installation
3. OS Support
4. Supported Functions
5. Known Issues
6. Special Notes
7. Contacting Support


1. Package Contents

The HBA API Libraries for VMware ESX Server 7.0/8.0/8.0 U2/9.0
package contains the SNIA HBA API Libraries from Marvell Semiconductor, Inc.
The ESX inbox driver version which supports this new interface is
1.0.12.0 onwards.
The ESX Out-of-Box driver version which supports this new interface is
1.1.3.0 onwards.

The base HBA API Library distributed is version 2.
This library was tested with above mentioned ESX 7.0/8.0/8.0 U2/9.0
FC/FCoE drivers.

2. Using the HBA API Libraries

2.1 Installing the HBA API Libraries

Note: Currently the scripts assume /usr/lib/ to be the install directory.
However as per new ongoing vmkmgmt interface this might change in future.
If it does, we need to manually copy required library files in the new path.

To install the HBA API libraries:

1. Unpack the tarball into the /snia subdirectory.

2. Change to the snia directory.

3. Enter the following command:

To install 32 bit binaries,
   ./Install.sh
To install 64 bit binaries,
   ./Install.sh x86_64
To install 64 bit dsdk binaries on ESXi 8.0/9.0,
   ./Install.sh dsdk

The script installs the QLogic libraries.

2.2 Removing the HBA API Libraries

To remove the HBA API libraries:

1. Change to the /snia subdirectory.

2. Enter the following command:

To remove 32 bit binaries,
   ./Remove.sh
To remove 64 bit binaries,
   ./Remove.sh x86_64

The script removes the libraries in
addition to the base HBA API library.

2.3 Testing the Installation

The hbaapitest test program for the SNIA libraries is located
in the snia subdirectory. You may use this program to
validate the installation.

To run this program:

1. Change to the /snia subdirectory.

2. Run the following program:

   hbaapitest

This test program displays all the SNIA information
on the console.


3. OS Support

This API library package was tested with VMware ESX
Server 6.5/6.7/7.0/8.0 Inbox FC driver.


4. Supported Functions

This API release is v1.05 build 3.  It supports the following functions:

RUBAH Common API functions --

 CPQFC_RegisterLibrary
 CPQFC_GetVersion
 CPQFC_LoadLibrary
 CPQFC_FreeLibrary
 CPQFC_GetNumberOfAdapters
 CPQFC_GetAdapterName
 CPQFC_OpenAdapter
 CPQFC_CloseAdapter
 CPQFC_GetAdapterAttributes2
 CPQFC_GetAdapterAttributes
 CPQFC_GetAdapterPortAttributes
 CPQFC_GetDiscoveredPortAttributes
 CPQFC_QosEnable
 CPQFC_QosDisable
 CPQFC_QosGetConfig
 CPQFC_QosSetConfig
 CPQFC_NpivQosCompRegister
 CPQFC_NpivQosGetCap
 CPQFC_NpivSetQos
 CPQFC_NpivGetQos
 CPQFC_NpivEnableQos
 CPQFC_NpivDisableQos
 CPQFC_NpivQosGetPerf
 CPQFC_NpivQosTuneSlo
 CPQFC_NpivQosGetList

SNIA Common API functions (from v2.0 final specification) --

 HBA_RegisterLibrary
 HBA_RegisterLibraryV2
 HBA_GetVersion
 HBA_LoadLibrary
 HBA_FreeLibrary
 HBA_GetNumberOfAdapters
 HBA_GetAdapterName
 HBA_OpenAdapter
 HBA_CloseAdapter
 HBA_GetAdapterAttributes
 HBA_GetAdapterPortAttributes
 HBA_GetPortStatistics
 HBA_GetDiscoveredPortAttributes
 HBA_GetPortAttributesByWWN
 HBA_SendCTPassThru
 HBA_SendScsiInquiry
 HBA_SendReportLUNs
 HBA_SendReadCapacity
 HBA_GetFcpTargetMapping
 HBA_GetFcpPersistentBinding
 HBA_GetEventBuffer
 HBA_SendRNID
 HBA_GetFcpTargetMappingV2
 HBA_SendCTPassThruV2
 HBA_ScsiInquiryV2
 HBA_ScsiReportLUNsV2
 HBA_ScsiReadCapacityV2
 HBA_SendRLS
 HBA_GetFC4Statistics


5. Known Issues

*	When running with just Emulex HBAs, an error message may occur:

	HBA_LoadLibrary: Encountered an error loading: /usr/lib/libqlsdm.so

	This is normal behavior when no QLogic HBAs are present. You can
	ignore this message.

*	When running with QLogic HBAs, the following error message
	appears:

	HBA_GetFcpPersistentBinding  is not supported

	This is normal since the HBA API support included in the ESX
	Server QLogic driver does not support this command.

*	The OSDeviceName displayed might not match the actual device name
	in the Classical version of the ESX.

	The mismatch is because the /proc node created by the COS is not
	based on the Scsi_Host no. assigned by the vmkernel.

6. Special Notes

*   FC port ID format:

    Currently, the QLogic defined SDM API in 3 byte fields always
    return the FC Port ID.  However, the SNIA-defined common API
    returns the FC Port ID in a 32-bit field.  In libqlsdm v1.10 Beta+
    and Linux HBA driver v4.35 Beta and later, the ioctl and API
    implementations treat this 32-bit field as if it is an array of 4
    bytes; it stores the FC Port ID in bytes 1, 2 and 3 of this array.
    It treats byte 0 of this 32-bit field as a reserved field.

*  HBA_SendRNID data format:

    Due to the current low level of interest in the usage of this
    function, the data format has been changed per customer request.
    The resulting data is shifted down 4 bytes compared to the
    format defined in the SNIA specification.  The value of the
    newly created 4 bytes at the beginning of the returned data
    should be ignored as they are currently only hard-coded
    values.  The function return status still represents the
    actual response status of the RNID command sent.

*  Other features not supported:

    Linux API library does not currently support any externally
    available NVRAM and diagnostics related the API function.
    QLogic plans to support these at a later date.


7. Contacting Support

Please feel free to contact your Marvell QLogic approved reseller or
Marvell QLogic Technical Support at any phase of integration for assistance.
Marvell QLogic Technical Support can be reached by the following methods:

 Web:    https://www.marvell.com/support.html
 E-mail: support@marvell.com


 Copyright 2012-2024. All rights reserved worldwide.
QLogic, the QLogic logo, and the Powered by QLogic logo are registered
trademarks of Marvell Semiconductor, Inc. All other brand and product names
are trademarks or registered trademarks of their respective owners.

