vlib_aux.h File Reference

Auxiliary functions used in the library. More...

`#include "vlib.h"`

Go to the source code of this file.

## Functions

struct vlib_adapter * | getAdapterByIndex (uint32_t)
| Get an adapter by its index.
struct vlib_adapter * | getAdapterByHandle (HBA_HANDLE, HBA_STATUS *)
| Get an adapter by its handle.
struct vlib_adapter * | getAdapterByDevid (devid_t)
| Get an adapter by its devid.
struct vlib_adapter * | getAdapterByHostNo (unsigned short)
| Get an adapter by SCSI Host number as in sysfs.
struct vlib_port * | getPortByIndex (const struct vlib_adapter *, const uint32_t)
| Get a port by its index.
struct vlib_port * | getPortByWWPN (const struct vlib_adapter *, const wwn_t)
| Get a port by its WWPN.
struct vlib_unit * | getUnitByIndex (const struct vlib_port *, const uint32_t)
| Get an unit by its index.
struct vlib_unit * | getUnitByFcLun (const struct vlib_port *, uint64_t)
| Get an unit by its fclun.
int | addAdapterToRepos (struct vlib_adapter *)
| Add an adapter to the repository.
int | addPortToRepos (struct vlib_adapter *, struct vlib_port *)
| Add a port from to the repository.
int | addUnitToRepos (struct vlib_port *, struct vlib_unit *)
| Add a unit to the repository.
int | findIndexByName (char *)
| Find an adapter index by name.
HBA_HANDLE | openAdapterByIndex (HBA_UINT32)
| Open an adapter by index.
char * | getSgDevFromPort (struct vlib_port *)
| Get the first sg device from an adapter.
char * | getAttachedWLUN (struct vlib_adapter *, struct vlib_port *)
| Try to attach the report luns wlun and return its name as in "/dev".
void | detachWLUN (struct vlib_adapter *, struct vlib_port *)
| Try to detach lun 0.
int | revalidateAdapters (void)
| Revalidate adapters in the repository.
int | updateAdapter (struct vlib_adapter *adapter)
| Update information about ports and units of an adapter.
void | doCloseAdapter (struct vlib_adapter *)
| Close an adapter in the repository.
void | closeAllAdapters (void)
| Close all adapters in the repository.
HBA_PORTTYPE | vlibCharToIntPortType (char *)
| Map the result of a port type string from sysfs to an int.
HBA_PORTSTATE | vlibCharToIntPortState (char *)
| Map the result of a port state string from sysfs to an int.
HBA_PORTSPEED | vlibCharToIntPortSpeed (char *)
| Map the result of a port speed string to the HBA_PORTSPEED int.
HBA_COS | vlibCharToIntCOS (char *)
| Map the result of a class of service string to an int.
static void | vlib_wwn_to_HBA_WWN (uint64_t wwn, HBA_WWN *hba)
| Convert uint64_t to HBA_WWN – hide ill-favoured type cast.
static void | vlib_HBA_WWN_to_wwn (HBA_WWN *hba, uint64_t *wwn)
| Convert HBA_WWN to uint64_t – hide ill-favoured type cast.
static uint32_t | vlib_FCID_to_hbaFCID (uint32_t fcid)
| Convert a FC DID to a FC-HBA PortFcId.
static uint32_t | vlib_hbaFCID_to_FCID (uint32_t fcid)
| Convert a FC-HBA PortFcId to a FC DID.
static void | invalidateAllAdapters (void)
| Mark all adapters in repository as invalid.
static void | markRepositoryInvalid (void)
| Mark repositroy of library as invalid. This is appropriate if a loss of events is detected.

## Detailed Description

Auxiliary functions used in the library.

## Function Documentation

## addAdapterToRepos()

int addAdapterToRepos | ( | struct vlib_adapter * | adapter | ) |

Add an adapter to the repository.

Parameters

  *adapter | adapter

Returns
  - -1 on error
  - 0 on success

Locks:
  vlib_data.mutex must be held

If the adapter specified in the event is already stored in the repository it is marked as valid.

