lib-zfcp-hbaapi
===============

DESCRIPTION
-----------

This is lib-zfcp-hbaapi (zfcp HBA API library) Version 3.0.2. It is part of an
implementation of FC-HBA for the ZFCP device driver.

The zfcp device driver is a FCP device driver for Linux on System z.
The whole implementation of FC-HBA for the zfcp device driver is called zfcp
HBA API. It is a shared library which provides the API defined in FC-HBA.

- Version 3.0.2 contains small updates for building.
- Version 3.0.1 contains small updates for building.
- Version 3.0.0 re-licenses lib-zfcp-hbaapi to EPL-1.0.
- Version 2.2.0 contains additional port speed capabilities.
- Version 2.1.1 contains bugfixes and minor adaptations to build in recent Linux
environments.
- Version 2.1 extends version 2.0 with some additional features and
two utilities (zfcp_ping, zfcp_show). These utilities are useful to discover
a storage area network (SAN). Refer to the respective man-pages for
further details.
- Version 2.0 is a complete re-implementation.
- Version 1.4 of lib-zfcp-hbaapi did not have a shared version of the library;
libzfcphbaapi was linked statically against the san_disc tool.  With Version 2,
the shared version of the library is available again.
The device file for the communication with the zfcp kernel module is not needed
any more. The only interfaces utilized now are the sysfs and the generic scsi
devices.

REQUIREMENTS
------------

Software:

- libsgutils
- doxygen for developer documentation
- Linux Kernel 2.6.27 (or later)
- Linux kernel 2.6.36 (or later) required for event triggers.

Hardware:

- The zfcp HBA API support was first available on IBM eServer zSeries 990
processors with a microcode level (MCL) that includes the enhancements of
October 31, 2003. Please ensure to use the latest available microcode level.
- All newer models are supported.

INSTALLATION
------------

The package doxygen is required for the complete build of the sources.

Generic installation instructions are given in file INSTALL.
To build and install lib-zfcp-hbaapi, use the following steps:

    ./configure
    make
    make docs
    make install

Configuration options:

    --enable-backtrace=yes|no    default: no
        Enable backtrace printing on mutex errors.

    --enable-vendor-lib=yes|no    default: no
        Builds the library as a vendor specific library to be used with the
        common SNIA library (see http://hbaapi.sourceforge.net). All entry
        points will be in the common library (libHBAAPI.so) and the
        common library header file (hbaapi.h) needs to be used.
        If the common library is not available, libzfcphbaapi can be built
        standalone, enabling applications to directly link against
        libzfcphbaapi.so (--enable-vendor-lib=no)
        In that case, an own copy of hbaapi.h will be installed.

    --enable-debug=yes|no        default: no
        Enable debug information.

    --enable-docs=yes|no        default: yes
        Builds additional developer documentation and man pages via doxygen
        which will be installed as well.

lib-zfcp-hbaapi installs by default in `/usr/local/lib`. The HBA API
header file is installed in `/usr/local/include` (only if compiled with
`--enable-vendor-lib=no`, otherwise no header file will be installed) and
documentation is installed in `/usr/local/share/zfcp-hbaapi-3.x`.

The library is named `libzfcphbaapi.so`. The HBA API header file is
named `hbaapi.h` and should be included by applications that link
against `libzfcphbaapi.so`. The header file will be supplied by the SNIA HBA API
(see http://hbaapi.sourceforge.net) or by lib-zfcp-hbaapi, see paragraph above.

CLEANING UP
-----------

The following steps describe how to remove files that were generated during the
build process.

    make clean
        Deletes all object files an the doxygen documentation

    make distclean
        Deletes all files generated during compilation

    make maintainer-clean-local
        Deletes all files generated by the autotools. To generate them again,
        run "./bootstrap"

SUPPORTED FUNCTIONS
-------------------

    HBA_GetVersion
    HBA_LoadLibrary
    HBA_FreeLibrary
    HBA_RegisterLibrary
    HBA_RegisterLibraryV2
    HBA_GetNumberOfAdapters
    HBA_RefreshInformation
    HBA_RefreshAdapterConfiguration
    HBA_GetAdapterName
    HBA_OpenAdapter
    HBA_CloseAdapter
    HBA_GetAdapterAttributes
    HBA_GetAdapterPortAttributes
    HBA_GetDiscoveredPortAttributes
    HBA_GetPortStatistics
    HBA_GetFcpTargetMapping
    HBA_GetFcpTargetMappingV2
    HBA_SendScsiInquiry
    HBA_SendReportLUNs
    HBA_ScsiReportLUNsV2
    HBA_SendCTPassThru
    HBA_SendCTPassThruV2
    HBA_GetRNIDMgmtInfo
    HBA_SendRNID
    HBA_SendRNIDV2
    HBA_GetEventBuffer


For more information see man page `libzfcphbaapi(3)`, and refer to the
'Device Drivers, Features, and Commands' manual on
https://www.ibm.com/docs/en/linux-on-systems?topic=overview-device-drivers-features-commands

<!-- vim: set syntax=markdown ft=markdown: -->
