NVIDIA DOCA SDK Data Center on a Chip Framework Documentation
Modules | Typedefs | Enumerations | Functions
DOCA Device Emulation - PCI Devices
DOCA Device Emulation
Collaboration diagram for DOCA Device Emulation - PCI Devices:

Modules

 DOCA Device Emulation - PCI Device Types
 

Typedefs

typedef uint64_t doca_dpa_dev_devemu_pci_db_t
 DPA handle for emulated PCI device doorbell. More...
 
typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_t
 DPA handle for emulated PCI device doorbell completion context. More...
 
typedef uint64_t doca_dpa_dev_devemu_pci_msix_t
 DPA handle for emulated PCI device MSI-X. More...
 
typedef void(* doca_devemu_pci_dev_event_hotplug_state_change_handler_cb_t) (struct doca_devemu_pci_dev *pci_dev, union doca_data user_data)
 Function to be executed on hotplug state change event occurrence. More...
 
typedef void(* doca_devemu_pci_dev_event_bar_stateful_region_driver_write_handler_cb_t) (struct doca_devemu_pci_dev_event_bar_stateful_region_driver_write *event, union doca_data user_data)
 Function to be executed on PCI write transactions to BAR stateful region. More...
 
typedef void(* doca_devemu_pci_dev_event_flr_handler_cb_t) (struct doca_devemu_pci_dev *pci_dev, union doca_data user_data)
 Function to be executed on PCI FLR (Function Level Reset). The event handler will enable users to quiesce, flush and reset the necessary resources associated with the emulated PCI device. Upon event, all PCI I/O transactions to/from the host memory are disabled. Additionally, the user should re-configure the emulated PCI device. This re-configuration requires flushing of all the outstanding resources associated with the emulated PCI device, which were initially owned by the PCI device and moved the the ownership of the user. The re-configuration also requires destruction of all the associated resources (e.g. DBs, MSIXs, MMAPs), resetting the associated emulated PCI device (perform stop() and start() operations) and re-creating all the needed resources. More...
 

Enumerations

enum  doca_devemu_pci_hotplug_state { DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF = 0 , DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS , DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS , DOCA_DEVEMU_PCI_HP_STATE_POWER_ON }
 DOCA devemu pci hotplug state. More...
 

Functions

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_cap_get_max_hotplug_devices (const struct doca_devinfo *devinfo, uint32_t *max_hotplug_devices)
 Get the maximum number of PCI devices, across all PCI types, that can be hot-plugged by the device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_cap_is_mmap_add_dev_supported (const struct doca_devinfo *devinfo, uint8_t *supported)
 Check if adding the device to a DOCA mmap associated with a DOCA devemu PCI device is supported. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_create (struct doca_devemu_pci_type *pci_type, struct doca_dev_rep *dev_rep, struct doca_pe *progress_engine, struct doca_devemu_pci_dev **pci_dev)
 Allocate DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_destroy (struct doca_devemu_pci_dev *pci_dev)
 Free a DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_device_id (const struct doca_devemu_pci_dev *pci_dev, uint16_t *device_id)
 Get the PCI Device ID configured to DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_device_id (struct doca_devemu_pci_dev *pci_dev, uint16_t device_id)
 Set the PCI Device ID of a specific DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_vendor_id (const struct doca_devemu_pci_dev *pci_dev, uint16_t *vendor_id)
 Get the PCI Vendor ID configured to DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_vendor_id (struct doca_devemu_pci_dev *pci_dev, uint16_t vendor_id)
 Set the PCI Vendor ID of a specific DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_subsystem_id (const struct doca_devemu_pci_dev *pci_dev, uint16_t *subsystem_id)
 Get the PCI Subsystem ID configured to DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_subsystem_id (struct doca_devemu_pci_dev *pci_dev, uint16_t subsystem_id)
 Set the PCI Subsystem ID of a specific DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_subsystem_vendor_id (const struct doca_devemu_pci_dev *pci_dev, uint16_t *subsystem_vid)
 Get the PCI Subsystem Vendor ID configured to DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_subsystem_vendor_id (struct doca_devemu_pci_dev *pci_dev, uint16_t subsystem_vid)
 Set the PCI Subsystem Vendor ID of a specific DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_revision_id (const struct doca_devemu_pci_dev *pci_dev, uint8_t *revision_id)
 Get the PCI Revision ID configured to DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_revision_id (struct doca_devemu_pci_dev *pci_dev, uint8_t revision_id)
 Set the PCI Revision ID of a specific DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_class_code (const struct doca_devemu_pci_dev *pci_dev, uint32_t *class_code)
 Get the PCI Class Code configured to DOCA devemu PCI device to identify generic operation. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_class_code (struct doca_devemu_pci_dev *pci_dev, uint32_t class_code)
 Set the PCI Class Code of a specific DOCA devemu PCI device to identify generic operation. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_num_msix (const struct doca_devemu_pci_dev *pci_dev, uint16_t *num_msix)
 Get the number of MSI-X vectors configured to DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_num_msix (struct doca_devemu_pci_dev *pci_dev, uint16_t num_msix)
 Set the number of MSI-X vectors of a specific DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_modify_bar_stateful_region_default_values (struct doca_devemu_pci_dev *pci_dev, uint8_t id, uint64_t start_addr, void *default_values, uint64_t size)
 Modify default registers values for stateful region in a DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_modify_bar_stateful_region_values (struct doca_devemu_pci_dev *pci_dev, uint8_t id, uint64_t offset, void *values, uint64_t size)
 Modify registers values for stateful region in a DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_query_bar_stateful_region_values (struct doca_devemu_pci_dev *pci_dev, uint8_t id, uint64_t offset, void *out_values, uint64_t size)
 Query registers values of the stateful region in a DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL struct doca_ctx * doca_devemu_pci_dev_as_ctx (struct doca_devemu_pci_dev *pci_dev)
 Convert DOCA devemu PCI device instance into DOCA context. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_is_flr (const struct doca_devemu_pci_dev *pci_dev, uint8_t *flr)
 Query wheather the DOCA devemu PCI device is having FLR (Function Level Reset). More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_hotplug_state (struct doca_devemu_pci_dev *pci_dev, enum doca_devemu_pci_hotplug_state *state)
 Get the hotplug state of the DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_rep_get_hotplug_state (struct doca_dev_rep *rep_dev, enum doca_devemu_pci_hotplug_state *state)
 Get the hotplug state of a DOCA representor device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_hotplug (struct doca_devemu_pci_dev *pci_dev)
 Issue hotplug procedure of the DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_hotunplug (struct doca_devemu_pci_dev *pci_dev)
 Issue hot unplug procedure of the DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_event_hotplug_state_change_register (struct doca_devemu_pci_dev *pci_dev, doca_devemu_pci_dev_event_hotplug_state_change_handler_cb_t handler, union doca_data user_data)
 Register to hotplug state changes. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_register (struct doca_devemu_pci_dev *pci_dev, doca_devemu_pci_dev_event_bar_stateful_region_driver_write_handler_cb_t handler, uint8_t bar_id, uint64_t bar_region_start_addr, union doca_data user_data)
 Register to BAR stateful region driver write event. More...
 
