FC SNIA API-Informational Fns.(3C) FC SNIA API-Informational Fns.(3C)
NAME
HBA_GetAdapterAttributes(), HBA_GetAdapterPortAttributes(),
HBA_GetPortStatistics(), HBA_GetDiscoveredPortAttributes(),
HBA_GetPortAttributesByWWN()
SYNOPSIS
HBA_STATUS HBA_GetAdapterAttributes (
HBA_HANDLE handle,
PHBA_ADAPTERATTRIBUTES *adapter_attributes
);
HBA_STATUS HBA_GetAdapterPortAttributes (
HBA_HANDLE handle,
HBA_UINT32 port_index,
HBA_PORTATTRIBUTES *port_attributes
);
HBA_STATUS HBA_GetPortStatistics (
HBA_HANDLE handle,
HBA_UINT32 port_index,
HBA_PORTSTATISTICS *port_statistics
);
HBA_STATUS HBA_GetDiscoveredPortAttributes (
HBA_HANDLE handle,
HBA_UINT32 port_index,
HBA_UINT32 discovered_port_index,
HBA_PORTATTRIBUTES *port_attributes
);
HBA_STATUS HBA_GetPortAttributesByWWN (
HBA_HANDLE handle,
HBA_WWN port_wwn,
HBA_PORTATTRIBUTES *port_attributes
);
DESCRIPTION
HBA_GetAdapterAttributes()
This function retrieves the attributes for the adapter. The
argument handle is of type HBA_HANDLE (Refer to FC MI Revision
1.6) and is obtained through a call to HBA_OpenAdapter(). The
argument adapter_attributes is a pointer to a structure of type
HBA_ADAPTER_ATTRIBUTES which includes:
Manufacturer
SerialNumber
Model
ModelDescription
NodeWWN
NodeSymbolicName
Hewlett-Packard Company - 1 - HP-UX Release 11i : December 2001
FC SNIA API-Informational Fns.(3C) FC SNIA API-Informational Fns.(3C)
HardwareVersion
DriverVersion
OptionROMVersion
FirmwareVersion
vendorSpecificID
NumberOfPorts
DriverName
NOTE:
All string attributes that are not supported by HP's vendor
library implementation will set the string attribute to the value
Not Supported.
HBA_GetAdapterPortAttributes()
This function retrieves the attributes for a specified port on
the adapter. The argument handle is of type HBA_HANDLE (Refer to
FC MI Revision 1.6) and is obtained through a call to
HBA_OpenAdapter(). The argument port_index corresponds to index
(this ranges from 0 to 1 less than the NumberOfPorts returned
from HBA_GetAdapterAttributes()) of the port which needs to be
queried. The argument port_attributes is a pointer to a structure
of type HBA_PORTATTRIBUTES which includes:
NodeWWN
PortWWN
PortFcId
PortType
PortState
PortSupportedClassofService
PortSupportedFc4Types
PortActiveFc4Types
OSDeviceName
PortSpeed
NumberofDiscoveredPorts
PortSymbolicName
PortSupportedSpeed
PortMaxFrameSize
FabricName
NOTE:
All string attributes that are not supported by HP's vendor
library implementation will set the string attribute to the value
Not Supported
HBA_GetPortStatistics()
This function retrieves the statistics for a specified port on
the adapter. The events being considered for statistics is vendor
dependent. LinkFailureCount, LossOfSyncCount, LossOfSignalCount,
PrimitiveSeqProtocolErrCount, InvalidTxWordCount, and
InvalidCRCCount are the values that are maintained by the port in
its Link Error Status Block (see FC-FS). The argument handle is
of type HBA_HANDLE (Refer to FC MI Revision 1.6) and is obtained
Hewlett-Packard Company - 2 - HP-UX Release 11i : December 2001
FC SNIA API-Informational Fns.(3C) FC SNIA API-Informational Fns.(3C)
through a call to HBA_OpenAdapter(). The argument port_index
corresponds to index of the port (this ranges from 0 to
(NumberOfPorts returned from HBA_GetAdapterAttributes() - 1) to
query. The argument port_statistics is a pointer to a structure
of type HBA_PORTSTATISTICS which includes:
SecondsSinceLastReset
TxFrames
TxWords
RxFrames
RxWords
LIPCount
NOSCount
ErrorFrames
DumpedFrames
LinkFailureCount
LossOfSyncCount
LossOfSignalCount
PrimitiveSeqProtocolErrCount
InvalidTxWordCount
InvalidCRCCount
NOTE:
If an HBA does not support a specific statistic it will return an
All-Ones unsigned integer.
HBA_GetDiscoveredPortAttributes()
This function retrieves the attributes for a specified port
discovered in the network. The argument handle is of type
HBA_HANDLE (Refer to FC MI Revision 1.6) and is obtained through
a call to HBA_OpenAdapter(). The argument port_index corresponds
to index of the port which needs to be queried. The argument
discovered_port_index corresponds to the index of the discovered
port (Ranges from 0 to 1 less than NumberOfDiscoveredPorts value
from HBA_GetAdapterPortAttributes()) which needs to be queried.
The argument port_attributes is a pointer to a structure of type
HBA_PORTATTRIBUTES which includes:
NodeWWN
PortWWN
PortFcId
PortType
PortState
PortSupportedClassofService
PortSupportedFc4Types
PortActiveFc4Types
OSDeviceName
PortSpeed
NumberofDiscoveredPorts
PortSymbolicName
PortSupportedSpeed
PortMaxFrameSize
FabricName
Hewlett-Packard Company - 3 - HP-UX Release 11i : December 2001
FC SNIA API-Informational Fns.(3C) FC SNIA API-Informational Fns.(3C)
NOTE:
1. NumberOfDiscoveredPorts is always 0 for discovered port
attributes.
2. HP's vendor library implementation returns
HBA_PORTSPEED_UNKNOWN for PortSpeed and PortSupportedSpeed
attributes for all remote ports.
3. All string attributes that are not supported by HP's vendor
library implementation will set the string attribute to the value
Not Supported.
HBA_GetPortAttributesByWWN()
This function retrieves the attributes for a specific discovered
port by WWN (World Wide Name). The argument handle is of type
HBA_HANDLE (Refer to FC MI Revision 1.6) and is obtained through
a call to HBA_OpenAdapter(). The argument port_index corresponds
to index of the port which needs to be queried. The argument
port_attributes is a pointer to a structure of type
HBA_PORTATTRIBUTES which includes:
NodeWWN
PortWWN
PortFcId
PortType
PortState
PortSupportedClassofService
PortSupportedFc4Types
PortActiveFc4Types
OSDeviceName
PortSpeed
NumberofDiscoveredPorts
PortSymbolicName
PortSupportedSpeed
PortMaxFrameSize
FabricName
NOTE:
1. NumberOfDiscoveredPorts is always 0 for discovered port
attributes.
2. HP's vendor library implementation returns
HBA_PORTSPEED_UNKNOWN for PortSpeed and PortSupportedSpeed
attributes for all remote ports.
3. All string attributes that are not supported by HP's vendor
library implementation will set the string attribute to the value
Not Supported.
WARNINGS
This implemention of the FC SNIA HBA API enforces a calling order as
follows:
Hewlett-Packard Company - 4 - HP-UX Release 11i : December 2001
FC SNIA API-Informational Fns.(3C) FC SNIA API-Informational Fns.(3C)
1. HBA_GetAdapterPortAttributes()/ HBA_GetPortStatistics() should be
called only after a call to HBA_GetAdapterAttributes() for the
same adapter is made.
2. HBA_GetDiscoveredPortAttributes() should be called only after a
call to HBA_GetAdapterPortAttributes() for the same adapter and
port has been made.
3. HBA_GetPortAttributesByWWN() should be called only after a call
to HBA_GetDiscoveredPortAttributes() for any port on the same
adapter.
RETURN VALUES
HBA_GetAdapterAttributes(), HBA_GetAdapterPortAttributes(),
HBA_GetPortStatistics(), HBA_GetDiscoveredPortAttributes() and
HBA_GetPortAttributesByWWN() return the following values in common:
HBA_STATUS_OK on success.
HBA_STATUS_ERROR when a internal error is
detected.
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_INVALID_HANDLE when the handle passed to this
function is invalid.
HBA_STATUS_ERROR_ARG when the pointer passed to this
function is NULL.
HBA_STATUS_ERROR_UNAVAILABLE when the adapter to which the
handle corresponds is not
available.
In addition to the above listed errors,
HBA_GetAdapterPortAttributes(), HBA_GetPortStatistics(), and
HBA_GetDiscoveredPortAttributes() return
HBA_STATUS_ERROR_ILLEGAL_INDEX when the port_index is invalid.
Also, HBA_GetPortAttributesByWWN() returns the following error values
in addition to the above listed common errors:
HBA_STATUS_ERROR_ILLEGAL_INDEX when the port_index is invalid.
HBA_STATUS_ERROR_ILLEGAL_WWN when the WWN given as input
does not match the WWN of any
discovered port.
EXAMPLES
Hewlett-Packard Company - 5 - HP-UX Release 11i : December 2001
FC SNIA API-Informational Fns.(3C) FC SNIA API-Informational Fns.(3C)
HBA_GetAdapterAttributes()
HBA_STATUS status;
HBA_ADAPTERATTRIBUTES adapter_attributes;
status = HBA_GetAdapterAttributes(adapter_handle,
&adapter_attributes);
if (status == HBA_STATUS_OK) {
printf("Manufacturer: %s\r\n",
adapter_attributes.Manufacturer);
printf("Serial Number: %s\r\n",
adapter_attributes.SerialNumber);
}
HBA_GetAdapterPortAttributes()
HBA_STATUS status;
HBA_ADAPTERATTRIBUTES adapter_attributes;
HBA_PORTATTRIBUTES port_attributes;
status = HBA_GetAdapterAttributes(adapter_handle,
&adapter_attributes);
if (status == HBA_STATUS_OK) {
for (i = 0; i < adapter_attributes.NumberOfPorts; i++) {
status =
HBA_GetAdapterPortAttributes(adapter_handle, i,
&port_attributes);
if (status == HBA_STATUS_OK) {
printf("Port %u has a Port FcID of %ld\n",
i, port_attributes.PortFcId);
}
}
}
HBA_GetPortStatistics()
HBA_STATUS status;
HBA_PORTSTATISTICS port_statistics;
status = HBA_GetPortStatistics(adapter_handle, port_index,
&port_statistics);
if (status == HBA_STATUS_OK) {
printf("Port %u has sent %u frames.\n", port_index,
port_statistics.TxFrames);
}
HBA_GetDiscoveredPortAttributes()
HBA_STATUS status;
HBA_PORTATTRIBUTES port_attributes;
/* Get the attributes for the first discovered port on first
adapter port */
status = HBA_GetDiscoveredPortAttributes(handle, 0, 0,
&port_attributes);
if (status == HBA_STATUS_OK) {
printf("Discovered Port 0 on Adapter Port 0 has a Port
FcID of %u\n", port_attributes.PortFcId);
}
Hewlett-Packard Company - 6 - HP-UX Release 11i : December 2001
FC SNIA API-Informational Fns.(3C) FC SNIA API-Informational Fns.(3C)
HBA_GetPortAttributesByWWN()
HBA_STATUS status;
HBA_PORTATTRIBUTES port_attributes;
status = HBA_GetPortAttributesByWWN(handle, wwn,
&port_attributes);
if (status == HBA_STATUS_OK) {
printf("Discovered has a Port FcID of %u0,
port_attributes.PortFcId);
}
FILES
/usr/include/snia_common.h Contains the related data structures and
definitions as in FC MI Revision 1.6.
AUTHOR
Hewlett-Packard Company
SEE ALSO
HBAAPI(3C), HBA_GetVersion(3C), HBA_LoadLibrary(3C),
HBA_FreeLibrary(3C), HBA_GetNumberOfAdapters(3C),
HBA_GetAdapterName(3C), HBA_OpenAdapter(3C), HBA_CloseAdapter(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 - 7 - HP-UX Release 11i : December 2001
|
