ext/pci: implement PCI path for device identification

[marmarek]

PCI SBDF may change if another device is added/removed from the system. Use PCI device path to avoid this issue. The PCI device path is more or less sysfs path, but with bus number behind bridges replaced with relative bus number to bridge's secondary bus number. Each component of the path is separated with '-', as that is allowed in qrexec arguments.

For example device 0000:c1:00.0 behind bridge at 0000:00:08.1 will get path 0000_00_08.1-00_00.0 (assuming bridge 0000:00:08.1 has secondary bus at 0xc1). Resolving device path requires access to the system's sysfs.

PCIDevice object will automatically resolve old device identifiers, which partially covers migration path.

TODO:

• [x] finalize migration path - adjust device assignments too
• [ ] consider still allowing attaching via SBDF, or otherwise expose function to translate SBDF to PCI path (an Admin API call?)
• [ ] fix salt listing/attaching devices to sys-net/sys-usb - depending on the above
• [ ] support path-based PCI in the dracut module too

Fixes QubesOS/qubes-issues#8681

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 88.23529% with 10 lines in your changes missing coverage. Please review.

Project coverage is 70.31%. Comparing base (a16975e) to head (20e3c20). Report is 25 commits behind head on main.

Files with missing lines	Patch %	Lines
qubes/ext/pci.py	60.00%	6 Missing :warning:
qubes/utils.py	94.02%	4 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #667      +/-   ##
==========================================
+ Coverage   70.14%   70.31%   +0.16%     
==========================================
  Files          59       59              
  Lines       12726    12819      +93     
==========================================
+ Hits         8927     9014      +87     
- Misses       3799     3805       +6     

Flag	Coverage Δ
unittests	70.31% <88.23%> (+0.16%)	:arrow_up:

Flags with carried forward coverage won't be shown. Click here to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[qubesos-bot]

OpenQA test summary

Complete test suite and dependencies: https://openqa.qubes-os.org/tests/overview?distri=qubesos&version=4.3&build=2025041403-4.3&flavor=pull-requests

Test run included the following:

• https://github.com/QubesOS/qubes-core-admin-linux/pull/190 (https://github.com/QubesOS/qubes-core-admin-linux/pull/190/commits/7806f5714558040e80d7b825806d7e8e83e54990)
• https://github.com/QubesOS/qubes-core-admin/pull/674 (https://github.com/QubesOS/qubes-core-admin/pull/674/commits/0918bc0b890374cdd8c9a9f5df4bb50a034444ff)
• https://github.com/QubesOS/qubes-core-admin/pull/667 (https://github.com/QubesOS/qubes-core-admin/pull/667/commits/69cea577bab1e31a666424f31310ba14a0c45f76)
• https://github.com/QubesOS/qubes-manager/pull/419 (https://github.com/QubesOS/qubes-manager/pull/419/commits/9cd7bec0d2cf3db93696a8296b4e534da0b01a4f)
• https://github.com/QubesOS/qubes-core-admin-linux/pull/189 (https://github.com/QubesOS/qubes-core-admin-linux/pull/189/commits/ab927ec4f0642e967e1ee59f160469e283b2b402)
• https://github.com/QubesOS/qubes-core-admin-client/pull/347 (https://github.com/QubesOS/qubes-core-admin-client/pull/347/commits/6dd1258a59c8f92651e9d27f1e15c098f0d51951)
• https://github.com/QubesOS/qubes-vmm-xen/pull/205 (https://github.com/QubesOS/qubes-vmm-xen/pull/205/commits/4426d1da870f493606542004d3d9249f7d822763)
• https://github.com/QubesOS/qubes-core-agent-linux/pull/569 (https://github.com/QubesOS/qubes-core-agent-linux/pull/569/commits/bbea99747966d9da09c7a9ff60df1379f281d1b4)
• https://github.com/QubesOS/qubes-desktop-linux-manager/pull/249 (https://github.com/QubesOS/qubes-desktop-linux-manager/pull/249/commits/203be8c1079512cafca4786eba0063874a2b5c00)
• https://github.com/QubesOS/qubes-core-admin/pull/675 (https://github.com/QubesOS/qubes-core-admin/pull/675/commits/aa6e363d2a724cd2f3afbe4914dcddda0f9ef71c)
• https://github.com/QubesOS/qubes-core-admin-client/pull/332 (https://github.com/QubesOS/qubes-core-admin-client/pull/332/commits/e22c531c6eb2e0b5404b58295e499ca758627009)

New failures, excluding unstable

