FC SNIA API-General Vndr. Fns.(3C) FC SNIA API-General Vndr. Fns.(3C)
NAME
HBA_GetVersion(), HBA_LoadLibrary(), HBA_FreeLibrary(),
HBA_GetNumberOfAdapters(), HBA_GetAdapterName(), HBA_OpenAdapter(),
HBA_CloseAdapter()
SYNOPSIS
HBA_UINT32 HBA_GetVersion (
void
);
HBA_STATUS HBA_LoadLibrary (
void
);
HBA_STATUS HBA_FreeLibrary (
void
);
HBA_UINT32 HBA_GetNumberOfAdapters (
void
);
HBA_STATUS HBA_GetAdapterName (
HBA_UINT32 adapter_index,
char * adapter_name
);
HBA_HANDLE HBA_OpenAdapter (
char * adapter_name
);
void HBA_CloseAdapter (
HBA_HANDLE handle
);
DESCRIPTION
HBA_GetVersion()
This function returns the version of the FC SNIA API this library
conforms to.
HBA_LoadLibrary()
This function loads the HBA libraries which have a valid entry in
the " /etc/hba.conf " file. This function must be called before
calling any other HBA library functions.
HBA_FreeLibrary()
This function frees the HBA vendor libraries loaded during a call
to HBA_LoadLibrary(). The only function in the library that may
be called once this has been called is HBA_LoadLibrary().
Hewlett-Packard Company - 1 - HP-UX Release 11i : December 2001
FC SNIA API-General Vndr. Fns.(3C) FC SNIA API-General Vndr. Fns.(3C)
HBA_GetNumberOfAdapters()
This function returns the current number of HBAs supported by the
library.
HBA_GetAdapterName()
This function is used to obtain the name of the adapter supported
by the library whose index is adapter_index. The text string
(pointed to by adapter_name) describes the adapter. This string
is used to open the adapter within the library and is of the
form: mfgdomain-model-adapter_index and is allocated by the
application calling this function. The valid range of
adapter_index is from 0 to 1 less than the value returned by
HBA_GetNumberOfAdapters().
HBA_OpenAdapter()
This function opens a named adapter. By opening the adapter, an
application is ensuring that all access to the HBA_HANDLE (Refer
to FC MI Revision 1.6) between an open and a close is to the same
adapter. A call to HBA_OpenAdapter() does not necessarily imply a
driver "open" and this is vendor implementation dependent.
adapter_name is a textual description of an adapter as retrieved
from a call to HBA_GetAdapterName().
HBA_CloseAdapter()
This function closes an open adapter. handle is of type
HBA_HANDLE (Refer to FC MI Revision 1.6) and is obtained for an
adapter by calling HBA_OpenAdapter().
WARNINGS
This implementation of the FC SNIA HBA API enforces a calling order as
follows:
1. HBA_FreeLibrary() should be called only after all open adapters
have been fully closed.
2. An adapter shall be deemed fully closed only when for every
successful HBA_OpenAdapter(), a HBA_CloseAdapter() has been called.
3. Every HBA_FreeLibrary() should be called only after a corresponding
HBA_LoadLibrary() is called.
4. Between two calls to HBA_LoadLibrary() a call to HBA_FreeLibrary()
must be made.
5. HBA_GetNumberOfAdapters() should be called only after
HBA_LoadLibrary() has been called.
6. HBA_GetAdapterName() should be called for any adapter only after
HBA_GetNumberOfAdapters() has been called atleast once.
7. HBA_OpenAdapter() should be called for an adapter only after
HBA_GetAdapterName() has been called atleast once for the same
Hewlett-Packard Company - 2 - HP-UX Release 11i : December 2001
FC SNIA API-General Vndr. Fns.(3C) FC SNIA API-General Vndr. Fns.(3C)
adapter.
RETURN VALUES
HBA_GetVersion() returns:
1 which is the version of the API
to which this library conforms
to. No other return value is
currently valid.
HBA_LoadLibrary() returns:
HBA_STATUS_OK when the library has been
loaded properly.
HBA_STATUS_ERROR_BUSY when the library is busy
processing a call that cannot
be executed concurrently with
other calls and may be
modifying internal data
structures.
HBA_STATUS_ERROR when there is a problem with
loading.
HBA_FreeLibrary() returns:
HBA_STATUS_OK when the library was able to
free all resources.
HBA_STATUS_ERROR_BUSY when the library is busy
processing a call that cannot
be executed concurrently with
other calls and may be
modifying internal data
structures.
HBA_STATUS_ERROR when there is a problem with
freeing resources.
If HBA_GetNumberOfAdapters() returns
0, thethe errno variable is set to one of the following listed values:
ENODEV When number of adapters in the system is 0
EBUSY When the library is busy processing another call
EILSEQ When there is an out of order call
EMFILES When there are too many open files
EIO When there is an internal error
Any other return value gives the number of adapters identified by this
library.
Hewlett-Packard Company - 3 - HP-UX Release 11i : December 2001
FC SNIA API-General Vndr. Fns.(3C) FC SNIA API-General Vndr. Fns.(3C)
HBA_GetAdapterName() returns:
HBA_STATUS_OK on success.
HBA_STATUS_ERROR_ARG when the pointer passed to this
function is NULL.
HBA_STATUS_ERROR_BUSY when the library is busy
processing a call that cannot
be executed concurrently with
other calls and may be
modifying internal data
structures.
HBA_STATUS_ERROR_ILLEGAL_INDEX when the adapter_index passed
is not valid.
HBA_STATUS_ERROR when an internal error has
occured.
HBA_OpenAdapter() returns:
0 when there is a problem in opening the adapter. In this case the
errno is set to one of the following listed values:
ENIVAL When an invalid argument is passed.
EBUSY When the library is busy processing another call
EILSEQ When there is an out of order call
EMXIO When an adapter is unavailable
EACCES When there is a file open error
EIO When there is an internal error
A non-zero value is a valid handle to the adapter.
EXAMPLES
HBA_GetVersion()
HBA_UINT32 version;
version = HBA_GetVersion();
printf("Running version %u of the HBA API library.", version);
HBA_LoadLibrary()
HBA_STATUS status;
status = HBA_LoadLibrary();
if (status == HBA_STATUS_OK) {
printf("Successfully loaded HBA library.\n");
}
HBA_FreeLibrary()
HBA_STATUS status;
status = HBA_FreeLibrary();
Hewlett-Packard Company - 4 - HP-UX Release 11i : December 2001
FC SNIA API-General Vndr. Fns.(3C) FC SNIA API-General Vndr. Fns.(3C)
if (status == HBA_STATUS_OK) {
printf("Successfully freed HBA library.\n");
}
HBA_GetNumberOfAdapters()
HBA_UINT32 version;
int i;
HBA_STATUS status;
char adapter_name[256];
number_of_adapters = HBA_GetNumberOfAdapters();
for (i = 0; i < number_of_adapters; i++) {
status = HBA_GetAdapterName(i, adapter_name);
if (status == HBA_STATUS_OK) {
printf("Adapter %d is named %s\r\n", i, adapter_name);
}
}
HBA_GetAdapterName()
HBA_UINT32 version;
int i;
HBA_STATUS status;
char adapter_name[256];
number_of_adapters = HBA_GetNumberOfAdapters();
for (i = 0; i < number_of_adapters; i++) {
status = HBA_GetAdapterName(i, &adapter_name);
if (status == HBA_STATUS_OK) {
printf("Adapter %d is named %s\r\n", i, adapter_name);
}
}
HBA_OpenAdapter()
int i;
HBA_STATUS status;
HBA_HANDLE adapterhandle;
char adapter_name[256];
number_of_adapters = HBA_GetNumberOfAdapters();
for (i = 0; i < number_of_adapters; i++) {
status = HBA_GetAdapterName (i, &adapter_name);
if (status == HBA_STATUS_OK) {
adapterhandle = HBA_OpenAdapter(adapter_name);
if (adapterhandle != 0) {
printf("Successfully opened %s\r\n",
adapter_name);
HBA_CloseAdapter(adapterhandle);
}
}
}
HBA_CloseAdapter()
adapterhandle = HBA_OpenAdapter(adapter_name);
if (adapterhandle != 0) {
Hewlett-Packard Company - 5 - HP-UX Release 11i : December 2001
FC SNIA API-General Vndr. Fns.(3C) FC SNIA API-General Vndr. Fns.(3C)
printf ("Successfully opened %s\r\n", adapter_name);
HBA_CloseAdapter(adapterhandle);
}
FILES
/usr/include/snia_common.h
Contains the related data structures and definitons as in FC MI
Revision 1.6.
AUTHOR
Hewlett-Packard Company
SEE ALSO
HBAAPI(3C), HBA_GetAdapterAttributes(3C),
HBA_GetAdapterPortAttributes(3C), HBA_GetPortStatistics(3C),
HBA_GetDiscoveredPortAttributes(3C), HBA_GetPortAttributesByWWN(3C),
HBA_SendCTPassThru(3C), HBA_GetEventBuffer(3C),
HBA_SetRNIDMgmtInfo(3C), HBA_GetRNIDMgmtInfo(3C), HBA_SendRNID(3C),
HBA_GetFcpTargetMapping(3C), HBA_GetFcpPersistentBinding(3C),
HBA_SendScsiInquiry(3C), HBA_SendReportLUNs(3C),
HBA_SendReadCapacity(3C), HBA_RefreshInformation(3C),
HBA_ResetStatistics(3C)
Hewlett-Packard Company - 6 - HP-UX Release 11i : December 2001
|