References vlib_data::adapters, block_addItem(), vlib_adapter_ident::bus_dev_name, vlib_adapter_ident::class_dev_name, vlib_adapter_ident::devid, getAdapterFromRepos(), vlib_adapter::handle, vlib_adapter_ident::host, vlib_adapter::ident, vlib_adapter::isInvalid, vlib_adapter_ident::sysfsPath, VLIB_INVALID_HANDLE, vlib_adapter_ident::wwnn, and vlib_adapter_ident::wwpn.

Referenced by addAdapterByDevPath().

## addPortToRepos()

int addPortToRepos | ( | struct vlib_adapter * | adapter,
|  | struct vlib_port * | port
| ) |  |

Add a port from to the repository.

Parameters

  *adapter | to which the port data should be added, if NULL is passed the adapter should be identified by the data in the event
  *port | port to be added

Returns
  - -1 on error
  - 0 on success

Locks:
  vlib_data.mutex must be held

If the port specified in the event is already stored in the repository it is marked as valid.

References block_addItem(), vlib_port::channel, vlib_port::did, getPortFromRepos(), vlib_port::host, vlib_port::isInvalid, vlib_port::name, vlib_adapter::ports, vlib_port::target, vlib_port::wwnn, and vlib_port::wwpn.

Referenced by addPortByName().

## addUnitToRepos()

int addUnitToRepos | ( | struct vlib_port * | port,
|  | struct vlib_unit * | unit
| ) |  |

Add a unit to the repository.

Parameters

  *port | to which the unit data should be added, if NULL is passed the port should be identified by the data in the event
  *unit | unit to be aded

Returns
  - -1 on error
  - 0 on success

Locks:
  vlib_data.mutex must be held

If the unit specified in the event is already stored in the repository it is marked as valid.

References block_addItem(), getUnitFromRepos(), vlib_unit::isInvalid, and vlib_port::units.

Referenced by sysfs_getUnitsFromPort().

## closeAllAdapters()

void closeAllAdapters | ( | void |  | ) |

Close all adapters in the repository.

Locks:
  vlib_data.mutex must be held

This function frees all allocated memory for the adapters.

References vlib_data::adapters, block_free(), doCloseAdapter(), getAdapterByIndex(), and block::used.

Referenced by HBA_FreeLibrary().

## detachWLUN()

void detachWLUN | ( | struct vlib_adapter * | adapter,
|  | struct vlib_port * | port
| ) |  |

Try to detach lun 0.

Parameters

  adapter* | Pointer to an adapter
  port* | Pointer to a port

Note
  This function issues a system call to detach lun0

References vlib_adapter_ident::bus_dev_name, vlib_unit::channel, getUnitByIndex(), vlib_unit::host, vlib_adapter::ident, REPORTLUNS_WLUN, revalidateUnits(), vlib_unit::target, and vlib_port::wwpn.

Referenced by _HBA_SendReportLUNs().

## doCloseAdapter()

void doCloseAdapter | ( | struct vlib_adapter * | adapter | ) |

Close an adapter in the repository.

Parameters

  *adapter | pointer to the adapter to be closed

Locks:
  vlib_data.mutex must be held

This function frees all allocated memory for the ports and units of this adapter and invalidates the adapter handle.

References block_free(), getPortByIndex(), vlib_adapter::handle, vlib_adapter::ports, vlib_port::units, block::used, and VLIB_INVALID_HANDLE.

Referenced by closeAllAdapters(), HBA_CloseAdapter(), and revalidateAdapters().

## findIndexByName()

int findIndexByName | ( | char * | name | ) |

Find an adapter index by name.

Parameters

  name | the name of the adapter

Returns
  - -1 on error.
  - index of adapter on success @parm Locks: vlib_data.mutex must be held

Note
  If adapter.isInvalid we do not return an adapter index - although the name might be generated. At the moment this is not an issue, because currently this flag is not really set for adapters within configured within zfcp. But it might be an issue in the future, if adapters can be removed from within zfcp.

References vlib_data::adapters, getAdapterByIndex(), vlib_adapter::isInvalid, block::used, VLIB_ADAPTERNAME_LEN, and VLIB_ADAPTERNAME_PREFIX.

Referenced by HBA_OpenAdapter().

## getAdapterByDevid()

