PCI devices configuration of Test Agents

Overview

// typedefs

typedef enum tapi_cfg_pci_param_cmode tapi_cfg_pci_param_cmode;

// enums

enum tapi_cfg_driver_type;
enum tapi_cfg_pci_param_cmode;

// global functions

te_errno tapi_cfg_pci_get_pci_vendor_device(const char* ta, const char* pci_addr, char** vendor, char** device);
te_errno tapi_cfg_pci_resolve_device_oid(char** pci_dev_oid, const char* pci_inst_fmt, ...);
te_errno te_errno tapi_cfg_pci_devices_by_vendor_device(const char* ta, const char* vendor, const char* device, unsigned int* size, char*** pci_oids);
te_errno tapi_cfg_pci_get_max_vfs_of_pf(const char* pf_oid, unsigned int* n_vfs);
te_errno tapi_cfg_pci_get_vfs_of_pf(const char* pf_oid, bool pci_device, unsigned int* n_pci_vfs, cfg_oid*** pci_vfs, unsigned int** pci_vf_ids);
te_errno tapi_cfg_pci_enable_vfs_of_pf(const char* pf_oid, unsigned int n_vfs);
te_errno tapi_cfg_pci_addr_by_oid(const cfg_oid* pci_device, char** pci_addr);
te_errno tapi_cfg_pci_addr_by_oid_array(unsigned int n_devices, const cfg_oid** pci_devices, char*** pci_addrs);
char* tapi_cfg_pci_rsrc_name(const cfg_oid* pci_instance);
char* tapi_cfg_pci_fn_netdev_rsrc_name(const cfg_oid* oid);
te_errno tapi_cfg_pci_grab(const cfg_oid* pci_instance);
te_errno tapi_cfg_pci_oid_by_addr(const char* ta, const char* pci_addr, char** pci_oid);
te_errno tapi_cfg_pci_instance_by_addr(const char* ta, const char* pci_addr, char** pci_inst);
te_errno tapi_cfg_pci_get_ta_driver(const char* ta, enum tapi_cfg_driver_type type, char** driver);
te_errno tapi_cfg_pci_get_devices(const char* pci_oid, unsigned int* count, char*** device_names);
te_errno tapi_cfg_pci_get_driver(const char* pci_oid, char** driver);
te_errno tapi_cfg_pci_bind_driver(const char* pci_oid, const char* driver);
te_errno tapi_cfg_pci_bind_ta_driver_on_device(const char* ta, enum tapi_cfg_driver_type type, const char* pci_addr);
te_errno tapi_cfg_pci_fn_netdev_get_net_if(const char* pci_fn_oid, const char* netdev, char** interface);
te_errno tapi_cfg_pci_get_net_if(const char* pci_oid, char** interface);
te_errno tapi_cfg_pci_oid_by_net_if(const char* ta, const char* if_name, char** pci_oid);
te_errno tapi_cfg_pci_get_numa_node(const char* pci_oid, char** numa_node);
te_errno tapi_cfg_pci_get_numa_node_id(const char* pci_oid, int* numa_node);
te_errno tapi_cfg_pci_bind_driver_by_vend_dev_inst(const char* ta, const char* vendor, const char* device, unsigned int instance, const char* driver);
te_errno tapi_cfg_pci_unbind_driver_by_vend_dev_inst(const char* ta, const char* vendor, const char* device, unsigned int instance);
te_errno tapi_cfg_pci_get_driver_by_vend_dev_inst(const char* ta, const char* vendor, const char* device, unsigned int instance, char** driver);
te_errno tapi_cfg_pci_get_serialno(const char* pci_oid, char** serialno);
te_errno tapi_cfg_pci_get_class(const char* pci_oid, unsigned int* class_id, unsigned int* subclass_id, unsigned int* intf_id);
te_errno tapi_cfg_pci_param_is_present(const char* pci_oid, const char* param_name, bool* present);
te_errno tapi_cfg_pci_get_param_str(const char* pci_oid, const char* param_name, tapi_cfg_pci_param_cmode cmode, char** value);
te_errno tapi_cfg_pci_get_param_uint(const char* pci_oid, const char* param_name, tapi_cfg_pci_param_cmode cmode, uint64_t* value);
te_errno tapi_cfg_pci_set_param_str(const char* pci_oid, const char* param_name, tapi_cfg_pci_param_cmode cmode, const char* value);
te_errno tapi_cfg_pci_set_param_uint(const char* pci_oid, const char* param_name, tapi_cfg_pci_param_cmode cmode, uint64_t value);
te_errno tapi_cfg_pci_get_vendor_dev_ids(const char* pci_oid, unsigned int* vendor_id, unsigned int* device_id, unsigned int* subsystem_vendor_id, unsigned int* subsystem_device_id);
te_errno tapi_cfg_pci_get_spdk_config_filename(const char* pci_oid, const char* cfg_name, bool create, char** filename);

