SupportedHBAAPIs(3)

📦
version 3.0.3 · 5 versions
, in opensuse-leap 16.0

🦋 SupportedHBAAPIs(3) 🦋

okay so welcome to the SupportedHBAAPIs(3) page bestie 💖 this is the full rundown of every HBA API function this library has your back on. it's giving "reference manual but make it a group chat", so let's go ✨

🌸 NAME 🌸

SupportedHBAAPIs — Supported HBA API Functions. that's it, that's the name, no cap 💅

✨ SYNOPSIS ✨

🎀 Functions 🎀

  • HBA_UINT32 HBA_GetVersion (void) — returns the version of the HBA API specification that this library is compliant with 👑
  • HBA_STATUS HBA_LoadLibrary (void) — does the initialization of the library.
  • HBA_STATUS HBA_FreeLibrary (void) — frees up the system resources that the library has used.
  • HBA_STATUS HBA_RegisterLibrary (HBA_ENTRYPOINTS *pHBAInfo) — registers the functionality of FC-MI with the wrapper library.
  • HBA_STATUS HBA_RegisterLibraryV2 (HBA_ENTRYPOINTSV2 *pHBAInfo) — registers the functionality of HBA API phase 2 with the wrapper library.
  • HBA_UINT32 HBA_GetNumberOfAdapters (void) — returns the number of adapters.
  • void HBA_RefreshInformation (HBA_HANDLE handle) — refreshes the information of one adapter.
  • void HBA_RefreshAdapterConfiguration (void) — according to a discussion with Bob Nixon (editor of FC-HBA), this function has no effect in an HBA specific library 🙈
  • void HBA_ResetStatistics (HBA_HANDLE handle, HBA_UINT32 portindex) — according to FC-HBA, this function is obsolete 💀
  • HBA_STATUS HBA_GetAdapterName (HBA_UINT32 adapterindex, char *pAdaptername) — returns the name that identifies an adapter.
  • HBA_HANDLE HBA_OpenAdapter (char *pAdaptername) — opens an adapter.
  • void HBA_CloseAdapter (HBA_HANDLE handle) — closes an open adapter.
  • HBA_STATUS HBA_GetAdapterAttributes (HBA_HANDLE handle, HBA_ADAPTERATTRIBUTES *pAdapterattributes) — returns the attributes for an adapter.
  • HBA_STATUS HBA_GetAdapterPortAttributes (HBA_HANDLE handle, HBA_UINT32 portindex, HBA_PORTATTRIBUTES *pPortattributes) — returns the attributes for an adapter port.
  • HBA_STATUS HBA_GetDiscoveredPortAttributes (HBA_HANDLE handle, HBA_UINT32 portindex, HBA_UINT32 discoveredportindex, HBA_PORTATTRIBUTES *pPortattributes) — returns the attributes of a discovered port.
  • HBA_STATUS HBA_GetPortStatistics (HBA_HANDLE handle, HBA_UINT32 portindex, HBA_PORTSTATISTICS *pPortstatistics) — returns the statistics of an adapter port.
  • HBA_STATUS HBA_GetFcpTargetMapping (HBA_HANDLE handle, HBA_FCPTARGETMAPPING *pMapping) — retrieves the mappings between OS SCSI targets/units and FCP targets/units.
  • HBA_STATUS HBA_GetFcpTargetMappingV2 (HBA_HANDLE handle, HBA_WWN hbaPortWWN, HBA_FCPTARGETMAPPINGV2 *pMappingV2) — retrieves the mappings between OS SCSI targets/units and FCP targets/units. yes, again, it's the V2 glow-up 🦋
  • HBA_STATUS HBA_SendScsiInquiry (HBA_HANDLE handle, HBA_WWN PortWWN, HBA_UINT64 fcLUN, HBA_UINT8 EVPD, HBA_UINT32 PageCode, void *pRspBuffer, HBA_UINT32 RspBufferSize, void *pSenseBuffer, HBA_UINT32 SenseBufferSize) — sends a SCSI INQUIRY command to a FCP LUN.
  • HBA_STATUS HBA_ScsiInquiryV2 (HBA_HANDLE handle, HBA_WWN hbaPortWWN, HBA_WWN discoveredPortWWN, HBA_UINT64 fcLUN, HBA_UINT8 CDB_Byte1, HBA_UINT8 CDB_Byte2, void *pRspBuffer, HBA_UINT32 *pRspBufferSize, HBA_UINT8 *pScsiStatus, void *pSenseBuffer, HBA_UINT32 *pSenseBufferSize) — sends a SCSI INQUIRY command to a FCP LUN.
  • HBA_STATUS HBA_SendReportLUNs (HBA_HANDLE handle, HBA_WWN portWWN, void *pRspBuffer, HBA_UINT32 RspBufferSize, void *pSenseBuffer, HBA_UINT32 SenseBufferSize) — sends a SCSI REPORT LUNS command to a target.
  • HBA_STATUS HBA_ScsiReportLUNsV2 (HBA_HANDLE handle, HBA_WWN hbaPortWWN, HBA_WWN discoveredPortWWN, void *pRspBuffer, HBA_UINT32 *pRspBufferSize, HBA_UINT8 *pScsiStatus, void *pSenseBuffer, HBA_UINT32 *pSenseBufferSize) — sends a SCSI REPORT LUNS command to a target.
  • HBA_STATUS HBA_SendReadCapacity (HBA_HANDLE handle, HBA_WWN portWWN, HBA_UINT64 fcLUN, void *pRspBuffer, HBA_UINT32 RspBufferSize, void *pSenseBuffer, HBA_UINT32 SenseBufferSize) — sends a SCSI READ CAPACITY command to a FCP LUN.
  • HBA_STATUS HBA_ScsiReadCapacityV2 (HBA_HANDLE handle, HBA_WWN hbaPortWWN, HBA_WWN discoveredPortWWN, HBA_UINT64 fcLUN, void *pRspBuffer, HBA_UINT32 *pRspBufferSize, HBA_UINT8 *pScsiStatus, void *pSenseBuffer, HBA_UINT32 *pSenseBufferSize) — sends a SCSI READ CAPACITY command to a FCP LUN.
  • HBA_STATUS HBA_SendCTPassThru (HBA_HANDLE handle, void *pReqBuffer, HBA_UINT32 ReqBufferSize, void *pRspBuffer, HBA_UINT32 RspBufferSize) — sends a CT pass thru — a CT frame constructed in userspace going directly to the HBA / SAN 🔥
  • HBA_STATUS HBA_SendCTPassThruV2 (HBA_HANDLE handle, HBA_WWN hbaPortWWN, void *pReqBuffer, HBA_UINT32 ReqBufferSize, void *pRspBuffer, HBA_UINT32 *pRspBufferSize) — sends a CT pass thru — a CT frame constructed in userspace going directly to the HBA / SAN.
  • HBA_STATUS HBA_SendRNID (HBA_HANDLE handle, HBA_WWN wwn, HBA_WWNTYPE wwntype, void *pRspBuffer, HBA_UINT32 *pRspBufferSize) — sends a RNID ELS to a port.
  • HBA_STATUS HBA_SendRNIDV2 (HBA_HANDLE handle, HBA_WWN hbaPortWWN, HBA_WWN destWWN, HBA_UINT32 destFCID, HBA_UINT32 NodeIdDataFormat, void *pRspBuffer, HBA_UINT32 *pRspBufferSize) — sends a RNID ELS to a port.
  • HBA_STATUS HBA_GetEventBuffer (HBA_HANDLE handle, HBA_EVENTINFO *pEventBuffer, HBA_UINT32 *pEventCount) — returns events for an adapter, pulled out of the event queue 🌈

