Fabric Vertex - Experimental

oneAPI Level Zero Specification - Version 1.18.31

Fabric Vertex - Experimental Functions

zeFabricVertexGetExp

Added in version 1.4

ZE_APIEXPORT ze_result_t ZE_APICALL zeFabricVertexGetExp(ze_driver_handle_t hDriver, uint32_t *pCount, ze_fabric_vertex_handle_t *phVertices)

Retrieves fabric vertices within a driver.

• A fabric vertex represents either a device or a switch connected to other fabric vertices.

• The application may call this function from simultaneous threads.

• The implementation of this function must be thread-safe.

Parameters:

• hDriver – [in] handle of the driver instance

• pCount – [in,out] pointer to the number of fabric vertices. if count is zero, then the driver shall update the value with the total number of fabric vertices available. if count is greater than the number of fabric vertices available, then the driver shall update the value with the correct number of fabric vertices available.

• phVertices – [in,out][optional][range(0, *pCount)] array of handle of fabric vertices. if count is less than the number of fabric vertices available, then driver shall only retrieve that number of fabric vertices.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hDriver

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zeFabricVertexGetSubVerticesExp

Added in version 1.4

ZE_APIEXPORT ze_result_t ZE_APICALL zeFabricVertexGetSubVerticesExp(ze_fabric_vertex_handle_t hVertex, uint32_t *pCount, ze_fabric_vertex_handle_t *phSubvertices)

Retrieves a fabric sub-vertex from a fabric vertex.

• Multiple calls to this function will return identical fabric vertex handles, in the same order.

• The number of handles returned from this function is affected by the ZE_AFFINITY_MASK environment variable.

• The application may call this function from simultaneous threads.

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

Parameters:

• hVertex – [in] handle of the fabric vertex object

• pCount – [in,out] pointer to the number of sub-vertices. if count is zero, then the driver shall update the value with the total number of sub-vertices available. if count is greater than the number of sub-vertices available, then the driver shall update the value with the correct number of sub-vertices available.

• phSubvertices – [in,out][optional][range(0, *pCount)] array of handle of sub-vertices. if count is less than the number of sub-vertices available, then driver shall only retrieve that number of sub-vertices.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hVertex

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pCount

zeFabricVertexGetPropertiesExp

Added in version 1.4

ZE_APIEXPORT ze_result_t ZE_APICALL zeFabricVertexGetPropertiesExp(ze_fabric_vertex_handle_t hVertex, ze_fabric_vertex_exp_properties_t *pVertexProperties)

Retrieves properties of the fabric vertex.

• The application may call this function from simultaneous threads.

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

Parameters:

• hVertex – [in] handle of the fabric vertex

• pVertexProperties – [in,out] query result for fabric vertex properties

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hVertex

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pVertexProperties

zeFabricVertexGetDeviceExp

Added in version 1.4

ZE_APIEXPORT ze_result_t ZE_APICALL zeFabricVertexGetDeviceExp(ze_fabric_vertex_handle_t hVertex, ze_device_handle_t *phDevice)

Returns device handle from fabric vertex handle.

• The application may call this function from simultaneous threads.

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

Parameters:

• hVertex – [in] handle of the fabric vertex

• phDevice – [out] device handle corresponding to fabric vertex

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hVertex

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == phDevice

• ZE_RESULT_EXP_ERROR_VERTEX_IS_NOT_DEVICE

  • Provided fabric vertex handle does not correspond to a device or subdevice.

• ZE_RESULT_EXP_ERROR_REMOTE_DEVICE

  • Provided fabric vertex handle corresponds to remote device or subdevice.

Fabric Vertex - Experimental Enums

ze_fabric_vertex_exp_type_t

Added in version 1.4

enum ze_fabric_vertex_exp_type_t

Fabric Vertex types.

Values:

enumerator ZE_FABRIC_VERTEX_EXP_TYPE_UNKNOWN

Fabric vertex type is unknown.

enumerator ZE_FABRIC_VERTEX_EXP_TYPE_DEVICE

Fabric vertex represents a device.

enumerator ZE_FABRIC_VERTEX_EXP_TYPE_SUBDEVICE

Fabric vertex represents a subdevice.

enumerator ZE_FABRIC_VERTEX_EXP_TYPE_SWITCH

Fabric vertex represents a switch.

enumerator ZE_FABRIC_VERTEX_EXP_TYPE_FORCE_UINT32

Value marking end of ZE_FABRIC_VERTEX_EXP_TYPE_* ENUMs.

Fabric Vertex - Experimental Structures

ze_fabric_vertex_pci_exp_address_t

Added in version 1.4

struct ze_fabric_vertex_pci_exp_address_t

PCI address.

• A PCI BDF address is the bus:device:function address of the device and is useful for locating the device in the PCI switch fabric.

Public Members

uint32_t domain

[out] PCI domain number

uint32_t bus

[out] PCI BDF bus number

uint32_t device

[out] PCI BDF device number

uint32_t function

[out] PCI BDF function number

ze_fabric_vertex_exp_properties_t

Added in version 1.4

struct ze_fabric_vertex_exp_properties_t

Fabric Vertex properties.

Public Members

ze_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).

ze_uuid_t uuid

[out] universal unique identifier. If the vertex is co-located with a device/subdevice, then this uuid will match that of the corresponding device/subdevice

ze_fabric_vertex_exp_type_t type

[out] does the fabric vertex represent a device, subdevice, or switch?

ze_bool_t remote

[out] does the fabric vertex live on the local node or on a remote node?

ze_fabric_vertex_pci_exp_address_t address

[out] B/D/F address of fabric vertex & associated device/subdevice if available