zfcp-hbaapi: A Shell repository from Open Mainframe Project

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

This is lib-zfcp-hbaapi (zfcp HBA API library) Version 2.2.0. 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 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: yes
	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-2.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).
openmainframeproject/zfcp-hbaapi