💜 Detailed Description 💜

lowkey this section is completely empty on the page — no prose, nothing, it just vibes there and hands the mic straight to the Function Documentation. iconic behaviour honestly 💅

👑 Function Documentation 👑

🫶 void HBA_CloseAdapter (HBA_HANDLE handle)

closes an open adapter. like, actually shuts it down.

Parameters

  • handle — handle of the adapter to be closed

Locks:

lock/unlock of vlib_data.mutex

the adapter handle gets invalidated, and all the info about the ports and units of this adapter is deleted 🗑️

References doCloseAdapter(), getAdapterByHandle(), vlib_adapter::handle, vlib_data::mutex, VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🫶 HBA_STATUS HBA_FreeLibrary (void )

frees the system resources that the library has used. spring cleaning bestie 🧹

Returns

  • HBA_STATUS_ERROR_NOT_LOADED if HBA_LoadLibrary was not called before.
  • HBA_STATUS_ERROR if HBA_FreeLibrary is already running.
  • HBA_STATUS_OK on success.

Locks:

lock/unlock of vlib_data.mutex

Note — this function tries to close the zfcp_hbaapi char device. 👀

References closeAllAdapters(), vlib_data::id, vlib_data::isLoaded, vlib_data::mutex, vlib_data::unloading, VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🫶 HBA_STATUS HBA_GetAdapterAttributes (HBA_HANDLE handle, HBA_ADAPTERATTRIBUTES * pAdapterattributes)

returns the attributes for an adapter. the whole personality profile, basically 🎀

Parameters

  • handle — handle of an opened adapter
  • pAdapterattributes — pointer to return atributes

Returns

  • HBA_STATUS_NOT_LOADED if the library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE if the handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE if the adapter is unavailable
  • HBA_STATUS_ERROR if any other internal error occurs
  • HBA_STATUS_OK on success

Locks:

lock/unlock of vlib_data.mutex

Note — ZFCP HBA API does not set the adapter attributes OptionROMVersion and NodeSymbolicName. so don't come for them when they're blank 🙈

References getAdapterByHandle(), vlib_adapter::handle, vlib_data::mutex, revalidateRepository(), sysfs_getAdapterAttributes(), VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🫶 HBA_STATUS HBA_GetAdapterName (HBA_UINT32 adapterindex, char * pAdaptername)

returns the name that identifies an adapter. name tag energy ✨

Parameters

  • adapterindex — index of the HBA
  • pAdaptername — used to return the ASCII string

Returns

  • HBA_STATUS_NOT_LOADED if the library is not loaded
  • HBA_STATUS_ERROR_ILLEGAL_INDEX if the index is invalid
  • HBA_STATUS_ERROR if any other internal error occurs
  • HBA_STATUS_OK on success

Locks:

lock/unlock of vlib_data.mutex

See also revalidateRepository()

