<commit_before># Setup to use SR-IOV with Clear Containers

Single Root I/O Virtualization (SR-IOV) enables splitting a physical device into
virtual functions (VFs). Virtual functions enable direct passthrough to virtual
machines or containers. For Clear Containers, we enabled a Container Network 
Model (CNM) plugin. Additionally, we made the necessary changes in the 
runtime to detect virtual functions in a container's network namespace to be 
able to use SR-IOV for network based devices.

## Install the SR-IOV Docker\* plugin

To create a network with associated VFs, which can be passed to
Clear Containers, you must install a SR-IOV Docker plugin. The 
created network is based on a physical function (PF) device. The network can
create 'n' containers, where 'n' is the number of VFs associated with the 
Physical Function (PF).

To install the plugin, follow the [plugin installation instructions](https://github.com/clearcontainers/sriov).


## Host setup for SR-IOV

In order to setup your host for SR-IOV, the following has to be true:

- The host system must support Intel VT-d. 
- The host kernel must have Input-Output Memory Management Unit (IOMMU) 
  and Virtual Function I/O (VFIO) support.
- `CONFIG_VFIO_NOIOMMU` must to be disabled in the host kernel
  configuration. You must rebuild your host system's kernel in
  order to disable `CONFIG_VFIO_NOIOMMU` in the kernel configuration.
- Optionally, you might need to add a PCI override for your Network Interface 
  Controller (NIC). The immediately following section describes how to assess 
  if you need to make NIC changes and how to make the necessary changes.

### IOMMU Groups and PCIe Access Control Services

Run the following command to see how the IOMMU groups are setup on your 
host system. 
```
$ find /sys/kernel/iommu_groups/ -type l
```
<commit_msg>docs: SR-IOV: Document using lspci to check SR-IOV caps<commit_after># Setup to use SR-IOV with Clear Containers

Single Root I/O Virtualization (SR-IOV) enables splitting a physical device into
virtual functions (VFs). Virtual functions enable direct passthrough to virtual
machines or containers. For Clear Containers, we enabled a Container Network 
Model (CNM) plugin. Additionally, we made the necessary changes in the 
runtime to detect virtual functions in a container's network namespace to be 
able to use SR-IOV for network based devices.

## Install the SR-IOV Docker\* plugin

To create a network with associated VFs, which can be passed to
Clear Containers, you must install a SR-IOV Docker plugin. The 
created network is based on a physical function (PF) device. The network can
create 'n' containers, where 'n' is the number of VFs associated with the 
Physical Function (PF).

To install the plugin, follow the [plugin installation instructions](https://github.com/clearcontainers/sriov).


## Host setup for SR-IOV

In order to setup your host for SR-IOV, the following has to be true:

- The host system must support Intel VT-d. 
- Your device (NIC) must support SR-IOV
- The host kernel must have Input-Output Memory Management Unit (IOMMU) 
  and Virtual Function I/O (VFIO) support.
- `CONFIG_VFIO_NOIOMMU` must to be disabled in the host kernel
  configuration. You must rebuild your host system's kernel in
  order to disable `CONFIG_VFIO_NOIOMMU` in the kernel configuration.
- Optionally, you might need to add a PCI override for your Network Interface 
  Controller (NIC). The immediately following section describes how to assess 
  if you need to make NIC changes and how to make the necessary changes.

### Checking your NIC for SR-IOV

The following is an example of how to use `lspci` to check if your NIC supports
SR-IOV.

```bash
$ lspci | fgrep -i ethernet
01:00.0 Ethernet controller: Intel Corporation Ethernet Controller 10-Gigabit X540-AT2 (rev 03)

...
$ #sudo required below to read the card capabilities

$ sudo lspci -s 01:00.0 -v
01:00.0 Ethernet controller: Intel Corporation Ethernet Controller 10-Gigabit X540-AT2 (rev 03)
        DeviceName: NIC1
        Subsystem: Dell Ethernet 10G 4P X540/I350 rNDC
        Flags: bus master, fast devsel, latency 0, IRQ 146
        Memory at 91c00000 (64-bit, prefetchable) [size=2M]
        Memory at 91e04000 (64-bit, prefetchable) [size=16K]
        Expansion ROM at 92800000 [disabled] [size=512K]
        Capabilities: [40] Power Management version 3
        Capabilities: [50] MSI: Enable- Count=1/1 Maskable+ 64bit+
        Capabilities: [70] MSI-X: Enable+ Count=64 Masked-
        Capabilities: [a0] Express Endpoint, MSI 00
        Capabilities: [e0] Vital Product Data
        Capabilities: [100] Advanced Error Reporting
        Capabilities: [150] Alternative Routing-ID Interpretation (ARI)
        Capabilities: [160] Single Root I/O Virtualization (SR-IOV)
        Capabilities: [1d0] Access Control Services
        Kernel driver in use: ixgbe
        Kernel modules: ixgbe
```

The important line being:

```
        Capabilities: [160] Single Root I/O Virtualization (SR-IOV)
```

If your card does not report this capability, then it does not support SR-IOV.

### IOMMU Groups and PCIe Access Control Services

Run the following command to see how the IOMMU groups are setup on your 
host system. 
```
$ find /sys/kernel/iommu_groups/ -type l
```

{'fraction_non_alphanumeric': 0.06427221172022685, 'fraction_numerical': 0.020415879017013232, 'mean_word_length': 3.8408051235132663, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3386535', 'n_tokens_mistral': 1617, 'n_tokens_neox': 1463, 'n_words': 732}