Detailed Documentation

Typedefs

typedef enum tapi_cfg_pci_param_cmode tapi_cfg_pci_param_cmode

Device parameter configuration mode

Global Functions

te_errno tapi_cfg_pci_get_pci_vendor_device(const char* ta, const char* pci_addr, char** vendor, char** device)

Get vendor and device identifiers of a PCI device.

Parameters:

ta	Test Agent name
pci_addr	PCI device address (BDF notation)
vendor	Vendor identifier (may be NULL to ignore)
device	Device identifier (may be NULL to ignore)

Returns:

Status code

te_errno tapi_cfg_pci_resolve_device_oid(char** pci_dev_oid, const char* pci_inst_fmt, ...)

Get a PCI device OID (/agent/hardware/pci/device) by PCI instance OID (/agent/hardware/pci/vendor/device/instance).

If a PCI device OID is provided, a copy of it is returned.

The OID is constructed from a format string fmt and arguments.

Parameters:

pci_dev_oid	PCI device OID (should be free()’d)
pci_inst_fmt	A printf() format for a PCI instance OID
…	Arguments

Returns:

Status code

te_errno te_errno tapi_cfg_pci_devices_by_vendor_device(const char* ta, const char* vendor, const char* device, unsigned int* size, char*** pci_oids)

Get PCI addresses of PCI functions with specified vendor and device identifiers.

Parameters:

ta	Test Agent name
vendor	Vendor identifier
device	Device identifier
size	Count of pci_addrs
pci_oids	OIDs of found devices (/agent/hardware/pci/device). Might be NULL to only get the count.

Returns:

Status code

te_errno tapi_cfg_pci_get_max_vfs_of_pf(const char* pf_oid, unsigned int* n_vfs)

Get maximum possible number of VFs by a PCI PF object identifier.

Parameters:

pf_oid	PF OID in string representation
n_vfs	Number of discovered VFs (must not be NULL)

Returns:

Status code

te_errno tapi_cfg_pci_get_vfs_of_pf(const char* pf_oid, bool pci_device, unsigned int* n_pci_vfs, cfg_oid*** pci_vfs, unsigned int** pci_vf_ids)

Get VFs by a PCI PF object identifier.

Parameters:

pf_oid	PF OID in string representation
pci_device	true - get PCI device OID (/agent/hardware/pci/device), false - get PCI instance OID (/agent/hardware/pci/vendor/device/instance)
n_pci_vfs	Number of discovered VFs (must not be NULL)
pci_vfs	VF object identifiers (may be NULL to ignore)
pci_vf_ids	Indices of the VFs (may be NULL to ignore)

Returns:

Status code

te_errno tapi_cfg_pci_enable_vfs_of_pf(const char* pf_oid, unsigned int n_vfs)

Set number of VFs by a PCI PF object identifier.

Parameters:

pf_oid	PF OID in string representation
n_vfs	Requested number of VFs

Returns:

Status code

te_errno tapi_cfg_pci_addr_by_oid(const cfg_oid* pci_device, char** pci_addr)

Get PCI address (BDF notation) by PCI device OID (/agent/hardware/pci/device)

Parameters:

pci_device	PCI device
pci_addr	PCI address (must not be NULL)

Returns:

Status code

te_errno tapi_cfg_pci_addr_by_oid_array(unsigned int n_devices, const cfg_oid** pci_devices, char*** pci_addrs)

Call tapi_cfg_pci_addr_by_oid() on an array of PCI device OIDs

Parameters:

n_devices	Number of PCI devices
pci_devices	PCI device OIDs
pci_addrs	PCI addresses (must not be NULL)

Returns:

Status code

char* tapi_cfg_pci_rsrc_name(const cfg_oid* pci_instance)

Allocate a string with resource name for grabbing a PCI instance.

Parameters:

pci_instance

PCI instance OID (/agent/hardware/pci/vendor/device/instance)

Returns:

Allocated resource name string

char* tapi_cfg_pci_fn_netdev_rsrc_name(const cfg_oid* oid)

Allocate a string with resource name for grabbing a PCI instance with netdev.

Parameters:

pci_instance

PCI instance OID (/agent/hardware/pci/vendor/device/instance/netdev)

Returns:

Allocated resource name string

te_errno tapi_cfg_pci_grab(const cfg_oid* pci_instance)

