[PATCH 0/1] USB Passthrough documentation

[PATCH 0/1] USB Passthrough documentation

[James Prestwood]

[-- Attachment #1: Type: text/plain, Size: 347 bytes --]

I just added this to the test-runner document. It ended up being longer
than I expected so if we want this in its own file I can add a separate
one.

James Prestwood (1):
  doc: describe hardware passthrough feature

 doc/test-runner.txt | 62 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

-- 
2.17.1

[PATCH 1/1] doc: describe hardware passthrough feature

[James Prestwood]

[-- Attachment #1: Type: text/plain, Size: 3398 bytes --]

There are wiki's floating around, but I have consolidated the steps for
USB passthough into our internal docs.
---
 doc/test-runner.txt | 62 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/doc/test-runner.txt b/doc/test-runner.txt
index 1bc02ced..2d45bedc 100644
--- a/doc/test-runner.txt
+++ b/doc/test-runner.txt
@@ -389,6 +389,68 @@ if __name__ == '__main__':
 	unittest.main()
 #~~~~~~~~~~~~~~~~~~ end of alwaysFailingTest.py ~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Using hardware passthrough
+---------------------------
+
+The --hw, -w flag lets you pass in a config file containing USB/PCI adapter
+addresses, which can then be used as radios inside the test/VM just as the
+virtual mac80211_hwsim radios are used. Note: physical radios cannot be used at
+the same time as mac80211_hwsim radios.
+
+Using this option, in some cases, does require some pre-configuration that won't
+be described in this document. Specifically, PCI adapters are very involved to
+get setup, and require special kernel boot options (on the host), BIOS changes,
+and most likely a lot of time to get the system working reliably. Because of
+this only USB adapters will be discussed in this document.
+
+If PCI passthrough is something you need, it would be best to follow this guide:
+
+https://wiki.archlinux.org/index.php/PCI_passthrough_via_OVMF
+
+First, whatever kernel you are using must contain the adapters driver and, if
+required, firmware built in. The driver can be built in using 'make menuconfig'
+and finding the correct driver for your adapter:
+
+Device Driver -> Network Device Support -> Wireless LAN
+
+Enable [*] the driver(s) you need, save, and exit.
+
+The firmware also needs to be built in, and this will require you finding the
+right firmware file (/lib/firmware/) required for your adapter and adding it to
+CONFIG_EXTRA_FIRMWARE in your .config file. It is sometimes not very obvious
+what firmware you need. I have found that during the kernel boot some adapters
+will print out if the firmware was not found, and the name of the firmware file
+they expect. If you are having trouble finding the firmware file try continuing
+on and see what happens when test-runner starts. Google is also your friend.
+
+Once you have the kernel built you can write your hardware config file for
+test-runner. Find the USB bus and device for the adapter:
+
+$ lsusb
+
+You should see your device listed with a 'Bus' and 'Device' number:
+
+$ Bus 001 Device 002: ........
+
+Put these into your passthrough config file under a 'USBAdapters' group:
+
+[USBAdapters]
+rad0=1,2
+
+Note: The 'rad#' does not matter at this time. These named keys will not
+correspond to rad0, rad1, etc in your test config file. This may change in the
+future.
+
+You can then run test-runner using this config file:
+
+./test-runner -k <kernel> --hw passthrough.conf ...
+
+If running specific tests you need to ensure you have enough adapters defined
+in the config file, and that the adapters support the features you expect. For
+example, some adapters cannot go into AP mode, or use certain channels. If your
+test expects these features and the adapters do not support them, the test will
+fail in sometimes unexpected ways.
+
 Using the 'shell' feature
 ---------------------------
 
-- 
2.17.1

Re: [PATCH 1/1] doc: describe hardware passthrough feature

[Paul Menzel]

[-- Attachment #1: Type: text/plain, Size: 3781 bytes --]

Dear James,


Thank you for writing documentation.

Am 17.12.19 um 01:06 schrieb James Prestwood:
> There are wiki's floating around, but I have consolidated the steps for
> USB passthough into our internal docs.

th*r*ough

> ---
>   doc/test-runner.txt | 62 +++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 62 insertions(+)
> 
> diff --git a/doc/test-runner.txt b/doc/test-runner.txt
> index 1bc02ced..2d45bedc 100644
> --- a/doc/test-runner.txt
> +++ b/doc/test-runner.txt
> @@ -389,6 +389,68 @@ if __name__ == '__main__':
>   	unittest.main()
>   #~~~~~~~~~~~~~~~~~~ end of alwaysFailingTest.py ~~~~~~~~~~~~~~~~~~~~~~~~~
>   
> +Using hardware passthrough
> +---------------------------
> +
> +The --hw, -w flag lets you pass in a config file containing USB/PCI adapter
> +addresses, which can then be used as radios inside the test/VM just as the
> +virtual mac80211_hwsim radios are used. Note: physical radios cannot be used at
> +the same time as mac80211_hwsim radios.
> +
> +Using this option, in some cases, does require some pre-configuration that won't
> +be described in this document. Specifically, PCI adapters are very involved to
> +get setup, and require special kernel boot options (on the host), BIOS changes,

The verb *set up* with a space.

> +and most likely a lot of time to get the system working reliably. Because of
> +this only USB adapters will be discussed in this document.
> +
> +If PCI passthrough is something you need, it would be best to follow this guide:
> +
> +https://wiki.archlinux.org/index.php/PCI_passthrough_via_OVMF
> +
> +First, whatever kernel you are using must contain the adapters driver and, if
> +required, firmware built in. The driver can be built in using 'make menuconfig'
> +and finding the correct driver for your adapter:
> +
> +Device Driver -> Network Device Support -> Wireless LAN
> +
> +Enable [*] the driver(s) you need, save, and exit.
> +
> +The firmware also needs to be built in, and this will require you finding the
> +right firmware file (/lib/firmware/) required for your adapter and adding it to
> +CONFIG_EXTRA_FIRMWARE in your .config file. It is sometimes not very obvious
> +what firmware you need. I have found that during the kernel boot some adapters
> +will print out if the firmware was not found, and the name of the firmware file
> +they expect. If you are having trouble finding the firmware file try continuing
> +on and see what happens when test-runner starts. Google is also your friend.

s/Google/A search engine/

> +
> +Once you have the kernel built you can write your hardware config file for
> +test-runner. Find the USB bus and device for the adapter:
> +
> +$ lsusb
> +
> +You should see your device listed with a 'Bus' and 'Device' number:
> +
> +$ Bus 001 Device 002: ........
> +
> +Put these into your passthrough config file under a 'USBAdapters' group:
> +
> +[USBAdapters]
> +rad0=1,2
> +
> +Note: The 'rad#' does not matter at this time. These named keys will not
> +correspond to rad0, rad1, etc in your test config file. This may change in the
> +future.
> +
> +You can then run test-runner using this config file:
> +
> +./test-runner -k <kernel> --hw passthrough.conf ...
> +
> +If running specific tests you need to ensure you have enough adapters defined
> +in the config file, and that the adapters support the features you expect. For
> +example, some adapters cannot go into AP mode, or use certain channels. If your
> +test expects these features and the adapters do not support them, the test will
> +fail in sometimes unexpected ways.
> +
>   Using the 'shell' feature
>   ---------------------------

The rest looks good.


Kind regards,

Paul

Re: [PATCH 1/1] doc: describe hardware passthrough feature

[Denis Kenzior]

[-- Attachment #1: Type: text/plain, Size: 305 bytes --]

Hi Paul,

On 12/17/19 3:18 AM, Paul Menzel wrote:
> Dear James,
> 
> 
> Thank you for writing documentation.
> 

And I'd like to thank you for the review.  I took the liberty of adding 
a Reviewed-By tag with your name on it to the v2 of this patch that I 
applied just now.

Regards,
-Denis