Metadata-Version: 2.1
Name: dpa-resource-mgmt
Version: 25.10.161
Summary: A package for DPA resource management
Author: Vadim Artishchev
Author-email: vadima@nvidia.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD-3-Clause
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown

# Single Point of Resource Distribution (SPRD) tool
===================================================

This tool with name **dpa-resource-mgmt** provides system admins with the ability to query and
distribute DPA resources between device functions and running applications. The tool gets a YAML
input file describing the resources to distribute and porvides an output YAML file with the per
DPA application information. The output YAML file may later be consumed by DPA applciaitons for
dynamic resource distribution.
The tool is a part of the **dpa-resource-mgmt** package and operates with its backend **dpaeumgmt**.

## Supported Operations
-----------------------

SPRD tool supports the following operations:
### Query
---------
query - queries the device for its functions and resources and exit
usage: dpa-resource-mgmt query [-h] -d DEVICE -t {chip,vhca,resources} [-f FILENAME] [-y] [-v]

Only query device info

optional arguments:
  -h, --help            show this help message and exit
  -d DEVICE, --device DEVICE
                        ibv device name. Mandatory parameter.
  -t {chip,vhca}, --type {chip,vhca}
                        output data type. Mandatory parameter.
  -f FILENAME, --filename FILENAME
                        Output filename. By default is stdout.
  -y, --yaml-format     Output format. By default - human-readable
  -v, --verbose         show commands of the tool. Optional parameter.


### Clear
---------
clear - clear previously allocated configuration
usage: dpa-resource-mgmt clear [-h] -d DEVICE [-v]

Clear previously allocated configuration

optional arguments:
  -h, --help            show this help message and exit
  -d DEVICE, --device DEVICE
                        ibv device name. Mandatory parameter.
  -v, --verbose         show commands of the tool. Optional parameter.


### Config
----------
config - create partitions and EU groups and per DPA application distribution
                           according to the input YAML file.

usage: dpa-resource-mgmt config [-h] -d DEVICE -f FILENAME [-o OUTPUT] [-v]

Config Chip performs the following operations:
- Check chip status – Verifies if the chip is empty (i.e., no partitions, groups, or
  running processes).
- Read hardware information – Retrieves details about VHCA and DPA resources.
- Parse input YAML file – Reads and validates the configuration for correctness.
- Configure partitions and groups – Applies the settings based on the YAML file.
- Generate output YAML files – Creates configuration files reflecting the applied settings.

optional arguments:
  -h, --help            show this help message and exit
  -d DEVICE, --device DEVICE
                        ibv device name. Mandatory parameter.
  -f FILENAME, --filename FILENAME
                        name of configuration YAML file. Mandatory parameter.
  -o OUTPUT, --output OUTPUT
                        the template for output files. Optional parameter.
  -v, --verbose         show commands of the tool. Optional parameter.


### Version
 -----------
 - version - print current version of the tool

## Examples of usage

### Query VHCA information:
$ dpa-resource-mgmt query -t vhca -d mlx5_0


└── VHCA_ID = 0x1
    FUNCTION_TYPE = ECPF
    PCI_BDF = 80:00.0
    VPORT_ID = 0x0
        │
        ├── VHCA_ID = 0x2
        │   FUNCTION_TYPE = PF
        │   PCI_BDF = 80:00.1
        │   VPORT_ID = 0x0
        │
        ├── VHCA_ID = 0x3
        │   FUNCTION_TYPE = PF
        │   PCI_BDF = 80:00.2
        │   VPORT_ID = 0x0
        │
        ├── VHCA_ID = 0x4
        │   FUNCTION_TYPE = PF
        │   PCI_BDF = 80:00.3
        │   VPORT_ID = 0x0
        │
...

### Query DPA chip information:
$ dpa-resource-mgmt query -t chip -d mlx5_0