Grab a PCI device as a resource.

Parameters:

pci_instance

PCI instance OID (/agent/hardware/pci/vendor/device/instance)

Returns:

Status code

te_errno tapi_cfg_pci_oid_by_addr(const char* ta, const char* pci_addr, char** pci_oid)

Get PCI device OID by the PCI address

Parameters:

ta	Test Agent name
pci_addr	PCI device address (BDF notation)
pci_oid	PCI device OID (/agent/hardware/pci/device)

Returns:

Status code

te_errno tapi_cfg_pci_instance_by_addr(const char* ta, const char* pci_addr, char** pci_inst)

Get PCI instance OID (used in network model resources) by PCI address.

Parameters:

ta	test agent name
pci_addr	PCI device address (BDF notation)
pci_inst	location for PCI instance OID

Returns:

Status code.

te_errno tapi_cfg_pci_get_ta_driver(const char* ta, enum tapi_cfg_driver_type type, char** driver)

Get PCI device driver assigned to a Test Agent

Parameters:

ta	Test Agent name
type	Driver type
driver	Driver name (on success, if no driver is assigned, the pointed data becomes NULL). The argument itself must not be NULL.

Returns:

Status code

te_errno tapi_cfg_pci_get_devices(const char* pci_oid, unsigned int* count, char*** device_names)

Get character or block devices names list of a PCI device

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device)
count	Count of device_names
device_names	Character or block devices names

Returns:

Status code

te_errno tapi_cfg_pci_get_driver(const char* pci_oid, char** driver)

Get driver of a PCI device

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device or /agent/hardware/pci/vendor/device/instance)
driver	Driver name (must not be NULL)

Returns:

Status code

te_errno tapi_cfg_pci_bind_driver(const char* pci_oid, const char* driver)

Bind driver to a PCI device

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device or /agent/hardware/pci/vendor/device/instance)
driver	Driver name

Returns:

Status code

te_errno tapi_cfg_pci_bind_ta_driver_on_device(const char* ta, enum tapi_cfg_driver_type type, const char* pci_addr)

Bind driver associated with a Test Agent on a PCI device.

Parameters:

ta	Test Agent name
type	Driver type
pci_addr	PCI address of the device to which the driver will be bound

Returns:

Status code

te_errno tapi_cfg_pci_fn_netdev_get_net_if(const char* pci_fn_oid, const char* netdev, char** interface)

Get the network interface associated with a PCI device with port.

Parameters:

pci_fn_oid	PCI device OID (/agent/hardware/pci/device/net)
netdev	Port (net) instance name
interface	Network interface name (must not be NULL)

Returns:

Status code

te_errno tapi_cfg_pci_get_net_if(const char* pci_oid, char** interface)

Get the first network interface associated with a PCI device.

In theory, more than one interface can be associated, in that case the function produces a warning.

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device)
interface	Network interface name (must not be NULL)

Returns:

Status code

te_errno tapi_cfg_pci_oid_by_net_if(const char* ta, const char* if_name, char** pci_oid)

Find out PCI device for a given network interface.

Parameters:

ta	Test Agent name
if_name	Interface name
pci_oid	Where to save pointer to OID of PCI device (should be released by caller)

Returns:

Status code.

te_errno tapi_cfg_pci_get_numa_node(const char* pci_oid, char** numa_node)

Get assigned NUMA node of a PCI device.

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device)
numa_node	OID (/agent/hardware/node) of a NUMA node where the device is local. Returns empty value if NUMA node is not assigned.

Returns:

Status code

te_errno tapi_cfg_pci_get_numa_node_id(const char* pci_oid, int* numa_node)

Get assigned NUMA node of a PCI device.

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device)
numa_node	Index of a NUMA node assigned to a PCI device. Returns -1 if NUMA node is not assigned.

Returns:

Status code

te_errno tapi_cfg_pci_bind_driver_by_vend_dev_inst(const char* ta, const char* vendor, const char* device, unsigned int instance, const char* driver)

Wrapper for tapi_cfg_pci_bind_driver to binding a driver by vendor, device and instance.

Parameters:

ta	Test Agent name
vendor	Vendor identifier
device	Device identifier
instance	Index of a PCI device with specified vendir/device IDs
driver	Driver to bind

Returns:

Status code

te_errno tapi_cfg_pci_unbind_driver_by_vend_dev_inst(const char* ta, const char* vendor, const char* device, unsigned int instance)

Wrapper for tapi_cfg_pci_bind_driver to unbinding a driver by vendor, device and instance.

Parameters:

