adqsetup 1.2.1

A pure Python tool and library to setup ADQ for Intel NICs

ADQ Setup Tool

SPDX-License-Identifier: BSD-3-Clause
Copyright (c) 2022, Intel Corporation

Dependencies: Python 2.7-3.10

Distro Support:

• Redhat: 7.1-8.x
• Fedora: 25-35
• Ubuntu: 18.04-21.04
• Debian: 11
• Others: ???

Installation

Python Package Index (pip):

python -m pip install adqsetup

Included with driver:

python scripts/adqsetup/adqsetup.py install

Configuration Parameters

Global

• arpfilter: (bool) Enable selective ARP activity
• bpstop: (bool) Channel-packet-clean-bp-stop feature
• bpstop-cfg: (bool) Channel-packet-clean-bp-stop-cfg feature
• busypoll: (integer) busy_poll value
• busyread: (integer) busy_read value
• cpus: (integer list|'auto') CPUs to use for handling 'default' traffic, default 'auto'
• numa: (integer|'local'|'remote'|'all') Numa node to use for 'default' traffic, default 'all' (prefer local)
• dev: (string) Network interface device to configure
• optimize: (bool) Channel-inspect-optimize feature
• priority: ('skbedit') Method to use for setting socket priority, default none
• queues: (integer) Number of queues in 'default' traffic class, default 2
• txring: (integer) Transmit ring buffer size
• txadapt: (bool) Adaptive transmit interrupt coalescing
• txusecs: (integer) Usecs for transmit interrupt coalescing
• rxring: (integer) Receive ring buffer size
• rxadapt: (bool) Adaptive receive interrupt coalescing
• rxusecs: (integer) Usecs for receive interrupt coalescing

User-defined Class (for each traffic class created)

• mode: ('exclusive'|'shared') Mode for traffic class
• queues: (integer) Number of queues in traffic class
• pollers: (integer) Number of independent pollers, default 0
• poller-timeout: (integer) Independent poller timeout value, default 10000
• protocol: ('tcp'|'udp') IP Protocol of traffic
• ports: (integer list) Local IP ports of traffic
• addrs: (string list) Local IP address of traffic
• remote-ports: (integer list) Remote IP ports of traffic
• remote-addrs: (string list) Remote IP address of traffic
• cpus: (integer list|'auto') CPUs to use for handling traffic, default 'auto'
• numa: (integer|'local'|'remote'|'all') Numa node to use for traffic, default 'all' (prefer local)

Usage

The basic usage is: adqsetup [options] <command> [parameters ...]

Commands

• help: Show help message
• examples: Creates an 'examples' subdirectory containing a set of example config files in the current directory.
• apply: Apply a config file
  • [filename]: (string) Filename (relative or full path). If empty or '-', read config file from stdin.
• create: Create a 'quick-config' consisting of one traffic class.
  • [name]: (string) User-defined name of traffic class. 'globals' and 'default' names are reserved and not allowed.
  • [key] [value]: (string, string) One or more space-seperated key and value pairs. See the above Class Configuration Parameter list for possible keys and values.
• reset: Remove ADQ traffic classes and filters. Does not reset any global options.
• persist: Persists a config file across reboots using a systemd service unit. One config per network interface, new configs overwrite old ones.
  • [filename]: (string) Filename (relative or full path). If empty or '-', read config file from stdin.
• install: Installs the adqsetup script as a system-wide command on the PATH.

Global configuration parameters can be specified with the matching --<key> <value> command line option, and when using the create command class configuration parameters are specified with one or more <key> <value> pairs after the user-defined class name.

Sample Usage

./adqsetup.py install
adqsetup help
adqsetup examples

adqsetup apply memcached.conf
adqsetup --dev=eth4 apply nginx.conf
adqsetup --dev=eth3 persist eth3.conf

cat memcached.conf | adqsetup apply

adqsetup --dev=eth4 --priority=skbedit create myapp \
    queues 8 ports 11211
adqsetup --dev=eth4 --priority=skbedit create myapp mode shared \
    queues 8 ports 11211-11218

Sample Usage With Pipes From Bash Script

#!/bin/bash 

QUEUES=8

for BP in {10000..50000..5000}; do 
adqsetup --dev=eth4 apply <<EOF
    [globals]
    busypoll=$BP
    [nginx]
    queues=$QUEUES
    ports=80
EOF
./run_test.sh
done

Common Issues

If you get a /usr/bin/env: ‘python’: No such file or directory error when you run the script, please install Python. If you have already installed Python, then try whereis python and you should see a message like: python: /usr/bin/python2.7 /usr/bin/python3.6 /usr/bin/python3.6m /usr/bin/python3.9 on the first line of the output. Either run the version you wish to use manually: python3.6 adqsetup.py help, or create a 'python' symbolic link on the path: ln -s /usr/bin/python3.6 /usr/local/bin/python

When using the pollers feature, if your driver does not have independent poller support, you will see the following error:

** Setting independent poller **
devlink answers: Invalid argument

Other Issues

Please run the malfunctioning config with the command line --debug option, which should include a short stack trace at the end of the output. Send the configuration file (if used), full commmand line, and output to your Intel support contact.