References getAdapterByIndex(), vlib_adapter::isInvalid, vlib_data::mutex, revalidateRepository(), VLIB_ADAPTERNAME_LEN, VLIB_ADAPTERNAME_PREFIX, VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🫶 HBA_STATUS HBA_GetAdapterPortAttributes (HBA_HANDLE handle, HBA_UINT32 portindex, HBA_PORTATTRIBUTES * pPortattributes)

returns the attributes for an adapter port 🦋

Parameters

  • handle — handle to an opened adapter
  • portindex — index of the adapter port
  • pPortattributes — pointer to return atributes

Returns

  • HBA_STATUS_NOT_LOADED if the library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE if the handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE if the adapter is unavailable
  • HBA_STATUS_ERROR_ILLEGAL_INDEX if portindex is invalid
  • HBA_STATUS_ERROR if any other internal error occurs
  • HBA_STATUS_OK on success

Locks:

lock/unlock of vlib_data.mutex

Note — the parameter portindex must be 0, since we have only one local port on our adapters. no cap, just the one.
Additionally, this function triggers creation of port configuration for this adapter (see revalidatePorts()).
ZFCP HBA API does not set the port attributes FabricName, OSDeviceName and PortSymbolicName for an adapter port.

References getAdapterByHandle(), vlib_adapter::handle, vlib_data::mutex, revalidatePorts(), revalidateRepository(), sysfs_getAdapterPortAttributes(), VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🫶 HBA_STATUS HBA_GetDiscoveredPortAttributes (HBA_HANDLE handle, HBA_UINT32 portindex, HBA_UINT32 discoveredportindex, HBA_PORTATTRIBUTES * pPortattributes)

returns the attributes of a discovered port 👀

Parameters

  • handle — handle to an opened adapter
  • portindex — index of the adapter port
  • discoveredportindex — index of the adapter port
  • pPortattributes — pointer to return atributes

Returns

  • HBA_STATUS_NOT_LOADED if the library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE if the handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE if the adapter is unavailable
  • HBA_STATUS_ERROR_ILLEGAL_INDEX if portindex or discoveredindex is invalid
  • HBA_STATUS_ERROR if any other internal error occurs
  • HBA_STATUS_OK on success

Locks:

lock/unlock of vlib_data.mutex

Note — the parameter portindex must be 0, since we have only one local port on our adapters.
For discovered ports, ZFCP HBA API does not set the port attributes OSDeviceName, PortMaxFrameSize and PortSupportedFc4Types. PortSupportedSpeed, PortSpeed, and PortState are set to values indicating unknwon. NumberofDiscoveredPorts is 0. Most other values are determined using a GA_NXT request on the Name Server Directory Service. 💀

okay that's exactly where this part of the page runs out bestie — the discovered-port note is literally the last thing on it, and the rest of the function docs are coming right up 🔥 don't go anywhere 🌈

Okay so for PortSupportedFc4Types and PortActive Fc4Types we do not follow FC-HBA Rev 10 — we do not store them “little-endian” but “big-endian”, exactly like Editors Note 1 suggests. That’s the vibe check for this one.

References: getAdapterByHandle(), getPortByIndex(), vlib_port::isInvalid, vlib_data::mutex, revalidateRepository(), sysfs_getDiscoveredPortAttributes(), VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by: HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🦋 HBA_GetEventBuffer

HBA_STATUS HBA_GetEventBuffer (HBA_HANDLE handle, HBA_EVENTINFO * pEventBuffer, HBA_UINT32 * pEventCount)

Bestie, this one returns events for an adapter from the event queue.

Parameters:

  • handle to an opened adapter
  • *pEventBuffer pointer to return events
  • *pEventCount pointer to size of event buffer (in event records)

Returns:

  • HBA_STATUS_NOT_LOADED if library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE if adapter is unavailable
  • HBA_STATUS_ERROR if any other internal error occurs
  • HBA_STATUS_OK on success.

Locks: lock/unlock of vlib_data.mutex

References: getAdapterByHandle(), vlib_data::mutex, revalidateRepository(), VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by: HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🎀 HBA_GetFcpTargetMapping

HBA_STATUS HBA_GetFcpTargetMapping (HBA_HANDLE handle, HBA_FCPTARGETMAPPING * pMapping)

This is the one that retrieves mappings between OS SCSI targets/units and FCP targets/units.

Parameters:

  • handle to an opened adapter
  • *pMapping pointer to return target mappings

Returns:

  • HBA_STATUS_NOT_LOADED if library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE if adapter is unavailable
  • HBA_STATUS_ERROR_MORE_DATA if there is not enough space in pMapping to return complete mapping information
  • HBA_STATUS_ERROR if any other internal error occurs
  • HBA_STATUS_OK on success.

Locks: lock/unlock of vlib_data.mutex

Note: An OSDeviceName is not provided for target mappings. Additionally this function triggers creation of unit configuration for this adapter (see revalidateUnits()).