ta	Test Agent name
vendor	Vendor identifier
device	Device identifier
instance	Index of a PCI device with specified vendir/device IDs

Returns:

Status code

te_errno tapi_cfg_pci_get_driver_by_vend_dev_inst(const char* ta, const char* vendor, const char* device, unsigned int instance, char** driver)

Wrapper for tapi_cfg_pci_get_driver to getiing a driver by vendor, device and instance.

Parameters:

ta	Test Agent name
vendor	Vendor identifier
device	Device identifier
instance	Index of a PCI device with specified vendir/device IDs
driver	Driver

Returns:

Status code

te_errno tapi_cfg_pci_get_serialno(const char* pci_oid, char** serialno)

Get PCI serial number.

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device)
serialno	Where to save PCI serial number (should be released by the caller)

Returns:

Status code.

te_errno tapi_cfg_pci_get_class(const char* pci_oid, unsigned int* class_id, unsigned int* subclass_id, unsigned int* intf_id)

Get PCI class, subclass and prog. interface of a device.

All output parameters may be passed NULL, then they are ignored.

The output parameters are all unsigned, not the corresponding enum types, because the enums above may not be exhaustive the caller must be prepared to deal with unlisted values.

Parameters:

pci_oid	PCI device OID or instance OID (/agent/hardware/pci/device or /agent/hardware/pci/vendor/device/instance, see tapi_cfg_pci_resolve_device_oid())
class_id	Class ID (see tapi_cfg_pci_class)
subclass_id	Subclass ID (see tapi_cfg_pci_subclass)
intf_id	Prog. interface ID (see tapi_cfg_pci_prog_interface)

Returns:

Status code.

te_errno tapi_cfg_pci_param_is_present(const char* pci_oid, const char* param_name, bool* present)

Check whether device parameter is present.

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device)
param_name	Parameter name
present	Will be set to true if device parameter is present, to false otherwise

Returns:

Status code.

te_errno tapi_cfg_pci_get_param_str(const char* pci_oid, const char* param_name, tapi_cfg_pci_param_cmode cmode, char** value)

Get device parameter value of string type.

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device)
param_name	Parameter name
cmode	Configuration mode of the value of interest
value	Where to save obtained value (should be released by the caller)

Returns:

Status code.

te_errno tapi_cfg_pci_get_param_uint(const char* pci_oid, const char* param_name, tapi_cfg_pci_param_cmode cmode, uint64_t* value)

Get device parameter value of unsigned integer type (this includes u8, u16, u32, u64 and flag parameters).

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device)
param_name	Parameter name
cmode	Configuration mode of the value of interest
value	Where to save obtained value

Returns:

Status code.

te_errno tapi_cfg_pci_set_param_str(const char* pci_oid, const char* param_name, tapi_cfg_pci_param_cmode cmode, const char* value)

Set device parameter value of string type.

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device)
param_name	Parameter name
cmode	Configuration mode of the value of interest
value	Value to set

Returns:

Status code.

te_errno tapi_cfg_pci_set_param_uint(const char* pci_oid, const char* param_name, tapi_cfg_pci_param_cmode cmode, uint64_t value)

Set device parameter value of unsigned integer type (can be used for any unsigned integer type, including flag type, it will fail if provided value is too big for the actual parameter type).

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device)
param_name	Parameter name
cmode	Configuration mode of the value of interest
value	Value to set

Returns:

Status code.

te_errno tapi_cfg_pci_get_vendor_dev_ids(const char* pci_oid, unsigned int* vendor_id, unsigned int* device_id, unsigned int* subsystem_vendor_id, unsigned int* subsystem_device_id)

Get vendor/device IDs of PCI device.

Parameters:

pci_oid	PCI device OID
vendor_id	Where to save vendor ID (may be NULL)
device_id	Where to save device ID (may be NULL)
subsystem_vendor_id	Where to save subsystem vendor ID (may be NULL)
subsystem_device_id	Where to save subsystem device ID (may be NULL)

Returns:

Status code.

te_errno tapi_cfg_pci_get_spdk_config_filename(const char* pci_oid, const char* cfg_name, bool create, char** filename)

Get the name of a SPDK JSON config file associated with the device.

The PCI OID must refer to a NVME device.

Parameters:

pci_oid	PCI device OID (/agent/hardware/pci/device or /agent/hardware/pci/vendor/device/instance)
cfg_name	SPDK configuration name
create	if true, create the requested configuration
filename	JSON file name (at the agent)
TE_ENOTBLK	The device is not NVME.
TE_ENOENT	The configuration or the device do not exist.
TE_EEXIST	The configuration already exists (if create is true).

Returns:

status code