Fabric Port

Contents

Fabric Port#

oneAPI Level Zero Specification - Version 1.18.31

Fabric Port Functions#

zesFabricPortGetProperties#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetProperties(zes_fabric_port_handle_t hPort, zes_fabric_port_properties_t *pProperties)#

Get Fabric port properties.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hPort – [in] Handle for the component.

  • pProperties – [in,out] Will contain properties of the Fabric Port.

Returns:

zesFabricPortGetLinkType#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetLinkType(zes_fabric_port_handle_t hPort, zes_fabric_link_type_t *pLinkType)#

Get Fabric port link type.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hPort – [in] Handle for the component.

  • pLinkType – [in,out] Will contain details about the link attached to the Fabric port.

Returns:

zesFabricPortGetConfig#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetConfig(zes_fabric_port_handle_t hPort, zes_fabric_port_config_t *pConfig)#

Get Fabric port configuration.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hPort – [in] Handle for the component.

  • pConfig – [in,out] Will contain configuration of the Fabric Port.

Returns:

zesFabricPortSetConfig#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortSetConfig(zes_fabric_port_handle_t hPort, const zes_fabric_port_config_t *pConfig)#

Set Fabric port configuration.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hPort – [in] Handle for the component.

  • pConfig – [in] Contains new configuration of the Fabric Port.

Returns:

zesFabricPortGetState#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetState(zes_fabric_port_handle_t hPort, zes_fabric_port_state_t *pState)#

Get Fabric port state - status (health/degraded/failed/disabled), reasons for link degradation or instability, current rx/tx speed.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hPort – [in] Handle for the component.

  • pState – [in,out] Will contain the current state of the Fabric Port

Returns:

zesFabricPortGetThroughput#

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetThroughput(zes_fabric_port_handle_t hPort, zes_fabric_port_throughput_t *pThroughput)#

Get Fabric port throughput.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hPort – [in] Handle for the component.

  • pThroughput – [in,out] Will contain the Fabric port throughput counters.

Returns:

zesFabricPortGetFabricErrorCounters#

Added in version 1.7

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetFabricErrorCounters(zes_fabric_port_handle_t hPort, zes_fabric_port_error_counters_t *pErrors)#

Get Fabric Port Error Counters.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

  • The memory backing the arrays for phPorts and ppThroughputs must be allocated in system memory by the user who is also responsible for releasing them when they are no longer needed.

Parameters:

  • hPort – [in] Handle for the component.

  • pErrors – [in,out] Will contain the Fabric port Error counters.

Returns:

zesFabricPortGetMultiPortThroughput#

Added in version 1.7

ZE_APIEXPORT ze_result_t ZE_APICALL zesFabricPortGetMultiPortThroughput(zes_device_handle_t hDevice, uint32_t numPorts, zes_fabric_port_handle_t *phPort, zes_fabric_port_throughput_t **pThroughput)#

Get Fabric port throughput from multiple ports in a single call.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hDevice – [in] Sysman handle of the device.

  • numPorts – [in] Number of ports enumerated in function zesDeviceEnumFabricPorts

  • phPort – [in][range(0, numPorts)] array of fabric port handles provided by user to gather throughput values.

  • pThroughput – [out][range(0, numPorts)] array of fabric port throughput counters from multiple ports of type zes_fabric_port_throughput_t.

Returns:

Fabric Port Enums#

zes_fabric_port_status_t#

Added in version 1.0

enum zes_fabric_port_status_t#

Fabric port status.

Values:

enumerator ZES_FABRIC_PORT_STATUS_UNKNOWN#

The port status cannot be determined.

enumerator ZES_FABRIC_PORT_STATUS_HEALTHY#

The port is up and operating as expected.

enumerator ZES_FABRIC_PORT_STATUS_DEGRADED#

The port is up but has quality and/or speed degradation.

enumerator ZES_FABRIC_PORT_STATUS_FAILED#

Port connection instabilities are preventing workloads making forward progress

enumerator ZES_FABRIC_PORT_STATUS_DISABLED#

The port is configured down.

enumerator ZES_FABRIC_PORT_STATUS_FORCE_UINT32#

Value marking end of ZES_FABRIC_PORT_STATUS_* ENUMs.

zes_fabric_port_qual_issue_flags_t#

Added in version 1.0

enum zes_fabric_port_qual_issue_flag_t#

Values:

enumerator ZES_FABRIC_PORT_QUAL_ISSUE_FLAG_LINK_ERRORS#

Excessive link errors are occurring.

enumerator ZES_FABRIC_PORT_QUAL_ISSUE_FLAG_SPEED#

There is a degradation in the bitrate and/or width of the link.

enumerator ZES_FABRIC_PORT_QUAL_ISSUE_FLAG_FORCE_UINT32#

Value marking end of ZES_FABRIC_PORT_QUAL_ISSUE_FLAG_* ENUMs.

zes_fabric_port_failure_flags_t#

Added in version 1.0

enum zes_fabric_port_failure_flag_t#

Values:

enumerator ZES_FABRIC_PORT_FAILURE_FLAG_FAILED#

A previously operating link has failed. Hardware will automatically retrain this port. This state will persist until either the physical connection is removed or the link trains successfully.

enumerator ZES_FABRIC_PORT_FAILURE_FLAG_TRAINING_TIMEOUT#

A connection has not been established within an expected time. Hardware will continue to attempt port training. This status will persist until either the physical connection is removed or the link successfully trains.