DOCA_EXPERIMENTAL struct doca_devemu_pci_dev * doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_pci_dev (struct doca_devemu_pci_dev_event_bar_stateful_region_driver_write *event)
 Get DOCA devemu PCI device from BAR stateful region driver write event. More...
 
DOCA_EXPERIMENTAL uint8_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_id (struct doca_devemu_pci_dev_event_bar_stateful_region_driver_write *event)
 Get the BAR id from BAR stateful region driver write event. More...
 
DOCA_EXPERIMENTAL uint64_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_region_start_addr (struct doca_devemu_pci_dev_event_bar_stateful_region_driver_write *event)
 Get the BAR region start address that is associated with BAR stateful region driver write event. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_event_flr_register (struct doca_devemu_pci_dev *pci_dev, doca_devemu_pci_dev_event_flr_handler_cb_t handler, union doca_data user_data)
 Register to PCI FLR (Function Level Reset) event. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_create (struct doca_dpa_thread *th, struct doca_devemu_pci_db_completion **db_comp)
 Allocate DOCA devemu PCI device doorbell completion context on DPA. The created completion context will be associated with a single dpa thread. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_destroy (struct doca_devemu_pci_db_completion *db_comp)
 Destroy the DOCA devemu PCI device doorbell completion context. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_start (struct doca_devemu_pci_db_completion *db_comp)
 Start DOCA devemu PCI device doorbell completion context. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_stop (struct doca_devemu_pci_db_completion *db_comp)
 Stop DOCA devemu PCI device doorbell completion context. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_get_dpa_handle (struct doca_devemu_pci_db_completion *db_comp, doca_dpa_dev_devemu_pci_db_completion_t *db_comp_handle)
 Get the DPA handle for the DOCA devemu PCI device doorbell completion context. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_set_max_num_dbs (struct doca_devemu_pci_db_completion *db_comp, uint32_t num_dbs)
 Set the maximal number of doorbells that can be associated with the completion context. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_get_max_num_dbs (struct doca_devemu_pci_db_completion *db_comp, uint32_t *num_dbs)
 Get the maximal number of doorbells that can be associated with the completion context. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_get_curr_num_dbs (struct doca_devemu_pci_db_completion *db_comp, uint32_t *num_dbs)
 Get the current number of doorbells that are associated with the completion context. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_create_on_dpa (struct doca_devemu_pci_dev *pci_dev, struct doca_devemu_pci_db_completion *db_comp, uint8_t bar_id, uint64_t bar_start_addr, uint32_t db_id, uint64_t user_data_on_dpa, struct doca_devemu_pci_db **db)
 Allocate DOCA devemu PCI device doorbell on DPA. The created doorbell will be associated with a single completion context that was also created on DPA. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_destroy (struct doca_devemu_pci_db *db)
 Destroy the DOCA devemu PCI device doorbell. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_get_dpa_handle (struct doca_devemu_pci_db *db, doca_dpa_dev_devemu_pci_db_t *db_handle)
 Get the DPA handle for the DOCA devemu PCI device doorbell. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_start (struct doca_devemu_pci_db *db)
 Start DOCA devemu PCI device doorbell. A started doorbell will be able to trigger completions on the associated doorbell completion context. Therefore, in case the doorbell was created on DPA, one should bind the associated doorbell handle to its doorbell completion context before starting the doorbell. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_stop (struct doca_devemu_pci_db *db)
 Stop DOCA devemu PCI device doorbell. A stopped doorbell will not trigger completions on the associated doorbell completion context. Therefore, in case the doorbell was created on DPA, one should stop the doorbell before un-binding the associated doorbell handle from its doorbell completion context. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_modify_value (struct doca_devemu_pci_db *db, uint32_t db_value)
 Modify the current value of DOCA devemu PCI device doorbell. If the doorbell is started, this setting will behave as if the doorbell value was modified by the PCI device driver. If doorbell value will not be modified before starting the DOCA devemu PCI device doorbell, the device will keep the current value of the doorbell. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_query_value (struct doca_devemu_pci_db *db, uint32_t *db_value)
 Query the current value of DOCA devemu PCI device doorbell. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_msix_create_on_dpa (struct doca_devemu_pci_dev *pci_dev, uint8_t bar_id, uint64_t bar_start_addr, uint16_t msix_idx, uint64_t user_data_on_dpa, struct doca_devemu_pci_msix **msix)
 Allocate DOCA devemu PCI device MSI-X context on DPA. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_msix_destroy (struct doca_devemu_pci_msix *msix)
 Destroy the DOCA devemu PCI device MSI-X. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_msix_get_dpa_handle (struct doca_devemu_pci_msix *msix, doca_dpa_dev_devemu_pci_msix_t *msix_handle)
 Get the DPA handle for the DOCA devemu PCI device MSI-X. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_mmap_create (struct doca_devemu_pci_dev *pci_dev, struct doca_mmap **mmap)
 Allocates zero size memory map object with default/unset attributes associated with a DOCA devemu PCI device. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_get_available_resources (const struct doca_devinfo *devinfo, struct doca_devemu_pci_resources **pci_resources)
 Retrieve available PCI resources for device usage. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_release_resources (struct doca_devemu_pci_resources *pci_resources)
 Release the DOCA devemu PCI resources structure. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_resources_get_num_msix (const struct doca_devemu_pci_resources *pci_resources, uint32_t *num_msix)
 Retrieve the number of MSI-X vectors from a PCI resources structure. More...
 
DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_resources_get_num_db (const struct doca_devemu_pci_resources *pci_resources, uint32_t *num_db)
 Retrieve the number of Doorbells from a PCI resources structure. More...
 

Detailed Description

DOCA library for emulated PCI devices

Typedef Documentation

◆ doca_devemu_pci_dev_event_bar_stateful_region_driver_write_handler_cb_t

typedef void(* doca_devemu_pci_dev_event_bar_stateful_region_driver_write_handler_cb_t) (struct doca_devemu_pci_dev_event_bar_stateful_region_driver_write *event, union doca_data user_data)

Function to be executed on PCI write transactions to BAR stateful region.

Parameters
[in]eventThe BAR stateful region driver write event.
[in]user_dataSame user data that was provided in doca_devemu_pci_dev_event_bar_stateful_region_driver_write_register().

Definition at line 718 of file doca_devemu_pci.h.

◆ doca_devemu_pci_dev_event_flr_handler_cb_t

typedef void(* doca_devemu_pci_dev_event_flr_handler_cb_t) (struct doca_devemu_pci_dev *pci_dev, union doca_data user_data)

Function to be executed on PCI FLR (Function Level Reset). The event handler will enable users to quiesce, flush and reset the necessary resources associated with the emulated PCI device. Upon event, all PCI I/O transactions to/from the host memory are disabled. Additionally, the user should re-configure the emulated PCI device. This re-configuration requires flushing of all the outstanding resources associated with the emulated PCI device, which were initially owned by the PCI device and moved the the ownership of the user. The re-configuration also requires destruction of all the associated resources (e.g. DBs, MSIXs, MMAPs), resetting the associated emulated PCI device (perform stop() and start() operations) and re-creating all the needed resources.

Parameters
[in]pci_devThe DOCA devemu PCI device that is associated with the event.
[in]user_dataSame user data that was provided in doca_devemu_pci_dev_event_flr_register().

Definition at line 810 of file doca_devemu_pci.h.

◆ doca_devemu_pci_dev_event_hotplug_state_change_handler_cb_t

typedef void(* doca_devemu_pci_dev_event_hotplug_state_change_handler_cb_t) (struct doca_devemu_pci_dev *pci_dev, union doca_data user_data)

Function to be executed on hotplug state change event occurrence.

Parameters
[in]pci_devThe DOCA devemu PCI device that is associated with the event.
[in]user_dataSame user data that was provided in doca_devemu_pci_dev_event_hotplug_state_change_register().

Definition at line 669 of file doca_devemu_pci.h.

◆ doca_dpa_dev_devemu_pci_db_completion_t

typedef uint64_t doca_dpa_dev_devemu_pci_db_completion_t

DPA handle for emulated PCI device doorbell completion context.

Definition at line 69 of file doca_devemu_pci.h.

◆ doca_dpa_dev_devemu_pci_db_t

typedef uint64_t doca_dpa_dev_devemu_pci_db_t

DPA handle for emulated PCI device doorbell.

Definition at line 58 of file doca_devemu_pci.h.

◆ doca_dpa_dev_devemu_pci_msix_t

typedef uint64_t doca_dpa_dev_devemu_pci_msix_t

DPA handle for emulated PCI device MSI-X.

Definition at line 80 of file doca_devemu_pci.h.

Enumeration Type Documentation

◆ doca_devemu_pci_hotplug_state

enum doca_devemu_pci_hotplug_state

DOCA devemu pci hotplug state.

The steps for hotplug a device are:

  1. check the current hotplug state 1.1 if state == DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF then issue hotplug operation (call doca_devemu_pci_dev_hotplug()) and wait for transition to DOCA_DEVEMU_PCI_HP_STATE_POWER_ON. 1.2 if state == DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS then wait for transition to DOCA_DEVEMU_PCI_HP_STATE_POWER_ON. 1.3 if state == DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS then wait for transition to DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF and go to step 1.1. 1.4 if state == DOCA_DEVEMU_PCI_HP_STATE_POWER_ON then do nothing --> device is plugged.

The steps for hot unplug a device are:

  1. check the current hotplug state 1.1 if state == DOCA_DEVEMU_PCI_HP_STATE_POWER_ON then issue hot unplug operation (call doca_devemu_pci_dev_hotunplug()) and wait for transition to DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF. 1.2 if state == DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS then wait for transition to DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF. 1.3 if state == DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS then wait for transition to DOCA_DEVEMU_PCI_HP_STATE_POWER_ON and go to step 1.1 or issue hot unplug operation (call doca_devemu_pci_dev_hotunplug()) then wait for DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF. 1.4 if state == DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF then do nothing --> device is un-plugged.
Note
It is recommended to use doca_devemu_pci_dev_event_hotplug_state_change mechanism to get notifications on hotplug state changes.
Enumerator
DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF 

Device is powered off and not visible by the host. Device is in transitional state to become un-plugged from host.

DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS 

Device is in transitional state to become plugged to host.

DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS 

Device is powered on and visible by the host.

DOCA_DEVEMU_PCI_HP_STATE_POWER_ON 

Definition at line 566 of file doca_devemu_pci.h.

Function Documentation

◆ doca_devemu_pci_cap_get_max_hotplug_devices()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_cap_get_max_hotplug_devices ( const struct doca_devinfo *  devinfo,
uint32_t *  max_hotplug_devices 
)

