Metadata-Version: 2.1
Name: dpa-resource-mgmt
Version: 26.1.172
Summary: A package for DPA resource management
Home-page: UNKNOWN
Author: Vadim Artishchev
Author-email: vadima@nvidia.com
License: UNKNOWN
Description: # 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.
        
Platform: UNKNOWN
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
