From 7ec250a776e0dd32f17de0162439622a1b80b552 Mon Sep 17 00:00:00 2001 From: Jana Halackova Date: Mon, 21 Oct 2024 17:07:55 +0200 Subject: [PATCH 1/7] Added pf-bb-config installation. --- articles/pf-bb-config.asm.xml | 199 ++++++++++++++++++++++++++ concepts/pf-bb-config-terminology.xml | 61 ++++++++ tasks/pf-bb-config-installation.xml | 61 ++++++++ 3 files changed, 321 insertions(+) create mode 100644 articles/pf-bb-config.asm.xml create mode 100644 concepts/pf-bb-config-terminology.xml create mode 100644 tasks/pf-bb-config-installation.xml diff --git a/articles/pf-bb-config.asm.xml b/articles/pf-bb-config.asm.xml new file mode 100644 index 000000000..6280f3e57 --- /dev/null +++ b/articles/pf-bb-config.asm.xml @@ -0,0 +1,199 @@ + + + + + %entities; +]> + + + + + + + + + + Glue example + + + Glue for more information + + + Glue what's next + + + + + + Concept example + + + + + + Installing pf-bb-config + + + + + + Reference example + + + + + + Legal Notice + + + GNU Free Documentation License + + + + + + The Physical Function Baseband Device Configuration Using <literal>pf-bb-config</literal> + Subtitle if necessary + + + + 2024-11-05 + + + + Initial version + + + + + + + + + + + + + + + + &x86-64; + + + + &slm; + + short title for SEO and social media, max. 55 chars + short description, max. 150 chars + ultrashort description for social media, max 55 chars + + + + + Configuration + + Products & Solutions + + + + https://bugzilla.suse.com/enter_bug.cgi + Smart Docs + Documentation + + jsindelarova@suse.com + + yes + + + + + WHAT? + + + The pf-bb-config is a configuration tool that based on a given + configuration files enables you to configure physical functions of various baseband devices. + + + + + WHY? + + + This article focuses on installation and usage of the pf-bb-config tool. + + + + + EFFORT + + + What's the effort one has to put in? + + + + + GOAL + + + What's the reader's take-away from this article? + + + + + REQUIREMENTS + + + + + A registered running instance of &productname; + + + + + + + + + + + + + + + + You are a very special concept now! + + + + + + + + + + + + diff --git a/concepts/pf-bb-config-terminology.xml b/concepts/pf-bb-config-terminology.xml new file mode 100644 index 000000000..b85caf815 --- /dev/null +++ b/concepts/pf-bb-config-terminology.xml @@ -0,0 +1,61 @@ + + + + + %entities; +]> + + + + + + + Concept + + + + + Introductory text + + + +
+ What is foo bar? + + A paragraph of text, answering the question above and explaining the + aim/function of foo bar. + +
+
+ How does foo bar work? + + A paragraph of text, answering the question above and explaining the + mechanism behind foo bar. + +
+ A figure + + + + + + + + +
+
+
+ Benefits of foo bar + + A paragraph of text, pointing out the benefits of foo bar. + +
+ diff --git a/tasks/pf-bb-config-installation.xml b/tasks/pf-bb-config-installation.xml new file mode 100644 index 000000000..4eb1ec471 --- /dev/null +++ b/tasks/pf-bb-config-installation.xml @@ -0,0 +1,61 @@ + + + + + %entities; +]> + + + + + + + Installing the <literal>pf-bb-config</literal> tool + + + + + The topic covers installation of the pf-bb-config tool. + + + + +The physical function broadband devices configuration tool is not delivered as part of the +pre-built image, so to use it you need to install it first: + + + + +Refresh repositories: + + +&prompt.sudo;zypper ref + + + + +Install the pf-bb-config package: + + +&prompt.sudo;transactional-update pkg install pf-bb-config + + + + + Reboot the system: + + +&prompt.sudo;reboot + + + + From c5ace17687a15ae950dff6de9be1274118c1ea3b Mon Sep 17 00:00:00 2001 From: Jana Halackova Date: Tue, 22 Oct 2024 15:39:01 +0200 Subject: [PATCH 2/7] Added pf_bb_config usage. --- concepts/pf-bb-config-terminology.xml | 2 +- references/pf-bb-config-usage.xml | 99 +++++++++++++++++++++++++++ tasks/pf-bb-config-installation.xml | 10 ++- 3 files changed, 109 insertions(+), 2 deletions(-) create mode 100644 references/pf-bb-config-usage.xml diff --git a/concepts/pf-bb-config-terminology.xml b/concepts/pf-bb-config-terminology.xml index b85caf815..b28c97b9c 100644 --- a/concepts/pf-bb-config-terminology.xml +++ b/concepts/pf-bb-config-terminology.xml @@ -10,7 +10,7 @@ - + + + + %entities; +]> + + + + + + + Usage of <literal>pf-bb-config</literal> + + + + + The topic covers how to invoke the pf-bb-config tool. + + + + + To run the pf_bb_config tool, use the following command: + + +&prompt.root;pf_bb_config DEVICE_NAME [-h] [-c PATH_TO_CONFIG_FILE] [-p PCI_ID] [-v VFIO_TOKEN] [-f FFT_LUT_FILE] + + + Where the arguments and options have the following meaning: + + + + DEVICE_NAME + + +The device name is mandatory. + + + + + -h + + + To print out help. + + + + + -c PATH_TO_CONFIG_FILE + + + Passes the configuration file to use for the particular BB device + + + + + -p PCI_ID + + + Specify the PCI ID of the device to be configured + + + + + -v VFIO_TOKEN + + +Provide a VFIO token that can be obtained using the uuid command: + + +&prompt.root;uuid=$(cat /proc/sys/kernel/random/uuid) + + + then to display it: + + +&prompt.root;echo $uuid + + + + + -f FFT_LUT_FILE + + + Using the option you can provide an alternative FFT LUT file. If not secified, the + default one is used. + + + + + diff --git a/tasks/pf-bb-config-installation.xml b/tasks/pf-bb-config-installation.xml index 4eb1ec471..1967992fc 100644 --- a/tasks/pf-bb-config-installation.xml +++ b/tasks/pf-bb-config-installation.xml @@ -10,7 +10,7 @@ -pf-bb-config package: &prompt.sudo;transactional-update pkg install pf-bb-config + + + In certain cases, you may need to use Data Plane Development Kit. To install it, run: + + +&prompt.sudo;transactional-update --continue pkg install dpdk + + Reboot the system: From 55095d8ab945d440ddc83fa76e6e8c96f4c78769 Mon Sep 17 00:00:00 2001 From: Jana Halackova Date: Thu, 24 Oct 2024 15:49:18 +0200 Subject: [PATCH 3/7] Added configuration details. --- concepts/pf-bb-config-terminology.xml | 38 +----- .../pf-bb-config-configuration-examples.xml | 77 ++++++++++++ references/pf-bb-config-usage.xml | 8 +- tasks/pf-bb-config-running-daemon.xml.xml | 114 ++++++++++++++++++ 4 files changed, 200 insertions(+), 37 deletions(-) create mode 100644 references/pf-bb-config-configuration-examples.xml create mode 100644 tasks/pf-bb-config-running-daemon.xml.xml diff --git a/concepts/pf-bb-config-terminology.xml b/concepts/pf-bb-config-terminology.xml index b28c97b9c..b6bf92b71 100644 --- a/concepts/pf-bb-config-terminology.xml +++ b/concepts/pf-bb-config-terminology.xml @@ -18,44 +18,14 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:trans="http://docbook.org/ns/transclusion"> - Concept + What is <literal>pf_bb_config</literal> - + - Introductory text + The topic covers basic information about pf_bb_config -
- What is foo bar? - - A paragraph of text, answering the question above and explaining the - aim/function of foo bar. - -
-
- How does foo bar work? - - A paragraph of text, answering the question above and explaining the - mechanism behind foo bar. - -
- A figure - - - - - - - - -
-
-
- Benefits of foo bar - - A paragraph of text, pointing out the benefits of foo bar. - -
+ diff --git a/references/pf-bb-config-configuration-examples.xml b/references/pf-bb-config-configuration-examples.xml new file mode 100644 index 000000000..a0dfd81ad --- /dev/null +++ b/references/pf-bb-config-configuration-examples.xml @@ -0,0 +1,77 @@ + + + + + %entities; +]> + + + + + + + Configuration examples description + + + + + The topic covers details regarding particular devices configuration. + + + + + You can find the broadband devices confiration examples in + /opt/pf-bb-config. The following section + provides details regarding ACC100/ACC200 accelarator. + +
+ The ACC100/ACC200 configuration + + In the examples /opt/pf-bb-config/acc*, you can adjust the following attributes: + + + + pf_mode_en + + + If set to 1, all queues on the device are assigned to physical function (PF) and none + is assigneg to virtual functions (VF). PF and VF are mutually exclusive. + + + + + num_qgroups + + + There are eight queue groups available that you can allocate to all operations. + + + + + num_vf_bundles + + + Choose value between 1 and 16. The available DDR is then split + + + + + num_aqs_per_groups + + + Defines the maximum count of atomic queues in a single queue group. + + + + + +
+ diff --git a/references/pf-bb-config-usage.xml b/references/pf-bb-config-usage.xml index 27f7cfefe..8a111a760 100644 --- a/references/pf-bb-config-usage.xml +++ b/references/pf-bb-config-usage.xml @@ -18,12 +18,12 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:trans="http://docbook.org/ns/transclusion"> - Usage of <literal>pf-bb-config</literal> + Usage of <literal>pf_bb_config</literal> - The topic covers how to invoke the pf-bb-config tool. + The topic covers how to invoke the pf_bb_config tool. @@ -57,7 +57,9 @@ The device name is mandatory. -c PATH_TO_CONFIG_FILE - Passes the configuration file to use for the particular BB device + Passes the configuration file to use for the particular BB device. Configuration examples + are installed to /opt/pf-bb-config/. For details regarding these + exaples, refer to . diff --git a/tasks/pf-bb-config-running-daemon.xml.xml b/tasks/pf-bb-config-running-daemon.xml.xml new file mode 100644 index 000000000..994459e45 --- /dev/null +++ b/tasks/pf-bb-config-running-daemon.xml.xml @@ -0,0 +1,114 @@ + + + + + %entities; +]> + + + + + + + Running <literal>pf_bb_config</literal> as daemon + + + + + The topic describes how to start the configuration tool as a daemon. + + + + + The pf_bb_config tool can be run also as a daemon in the + VFIO mode. Then you + can use its CLI interface for interactions. + +
+ Enabling the daemon mode + + A paragraph of text. + +
+
+ The available CLI commands + + The following commands are available on the pf_bb_config CLI: + + + + RESET_MODE_CMD_ID + + + + + + + + AUTO_RESET_CMD_ID + + + turns on or off automatic resetting of the ACC devices + + + + + CLEAR_LOG_CMD_ID + + + + + + + + EXIT_APP_CMD_ID + + + + + + + + REG_DUMP_CMD_ID + + + + + + + + RECONFIG_ACC_CMD_ID + + + + + + + + MM_READ_CMD_ID + + + + + + + + DEVICE_DATA_CMD_ID + + + + + + + +
+ From 286e3cab1daed3c11fcecbae23bc2f57b3ddf06d Mon Sep 17 00:00:00 2001 From: Jana Halackova Date: Fri, 25 Oct 2024 14:21:40 +0200 Subject: [PATCH 4/7] Maek it buildable. --- DC-Micro-pf_bb_config | 15 ++++++ articles/pf-bb-config.asm.xml | 75 +++++++++++++++------------ concepts/pf-bb-config-terminology.xml | 11 +++- references/pf-bb-config-usage.xml | 2 +- 4 files changed, 69 insertions(+), 34 deletions(-) create mode 100644 DC-Micro-pf_bb_config diff --git a/DC-Micro-pf_bb_config b/DC-Micro-pf_bb_config new file mode 100644 index 000000000..d3f86ad63 --- /dev/null +++ b/DC-Micro-pf_bb_config @@ -0,0 +1,15 @@ +# This file originates from the project https://github.com/openSUSE/doc-kit +# This file can be edited downstream. + +MAIN="pf-bb-config.asm.xml" +# Point to the ID of the of your assembly +ROOTID="pf-bb-config" +SRC_DIR="articles" +IMG_SRC_DIR="images" + +PROFOS="slmicro" +#PROFCONDITION="suse-product;beta" +#PROFCONDITION="community-project" + +STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns" +FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns" diff --git a/articles/pf-bb-config.asm.xml b/articles/pf-bb-config.asm.xml index 6280f3e57..93a1e02e9 100644 --- a/articles/pf-bb-config.asm.xml +++ b/articles/pf-bb-config.asm.xml @@ -18,22 +18,11 @@ - - - - Glue example - - - Glue for more information - - - Glue what's next - - + - - Concept example + + About the tool @@ -44,9 +33,12 @@ - - Reference example - + + Usage + + + Configuration description + @@ -58,13 +50,12 @@ - + The Physical Function Baseband Device Configuration Using <literal>pf-bb-config</literal> - Subtitle if necessary - + - + 2024-11-05 @@ -106,9 +97,11 @@ &slm; - short title for SEO and social media, max. 55 chars - short description, max. 150 chars - ultrashort description for social media, max 55 chars + pf_bb_config—the tool to configure broadband devices + Configuration of physica functions of broadband + device using pf_bb_config + Configuration of physica functions of broadband + device using pf_bb_config @@ -133,7 +126,7 @@ WHAT? - The pf-bb-config is a configuration tool that based on a given + The pf_bb_config is a configuration tool that based on a given configuration files enables you to configure physical functions of various baseband devices. @@ -180,17 +173,35 @@ - + + + + + + + - + - You are a very special concept now! + + + - - - - + + + + + + + + + + + + + + diff --git a/concepts/pf-bb-config-terminology.xml b/concepts/pf-bb-config-terminology.xml index b6bf92b71..245a103cc 100644 --- a/concepts/pf-bb-config-terminology.xml +++ b/concepts/pf-bb-config-terminology.xml @@ -18,7 +18,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:trans="http://docbook.org/ns/transclusion"> - What is <literal>pf_bb_config</literal> + What is <literal>pf_bb_config</literal>? @@ -27,5 +27,14 @@ + + pf_bb_config is a tool that enables you to configure broadband devices on + your host system. The tool acceses the configuration space and sets parameters using + memory-mapped I/O (MMIO) read and write operations. + + + The particular braodband device configuration parameters are parsed from a passed configuration + file specific to that device. + diff --git a/references/pf-bb-config-usage.xml b/references/pf-bb-config-usage.xml index 8a111a760..30306f3f7 100644 --- a/references/pf-bb-config-usage.xml +++ b/references/pf-bb-config-usage.xml @@ -59,7 +59,7 @@ The device name is mandatory. Passes the configuration file to use for the particular BB device. Configuration examples are installed to /opt/pf-bb-config/. For details regarding these - exaples, refer to . + exaples, refer to . From 94ba9d155840c18f7a8306aaa9b3d787a5b5c34e Mon Sep 17 00:00:00 2001 From: Jana Halackova Date: Fri, 25 Oct 2024 15:49:39 +0200 Subject: [PATCH 5/7] Fixed the tool name. --- articles/pf-bb-config.asm.xml | 6 +-- tasks/pf-bb-config-vfio.xml | 98 +++++++++++++++++++++++++++++++++++ 2 files changed, 101 insertions(+), 3 deletions(-) create mode 100644 tasks/pf-bb-config-vfio.xml diff --git a/articles/pf-bb-config.asm.xml b/articles/pf-bb-config.asm.xml index 93a1e02e9..a01fa4d6a 100644 --- a/articles/pf-bb-config.asm.xml +++ b/articles/pf-bb-config.asm.xml @@ -28,7 +28,7 @@ - Installing pf-bb-config + Installing pf_bb_config @@ -52,7 +52,7 @@ - The Physical Function Baseband Device Configuration Using <literal>pf-bb-config</literal> + The Physical Function Baseband Device Configuration Using <literal>pf_bb_config</literal> @@ -135,7 +135,7 @@ WHY? - This article focuses on installation and usage of the pf-bb-config tool. + This article focuses on installation and usage of the pf_bb_config tool. diff --git a/tasks/pf-bb-config-vfio.xml b/tasks/pf-bb-config-vfio.xml new file mode 100644 index 000000000..3601c87dd --- /dev/null +++ b/tasks/pf-bb-config-vfio.xml @@ -0,0 +1,98 @@ + + + + + %entities; +]> + + + + + + + Using the <literal>vfio-pci</literal> module + + + + + Introductory text + + + +
+ Introduction + + A paragraph of text. + +
+
+ Requirements + + + + An + + + + + Unordered + + + + + List + + + + + A paragraph of text. + +
+
+ Executing the task + + A paragraph of text. + + + + A short introduction to the procedure. + + + + A step. + + + + + A second step. + + + + + A third step. + + + +
+
+ Summary + + A paragraph of text, summing up the result of the task. + +
+
+ Troubleshooting + + Add some troubleshooting information, if applicable. + +
+ From ffc9d22f807a47620734a10f4c1d355c41d8d7a2 Mon Sep 17 00:00:00 2001 From: Jana Halackova Date: Tue, 29 Oct 2024 14:55:29 +0100 Subject: [PATCH 6/7] Added enabling the vfio-pci driver. --- articles/pf-bb-config.asm.xml | 13 ++- tasks/pf-bb-config-vfio.xml | 156 ++++++++++++++++++++-------------- 2 files changed, 102 insertions(+), 67 deletions(-) diff --git a/articles/pf-bb-config.asm.xml b/articles/pf-bb-config.asm.xml index a01fa4d6a..020e3f398 100644 --- a/articles/pf-bb-config.asm.xml +++ b/articles/pf-bb-config.asm.xml @@ -30,6 +30,9 @@ Installing pf_bb_config + + Enabling the vfio-pci driver + @@ -143,7 +146,7 @@ EFFORT - What's the effort one has to put in? + It takes approximately 10 minut to read the article. @@ -194,6 +197,14 @@ + + + + + + + + diff --git a/tasks/pf-bb-config-vfio.xml b/tasks/pf-bb-config-vfio.xml index 3601c87dd..ce9e6a71c 100644 --- a/tasks/pf-bb-config-vfio.xml +++ b/tasks/pf-bb-config-vfio.xml @@ -24,75 +24,99 @@ in the assembly --> - Introductory text + The topic covers preparing the machine to use the vfio-pci driver. -
- Introduction - - A paragraph of text. - -
-
- Requirements - - - - An - - - - - Unordered - - - - - List - - - - - A paragraph of text. - -
-
- Executing the task - - A paragraph of text. - - + + To enable you device direct access to the hardware resources, you need use the + vfio-pci driver. Before proceeding further, ensure that the following conditions are met: + + + - A short introduction to the procedure. + the vfio-pci module is built-in - - - A step. - - - - - A second step. - - - - - A third step. - - - -
-
- Summary - - A paragraph of text, summing up the result of the task. - -
-
- Troubleshooting - - Add some troubleshooting information, if applicable. - -
+ + + + Intel™ VT-d is enabled in kernel and UEFI and implemented in IOMMU + + + + + IOMMU is enabled on runtime. To check that, run the command: + + +&prompt.sudo;dmesg | grep "DMAR: IOMMU" + + + + + DPDK is installed. + + + + + If the above conditions are met, you can enable the vfio-pci driver as described below. + + + + + The vfio-pci module is loaded automatically during boot, you just need to pass parameters + to the module. You can do that in three ways: + + + + + pass the following parameters on the kernel CLI: + + vfio_pci.enable_sriov=1 vfio_pci.disable_idle_d3=1 + + + + set the required parameters after the system is fully booted: + + +&prompt.root;echo 1 | sudo tee /sys/module/vfio_pci/parameters/enable_sriov + +&prompt.root;echo 1 | sudo tee /sys/module/vfio_pci/parameters/disable_idle_d3 + + + + + or you can use modprobe to load the module with these parameters + + +&prompt.root;modprobe vfio-pci enable_sriov=1 disable_idle_d3=1 + + + + + + + Bind the PF with the vfio-pci module + + +&prompt.sudo;PATH_TO_DPDK/usertools/dpdk-devbind.py --bind=vfio-pci $PCI_DRIVER_ADDRESS + + + + + Configure the device using the pf_bb_config tool: + + +&prompt.sudo;./pf_bb_config ACC100 -v 00112233-4455-6677-8899-aabbccddeeff -c acc100/acc100_config_2vf_4g5g.cfg + + + + + + For example, create two VF on the device: + + +&prompt.sudo;echo 2 | sudo tee /sys/bus/pci/devices/0000:$PF_PCI_DEVICE_ADDRESS/sriov_numvfs + + + From 77d997001f3b57d54c2869f7ee0a81628f50dabd Mon Sep 17 00:00:00 2001 From: Jana Halackova Date: Wed, 30 Oct 2024 11:14:52 +0100 Subject: [PATCH 7/7] Finalize the article. --- articles/pf-bb-config.asm.xml | 9 +++++---- concepts/pf-bb-config-terminology.xml | 4 ++-- references/pf-bb-config-configuration-examples.xml | 11 ++++++++++- tasks/pf-bb-config-installation.xml | 2 +- tasks/pf-bb-config-vfio.xml | 2 +- 5 files changed, 19 insertions(+), 9 deletions(-) diff --git a/articles/pf-bb-config.asm.xml b/articles/pf-bb-config.asm.xml index 020e3f398..eb76c05ad 100644 --- a/articles/pf-bb-config.asm.xml +++ b/articles/pf-bb-config.asm.xml @@ -71,9 +71,9 @@ - + - + The physical function broadband devices configuration tool is not delivered as part of the -pre-built image, so to use it you need to install it first: +pre-built images. To use it, you need to install it first: diff --git a/tasks/pf-bb-config-vfio.xml b/tasks/pf-bb-config-vfio.xml index ce9e6a71c..03a8e5921 100644 --- a/tasks/pf-bb-config-vfio.xml +++ b/tasks/pf-bb-config-vfio.xml @@ -95,7 +95,7 @@ in the assembly --> - Bind the PF with the vfio-pci module + Bind the PF with the vfio-pci module: &prompt.sudo;PATH_TO_DPDK/usertools/dpdk-devbind.py --bind=vfio-pci $PCI_DRIVER_ADDRESS