Get the maximum number of PCI devices, across all PCI types, that can be hot-plugged by the device.

Parameters
[in]devinfoThe device to query.
[out]max_hotplug_devicesNumber of PCI devices that can be hot plugged by the device.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_DRIVER - internal doca driver error.

◆ doca_devemu_pci_cap_is_mmap_add_dev_supported()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_cap_is_mmap_add_dev_supported ( const struct doca_devinfo *  devinfo,
uint8_t *  supported 
)

Check if adding the device to a DOCA mmap associated with a DOCA devemu PCI device is supported.

Parameters
[in]devinfoThe device to query.
[out]supported1 if adding the device to a DOCA devemu PCI device associated DOCA mmap is supported, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - received invalid input.
  • DOCA_ERROR_DRIVER - internal doca driver error.

◆ doca_devemu_pci_db_completion_create()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_create ( struct doca_dpa_thread *  th,
struct doca_devemu_pci_db_completion **  db_comp 
)

Allocate DOCA devemu PCI device doorbell completion context on DPA. The created completion context will be associated with a single dpa thread.

Parameters
[in]thThe DOCA dpa thread to be associated with the completion context.
[out]db_compThe newly created DOCA devemu PCI device doorbell completion context.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_completion_destroy()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_destroy ( struct doca_devemu_pci_db_completion *  db_comp)

Destroy the DOCA devemu PCI device doorbell completion context.

The associated dpa handle will be destroyed as well.

Parameters
[in]db_compThe DOCA devemu PCI device doorbell completion context to destroy. Must be stopped.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_completion_get_curr_num_dbs()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_get_curr_num_dbs ( struct doca_devemu_pci_db_completion *  db_comp,
uint32_t *  num_dbs 
)

Get the current number of doorbells that are associated with the completion context.

Parameters
[in]db_compThe DOCA devemu PCI device doorbell completion context to query.
[out]num_dbsThe current number of doorbells that are associated with the context.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_completion_get_dpa_handle()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_get_dpa_handle ( struct doca_devemu_pci_db_completion *  db_comp,
doca_dpa_dev_devemu_pci_db_completion_t *  db_comp_handle 
)

Get the DPA handle for the DOCA devemu PCI device doorbell completion context.

Parameters
[in]db_compThe DOCA devemu PCI device doorbell completion context previously created on DPA.
[out]db_comp_handleA pointer to the associated DPA handle in the dpa memory space.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_completion_get_max_num_dbs()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_get_max_num_dbs ( struct doca_devemu_pci_db_completion *  db_comp,
uint32_t *  num_dbs 
)

Get the maximal number of doorbells that can be associated with the completion context.

Parameters
[in]db_compThe DOCA devemu PCI device doorbell completion context to query.
[out]num_dbsThe maximal number of doorbells that can be associated with the context.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_completion_set_max_num_dbs()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_set_max_num_dbs ( struct doca_devemu_pci_db_completion *  db_comp,
uint32_t  num_dbs 
)

Set the maximal number of doorbells that can be associated with the completion context.

Parameters
[in]db_compThe DOCA devemu PCI device doorbell completion context to modify. Must be stopped.
[in]num_dbsThe maximal number of doorbells that can be associated with the context.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_completion_start()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_start ( struct doca_devemu_pci_db_completion *  db_comp)

Start DOCA devemu PCI device doorbell completion context.

On start verifies and finalizes the completion context configuration.

The following is possible for started completion context:

  • Associating DOCA devemu PCI device doorbells with the completion context.

The following is NOT possible while completion context is started:

  • Setting the properties of the completion context
Parameters
[in]db_compThe DOCA devemu PCI device doorbell completion context to start.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_completion_stop()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_completion_stop ( struct doca_devemu_pci_db_completion *  db_comp)

Stop DOCA devemu PCI device doorbell completion context.

On stop prevents execution of different operations and allows operations that were available before start. For details, see doca_devemu_pci_db_completion_start(). Completion context can't be stopped while there are DOCA devemu PCI device doorbells associated with it.

The following is possible for stopped completion context:

  • Setting the properties of the completion context

The following is NOT possible while completion context is stopped:

  • Associating DOCA devemu PCI device doorbells with the completion context.
Parameters
[in]db_compThe DOCA devemu PCI device doorbell completion context to stop.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_create_on_dpa()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_create_on_dpa ( struct doca_devemu_pci_dev *  pci_dev,
struct doca_devemu_pci_db_completion *  db_comp,
uint8_t  bar_id,
uint64_t  bar_start_addr,
uint32_t  db_id,
uint64_t  user_data_on_dpa,
struct doca_devemu_pci_db **  db 
)

Allocate DOCA devemu PCI device doorbell on DPA. The created doorbell will be associated with a single completion context that was also created on DPA.

Parameters
[in]pci_devThe DOCA devemu PCI device to be associated with the doorbell. Must be started.
[in]db_compThe DOCA devemu PCI device doorbell completion context to be associated with the doorbell. Must be started.
[in]bar_idThe identifier of the BAR that contains the associated doorbell region for the created doorbell.
[in]bar_start_addrThe start address of the associated doorbell region within the BAR. This value must conform with the start address that was configured to the doorbell region during the configuration cycle of the PCI type that is associated with the given PCI device.
[in]db_idThe doorbell identifier that will be used to map the doorbell to its handler. This value must be in the range of [0, num_db - 1] when num_db is the number of doorbells configured to the associated DOCA devemu PCI device. The default num_db value configured for any DOCA devemu PCI device created by doca_devemu_pci_dev_create(), if not configured otherwise, is equal to the value returned in doca_devemu_pci_cap_type_get_max_num_db().
[in]user_data_on_dpaThe user data that is associated with and can be retrieved by the DOCA devemu PCI device doorbell DPA handle.
[out]dbThe newly created DOCA devemu PCI device doorbell.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_destroy()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_destroy ( struct doca_devemu_pci_db *  db)