References: vlib_unit::channel, vlib_port::did, vlib_unit::fcLun, getAdapterByHandle(), getPortByIndex(), getUnitByIndex(), vlib_adapter_ident::host, vlib_adapter::ident, vlib_port::isInvalid, vlib_unit::isInvalid, vlib_unit::lun, vlib_data::mutex, vlib_adapter::ports, revalidatePorts(), revalidateRepository(), revalidateUnits(), vlib_unit::target, vlib_port::units, block::used, vlib_FCID_to_hbaFCID(), VLIB_MUTEX_LOCK, VLIB_MUTEX_UNLOCK, vlib_wwn_to_HBA_WWN(), vlib_port::wwnn, and vlib_port::wwpn.

Referenced by: HBA_GetFcpTargetMappingV2(), HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

✨ HBA_GetFcpTargetMappingV2

HBA_STATUS HBA_GetFcpTargetMappingV2 (HBA_HANDLE handle, HBA_WWN hbaPortWWN, HBA_FCPTARGETMAPPINGV2 * pMappingV2)

Same mapping energy as above — retrieve mappings between OS SCSI targets/units and FCP targets/units.

Parameters:

  • handle to an opened adapter
  • *pMapping pointer to return target mappings
  • *hbaPortWWN wwpn to identify the port on the adapter

Returns: see HBA_GetFcpTargetMapping

Locks: lock/unlock of vlib_data.mutex

Note: HBA_LUID is not provided for target mappings. Our “adapters” have only one port, so the WWN parameter is superfluous. We only check if it matches to the adapter handle, if yes, we call HBA_GetFcpTargetMapping.

References: getAdapterByHandle(), vlib_adapter::handle, HBA_GetFcpTargetMapping(), vlib_adapter::ident, vlib_data::mutex, vlib_HBA_WWN_to_wwn(), VLIB_MUTEX_LOCK, VLIB_MUTEX_UNLOCK, and vlib_adapter_ident::wwpn.

Referenced by: HBA_RegisterLibraryV2().

🌸 HBA_GetNumberOfAdapters

HBA_UINT32 HBA_GetNumberOfAdapters (void )

Returns the number of adapters. Simple as that, no cap.

Returns:

  • 0 on error or if no adapters are configured
  • number of adapters on success

Locks: lock/unlock of vlib_data.mutex

References: vlib_data::adapters, vlib_data::mutex, revalidateRepository(), block::used, VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by: HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

💜 HBA_GetPortStatistics

HBA_STATUS HBA_GetPortStatistics (HBA_HANDLE handle, HBA_UINT32 portindex, HBA_PORTSTATISTICS * pPortstatistics)

Returns statistics of an adapter port. It’s giving “numbers with lore.”

Parameters:

  • handle to an opened adapter
  • portindex index of adapter port
  • pPortstatistics pointer to return statistics

Returns:

  • HBA_STATUS_NOT_LOADED if library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE if adapter is unavailable
  • HBA_STATUS_ERROR_ILLEGAL_INDEX if portindex is invalid
  • HBA_STATUS_ERROR if any other internal error occurs
  • HBA_STATUS_OK on success.

Locks: lock/unlock of vlib_data.mutex

Note: Parameter portindex must be 0, since we have only one local port on our adapters.

References: getAdapterByHandle(), vlib_adapter::handle, vlib_data::mutex, revalidateRepository(), sysfs_getPortStatistics(), VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by: HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

⭐ HBA_GetVersion

HBA_UINT32 HBA_GetVersion (void )

Returns the version of the HBA API specification with which this library is compliant.

Returns:

  • 2 (compliant to FC-HBA)
Note: No check if library is loaded has to be performed.

References: HBAAPI_LIBRARY_VERSION.

Referenced by: HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🧚 HBA_LoadLibrary

HBA_STATUS HBA_LoadLibrary (void )

Performs initialization of the library. The setup era, basically.

Returns:

  • HBA_STATUS_ERROR_ALREADY_LOADED if this function was already called before.
  • HBA_STATUS_ERROR if initialization fails.
  • HBA_STATUS_OK on success.

Locks: lock/unlock of vlib_data.mutex

Note: This function tries to open the zfcp_hbaapi char device.

References: vlib_data::isLoaded, vlib_data::mutex, sysfs_createAndReadConfigAdapter(), VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by: HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🫶 HBA_OpenAdapter

HBA_HANDLE HBA_OpenAdapter (char * pAdaptername)

Opens an adapter. Main character moment for your adapter handle.

Parameters:

  • pAdaptername name of adapter to be opened (name was obtained by previous call to HBA_GetAdapterName())

Returns:

  • VLIB_INVALID_HANDLE on error
  • handle on success

Locks: lock/unlock of vlib_data.mutex

Note: Possible (theoretical) overflow of index values.

References: findIndexByName(), vlib_adapter::handle, vlib_data::mutex, openAdapterByIndex(), revalidateRepository(), VLIB_INVALID_HANDLE, VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by: HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🌈 HBA_RefreshInformation

void HBA_RefreshInformation (HBA_HANDLE handle)

Refresh information of an adapter. Glow-up, but for data.

Parameters:

  • handle of the adapter for which information should be refreshed.

Locks: lock/unlock of vlib_data.mutex

References: getAdapterByHandle(), vlib_adapter::handle, vlib_data::mutex, updateAdapter(), VLIB_LOG, VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by: HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

👑 HBA_RegisterLibrary

HBA_STATUS HBA_RegisterLibrary (HBA_ENTRYPOINTS * pHBAInfo)

Registers the functionality of FC-MI with the wrapper library. This is the phase 1 crew.