struct vlib_adapter * getAdapterByDevid | ( | devid_t | devid | ) |

Get an adapter by its devid.

Parameters

  devid | of the adapter

Returns
  - NULL if no such adapter exists
  - pointer to found adapter

Locks:
  vlib_data.mutex must be held

References vlib_data::adapters, vlib_adapter_ident::devid, getAdapterByIndex(), vlib_adapter::ident, and block::used.

## getAdapterByHandle()

struct vlib_adapter * getAdapterByHandle | ( | HBA_HANDLE | handle,
|  | HBA_STATUS * | status
| ) |  |

Get an adapter by its handle.

Parameters

  handle | of the adapter
  *status | pointer to return error status code

Returns
  - NULL on error (*status contains error status code)
  - pointer to adapter structure on success

Locks:
  vlib_data.mutex must be held

If NULL is returned *status contains an error status code which should be checked by the calling function. If non-NULL is returned *status is HBA_STATUS_OK. Possible error status codes are:

- HBA_STATUS_ERROR_INVALID_HANDLE if handle is invalid
- HBA_STATUS_ERROR_UNAVAILABLE if adapter is unavailable

References getAdapterByIndex(), vlib_adapter::handle, vlib_adapter::isInvalid, and VLIB_INVALID_HANDLE.

Referenced by _HBA_SendReadCapacity(), _HBA_SendReportLUNs(), _HBA_SendScsiInquiry(), HBA_CloseAdapter(), HBA_GetAdapterAttributes(), HBA_GetAdapterPortAttributes(), HBA_GetDiscoveredPortAttributes(), HBA_GetEventBuffer(), HBA_GetFcpTargetMapping(), HBA_GetFcpTargetMappingV2(), HBA_GetPortStatistics(), HBA_GetRNIDMgmtInfo(), HBA_RefreshInformation(), HBA_SendCTPassThru(), and HBA_SendRNID().

## getAdapterByHostNo()

struct vlib_adapter * getAdapterByHostNo | ( | unsigned short | host | ) |

Get an adapter by SCSI Host number as in sysfs.

Parameters

  SCSI | host number of the adapter

Returns
  - NULL if no such adapter exists
  - pointer to found adapter

Locks:
  vlib_data.mutex must be held

References vlib_data::adapters, getAdapterByIndex(), vlib_adapter_ident::host, vlib_adapter::ident, and block::used.

Referenced by sysfs_getUnitsFromPort().

## getAdapterByIndex()

struct vlib_adapter * getAdapterByIndex | ( | uint32_t | index | ) |

Get an adapter by its index.

Parameters

  index | of the adapter

Returns
  - NULL if index is out of range
  - pointer to found adapter on success @parm Locks: vlib_data.mutex must be held

References vlib_data::adapters, block::data, and block::used.

Referenced by closeAllAdapters(), findIndexByName(), getAdapterByDevid(), getAdapterByHandle(), getAdapterByHostNo(), getAdapterFromRepos(), HBA_GetAdapterName(), invalidateAllAdapters(), openAdapterByIndex(), and revalidateAdapters().

## getAttachedWLUN()

char * getAttachedWLUN | ( | struct vlib_adapter * | adapter,
|  | struct vlib_port * | port
| ) |  |

Try to attach the report luns wlun and return its name as in "/dev".

Parameters

  adapter* | Pointer to an adapter
  port* | Pointer to a port

Note
  This function issues a system call to attach lun0

References vlib_adapter_ident::bus_dev_name, getSgDevFromPort(), vlib_adapter::ident, REPORTLUNS_WLUN, and vlib_port::wwpn.

Referenced by _HBA_SendReportLUNs().

## getPortByIndex()

struct vlib_port * getPortByIndex | ( | const struct vlib_adapter * | adapter,
|  | const uint32_t | index
| ) |  |

Get a port by its index.

Parameters

  *adapter | to which the port belongs
  index | of the port

Returns
  - NULL if index is out of range
  - pointer to found port on success

Locks:
  vlib_Data.mutex must be held

References block::data, vlib_adapter::ports, and block::used.

Referenced by doCloseAdapter(), getPortByWWPN(), getPortFromRepos(), HBA_GetDiscoveredPortAttributes(), HBA_GetFcpTargetMapping(), and updateAdapter().