enumerator ZES_FABRIC_PORT_FAILURE_FLAG_FLAPPING#

Port has excessively trained and then transitioned down for some period of time. Driver will allow port to continue to train, but will not enable the port for use until the port has been disabled and subsequently re-enabled using zesFabricPortSetConfig().

enumerator ZES_FABRIC_PORT_FAILURE_FLAG_FORCE_UINT32#

Value marking end of ZES_FABRIC_PORT_FAILURE_FLAG_* ENUMs.

Fabric Port Structures#

zes_fabric_port_id_t#

Added in version 1.0

struct zes_fabric_port_id_t#

Unique identifier for a fabric port.

  • This is not a universal identifier. The identified is guaranteed to be unique for the current hardware configuration of the system. Changes in the hardware may result in a different identifier for a given port.

  • The main purpose of this identifier to build up an instantaneous topology map of system connectivity. An application should enumerate all fabric ports and match the remotePortId member of zes_fabric_port_state_t to the portId member of zes_fabric_port_properties_t.

Public Members

uint32_t fabricId#

[out] Unique identifier for the fabric end-point

uint32_t attachId#

[out] Unique identifier for the device attachment point

uint8_t portNumber#

[out] The logical port number (this is typically marked somewhere on the physical device)

zes_fabric_port_speed_t#

Added in version 1.0

struct zes_fabric_port_speed_t#

Fabric port speed in one direction.

Public Members

int64_t bitRate#

[out] Bits/sec that the link is operating at. A value of -1 means that this property is unknown.

int32_t width#

[out] The number of lanes. A value of -1 means that this property is unknown.

zes_fabric_port_properties_t#

Added in version 1.0

struct zes_fabric_port_properties_t#

Fabric port properties.

Public Members

zes_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

char model[ZES_MAX_FABRIC_PORT_MODEL_SIZE]#

[out] Description of port technology. Will be set to the string “unknown” if this cannot be determined for this port.

ze_bool_t onSubdevice#

[out] True if the port is located on a sub-device; false means that the port is on the device of the calling Sysman handle

uint32_t subdeviceId#

[out] If onSubdevice is true, this gives the ID of the sub-device

zes_fabric_port_id_t portId#

[out] The unique port identifier

zes_fabric_port_speed_t maxRxSpeed#

[out] Maximum speed supported by the receive side of the port (sum of all lanes)

zes_fabric_port_speed_t maxTxSpeed#

[out] Maximum speed supported by the transmit side of the port (sum of all lanes)

zes_fabric_port_config_t#

Added in version 1.0

struct zes_fabric_port_config_t#

Fabric port configuration.

Public Members

zes_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_bool_t enabled#

[in,out] Port is configured up/down

ze_bool_t beaconing#

[in,out] Beaconing is configured on/off

zes_fabric_port_state_t#

Added in version 1.0

struct zes_fabric_port_state_t#

Fabric port state.

Public Members

zes_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

zes_fabric_port_status_t status#

[out] The current status of the port

zes_fabric_port_qual_issue_flags_t qualityIssues#

[out] If status is ZES_FABRIC_PORT_STATUS_DEGRADED, then this gives a combination of zes_fabric_port_qual_issue_flag_t for quality issues that have been detected; otherwise, 0 indicates there are no quality issues with the link at this time.

zes_fabric_port_failure_flags_t failureReasons#

[out] If status is ZES_FABRIC_PORT_STATUS_FAILED, then this gives a combination of zes_fabric_port_failure_flag_t for reasons for the connection instability; otherwise, 0 indicates there are no connection stability issues at this time.

zes_fabric_port_id_t remotePortId#

[out] The unique port identifier for the remote connection point if status is ZES_FABRIC_PORT_STATUS_HEALTHY, ZES_FABRIC_PORT_STATUS_DEGRADED or ZES_FABRIC_PORT_STATUS_FAILED

zes_fabric_port_speed_t rxSpeed#

[out] Current maximum receive speed (sum of all lanes)

zes_fabric_port_speed_t txSpeed#

[out] Current maximum transmit speed (sum of all lanes)

zes_fabric_port_throughput_t#

Added in version 1.0

struct zes_fabric_port_throughput_t#

Fabric port throughput.

Public Members

uint64_t timestamp#

[out] Monotonic timestamp counter in microseconds when the measurement was made. This timestamp should only be used to calculate delta time between snapshots of this structure. Never take the delta of this timestamp with the timestamp from a different structure since they are not guaranteed to have the same base. The absolute value of the timestamp is only valid during within the application and may be different on the next execution.

uint64_t rxCounter#

[out] Monotonic counter for the number of bytes received (sum of all lanes). This includes all protocol overhead, not only the GPU traffic.

uint64_t txCounter#

[out] Monotonic counter for the number of bytes transmitted (sum of all lanes). This includes all protocol overhead, not only the GPU traffic.

zes_fabric_port_error_counters_t#

Added in version 1.7

struct zes_fabric_port_error_counters_t#

Fabric Port Error Counters.

Public Members

zes_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

uint64_t linkFailureCount#

[out] Link Failure Error Count reported per port

uint64_t fwCommErrorCount#

[out] Firmware Communication Error Count reported per device

uint64_t fwErrorCount#

[out] Firmware reported Error Count reported per device

uint64_t linkDegradeCount#

[out] Link Degrade Error Count reported per port