Destroy the DOCA devemu PCI device doorbell.

If the doorbell was created on dpa, the associated dpa handle will be destroyed as well.

Parameters
[in]dbThe DOCA devemu PCI device doorbell to destroy. Must be stopped.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_get_dpa_handle()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_get_dpa_handle ( struct doca_devemu_pci_db *  db,
doca_dpa_dev_devemu_pci_db_t *  db_handle 
)

Get the DPA handle for the DOCA devemu PCI device doorbell.

Parameters
[in]dbThe DOCA devemu PCI device doorbell previously created on DPA.
[out]db_handleA pointer to the associated DPA handle in the dpa memory space.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_modify_value()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_modify_value ( struct doca_devemu_pci_db *  db,
uint32_t  db_value 
)

Modify the current value of DOCA devemu PCI device doorbell. If the doorbell is started, this setting will behave as if the doorbell value was modified by the PCI device driver. If doorbell value will not be modified before starting the DOCA devemu PCI device doorbell, the device will keep the current value of the doorbell.

Parameters
[in]dbThe DOCA devemu PCI device doorbell to modify.
[in]db_valueThe new value of the DOCA devemu PCI device doorbell.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_query_value()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_query_value ( struct doca_devemu_pci_db *  db,
uint32_t *  db_value 
)

Query the current value of DOCA devemu PCI device doorbell.

Parameters
[in]dbThe DOCA devemu PCI device doorbell to query.
[out]db_valueThe current value of the DOCA devemu PCI device doorbell.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_start()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_start ( struct doca_devemu_pci_db *  db)

Start DOCA devemu PCI device doorbell. A started doorbell will be able to trigger completions on the associated doorbell completion context. Therefore, in case the doorbell was created on DPA, one should bind the associated doorbell handle to its doorbell completion context before starting the doorbell.

Parameters
[in]dbThe DOCA devemu PCI device doorbell to start.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_db_stop()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_db_stop ( struct doca_devemu_pci_db *  db)

Stop DOCA devemu PCI device doorbell. A stopped doorbell will not trigger completions on the associated doorbell completion context. Therefore, in case the doorbell was created on DPA, one should stop the doorbell before un-binding the associated doorbell handle from its doorbell completion context.

Parameters
[in]dbThe DOCA devemu PCI device doorbell to stop.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_dev_as_ctx()

DOCA_EXPERIMENTAL struct doca_ctx* doca_devemu_pci_dev_as_ctx ( struct doca_devemu_pci_dev *  pci_dev)

Convert DOCA devemu PCI device instance into DOCA context.

Parameters
[in]pci_devDOCA devemu PCI device. The device must remain valid until after the returned DOCA context is no longer required.
Returns
DOCA context upon success, NULL otherwise.

◆ doca_devemu_pci_dev_create()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_create ( struct doca_devemu_pci_type *  pci_type,
struct doca_dev_rep *  dev_rep,
struct doca_pe *  progress_engine,
struct doca_devemu_pci_dev **  pci_dev 
)

Allocate DOCA devemu PCI device.

Parameters
[in]pci_typeThe DOCA PCI type to be associated with the device. Must be started.
[in]dev_repRepresentor DOCA device.
[in]progress_engineThe progress engine that will be used to receive events and task completions.
[out]pci_devThe newly created DOCA devemu PCI device.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_type', 'dev_rep', 'progress_engine' or 'pci_dev' are NULL. Or representor type does not match the PCI type
  • DOCA_ERROR_NO_MEMORY - allocation failure

◆ doca_devemu_pci_dev_destroy()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_destroy ( struct doca_devemu_pci_dev *  pci_dev)

Free a DOCA devemu PCI device.

Parameters
[in]pci_devThe previously created DOCA devemu PCI device. Must be idle.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:

◆ doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_id()

DOCA_EXPERIMENTAL uint8_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_id ( struct doca_devemu_pci_dev_event_bar_stateful_region_driver_write *  event)

Get the BAR id from BAR stateful region driver write event.

Parameters
[in]eventThe registered BAR stateful region driver write event. Must not be NULL.
Returns
The BAR id that is associated with the event.

◆ doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_region_start_addr()

DOCA_EXPERIMENTAL uint64_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_bar_region_start_addr ( struct doca_devemu_pci_dev_event_bar_stateful_region_driver_write *  event)

Get the BAR region start address that is associated with BAR stateful region driver write event.

Parameters
[in]eventThe registered BAR stateful region driver write event. Must not be NULL.
Returns
The start address of the BAR stateful region that is associated with the event.

◆ doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_pci_dev()

DOCA_EXPERIMENTAL struct doca_devemu_pci_dev* doca_devemu_pci_dev_event_bar_stateful_region_driver_write_get_pci_dev ( struct doca_devemu_pci_dev_event_bar_stateful_region_driver_write *  event)

Get DOCA devemu PCI device from BAR stateful region driver write event.

Parameters
[in]eventThe registered BAR stateful region driver write event. Must not be NULL.
Returns
The DOCA devemu PCI device associated with the event.

◆ doca_devemu_pci_dev_event_bar_stateful_region_driver_write_register()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_event_bar_stateful_region_driver_write_register ( struct doca_devemu_pci_dev *  pci_dev,
doca_devemu_pci_dev_event_bar_stateful_region_driver_write_handler_cb_t  handler,
uint8_t  bar_id,
uint64_t  bar_region_start_addr,
union doca_data  user_data 
)

Register to BAR stateful region driver write event.

Registration can be done only while DOCA devemu PCI device is idle. If called multiple times, for the same {pci_dev, bar_id, bar_region_start_addr} tuple, then only the last call will take effect. The registration will be valid for the entire stateful region that was configured for the associated DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device to be associated with the event. Must be idle.
[in]handlerMethod that is invoked once event is triggered.
[in]bar_idThe BAR id to be associated with the event. Must conform with the BAR stateful region configuration that was done using doca_devemu_pci_type_set_bar_stateful_region_conf().
[in]bar_region_start_addrThe start address of the BAR stateful region to be associated with the event. Must conform with the BAR stateful region configuration that was done using doca_devemu_pci_type_set_bar_stateful_region_conf().
[in]user_dataUser data that will be provided to the handler once invoked.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'handler' are NULL
  • DOCA_ERROR_BAD_STATE - PCI device is not idle