Maximal number of DPA EU per group (max_num_dpa_eu_per_group): 190
Maximal number of DPA EU partitions (max_num_dpa_eu_partitions): 15
Maximal number of VHCAs associated with a single partition (max_num_partition_vhca_id): 32
Maximal number of DPA processes (max_processes): 124
Maximal number of DPA threads (max_threads): 65536
Maximal number of DPA threads per process (max_threads_per_process): 16384
DPA thread stack size (thread_stack_size): 8192
Maximal number of EU groups (max_eu_groups): 16
Maximal number of active DPA EU groups (max_num_dpa_eu): 190
Heap maximal size (heap_max_size): 1073741824
Number of cores (num_cores): 12
Cores:
    ├── Core ID 0
    │   EUs number 16
    │   EUs IDs 0-15
    │   EUs indexes 0-15
    │
    ├── Core ID 1
    │   EUs number 16
    │   EUs IDs 16-31
    │   EUs indexes 0-15
    │
    ├── Core ID 2
    │   EUs number 16
    │   EUs IDs 32-47
    │   EUs indexes 0-15
    │
...

### Query DPA resource information:
$ dpa-resource-mgmt query -t resources -d mlx5_0

Free EUs in ROOT partition 0-3,9-15,30,31,40-47,67-79,112-159,169
Cores available for use in ROOT partition 0-2,4,7-9,14
Free EUs in ROOT partition with groups 0-3,9-15,30,31,40-47,67-79,112-159,162-189
Cores available for use ROOT partition with groups 0-2,4,7-9,14,15
│
├── PARTITIONS:
│   │
│   ├── PARTITION_1:
│   │   partition_id: 1
│   │   vhca_id: 5
│   │   Range of EUs: 4-8,16-29,32-39
│   │   Cores in use: 0-2
│   │   GROUPS:
│   │   │
│   │   ├── name: EU1
│   │   │   group_id: 1
│   │   │   abs_EUs: 16,17,20-22,32
│   │   │   Relative EUs: 16,17,20-22,32
│   │   │   Cores in use: 1,2
│   │   │
│   │   └── name: EU1_1
│   │       group_id: 2
│   │       abs_EUs: 26-28
│   │       Relative EUs: 26-28
│   │       Cores in use: 1
│   │
│   ├── PARTITION_2:
│   │   partition_id: 2
│   │   vhca_id: 2
│   │   Range of EUs: 48-66
│   │   Cores in use: 3,4
│   │   GROUPS:
│   │   │
│   │   └── name: EU2
│   │       group_id: 1
│   │       abs_EUs: 48-51,64
│   │       Relative EUs: 48-51,64
│   │       Cores in use: 3,4
│   │
│   └── PARTITION_3:
│       partition_id: 3
│       vhca_id: 3,4,9-13
│       Range of EUs: 80-111,160,161
│       Cores in use: 5,6,14
│       GROUPS:
│       │
│       └── name: EU3
│           group_id: 1
│           abs_EUs: 80-96
│           Relative EUs: 80-96
│           Cores in use: 5,6
│
└── ROOT_PARTITION_GROUPS:
    │
    ├── name: RG0
    │   group_id: 1
    │   abs_EUs: 170-189
    │   Cores in use: 14,15
    │
    └── name: RG1
        group_id: 2
        abs_EUs: 162-168
        Cores in use: 14

Core's information:
├── Core #0, with 16 EUs, has 11 EUs available: 0-3,9-15.
├── Core #1, with 16 EUs, has 2 EUs available: 30,31.
├── Core #2, with 16 EUs, has 8 EUs available: 40-47.
├── Core #3, with 16 EUs, is fully utilized.
├── Core #4, with 16 EUs, has 13 EUs available: 67-79.
├── Core #5, with 16 EUs, is fully utilized.
├── Core #6, with 16 EUs, is fully utilized.
├── Core #7, with 16 EUs, is fully available.
├── Core #8, with 16 EUs, is fully available.
├── Core #9, with 16 EUs, is fully available.
├── Core #14, with 16 EUs, has one EU available: 169.
└── Core #15, with 14 EUs, is fully utilized.

VHCA information:
    10 unutilized VHCAs: 6-8,14-20


### Clear previously allocated configuration:
$ dpa-resource-mgmt clear -d mlx5_0
Successfully destroyed all partitions and groups.

### Config
$ dpa-resource-mgmt config -f config.yaml -d mlx5_0 -v