## getPortByWWPN()

struct vlib_port * getPortByWWPN | ( | const struct vlib_adapter * | adapter,
|  | const wwn_t | wwpn
| ) |  |

Get a port by its WWPN.

Parameters

  *adapter | to which the port belongs
  wwpn | of the port

Returns
  - NULL if no port with such a WWPN exists
  - pointer to found port on success

Locks:
  vlib_data.mutex must be held

References getPortByIndex(), vlib_adapter::ports, block::used, and vlib_port::wwpn.

Referenced by _HBA_SendReadCapacity(), _HBA_SendReportLUNs(), and _HBA_SendScsiInquiry().

## getSgDevFromPort()

char * getSgDevFromPort | ( | struct vlib_port * | port | ) |

Get the first sg device from an adapter.

Parameters

  port* | Pointer to a port

Note
  This function looks for the first lun belonging to the first port of the adapter and returns its sg device

References getUnitByIndex(), revalidateUnits(), and vlib_unit::sg_dev.

Referenced by _HBA_SendReportLUNs(), and getAttachedWLUN().

## getUnitByFcLun()

struct vlib_unit * getUnitByFcLun | ( | const struct vlib_port * | port,
|  | uint64_t | fcLun
| ) |  |

Get an unit by its fclun.

Parameters

  *port | to which the unit belongs
  index | of the unit

Returns
  - NULL if index is out of range
  - pointer to found unit on success

Locks:
  vlib_data.mutex must be held

References vlib_unit::fcLun, getUnitByIndex(), vlib_port::units, and block::used.

Referenced by _HBA_SendReadCapacity(), and _HBA_SendScsiInquiry().

## getUnitByIndex()

struct vlib_unit * getUnitByIndex | ( | const struct vlib_port * | port,
|  | const uint32_t | index
| ) |  |

Get an unit by its index.

Parameters

  *port | to which the unit belongs
  index | of the unit

Returns
  - NULL if index is out of range
  - pointer to found unit on success

Locks:
  vlib_data.mutex must be held

References block::data, vlib_port::units, and block::used.

Referenced by detachWLUN(), getSgDevFromPort(), getUnitByFcLun(), getUnitFromRepos(), and HBA_GetFcpTargetMapping().

## invalidateAllAdapters()

static void invalidateAllAdapters | ( | void |  | ) |

inline static

Mark all adapters in repository as invalid.

Locks:
  vlib_data.mutex must be held

References vlib_data::adapters, getAdapterByIndex(), vlib_adapter::isInvalid, and block::used.

## markRepositoryInvalid()

static void markRepositoryInvalid | ( | void |  | ) |

inline static

Mark repositroy of library as invalid. This is appropriate if a loss of events is detected.

Locks:
  lock/unlock of vlib_data.mutex

References vlib_data::isValid, vlib_data::mutex, VLIB_MUTEX_LOCK, and VLIB_MUTEX_UNLOCK.

## openAdapterByIndex()

HBA_HANDLE openAdapterByIndex | ( | HBA_UINT32 | index | ) |

Open an adapter by index.

Parameters

  index | of the adapter

Returns
  - VLIB_INVALID_HANDLE if index is invalid
  - handle to the adapter on success

Locks:
  vlib_data.mutex must be held

If compiled as a vendor library, we shall only use the lower 16 Bit of the handle.

References getAdapterByIndex(), vlib_adapter::handle, and VLIB_INVALID_HANDLE.

Referenced by HBA_OpenAdapter().

## revalidateAdapters()

int revalidateAdapters | ( | void |  | ) |

Revalidate adapters in the repository.

Returns
  - -1 on error
  - 0 on success

Locks:
  vlib_data.mutex must be held

Port and unit configuration data is only updated if it was already generated before. Generation of port and unit configuration information is triggered in HBA_GetAdapterPortAttributes() and HBA_GetFcpTargetMapping(), resp.

References vlib_data::adapters, block::allocated, doCloseAdapter(), getAdapterByIndex(), vlib_adapter::isInvalid, vlib_adapter::ports, updateAdapter(), and block::used.

Referenced by sysfs_createAndReadConfigAdapter().