◆ doca_devemu_pci_dev_event_flr_register()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_event_flr_register ( struct doca_devemu_pci_dev *  pci_dev,
doca_devemu_pci_dev_event_flr_handler_cb_t  handler,
union doca_data  user_data 
)

Register to PCI FLR (Function Level Reset) event.

Parameters
[in]pci_devThe DOCA devemu PCI device to be associated with the event. Must be idle.
[in]handlerMethod that is invoked once event is triggered.
[in]user_dataUser data that will be provided to the handler once invoked.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'handler' are NULL
  • DOCA_ERROR_BAD_STATE - PCI device is not idle

◆ doca_devemu_pci_dev_event_hotplug_state_change_register()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_event_hotplug_state_change_register ( struct doca_devemu_pci_dev *  pci_dev,
doca_devemu_pci_dev_event_hotplug_state_change_handler_cb_t  handler,
union doca_data  user_data 
)

Register to hotplug state changes.

Registration can be done only while DOCA devemu PCI device is idle. If called multiple times then only the last call will take effect.

Parameters
[in]pci_devThe DOCA devemu PCI device to be associated with the event. Must be idle.
[in]handlerMethod that is invoked once event is triggered.
[in]user_dataUser data that will be provided to the handler once invoked.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'handler' are NULL
  • DOCA_ERROR_BAD_STATE - PCI device is not idle

◆ doca_devemu_pci_dev_get_class_code()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_class_code ( const struct doca_devemu_pci_dev *  pci_dev,
uint32_t *  class_code 
)

Get the PCI Class Code configured to DOCA devemu PCI device to identify generic operation.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to query.
[out]class_codeThe PCI Class Code to identify generic operation. Only 24 LSBits are valid.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'class_code' are NULL

◆ doca_devemu_pci_dev_get_device_id()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_device_id ( const struct doca_devemu_pci_dev *  pci_dev,
uint16_t *  device_id 
)

Get the PCI Device ID configured to DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to query.
[out]device_idThe PCI Device ID (DID) assigned by the vendor.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'device_id' are NULL

◆ doca_devemu_pci_dev_get_hotplug_state()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_hotplug_state ( struct doca_devemu_pci_dev *  pci_dev,
enum doca_devemu_pci_hotplug_state *  state 
)

Get the hotplug state of the DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device. Must be started.
[out]stateThe hotplug state of the given DOCA devemu PCI device.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'state' are NULL
  • DOCA_ERROR_BAD_STATE - PCI device is not started

◆ doca_devemu_pci_dev_get_num_msix()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_num_msix ( const struct doca_devemu_pci_dev *  pci_dev,
uint16_t *  num_msix 
)

Get the number of MSI-X vectors configured to DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to query.
[out]num_msixThe number of MSI-X vectors configured for the device.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'num_msix' is NULL

◆ doca_devemu_pci_dev_get_revision_id()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_revision_id ( const struct doca_devemu_pci_dev *  pci_dev,
uint8_t *  revision_id 
)

Get the PCI Revision ID configured to DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to query.
[out]revision_idThe PCI Revision ID assigned by the vendor.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'revision_id' are NULL

◆ doca_devemu_pci_dev_get_subsystem_id()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_subsystem_id ( const struct doca_devemu_pci_dev *  pci_dev,
uint16_t *  subsystem_id 
)

Get the PCI Subsystem ID configured to DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to query.
[out]subsystem_idThe PCI Subsystem ID (SSID) assigned by the subsystem vendor.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'subsystem_id' are NULL

◆ doca_devemu_pci_dev_get_subsystem_vendor_id()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_subsystem_vendor_id ( const struct doca_devemu_pci_dev *  pci_dev,
uint16_t *  subsystem_vid 
)

Get the PCI Subsystem Vendor ID configured to DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to query.
[out]subsystem_vidThe PCI Subsystem Vendor ID (SVID) assigned by the subsystem vendor.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'subsystem_vid' are NULL

◆ doca_devemu_pci_dev_get_vendor_id()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_get_vendor_id ( const struct doca_devemu_pci_dev *  pci_dev,
uint16_t *  vendor_id 
)

Get the PCI Vendor ID configured to DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to query.
[out]vendor_idThe PCI Vendor ID (VID) assigned by the vendor.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'vendor_id' are NULL

◆ doca_devemu_pci_dev_hotplug()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_hotplug ( struct doca_devemu_pci_dev *  pci_dev)

Issue hotplug procedure of the DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device to hotplug. Must be started.
Returns
DOCA_SUCCESS - in case of success. On success, pci_dev is at DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS state. Event will not be raised in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
  • DOCA_ERROR_BAD_STATE - PCI device is not started, or hotplug state is not DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF
  • DOCA_ERROR_DRIVER - internal doca driver error
  • DOCA_ERROR_NOT_SUPPORTED - The DOCA device that was set does not support hotplug, use doca_devemu_pci_cap_type_is_hotplug_supported() to find device that supports it
  • DOCA_ERROR_AGAIN - host system is not ready, try again later

◆ doca_devemu_pci_dev_hotunplug()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_hotunplug ( struct doca_devemu_pci_dev *  pci_dev)

Issue hot unplug procedure of the DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device to hot unplug. Must be started.
Returns
DOCA_SUCCESS - in case of success. On success, pci_dev is at DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS state. Event will not be raised in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
  • DOCA_ERROR_BAD_STATE - PCI device is not started, or current hotplug state is not one of DOCA_DEVEMU_PCI_HP_STATE_POWER_ON or DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS
  • DOCA_ERROR_DRIVER - internal doca driver error
  • DOCA_ERROR_NOT_SUPPORTED - The DOCA device that was set does not support hot unplug, use doca_devemu_pci_cap_type_is_hotplug_supported() to find device that supports it
  • DOCA_ERROR_AGAIN - host system is not ready, try again later