Parameters:

  • pHBAInfo entry points of HBA API phase 1 library functions

Returns: HBA_STATUS_OK

Note: This function is only defined if this library was built as a vendor specific library.

References: HBA_CloseAdapter(), HBA_FreeLibrary(), HBA_GetAdapterAttributes(), HBA_GetAdapterName(), HBA_GetAdapterPortAttributes(), HBA_GetDiscoveredPortAttributes(), HBA_GetEventBuffer(), HBA_GetFcpPersistentBinding(), HBA_GetFcpTargetMapping(), HBA_GetNumberOfAdapters(), HBA_GetPortAttributesByWWN(), HBA_GetPortStatistics(), HBA_GetRNIDMgmtInfo(), HBA_GetVersion(), HBA_LoadLibrary(), HBA_OpenAdapter(), HBA_RefreshInformation(), HBA_ResetStatistics(), HBA_SendCTPassThru(), HBA_SendReadCapacity(), HBA_SendReportLUNs(), HBA_SendRNID(), HBA_SendScsiInquiry(), and HBA_SetRNIDMgmtInfo().

💅 HBA_RegisterLibraryV2

HBA_STATUS HBA_RegisterLibraryV2 (HBA_ENTRYPOINTSV2 * pHBAInfo)

Registers the functionality of HBA API phase 2 with the wrapper library. The V2 sequel, and yes it ate.

Parameters:

  • pHBAInfo entry points of HBA API phase 2 library functions

Returns: HBA_STATUS_OK on success

Note: This function is only defined if this library was built as a vendor specific library.

References: _GetVendorLibraryAttributes(), HBA_CloseAdapter(), HBA_FreeLibrary(), HBA_GetAdapterAttributes(), HBA_GetAdapterName(), HBA_GetAdapterPortAttributes(), HBA_GetBindingCapability(), HBA_GetBindingSupport(), HBA_GetDiscoveredPortAttributes(), HBA_GetEventBuffer(), HBA_GetFC4Statistics(), HBA_GetFcpPersistentBinding(), HBA_GetFCPStatistics(), HBA_GetFcpTargetMapping(), HBA_GetFcpTargetMappingV2(), HBA_GetNumberOfAdapters(), HBA_GetPersistentBindingV2(), HBA_GetPortAttributesByWWN(), HBA_GetPortStatistics(), HBA_GetRNIDMgmtInfo(), HBA_GetVersion(), HBA_LoadLibrary(), HBA_OpenAdapter(), HBA_OpenAdapterByWWN(), HBA_RefreshAdapterConfiguration(), HBA_RefreshInformation(), HBA_RegisterForAdapterAddEvents(), HBA_RegisterForAdapterEvents(), HBA_RegisterForAdapterPortEvents(), HBA_RegisterForAdapterPortStatEvents(), HBA_RegisterForLinkEvents(), HBA_RegisterForTargetEvents(), HBA_RemoveAllPersistentBindings(), HBA_RemoveCallback(), HBA_RemovePersistentBinding(), HBA_ResetStatistics(), HBA_ScsiInquiryV2(), HBA_ScsiReadCapacityV2(), HBA_ScsiReportLUNsV2(), HBA_SendCTPassThru(), HBA_SendCTPassThruV2(), HBA_SendLIRR(), HBA_SendReadCapacity(), HBA_SendReportLUNs(), HBA_SendRLS(), HBA_SendRNID(), HBA_SendRNIDV2(), HBA_SendRPL(), HBA_SendRPS(), HBA_SendScsiInquiry(), HBA_SendSRL(), HBA_SetBindingSupport(), HBA_SetPersistentBindingV2(), and HBA_SetRNIDMgmtInfo().

💀 HBA_ResetStatistics

void HBA_ResetStatistics (HBA_HANDLE handle, HBA_UINT32 portindex)

According to FC-HBA this function is obsolete. This function has no effect. Literally zero effect, bestie — not a single stat gets reset.

Referenced by: HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🍓 HBA_ScsiInquiryV2

HBA_STATUS HBA_ScsiInquiryV2 (HBA_HANDLE handle, HBA_WWN hbaPortWWN, HBA_WWN discoveredPortWWN, HBA_UINT64 fcLUN, HBA_UINT8 CDB_Byte1, HBA_UINT8 CDB_Byte2, void * pRspBuffer, HBA_UINT32 * pRspBufferSize, HBA_UINT8 * pScsiStatus, void * pSenseBuffer, HBA_UINT32 * pSenseBufferSize)

Send a SCSI INQUIRY command to a FCP LUN.

Parameters

  • handle — a handle to an opened adapter
  • hbaPortWWN — the WWPN of the local adapter port
  • discoveredPortWWN — the WWPN of the target port
  • fcLUN — the FCP LUN of the unit
  • EVPD — Enhanced Vital Product Data
  • PageCode — Vital Product Data page code, used if EVPD is set
  • *pRspBuffer — pointer to the return response data
  • RspBufferSize — the size of the response buffer
  • *pSenseBuffer — pointer to return sense data on SCSI CHECK_CONDITION
  • SenseBufferSize — the size of the sense buffer