## updateAdapter()

int updateAdapter | ( | struct vlib_adapter * | adapter | ) |

Update information about ports and units of an adapter.

Parameters

  *adapter | to be updated

Returns
  - -1 on error
  - 0 on success

Locks:
  vlib_data.mutex must be held

Note
  Additionally this function triggers creation of unit configuration for this adapter (see getUnitsFromPort()).

References getPortByIndex(), vlib_adapter::isInvalid, vlib_adapter::ports, sysfs_createAndReadConfigPorts(), sysfs_getUnitsFromPort(), and block::used.

Referenced by HBA_RefreshInformation(), and revalidateAdapters().

## vlib_FCID_to_hbaFCID()

static uint32_t vlib_FCID_to_hbaFCID | ( | uint32_t | fcid | ) |

inline static

Convert a FC DID to a FC-HBA PortFcId.

Parameters

  fcid | a FC DID (uses 3 least significant bytes)

Returns
  a PortFcId as specified in FC-HBA (uses 3 most significant bytes)

Referenced by HBA_GetFcpTargetMapping().

## vlib_HBA_WWN_to_wwn()

static void vlib_HBA_WWN_to_wwn | ( | HBA_WWN * | hba,
|  | uint64_t * | wwn
| ) |  |

inline static

Convert HBA_WWN to uint64_t – hide ill-favoured type cast.

Parameters

  *hba | pointer WWN of type HBA_WWN (to be converted)
  *wwn | pointer to return WWN as uint64_t

Referenced by _HBA_SendReadCapacity(), _HBA_SendReportLUNs(), _HBA_SendScsiInquiry(), HBA_GetFcpTargetMappingV2(), and HBA_SendRNID().

## vlib_hbaFCID_to_FCID()

static uint32_t vlib_hbaFCID_to_FCID | ( | uint32_t | fcid | ) |

inline static

Convert a FC-HBA PortFcId to a FC DID.

Parameters

  fcid | PortFcId as specified in FC-HBA (uses 3 most significant bytes)

Returns
  a FC DID (uses 3 least significant bytes)

## vlib_wwn_to_HBA_WWN()

static void vlib_wwn_to_HBA_WWN | ( | uint64_t | wwn,
|  | HBA_WWN * | hba
| ) |  |

inline static

Convert uint64_t to HBA_WWN – hide ill-favoured type cast.

Parameters

  wwn | WWN stored as uint64_t (to be converted)
  *hba | pointer to return WWN of type HBA_WWN

Referenced by getPortAttributes(), HBA_GetFcpTargetMapping(), HBA_GetRNIDMgmtInfo(), and sysfs_getAdapterAttributes().

## vlibCharToIntCOS()

HBA_COS vlibCharToIntCOS | ( | char * | s | ) |

Map the result of a class of service string to an int.

Parameters

  char* | containing the class of service string

Note
  This function maps the class of service from sysfs which is in the form "Class2, Class3" to its integer representation via bit flags

References vlibCOStoFlag().

Referenced by getPortAttributes().

## vlibCharToIntPortSpeed()

HBA_PORTSPEED vlibCharToIntPortSpeed | ( | char * | pS | ) |

Map the result of a port speed string to the HBA_PORTSPEED int.

Parameters

  char* | containing the port speed string

Note
  This function maps the port speed from the sysfs (which is in the form "1 Gbit, 2 Gbit" to an int storing a flag for each port speed

References vlibIntToSymbolPortSpeed().

Referenced by getPortAttributes().

## vlibCharToIntPortState()

HBA_PORTSTATE vlibCharToIntPortState | ( | char * | portState | ) |

Map the result of a port state string from sysfs to an int.

Parameters

  char* | containing the port state

Note
  This function maps the port states from the sysfs attribute (which are strings) to their number as defined in hbaapi.h

Referenced by getPortAttributes().

## vlibCharToIntPortType()

HBA_PORTTYPE vlibCharToIntPortType | ( | char * | portType | ) |

Map the result of a port type string from sysfs to an int.

Parameters

  char* | containing the port type

Note
  This function maps the port types from the sysfs attribute (which are strings) to their number as defined in hbaapi.h

Referenced by getPortAttributes().