◆ doca_devemu_pci_dev_is_flr()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_is_flr ( const struct doca_devemu_pci_dev *  pci_dev,
uint8_t *  flr 
)

Query wheather the DOCA devemu PCI device is having FLR (Function Level Reset).

If true, all PCI I/O transactions to/from the host memory are disabled and the user should re-configure the emulated PCI device. This re-configuration requires destruction of all the associated resources (e.g. DBs, MSIXs, MMAPs), resetting the associated emulated PCI device (perform stop() and start() operations) and re-creating all the needed resources.

Parameters
[in]pci_devThe DOCA devemu PCI device to query. Must be started.
[out]flr1 if the DOCA devemu PCI device is having FLR, 0 otherwise.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' or 'flr' are NULL.
  • DOCA_ERROR_BAD_STATE - PCI device is not started.

◆ doca_devemu_pci_dev_modify_bar_stateful_region_default_values()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_modify_bar_stateful_region_default_values ( struct doca_devemu_pci_dev *  pci_dev,
uint8_t  id,
uint64_t  start_addr,
void *  default_values,
uint64_t  size 
)

Modify default registers values for stateful region in a DOCA devemu PCI device.

This method will modify the default values for the entire stateful region registers area in a PCI device BAR (before the first modification, the initial default values of the stateful region registers are taken from the associated PCI type). These values will override the previous default values and will become valid during the next exposure/hotplug of the associated PCI device to the host or during the next FLR.

Parameters
[in]pci_devThe DOCA devemu PCI device. Must be started.
[in]idThe BAR id that contains the stateful region.
[in]start_addrThe start address of the region within the BAR. This value must conform with the start address provided during doca_devemu_pci_type_set_bar_stateful_region_conf().
[in]default_valuesInput buffer that contain the default values data.
[in]sizeThe size of the default_values buffer in bytes. The size must not be smaller than the actual size of the stateful bar region that was configured using doca_devemu_pci_type_set_bar_stateful_region_conf(). If size is bigger than the actual size, the first relevant bytes will be used according to the actual size. The rest of the buffer will be ignored.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_dev_modify_bar_stateful_region_values()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_modify_bar_stateful_region_values ( struct doca_devemu_pci_dev *  pci_dev,
uint8_t  id,
uint64_t  offset,
void *  values,
uint64_t  size 
)

Modify registers values for stateful region in a DOCA devemu PCI device.

This method will modify the values of the stateful region registers in a PCI device BAR. These values will override the existing values of the stateful region of the associated PCI device. Modifying registers by calling this method will not trigger the registered event handler of the doca_devemu_pci_dev_event_bar_stateful_region_driver_write event.

Parameters
[in]pci_devThe DOCA devemu PCI device. Must be started.
[in]idThe BAR id that contains the stateful region.
[in]offsetThe offset of the registers region to modify within the BAR. Must be located within the stateful BAR region.
[in]valuesInput buffer that contain the values data.
[in]sizeThe size of the values buffer in bytes. The (offset + size) must be located within the stateful BAR region.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_dev_query_bar_stateful_region_values()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_query_bar_stateful_region_values ( struct doca_devemu_pci_dev *  pci_dev,
uint8_t  id,
uint64_t  offset,
void *  out_values,
uint64_t  size 
)

Query registers values of the stateful region in a DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device. Must be started.
[in]idThe BAR id that contains the stateful region.
[in]offsetThe offset of the registers region to query within the BAR. Must be located within the stateful BAR region.
[out]out_valuesOutput buffer that will contain the values data upon success.
[in]sizeThe size of the out_values buffer in bytes. The (offset + size) must be located within the stateful BAR region.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_dev_set_class_code()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_class_code ( struct doca_devemu_pci_dev *  pci_dev,
uint32_t  class_code 
)

Set the PCI Class Code of a specific DOCA devemu PCI device to identify generic operation.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
[in]class_codeThe PCI Class Code to identify generic operation. Only 24 LSBits are valid.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
  • DOCA_ERROR_BAD_STATE - pci_dev is not idle.
  • DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

◆ doca_devemu_pci_dev_set_device_id()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_device_id ( struct doca_devemu_pci_dev *  pci_dev,
uint16_t  device_id 
)

Set the PCI Device ID of a specific DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
[in]device_idThe PCI Device ID (DID) to assign.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
  • DOCA_ERROR_BAD_STATE - pci_dev is not idle.
  • DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

◆ doca_devemu_pci_dev_set_num_msix()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_num_msix ( struct doca_devemu_pci_dev *  pci_dev,
uint16_t  num_msix 
)

Set the number of MSI-X vectors of a specific DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
[in]num_msixThe number of MSI-X vectors to be configured for the device. This value must conform with device capabilities.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
  • DOCA_ERROR_BAD_STATE - device is not idle
  • DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

◆ doca_devemu_pci_dev_set_revision_id()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_revision_id ( struct doca_devemu_pci_dev *  pci_dev,
uint8_t  revision_id 
)

Set the PCI Revision ID of a specific DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
[in]revision_idThe PCI Revision ID to assign.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
  • DOCA_ERROR_BAD_STATE - pci_dev is not idle.
  • DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

◆ doca_devemu_pci_dev_set_subsystem_id()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_subsystem_id ( struct doca_devemu_pci_dev *  pci_dev,
uint16_t  subsystem_id 
)

Set the PCI Subsystem ID of a specific DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
[in]subsystem_idThe PCI Subsystem ID (SSID) to assign.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
  • DOCA_ERROR_BAD_STATE - pci_dev is not idle.
  • DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

◆ doca_devemu_pci_dev_set_subsystem_vendor_id()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_subsystem_vendor_id ( struct doca_devemu_pci_dev *  pci_dev,
uint16_t  subsystem_vid 
)

