QLogic Fibre Channel Adapter and Converged Network Adapter API for Linux Kernel 2.4.x/2.6.x/3.x Readme QLogic Corporation All rights reserved Table of Contents 1. Package Contents 2. OS Support 3. Supported Functions 4. Using the SNIA API Library 4.1 Downloading the API Release 4.2 Extracting SNIA API Library 4.3 Installing SNIA API Library 4.4 Installing on RHEL 4.x 4.5 Uninstalling SNIA API Library 4.6 Enabling Debug in API 5. Additional Notes 6. Contacting Support 1. Package Contents The following table describes the contents provided in the Fibre Channel Adapter and Converged Network Adapter (FCoE) API for the Linux package. * hba.conf - Configuration file for QLogic Host Bus Adapters. * lib - This directory contains API binary files to be installed. * get_version - This directory contains binary files to get API versions. * libinstall - Script file to install/setup Host Bus Adapter API library. * libremove - Linux script to remove libqlsdm.so from /usr/lib and /usr/lib64. * Release - Text version of this package release file. * Readme - Text version of this package readme file. 2. OS Support The Fibre Channel Adapter and Converged Network Adapter API for Linux is compatible with the following OS platforms: * Red Hat RHEL AS 3.0 32-bit/64-bit on Intel x86, Intel 64, AMD64, Intel IA64, and PPC64 platforms. * Red Hat RHEL AS 4.0 32-bit/64-bit on Intel x86, Intel 64, AMD64, Intel IA64, and PPC64 platforms. * Red Hat RHEL AS 5.0 32-bit/64-bit on Intel x86, Intel 64, AMD64, Intel IA64, and PPC64 platforms. * Red Hat RHEL AS 6.0 32-bit/64-bit on Intel x86, Intel 64, AMD64, and PPC64 platforms. * Red Hat RHEL AS 7.0 64-bit on Intel 64, AMD64 and PPC64 platforms. * Novell SLES 9 32-bit/64-bit on Intel x86, Intel 64, AMD64, Intel IA64, and PPC64 platforms. * Novell SLES 10 32-bit, 64-bit on Intel x86, Intel 64, AMD64, Intel IA64, and PPC64 platforms. * Novell SLES 11 32-bit, 64-bit on Intel x86, Intel 64, AMD64, Intel IA64, and PPC64 platforms. * Novell SLES 12 64-bit on Intel 64, AMD64, PPC64LE platforms. 3. Supported Functions The Fibre Channel Adapter and Converged Network Adapter API for Linux supports the following SNIA Common API functions (from v2.0 final specification): HBA_GetVersion HBA_LoadLibrary HBA_FreeLibrary HBA_GetNumberOfAdapters HBA_GetAdapterName HBA_OpenAdapter HBA_CloseAdapter HBA_GetAdapterAttributes HBA_GetAdapterPortAttributes HBA_GetDiscoveredPortAttributes HBA_SendCTPassThru HBA_SetRNIDMgmtInfo HBA_GetRNIDMgmtInfo HBA_SendRNID (NOTE: Data returned is not SNIA 1.x compliant. See Additional Notes.) HBA_SendScsiInquiry HBA_SendReportLUNs HBA_SendReadCapacity HBA_SendScsiInquiryV2 HBA_SendReportLUNsV2 HBA_SendReadCapacityV2 HBA_GetFcpTargetMappingV2 HBA_GetFcpTargetMapping HBA_GetPortStatistics HBA_GetEventBuffer HBA_SendRPS HBA_SendRLS (current via response buffer of HBA_SendRPS) 4. Using the SNIA API Library This section provides procedures for downloading, extracting, installing and uninstalling the SNIA API library. For details, see the following topics: * 4.1 Downloading the API Release * 4.2 Extracting SNIA API Library * 4.3 Installing SNIA API Library * 4.4 Installing on RHEL 4.x * 4.5 Uninstalling SNIA API Library 4.1 Downloading the API Release To download the current API release package: 1. Download the API distribution package (qlapi-vx.yybuildzz-rel.tgz) from the download pages of the QLogic Web site for your Fibre Channel Adapter/Converged Network Adapter and OS (http://support.qlogic.com/support/drivers_software.aspx). NOTE: x is a major version, yy is a minor version, and zz is a build version of API. 2. If prompted "What would you like to do with this file?" choose "Save this file to disk". 3. Create a directory on the local hard drive and download the driver. 4.2 Extracting SNIA API Library Using the files you downloaded as described in Section 4.1, copy the distribution file (qlapi-vx.yybuildzz-rel.tgz) to /qlapi. Enter the following commands from the / (root) directory: # mkdir qlapi # cp qlapi-vx.yybuildzz-rel.tgz qlapi/ # cd qlapi # tar -xvzf *.tgz 4.3 Installing SNIA API Library To install and set up the API library, enter the following command in the current directory: # ./libinstall (this installs and sets up the Converged Network Adapter/Host Bus Adapter API library) 4.4 Installing on RHEL 4.x In addition to installing the SNIA API library, RHEL4.x users must load an additional kernel module, then set the system to load the module automatically at boot time. For details, see the following sections: * 4.4.1 Load Additional Kernel Module Manually * 4.4.2 Load Module Automatically at Boot Time 4.4.1 Load Additional Kernel Module Manually You must load an additional kernel module before using the API library on RHEL 4 Update 6 and above distributions. To load this module, enter the following commands: # modprobe qioctlmod # lsmod | grep qioctlmod (should show the loaded module) 4.4.2 Load Module Automatically at Boot Time To set your system to load the qioctlmod kernel module automatically during system boot, run the following commands: # echo modprobe qioctlmod >> /etc/rc.modules # chmod +x /etc/rc.modules 4.5 Uninstalling SNIA API Library To remove the API library, enter the following command in the current directory: # ./libremove (Script file to remove Host Bus Adapter API library) 4.6 Enabling Debug in API To enable debug in API, enter following command: # export QL_FCAPI_DEBUG= The following debug levels are supported by API: # QL_FCAPI_DEBUG=0x27 For SDM API debug with IOCTL-based drivers # QL_FCAPI_DEBUG=0x47 For SNIA API debug with IOCTL-based drivers # QL_FCAPI_DEBUG=0x87 For RUBAH API debug with IOCTL-based drivers # QL_FCAPI_DEBUG=0x267 For SDM and SNIA API debug with sysfs and IOCTL-based drivers # QL_FCAPI_DEBUG=0x2E7 For SDM, RUBAH, and SNIA API debug with sysfs and IOCTL-based drivers * The QL_FCAPI_DEBUG=0x267 is the recommended debug level. * The API debug log is saved in /usr/lib/libqlsdm.log file. * To redirect log messages seen on the console, redirect stderr to a log file. e.g.: ./hbaapitest 2> console_log.txt 5. Additional Notes * Fibre Channel port ID format: The QLogic-defined SDM API always returns the Fibre Channel port ID in 3-byte fields. However, the SNIA-defined Common API returns the Fibre Channel port ID in a 32-bit field. In libqlsdm v1.10 Beta+ and Linux Host Bus Adapter Driver v4.35 Beta and later, the ioctl and API implementations treat this 32-bit field as if it was an array of 4 bytes; it stores the Fibre Channel 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 low level of interest in using 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. You should ignore the value of the newly created 4 bytes at the beginning of the returned data because there 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: The Linux API library does not support any externally available NVRAM and diagnostics-related API function. QLogic plans to support these features at a later date. 6. Contacting Support Please feel free to contact your QLogic approved reseller or QLogic Technical Support at any phase of integration for assistance. QLogic Technical Support can be reached by the following methods: Web: http://support.qlogic.com E-mail: support@qlogic.com (c) Copyright 2015. All rights reserved worldwide. QLogic, the QLogic logo, and the Powered by QLogic logo are registered trademarks of QLogic Corporation. All other brand and product names are trademarks or registered trademarks of their respective owners.