Compared to: https://openqa.qubes-os.org/tests/overview?distri=qubesos&version=4.3&build=2025031804-4.3&flavor=update

• system_tests_whonix

  • whonixcheck: wait_serial (wait serial expected) # wait_serial expected: qr/_oatY-\d+-/...

  • whonixcheck: Failed (test died + timed out) # Test died: command 'qvm-run -ap anon-whonix 'LC_ALL=C whonixchec...

• system_tests_kde_gui_interactive

  • gui_keyboard_layout: wait_serial (wait serial expected) # wait_serial expected: "echo -e '[Layout]\nLayoutList=us,de' | sud...

  • gui_keyboard_layout: Failed (test died) # Test died: command 'test "$(cd ~user;ls e1*)" = "$(qvm-run -p wor...

• system_tests_qwt_win10_seamless@hw13

  • windows_clipboard_and_filecopy: unnamed test (unknown)
  • windows_clipboard_and_filecopy: Failed (test died) # Test died: no candidate needle with tag(s) 'windows-Explorer-empt...

• system_tests_qwt_win11@hw13

  • windows_install: wait_serial (wait serial expected) # wait_serial expected: qr/dcWzE-\d+-/...

  • windows_install: Failed (test died + timed out) # Test died: command 'script -e -c 'bash -x /usr/bin/qvm-create-win...

• system_tests_basic_vm_qrexec_gui_ext4

  • TC_30_Gui_daemon: test_000_clipboard (error) FileNotFoundError: [Errno 2] No such file or directory: '/var/run/q...

• system_tests_basic_vm_qrexec_gui_zfs

  • startup: wait_serial (wait serial expected) # wait_serial expected: qr/PS1="root# "/u...

• system_tests_suspend@hw1

  • suspend: unnamed test (unknown)
  • suspend: Failed (test died) # Test died: no candidate needle with tag(s) 'SUSPEND-FAILED' match...

Failed tests

16 failures

• system_tests_whonix

  • whonixcheck: wait_serial (wait serial expected) # wait_serial expected: qr/_oatY-\d+-/...

  • whonixcheck: Failed (test died + timed out) # Test died: command 'qvm-run -ap anon-whonix 'LC_ALL=C whonixchec...

• system_tests_suspend

  • suspend: unnamed test (unknown)
  • suspend: Failed (test died) # Test died: no candidate needle with tag(s) 'SUSPEND-FAILED' match...

• system_tests_kde_gui_interactive

  • gui_keyboard_layout: wait_serial (wait serial expected) # wait_serial expected: "echo -e '[Layout]\nLayoutList=us,de' | sud...

  • gui_keyboard_layout: Failed (test died) # Test died: command 'test "$(cd ~user;ls e1*)" = "$(qvm-run -p wor...

• system_tests_whonix@hw7

  • whonixcheck: fail (unknown) Whonixcheck for sys-whonix failed...

  • whonixcheck: unnamed test (unknown)

• system_tests_qwt_win10_seamless@hw13

  • windows_clipboard_and_filecopy: unnamed test (unknown)
  • windows_clipboard_and_filecopy: Failed (test died) # Test died: no candidate needle with tag(s) 'windows-Explorer-empt...

• system_tests_qwt_win11@hw13

  • windows_install: wait_serial (wait serial expected) # wait_serial expected: qr/dcWzE-\d+-/...

  • windows_install: Failed (test died + timed out) # Test died: command 'script -e -c 'bash -x /usr/bin/qvm-create-win...

• system_tests_basic_vm_qrexec_gui_ext4

  • TC_30_Gui_daemon: test_000_clipboard (error) FileNotFoundError: [Errno 2] No such file or directory: '/var/run/q...

• system_tests_basic_vm_qrexec_gui_zfs

  • startup: wait_serial (wait serial expected) # wait_serial expected: qr/PS1="root# "/u...

• system_tests_suspend@hw1

  • suspend: unnamed test (unknown)
  • suspend: Failed (test died) # Test died: no candidate needle with tag(s) 'SUSPEND-FAILED' match...

Fixed failures

Compared to: https://openqa.qubes-os.org/tests/132953#dependencies

10 fixed

• system_tests_whonix

  • whonixcheck: fail (unknown) Whonixcheck for sys-whonix failed...

  • whonixcheck: unnamed test (unknown)

• system_tests_basic_vm_qrexec_gui

  • TC_20_NonAudio_whonix-gateway-17: test_300_bug_1028_gui_memory_pinning (failure) AssertionError: Dom0 window doesn't match VM window content, saved ...