Set the PCI Subsystem Vendor ID of a specific DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
[in]subsystem_vidThe PCI Subsystem Vendor ID (SVID) to assign.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
  • DOCA_ERROR_BAD_STATE - pci_dev is not idle.
  • DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

◆ doca_devemu_pci_dev_set_vendor_id()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_dev_set_vendor_id ( struct doca_devemu_pci_dev *  pci_dev,
uint16_t  vendor_id 
)

Set the PCI Vendor ID of a specific DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device instance to modify. Must be idle and not a static Physical Function (PF).
[in]vendor_idThe PCI Vendor ID (VID) to assign.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_dev' is NULL
  • DOCA_ERROR_BAD_STATE - pci_dev is not idle.
  • DOCA_ERROR_NOT_PERMITTED - device is a static Physical Function (PF).

◆ doca_devemu_pci_get_available_resources()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_get_available_resources ( const struct doca_devinfo *  devinfo,
struct doca_devemu_pci_resources **  pci_resources 
)

Retrieve available PCI resources for device usage.

The returned structure represents the PCI resources that can be utilized by all DOCA devemu PCI devices and PCI types associated with the specified device. These resources are global and shared across all supported devices. The distribution of the available resources should comply with the relevant capabilities.

Parameters
[in]devinfoThe device to query.
[out]pci_resourcesThe newly created DOCA devemu PCI resources structure.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.
Note
The returned structure must be deallocated using doca_devemu_pci_release_resources() to prevent memory leaks.

◆ doca_devemu_pci_mmap_create()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_mmap_create ( struct doca_devemu_pci_dev *  pci_dev,
struct doca_mmap **  mmap 
)

Allocates zero size memory map object with default/unset attributes associated with a DOCA devemu PCI device.

The returned memory map object can be manipulated with common doca_mmap APIs.

The created memory map object will cover a memory range in the domain that hosts the DOCA devemu PCI device.

Parameters
[in]pci_devThe DOCA devemu PCI device to be associated with the doca_mmap. Must be started.
[out]mmapDOCA memory map structure with default/unset attributes.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_msix_create_on_dpa()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_msix_create_on_dpa ( struct doca_devemu_pci_dev *  pci_dev,
uint8_t  bar_id,
uint64_t  bar_start_addr,
uint16_t  msix_idx,
uint64_t  user_data_on_dpa,
struct doca_devemu_pci_msix **  msix 
)

Allocate DOCA devemu PCI device MSI-X context on DPA.

Parameters
[in]pci_devThe DOCA devemu PCI device to be associated with the MSI-X. Must be started.
[in]bar_idThe identifier of the BAR that contains the associated MSI-X table region for the created msix. This value must conform with the identifier that was configured to the MSI-X table region during the configuration cycle of the pci type that is associated with the given PCI device.
[in]bar_start_addrThe start address of the associated MSI-X table region within the BAR. This value must conform with the start address that was configured to the MSI-X table region during the configuration cycle of the PCI type that is associated with the given PCI device.
[in]msix_idxThe associated MSI-X table entry index.
[in]user_data_on_dpaThe user data that is associated with and can be retrieved by the DOCA devemu PCI device MSI-X DPA handle.
[out]msixThe newly created DOCA devemu PCI device MSI-X.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_msix_destroy()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_msix_destroy ( struct doca_devemu_pci_msix *  msix)

Destroy the DOCA devemu PCI device MSI-X.

If the MSI-X was created on dpa, the associated dpa handle will be destroyed as well.

Parameters
[in]msixThe DOCA devemu PCI device MSI-X context to destroy.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_msix_get_dpa_handle()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_msix_get_dpa_handle ( struct doca_devemu_pci_msix *  msix,
doca_dpa_dev_devemu_pci_msix_t *  msix_handle 
)

Get the DPA handle for the DOCA devemu PCI device MSI-X.

Parameters
[in]msixThe DOCA devemu PCI device MSI-X previously created on DPA.
[out]msix_handleA pointer to the associated DPA handle in the dpa memory space.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_release_resources()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_release_resources ( struct doca_devemu_pci_resources *  pci_resources)

Release the DOCA devemu PCI resources structure.

Parameters
[in]pci_resourcesPCI resources structure to be released.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure. see doca_error_t.

◆ doca_devemu_pci_rep_get_hotplug_state()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_rep_get_hotplug_state ( struct doca_dev_rep *  rep_dev,
enum doca_devemu_pci_hotplug_state *  state 
)

Get the hotplug state of a DOCA representor device.

The specified representor device should be a hotplug device, which can be verified using doca_devinfo_rep_get_is_hotplug(). Upon success, the current hotplug state is returned.

Parameters
[in]rep_devDOCA representor device instance.
[out]stateThe hotplug state of the given DOCA representor device.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'rep_dev' or 'state' are NULL
  • DOCA_ERROR_NOT_PERMITTED - 'rep_dev' is not a hotplug device

◆ doca_devemu_pci_resources_get_num_db()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_resources_get_num_db ( const struct doca_devemu_pci_resources *  pci_resources,
uint32_t *  num_db 
)

Retrieve the number of Doorbells from a PCI resources structure.

Parameters
[in]pci_resourcesThe DOCA devemu PCI resources instance to query.
[out]num_dbThe number of Doorbells associated with PCI resources structure.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_resources' or 'num_db' is NULL

◆ doca_devemu_pci_resources_get_num_msix()

DOCA_EXPERIMENTAL doca_error_t doca_devemu_pci_resources_get_num_msix ( const struct doca_devemu_pci_resources *  pci_resources,
uint32_t *  num_msix 
)

Retrieve the number of MSI-X vectors from a PCI resources structure.

Parameters
[in]pci_resourcesThe DOCA devemu PCI resources instance to query.
[out]num_msixThe number of MSI-X vectors associated with PCI resources structure.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - 'pci_resources' or 'num_msix' is NULL