Returns

  • HBA_STATUS_NOT_LOADED — if the library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE — if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE — if the adapter is unavailable
  • HBA_STATUS_ERROR_INVALID_LUN — if there's no unit configured for the the specified fcLUN
  • HBA_STATUS_ERROR_MORE_DATA — if there's not enough space in pRspBuffer
  • HBA_STATUS_ERROR — if any other internal error occurs
  • HBA_STATUS_OK — on success ✨

Locks: it does a lock/unlock of vlib_data.mutex 🔒

Note

  • HBA_STATUS_ERROR_NOT_A_TARGET is not returned, because zfcp just deals with SCSI target ports.
  • HBA_STATUS_ERROR_TARGET_BUSY is not returned, because zfcp cannot detect SCSI command overlap situations in general.

References _HBA_SendScsiInquiry().

Referenced by HBA_RegisterLibraryV2().

💖 HBA_STATUS HBA_ScsiReadCapacityV2 (HBA_HANDLE handle, HBA_WWN hbaPortWWN, HBA_WWN discoveredPortWWN, HBA_UINT64 fcLUN, void * pRspBuffer, HBA_UINT32 * pRspBufferSize, HBA_UINT8 * pScsiStatus, void * pSenseBuffer, HBA_UINT32 * pSenseBufferSize)

Okay so this one sends a SCSI READ CAPACITY command to a FCP LUN. Iconic, lowkey essential. 👑

Parameters

  • handle — a handle to an opened adapter
  • portWWN — the WWPN of the target port
  • fcLUN — the FCP LUN of the unit
  • *pRspBuffer — pointer to the return response data
  • RspBufferSize — the size of the response buffer
  • *pSenseBuffer — pointer to return sense data on SCSI CHECK_CONDITION
  • SenseBufferSize — the size of the sense buffer

Returns

  • HBA_STATUS_NOT_LOADED — if the library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE — if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE — if the adapter is unavailable
  • HBA_STATUS_ERROR_INVALID_LUN — if there's no unit configured for the the specified fcLUN
  • HBA_STATUS_ERROR_MORE_DATA — if there's not enough space in pRspBuffer
  • HBA_STATUS_ERROR — if any other internal error occurs
  • HBA_STATUS_OK — on success 💅

Locks: lock/unlock of vlib_data.mutex 🔒

Note

  • HBA_STATUS_ERROR_NOT_A_TARGET is not returned, because zfcp just deals with SCSI target ports.
  • HBA_STATUS_ERROR_TARGET_BUSY is not returned, because zfcp cannot detect SCSI command overlap situations in general.
  • ZFCP HBA API sends READ CAPACITY via libsgutils. Sense date is not supported that way, so the sensebuffer is always NULL — no cap, that's just how it is. 🫠

References _HBA_SendReadCapacity().

Referenced by HBA_RegisterLibraryV2().

🎀 HBA_STATUS HBA_ScsiReportLUNsV2 (HBA_HANDLE handle, HBA_WWN hbaPortWWN, HBA_WWN discoveredPortWWN, void * pRspBuffer, HBA_UINT32 * pRspBufferSize, HBA_UINT8 * pScsiStatus, void * pSenseBuffer, HBA_UINT32 * pSenseBufferSize)

Sends a SCSI REPORT LUNS command to a target. Very "tell me everything you've got" energy. 💁‍♀️

Parameters

  • handle — a handle to an opened adapter
  • portWWN — the WWPN of the local port
  • discoveredPortWWN — the WWPN of the target port
  • *pRspBuffer — pointer to the return response data
  • *RspBufferSize — pointer to the size of the response buffer
  • *pSenseBuffer — pointer to return sense data on SCSI CHECK_CONDITION
  • *SenseBufferSize — pointer to the size of the sense buffer

Returns

  • HBA_STATUS_NOT_LOADED — if the library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE — if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE — if the adapter is unavailable
  • HBA_STATUS_SCSI_CHECK_CONDITION — if a SCSI CHECK_CONDITION occurs
  • HBA_STATUS_ERROR — if any other internal error occurs
  • HBA_STATUS_OK — on success 🌟

Locks: lock/unlock of vlib_data.mutex 🔒

Note

Lun Scanning only works if we have at least Lun 0 attached. In all other cases we cannot scan the Luns (yet). 😭 In addition, no SCSI sense data will be returned. The only real difference to the V1 function is the additional parameter for the local port. Since our "adapters" have only one port, we can omit it.

References _HBA_SendReportLUNs().

Referenced by HBA_RegisterLibraryV2().

🦋 HBA_STATUS HBA_SendCTPassThru (HBA_HANDLE handle, void * pReqBuffer, HBA_UINT32 ReqBufferSize, void * pRspBuffer, HBA_UINT32 RspBufferSize)

Send a CT pass thru — a CT frame constructed in userspace directly to the HBA / SAN. Literally just yeeting your own frame straight out there. 📤

Parameters

  • handle — a handle to an opened adapter
  • *pReqBuffer — pointer to the CT frame
  • ReqBufferSize — the size of the request buffer
  • *pRspBuffer — pointer to the return response data
  • RspBufferSize — the size of the response buffer

Returns

  • HBA_STATUS_NOT_LOADED — if the library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE — if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE — if the adapter is unavailable
  • HBA_STATUS_ERROR_MORE_DATA — if there's not enough space in pRspBuffer
  • HBA_STATUS_ERROR — if any other internal error occurs
  • HBA_STATUS_OK — on success 💫