• system_tests_qrexec

  • TC_00_Qrexec_fedora-41-xfce: test_081_qrexec_service_argument_allow_specific (error) subprocess.CalledProcessError: Command '/usr/lib/qubes/qrexec-clien...

• system_tests_kde_gui_interactive

  • clipboard_and_web: unnamed test (unknown)

  • clipboard_and_web: Failed (test died) # Test died: no candidate needle with tag(s) 'qubes-website' matche...

  • clipboard_and_web: wait_serial (wait serial expected) # wait_serial expected: "lspci; echo 2E8vz-\$?-"...

• system_tests_guivm_vnc_gui_interactive

  • gui_filecopy: unnamed test (unknown)
  • gui_filecopy: Failed (test died) # Test died: no candidate needle with tag(s) 'files-work' matched...

• system_tests_audio

  • TC_20_AudioVM_Pulse_whonix-workstation-17: test_252_audio_playback_audiovm_switch_hvm (failure) AssertionError: only silence detected, no useful audio data

Unstable tests

Performance Tests

Performance degradation:

16 performance degradations

• dom0_root_seq1m_q8t1_read 3:read_bandwidth_kb: 197883.00 :small_red_triangle_up: ( previous job: 446963.00, degradation: 44.27%)
• dom0_root_seq1m_q1t1_read 3:read_bandwidth_kb: 81084.00 :small_red_triangle_up: ( previous job: 294295.00, degradation: 27.55%)
• dom0_root_rnd4k_q32t1_read 3:read_bandwidth_kb: 35814.00 :small_red_triangle_up: ( previous job: 79803.00, degradation: 44.88%)
• dom0_root_rnd4k_q1t1_write 3:write_bandwidth_kb: 3944.00 :small_red_triangle_up: ( previous job: 4826.00, degradation: 81.72%)
• dom0_varlibqubes_seq1m_q8t1_write 3:write_bandwidth_kb: 182791.00 :small_red_triangle_up: ( previous job: 250795.00, degradation: 72.88%)
• fedora-41-xfce_root_seq1m_q1t1_write 3:write_bandwidth_kb: 43999.00 :small_red_triangle_up: ( previous job: 87940.00, degradation: 50.03%)
• fedora-41-xfce_root_rnd4k_q32t1_write 3:write_bandwidth_kb: 2197.00 :small_red_triangle_up: ( previous job: 3599.00, degradation: 61.04%)
• fedora-41-xfce_private_rnd4k_q1t1_write 3:write_bandwidth_kb: 651.00 :small_red_triangle_up: ( previous job: 1130.00, degradation: 57.61%)
• fedora-41-xfce_volatile_seq1m_q8t1_write 3:write_bandwidth_kb: 158116.00 :small_red_triangle_up: ( previous job: 179949.00, degradation: 87.87%)
• fedora-41-xfce_volatile_rnd4k_q32t1_write 3:write_bandwidth_kb: 2999.00 :small_red_triangle_up: ( previous job: 5672.00, degradation: 52.87%)
• fedora-41-xfce_volatile_rnd4k_q1t1_write 3:write_bandwidth_kb: 1036.00 :small_red_triangle_up: ( previous job: 1953.00, degradation: 53.05%)
• debian-12-xfce_exec: 8.57 :small_red_triangle_up: ( previous job: 7.12, degradation: 120.38%)
• whonix-gateway-17_socket: 9.31 :small_red_triangle_up: ( previous job: 7.24, degradation: 128.64%)
• whonix-gateway-17_exec-data-duplex-root: 100.06 :small_red_triangle_up: ( previous job: 88.52, degradation: 113.04%)
• whonix-workstation-17_exec: 8.75 :small_red_triangle_up: ( previous job: 7.67, degradation: 114.14%)
• whonix-workstation-17_socket: 9.13 :small_red_triangle_up: ( previous job: 8.19, degradation: 111.35%)

Remaining performance tests:

56 tests