sudo /opt/mellanox/doca/tools/dpaeumgmt version
sudo /opt/mellanox/doca/tools/dpaeumgmt info status --dpa_device mlx5_0
sudo /opt/mellanox/doca/tools/dpaeumgmt info vhca --dpa_device mlx5_0
sudo /opt/mellanox/doca/tools/dpaeumgmt info chip --dpa_device mlx5_0
sudo /opt/mellanox/doca/tools/dpaeumgmt partition info --dpa_device mlx5_0
sudo /opt/mellanox/doca/tools/dpaeumgmt eu_group info --dpa_device mlx5_0
sudo /opt/mellanox/doca/tools/dpaeumgmt partition create --dpa_device mlx5_0 --vhca_list 5 --range_eus 4-8,16-29,32-39 --max_num_eu_group 2
sudo /opt/mellanox/doca/tools/dpaeumgmt partition create --dpa_device mlx5_0 --vhca_list 2 --range_eus 48-66 --max_num_eu_group 1
sudo /opt/mellanox/doca/tools/dpaeumgmt partition create --dpa_device mlx5_0 --vhca_list 3,4,9-13 --range_eus 80-111,160,161 --max_num_eu_group 1
sudo /opt/mellanox/doca/tools/dpaeumgmt eu_group create --dpa_device mlx5_0 --range 5,6,9-11,19 --id_partition 1 --name_group EU1
sudo /opt/mellanox/doca/tools/dpaeumgmt eu_group create --dpa_device mlx5_0 --range 15-17 --id_partition 1 --name_group EU1_1
sudo /opt/mellanox/doca/tools/dpaeumgmt eu_group create --dpa_device mlx5_0 --range 0-3,16 --id_partition 2 --name_group EU2
sudo /opt/mellanox/doca/tools/dpaeumgmt eu_group create --dpa_device mlx5_0 --range 0-16 --id_partition 3 --name_group EU3
sudo /opt/mellanox/doca/tools/dpaeumgmt eu_group create --dpa_device mlx5_0 --range 170-188 --name_group RG0
sudo /opt/mellanox/doca/tools/dpaeumgmt eu_group create --dpa_device mlx5_0 --range 162-168 --name_group RG1

## Format of the input YAML file
--------------------------------

The input YAML file divided by two parts - partition's part and application part.

### Partition's Part
--------------------

Partition's part contain version, partitions and root_partition_groups sections.

##### Example:
------------
version: 25.04
partitions:
   ARM:
      vhca_id: 5
      EU_allocation:
         - abs_EUs: 4-8
         - core: 1
           num_EUs: 14
         - core: 2
           num_EUs: 8
      groups:
         - name: EU1
           EUs:
              - abs_EUs: 16,17,20-22
              - core: 2
                num_EUs: 1
         - name: EU1_1
           EUs:
              - abs_EUs: 26-28
   HOSTx86:
      vhca_id: 2
      EU_allocation:
         - core: 3
           num_EUs: 16
         - core: 4
           num_EUs: 3
      groups:
        name: EU2
        EUs:
          - core: 3
            num_EUs: 4
          - core: 4
            num_EUs: 1
root_partition_groups:
  - name: RG0
    EUs:
      - abs_EUs: 170-188
  - name: RG1
    EUs:
      - core: 14
        num_EUs: 7


#### version
------------
Mandatory section. Specifies the version of the input YAML file.

#### partitions
---------------
Optional section, but mostly used.
This section defines partitions, their VHCA IDs, EU allocations,
and groups with assigned execution units (EUs).
All unassigned EUs will be automatically assigned to the ROOT (default) partition.

##### Structure Overview
------------------------
The configuration consists of:
1. partitions - Define computing partitions like ARM, HOSTx86, etc.
2. vhca_id - Assigns a VHCA (Virtual Host Channel Adapter) to each partition. Root
   vhca_id cannot be assigned to partition (it already used by default partition).
   It will be passed as --vhca_list/-v to dpaeumgmt partition create command.
3. EU_allocation - Assigns execution units (EUs) either by absolute ID or by core.
   Will be passed as --range_eus/-r to dpaeumgmt partition create command.
4. groups - Define sub-allocations of EUs within a partition.
   Number of the groups Will be passed as --max_num_eu_group/-m to dpaeumgmt partition create
   command.

##### partitions
----------------
Section defining multiple partitions.
Each partition have its name.