Locks: lock/unlock of vlib_data.mutex 🔒

References getAdapterByHandle(), vlib_adapter::handle, vlib_data::mutex, revalidateRepository(), VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by HBA_RegisterLibrary(), HBA_RegisterLibraryV2(), and HBA_SendCTPassThruV2().

🌸 HBA_STATUS HBA_SendCTPassThruV2 (HBA_HANDLE handle, HBA_WWN hbaPortWWN, void * pReqBuffer, HBA_UINT32 ReqBufferSize, void * pRspBuffer, HBA_UINT32 * pRspBufferSize)

Same CT pass thru vibe — a CT frame constructed in userspace, sent directly to the HBA / SAN. Glow-up version with a port WWN in the mix. ✨

Parameters

  • handle — a handle to an opened adapter
  • hbaPortWWN — local port of adapter — not necessary in our case
  • *pReqBuffer — pointer to the CT frame
  • ReqBufferSize — the size of the request buffer
  • *pRspBuffer — pointer to the return response data
  • RspBufferSize — the size of the response buffer

Returns

  • HBA_STATUS_NOT_LOADED — if the library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE — if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE — if the adapter is unavailable
  • HBA_STATUS_ERROR_MORE_DATA — if there's not enough space in pRspBuffer
  • HBA_STATUS_ERROR — if any other internal error occurs
  • HBA_STATUS_OK — on success 🎉

Locks: lock/unlock of vlib_data.mutex 🔒

References vlib_adapter::handle, and HBA_SendCTPassThru().

Referenced by HBA_RegisterLibraryV2().

🧚 HBA_STATUS HBA_SendReadCapacity (HBA_HANDLE handle, HBA_WWN portWWN, HBA_UINT64 fcLUN, void * pRspBuffer, HBA_UINT32 RspBufferSize, void * pSenseBuffer, HBA_UINT32 SenseBufferSize)

Sends a SCSI READ CAPACITY command to a FCP LUN. The O.G. version, no V2 energy. 💅

Parameters

  • handle — a handle to an opened adapter
  • portWWN — the WWPN of the target port
  • fcLUN — the FCP LUN of the unit
  • *pRspBuffer — pointer to the return response data
  • RspBufferSize — the size of the response buffer
  • *pSenseBuffer — pointer to return sense data on SCSI CHECK_CONDITION
  • SenseBufferSize — the size of the sense buffer

Returns

  • HBA_STATUS_NOT_LOADED — if the library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE — if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE — if the adapter is unavailable
  • HBA_STATUS_ERROR_INVALID_LUN — if there's no unit configured for the the specified fcLUN
  • HBA_STATUS_ERROR_MORE_DATA — if there's not enough space in pRspBuffer
  • HBA_STATUS_ERROR — if any other internal error occurs
  • HBA_STATUS_OK — on success 🌈

Locks: lock/unlock of vlib_data.mutex 🔒

Note

  • HBA_STATUS_ERROR_NOT_A_TARGET is not returned, because zfcp just deals with SCSI target ports.
  • HBA_STATUS_ERROR_TARGET_BUSY is not returned, because zfcp cannot detect SCSI command overlap situations in general.
  • ZFCP HBA API sends READ CAPACITY via libsgutils. Sense date is not supported that way, so the sensebuffer is always NULL. Sir, this is a NULL. 💀

References _HBA_SendReadCapacity().

Referenced by HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🍓 HBA_STATUS HBA_SendReportLUNs (HBA_HANDLE handle, HBA_WWN portWWN, void * pRspBuffer, HBA_UINT32 RspBufferSize, void * pSenseBuffer, HBA_UINT32 SenseBufferSize)

Sends a SCSI REPORT LUNS command to a target. 👯‍♀️

Parameters

  • handle — a handle to an opened adapter
  • portWWN — the WWPN of the target port
  • *pRspBuffer — pointer to the return response data
  • RspBufferSize — the size of the response buffer
  • *pSenseBuffer — pointer to return sense data on SCSI CHECK_CONDITION
  • SenseBufferSize — the size of the sense buffer

Returns

  • HBA_STATUS_NOT_LOADED — if the library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE — if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE — if the adapter is unavailable
  • HBA_STATUS_SCSI_CHECK_CONDITION — if a SCSI CHECK_CONDITION occurs
  • HBA_STATUS_ERROR — if any other internal error occurs
  • HBA_STATUS_OK — on success ⭐

Locks: lock/unlock of vlib_data.mutex 🔒

Note

Lun Scanning only works if we have at least Lun 0 attached. In all other cases we cannot scan the Luns (yet). 🙃 In addition, no SCSI sense data will be returned.

References _HBA_SendReportLUNs().

Referenced by HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

💜 HBA_STATUS HBA_SendRNID (HBA_HANDLE handle, HBA_WWN wwn, HBA_WWNTYPE wwntype, void * pRspBuffer, HBA_UINT32 * pRspBufferSize)

Sends a RNID ELS to a port. Little hello-how-are-you packet, bestie. 👋

Parameters

  • handle — a handle to an opened adapter
  • wwn — of port to which to send RNID ELS
  • wwntype — deprecated ⚠️
  • *pRspBuffer — pointer to the return response data
  • *pRspBufferSize — pointer to the size of the response buffer