• dom0_root_seq1m_q8t1_write 3:write_bandwidth_kb: 188899.00 :green_circle: ( previous job: 129298.00, improvement: 146.10%)
• dom0_root_seq1m_q1t1_write 3:write_bandwidth_kb: 180270.00 :green_circle: ( previous job: 95454.00, improvement: 188.86%)
• dom0_root_rnd4k_q32t1_write 3:write_bandwidth_kb: 10794.00 :green_circle: ( previous job: 6149.00, improvement: 175.54%)
• dom0_root_rnd4k_q1t1_read 3:read_bandwidth_kb: 11821.00 :green_circle: ( previous job: 10795.00, improvement: 109.50%)
• dom0_varlibqubes_seq1m_q8t1_read 3:read_bandwidth_kb: 496484.00 :green_circle: ( previous job: 382273.00, improvement: 129.88%)
• dom0_varlibqubes_seq1m_q1t1_read 3:read_bandwidth_kb: 420945.00 :small_red_triangle_up: ( previous job: 437636.00, degradation: 96.19%)
• dom0_varlibqubes_seq1m_q1t1_write 3:write_bandwidth_kb: 178433.00 :small_red_triangle_up: ( previous job: 184752.00, degradation: 96.58%)
• dom0_varlibqubes_rnd4k_q32t1_read 3:read_bandwidth_kb: 99347.00 :green_circle: ( previous job: 62195.00, improvement: 159.73%)
• dom0_varlibqubes_rnd4k_q32t1_write 3:write_bandwidth_kb: 8299.00 :green_circle: ( previous job: 6479.00, improvement: 128.09%)
• dom0_varlibqubes_rnd4k_q1t1_read 3:read_bandwidth_kb: 8269.00 :green_circle: ( previous job: 7669.00, improvement: 107.82%)
• dom0_varlibqubes_rnd4k_q1t1_write 3:write_bandwidth_kb: 4748.00 :small_red_triangle_up: ( previous job: 4903.00, degradation: 96.84%)
• fedora-41-xfce_root_seq1m_q8t1_read 3:read_bandwidth_kb: 384657.00 :green_circle: ( previous job: 368309.00, improvement: 104.44%)
• fedora-41-xfce_root_seq1m_q8t1_write 3:write_bandwidth_kb: 213211.00 :green_circle: ( previous job: 162081.00, improvement: 131.55%)
• fedora-41-xfce_root_seq1m_q1t1_read 3:read_bandwidth_kb: 302444.00 :small_red_triangle_up: ( previous job: 318716.00, degradation: 94.89%)
• fedora-41-xfce_root_rnd4k_q32t1_read 3:read_bandwidth_kb: 88569.00 :green_circle: ( previous job: 82694.00, improvement: 107.10%)
• fedora-41-xfce_root_rnd4k_q1t1_read 3:read_bandwidth_kb: 8841.00 :green_circle: ( previous job: 8485.00, improvement: 104.20%)
• fedora-41-xfce_root_rnd4k_q1t1_write 3:write_bandwidth_kb: 1504.00 :green_circle: ( previous job: 542.00, improvement: 277.49%)
• fedora-41-xfce_private_seq1m_q8t1_read 3:read_bandwidth_kb: 356658.00 :small_red_triangle_up: ( previous job: 373957.00, degradation: 95.37%)
• fedora-41-xfce_private_seq1m_q8t1_write 3:write_bandwidth_kb: 166697.00 :small_red_triangle_up: ( previous job: 170062.00, degradation: 98.02%)
• fedora-41-xfce_private_seq1m_q1t1_read 3:read_bandwidth_kb: 341444.00 :green_circle: ( previous job: 334687.00, improvement: 102.02%)
• fedora-41-xfce_private_seq1m_q1t1_write 3:write_bandwidth_kb: 84430.00 :green_circle: ( previous job: 61534.00, improvement: 137.21%)
• fedora-41-xfce_private_rnd4k_q32t1_read 3:read_bandwidth_kb: 86624.00 :green_circle: ( previous job: 80283.00, improvement: 107.90%)
• fedora-41-xfce_private_rnd4k_q32t1_write 3:write_bandwidth_kb: 2219.00 :green_circle: ( previous job: 2215.00, improvement: 100.18%)
• fedora-41-xfce_private_rnd4k_q1t1_read 3:read_bandwidth_kb: 7814.00 :green_circle: ( previous job: 7540.00, improvement: 103.63%)
• fedora-41-xfce_volatile_seq1m_q8t1_read 3:read_bandwidth_kb: 353412.00 :small_red_triangle_up: ( previous job: 369868.00, degradation: 95.55%)
• fedora-41-xfce_volatile_seq1m_q1t1_read 3:read_bandwidth_kb: 316790.00 :small_red_triangle_up: ( previous job: 324737.00, degradation: 97.55%)
• fedora-41-xfce_volatile_seq1m_q1t1_write 3:write_bandwidth_kb: 94466.00 :green_circle: ( previous job: 17567.00, improvement: 537.75%)
• fedora-41-xfce_volatile_rnd4k_q32t1_read 3:read_bandwidth_kb: 80609.00 :green_circle: ( previous job: 79021.00, improvement: 102.01%)
• fedora-41-xfce_volatile_rnd4k_q1t1_read 3:read_bandwidth_kb: 8400.00 :green_circle: ( previous job: 7867.00, improvement: 106.78%)
• debian-12-xfce_exec-root: 28.18 :green_circle: ( previous job: 28.65, improvement: 98.35%)
• debian-12-xfce_socket: 8.87 :small_red_triangle_up: ( previous job: 8.60, degradation: 103.15%)
• debian-12-xfce_socket-root: 8.52 :green_circle: ( previous job: 8.52, improvement: 99.93%)
• debian-12-xfce_exec-data-simplex: 62.25 :green_circle: ( previous job: 71.62, improvement: 86.91%)
• debian-12-xfce_exec-data-duplex: 72.13 :small_red_triangle_up: ( previous job: 70.34, degradation: 102.54%)
• debian-12-xfce_exec-data-duplex-root: 88.59 :small_red_triangle_up: ( previous job: 82.72, degradation: 107.10%)
• debian-12-xfce_socket-data-duplex: 145.97 :green_circle: ( previous job: 156.96, improvement: 93.00%)
• fedora-41-xfce_exec: 9.33 :small_red_triangle_up: ( previous job: 9.27, degradation: 100.69%)
• fedora-41-xfce_exec-root: 65.28 :small_red_triangle_up: ( previous job: 61.51, degradation: 106.14%)
• fedora-41-xfce_socket: 8.80 :small_red_triangle_up: ( previous job: 8.63, degradation: 102.04%)
• fedora-41-xfce_socket-root: 7.89 :green_circle: ( previous job: 8.71, improvement: 90.65%)
• fedora-41-xfce_exec-data-simplex: 72.45 :green_circle: ( previous job: 75.53, improvement: 95.92%)
• fedora-41-xfce_exec-data-duplex: 62.89 :green_circle: ( previous job: 71.56, improvement: 87.88%)
• fedora-41-xfce_exec-data-duplex-root: 96.70 :green_circle: ( previous job: 109.13, improvement: 88.62%)
• fedora-41-xfce_socket-data-duplex: 154.61 :small_red_triangle_up: ( previous job: 150.61, degradation: 102.66%)
• whonix-gateway-17_exec: 6.78 :green_circle: ( previous job: 6.82, improvement: 99.49%)
• whonix-gateway-17_exec-root: 38.55 :green_circle: ( previous job: 40.43, improvement: 95.35%)
• whonix-gateway-17_socket-root: 7.65 :small_red_triangle_up: ( previous job: 7.65, degradation: 100.00%)
• whonix-gateway-17_exec-data-simplex: 77.81 :green_circle: ( previous job: 78.32, improvement: 99.35%)
• whonix-gateway-17_exec-data-duplex: 76.82 :small_red_triangle_up: ( previous job: 76.65, degradation: 100.23%)
• whonix-gateway-17_socket-data-duplex: 167.65 :green_circle: ( previous job: 171.76, improvement: 97.61%)
• whonix-workstation-17_exec-root: 56.58 :green_circle: ( previous job: 58.26, improvement: 97.11%)
• whonix-workstation-17_socket-root: 8.43 :small_red_triangle_up: ( previous job: 8.13, degradation: 103.69%)
• whonix-workstation-17_exec-data-simplex: 73.44 :green_circle: ( previous job: 74.99, improvement: 97.93%)
• whonix-workstation-17_exec-data-duplex: 73.50 :small_red_triangle_up: ( previous job: 72.71, degradation: 101.08%)
• whonix-workstation-17_exec-data-duplex-root: 103.23 :small_red_triangle_up: ( previous job: 99.82, degradation: 103.42%)
• whonix-workstation-17_socket-data-duplex: 169.39 :green_circle: ( previous job: 169.50, improvement: 99.93%)

[DemiMarie]

Has this been tested on real hardware? I like the idea but I think it would be best to make sure that it actually works.

0000_00_08.1-00_00.0

I read this as:

• Segment 0000.
• Bus 00 on the root complex.
• Slot 08.
• Function 01, which is a bridge.
• Something 00.
• Slot 00 on the previous bridge.
• Function 00 of the device on that bridge.

What is the something?

[marmarek]

What is the something?

See issue description, commit message, or simply this PR description. But yes, this needs to be also added to a documentation.

Has this been tested on real hardware? I like the idea but I think it would be best to make sure that it actually works.

Yes.