##### vhca_id
-------------
The VHCA ID assigned to the partition.
Format can include:
  - A single number (e.g., 2).
  - An array (e.g., [2,3]).
  - A list of numbers (e.g., 2,3,5).
  - A range of numbers (e.g., 2-6).
  - A mixed format combining ranges and individual numbers (e.g., 2-9,11).

##### EUs
---------
Defines how Execution Units (EUs) are allocated.
Each EU or EU group can be assigned in two ways:
- abs_EUs – Absolute EU numbers. The format can include:
  - A single number (e.g., 7).
  - An array (e.g., [7,8]).
  - A list of numbers (e.g., 7,8,9).
  - A range of numbers (e.g., 7-9).
  - A mixed format combining ranges and individual numbers (e.g., 7-9,11).
- Core-based assignment (core/num_EUs) – A pair of values:
  - core – Core ID.
  - num_EUs – The number of EUs to be used.
      num_EUs cannot exceed the total number of EUs available in the specified core.
      The dpa-resource-tool attempts to reserve num_EUs free EUs within the given core.

##### groups
------------
Defines named groups within a partition that allocate specific EUs.

Each group within a partition has a unique name and a unique set of EUs within that
partition, similar to how EUs are uniquely assigned within a partition.
 1. Name - Assign the name of the group in the partition.
    It will be passed as --name_group/-n to dpaeumgmt eu_group create command.
3. EU_allocation - Assigns execution units (EUs) either by absolute ID or by core.
   Will be passed as --range_eus/-r to dpaeumgmt eu_group create command.

#### root_group_partition
-------------------------
Optional section.
Defines named groups within the ROOT (default) partition that allocate specific EUs.
The format follows the same structure as groups.

### Application's Part
----------------------
Application's part describe a list of the applications.

##### Example:
--------------
DPA_APPS:
  APP1:
    - partition: ARM
      affinity_EUs: [35, 37-39]
      affinity_core:
        - core: 1
          num_EUs: 4
      groups: [EU1, EU1_1]
    - partition: HOSTx86
      affinity_EUs: [61, 62]
      groups: EU2
    - partition: ROOT
      groups: RG0
      affinity_core:
        - core: 0
          num_EUs: 2
      affinity_EUs: [190, 191]
  APP2:
    - partition: HOSTx86
      affinity_EUs: [63]
      groups: EU2

##### Structure Overview
------------------------
The configuration consists of the following sections:
1. DPA_APPS - Defines applications and their partition configurations.
2. <App_Name> - Application name (APP1, APP2, etc.).
3. Partition Assignments (partition) - Specifies where the application runs.
4. Affinity Execution Units (affinity_EUs) - Defines EUs assigned to the application.
5. Affinity Execution Units by Cores (affinity_cores) - Defines EUs by a pairs
  of values (core/num_EUs) assigned to the application.
6. Groups (groups) - Lists the EU groups assigned to the application.

## Output YAML files
--------------------
After successful run dpa-resource-mgmt tool produce output files, each per partition with partition
name.
The user is responsible for correctly distributing these files across partitions. Since partitions
are assigned based on vhca_id, the user can determine the appropriate device using its PCI BDF
address and copy or use the file on the required device.

If a partition includes multiple vhca_id, the same file will be used on multiple child devices.

### Example:
------------
version: 25.04
DPA_APPS:
  - name: APP1
    number_of_groups: 1
    # EU2
    groups: [1]
    number_of_affinity_EUs: 2
    affinity_EUs: [5, 6, 7, 8, 9, 13, 14]
  - name: APP2
    number_of_groups: 1
    # EU2
    groups: [1]
    number_of_affinity_EUs: 1
    affinity_EUs: [15]

### Structure overview
----------------------
The YAML configuration consists of the following sections:

1. version - Defines the global configuration version.
2. DPA_APPS - Contains a list of applications with their configurations.
3. Application Fields:
3.1 name - The application name.
3.2 number_of_groups - The total number of groups assigned.
3.3 groups - The group IDs assigned to the application.
3.4 number_of_affinity_EUs - The number of execution units (EUs) allocated.
3.5 affinity_EUs - A list of specific EUs assigned.