Returns

  • HBA_STATUS_NOT_LOADED — if the library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE — if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE — if the adapter is unavailable
  • HBA_STATUS_ERROR_MORE_DATA — if there's not enough space in pRspBuffer and response data is truncated
  • HBA_STATUS_ERROR — if any other internal error occurs
  • HBA_STATUS_OK — on success (LS_ACC or LS_RJT) 🔥

Locks: lock/unlock of vlib_data.mutex 🔒

References getAdapterByHandle(), vlib_data::mutex, revalidateRepository(), vlib_HBA_WWN_to_wwn(), VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

Referenced by HBA_RegisterLibrary(), HBA_RegisterLibraryV2(), and HBA_SendRNIDV2().

💅 HBA_SendRNIDV2 — send a RNID ELS

Okay so bestie, this one sends a RNID ELS to a port. The signature stays exactly like this:

HBA_STATUS HBA_SendRNIDV2 (HBA_HANDLE handle, HBA_WWN hbaPortWWN, HBA_WWN
    destWWN, HBA_UINT32 destFCID, HBA_UINT32 NodeIdDataFormat, void *
    pRspBuffer, HBA_UINT32 * pRspBufferSize)

Parameters — the original parameter blob, preserved with zero edits from me:

  • handle — handle to an opened adapter
  • hbaPortWWN — local port of adapter - not necessary in our case
  • wwn of port to which to send RNID ELS
  • wwntype — deprecated
  • *pRspBuffer — pointer to return response data
  • *pRspBufferSize — pointer to size of response buffer

Returns

  • HBA_STATUS_NOT_LOADED if library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE if adapter is unavailable
  • HBA_STATUS_ERROR_MORE_DATA if there is not enough space in pRspBuffer and response data is truncated
  • HBA_STATUS_ERROR if any other internal error occurs
  • HBA_STATUS_OK on success (LS_ACC or LS_RJT).

Locks: lock/unlock of vlib_data.mutex

Note: this function just calls the V1 version above so the new functionality offered by V2 is not supported.

References HBA_SendRNID().

Referenced by HBA_RegisterLibraryV2().

🦋 HBA_SendScsiInquiry — send a SCSI INQUIRY command to a FCP LUN

This one is literally sending a SCSI INQUIRY command to a FCP LUN. Signature, untouched:

HBA_STATUS HBA_SendScsiInquiry (HBA_HANDLE handle, HBA_WWN PortWWN,
    HBA_UINT64 fcLUN, HBA_UINT8 EVPD, HBA_UINT32 PageCode, void *
    pRspBuffer, HBA_UINT32 RspBufferSize, void * pSenseBuffer, HBA_UINT32
    SenseBufferSize)

Parameters

  • handle — handle to an opened adapter
  • PortWWN — WWPN of the target port
  • fcLUN — FCP LUN of the unit
  • EVPD — Enhanced Vital Product Data
  • PageCode — Vital Product Data page code if EVPD is set
  • *pRspBuffer — pointer to return response data
  • RspBufferSize — size of the response buffer
  • *pSenseBuffer — pointer to return sense data on SCSI CHECK_CONDITION
  • SenseBufferSize — size of the sense buffer

Returns

  • HBA_STATUS_NOT_LOADED if library is not loaded
  • HBA_STATUS_ERROR_INVALID_HANDLE if handle is invalid
  • HBA_STATUS_ERROR_UNAVAILABLE if adapter is unavailable
  • HBA_STATUS_ERROR_INVALID_LUN if there is no unit for the the specified fcLUN configured
  • HBA_STATUS_ERROR_MORE_DATA if there is not enough space in pRspBuffer
  • HBA_STATUS_SCSI_CHECK_CONDITION if a SCSI CHECK_CONDITION occurs
  • HBA_STATUS_ERROR_ARG if EVPD is neither 0 nor 1
  • HBA_STATUS_ERROR if any other internal error occurs
    • HBA_STATUS_OK on success.

Locks: lock/unlock of vlib_data.mutex

Note

  • HBA_STATUS_ERROR_NOT_A_TARGET is not returned because zfcp just deals with SCSI target ports.
  • HBA_STATUS_ERROR_TARGET_BUSY is not returned because zfcp cannot detect SCSI command overlap situations in general.
  • ZFCP HBA API sends INQUIRY as untagged if the unit is not previously registered at the SCSI mid layer. If the device is already registered there, untagged/tagged is chosen as indicated in the associated Scsi_Device structure of the unit.

And then the page says it again, slightly shorter — keeping both because details are sacred:

ZFCP HBA API sends INQUIRY as untagged if the unit is not previously registered at the mid layer. If the device is already registered there, untagged/tagged is chosen as indicated in the associated Scsi_Device structure of the unit.

References _HBA_SendScsiInquiry().

Referenced by HBA_RegisterLibrary(), and HBA_RegisterLibraryV2().

🌸 Author 🌸

Generated automatically by Doxygen for ZFCP HBA API Library from the source code. Not me, bestie — I’m just the vibe translator. 💖

Source/version/date sign-off: source is ZFCP HBA API Library, version is Version 1, page is SupportedHBAAPIs(3) — and the footer doesn’t list a separate date here, so I’m not inventing one. Periodt. 🎀

📦 where this page comes from