How does the "/sys/bus/pci/drivers/*/*" interface work?

How does the "/sys/bus/pci/drivers/*/*" interface work?

[linux.enthusiast]

Hello,
I hope this is the correct mailing list to ask my question.

Looking at "/sys/bus/pci/drivers/xxxxx/" I see a bunch of files, which (for a lack of better term) I will call "interfaces" and they can be used to associate a device with a driver. E.g.:

```
$ ls /sys/bus/pci/drivers/vfio-pci/
bind  module  new_id  remove_id  uevent  unbind
```

For example I can use `bind` or `new_id` to bind a driver to a device:

```
sudo bash -c "echo '0000:${PCI_ADDRESS}' > '/sys/bus/pci/drivers/vfio-pci/bind'"

sudo bash -c "echo '${VENDOR_ID} ${DEVICE_ID}' > '/sys/bus/pci/drivers/vfio-pci/new_id'"
```

and I can use `unbind` to unbind the currently used driver from a device:

```
sudo bash -c "echo '0000:${PCI_ADDRESS}' > '/sys/bus/pci/drivers/${DRIVER}/unbind'"
```

My problem is that I can find no official documentation on these "interfaces" (`bind`, `unbind`, `new_id`, `remove_id`,`uevent`).


It seems to me that I have to use `new_id` to bind the driver for the first time after a reboot and if I then unbind it again, I have to use `bind` instead of `new_id` until I reboot again.

If I use `remove_id` after using `new_id`, I have to use `new_id` again the next time.
But if I use `remove_id` before using `new_id`, I get an error (`echo: write error: No such device`). Same for using `bind` before using `new_id` first.

I have 3 questions now:
1. Are my assumptions correct?
2. If so, how can I check which of these "interfaces" I need (`new_id` vs `bind`) without blindly executing them an then checking if it failed?
3. What are each of these "interfaces" actually doing and how do you use them correctly?

Thanks in advance. I hope I'm doing this correctly, this is my first time on a mailing list.

Best regards
linux.enthusiast

Re: How does the "/sys/bus/pci/drivers/*/*" interface work?

[Keith Busch]

On Thu, May 13, 2021 at 01:49:58PM +0000, linux.enthusiast wrote:
> My problem is that I can find no official documentation on these "interfaces" (`bind`, `unbind`, `new_id`, `remove_id`,`uevent`).

Except uevent (that's for udev), these are currently described in
Documentation/ABI/testing/sysfs-bus-pci.

Re: How does the "/sys/bus/pci/drivers/*/*" interface work?

[linux.enthusiast]

> Documentation/ABI/testing/sysfs-bus-pci.
Thank you, that was incredibly helpful!

There's just one thing that I couldn't find an answer to and that is how to list the current device IDs of a given PCI device driver.

I mean I understand there are default ones and that I can use `new_id` to add dynamic ones, but I don't know how to list any of these in order to know if a `new_id` call would even make sense.

Re: How does the "/sys/bus/pci/drivers/*/*" interface work?

[Keith Busch]

On Thu, May 13, 2021 at 03:25:50PM +0000, linux.enthusiast wrote:
> > Documentation/ABI/testing/sysfs-bus-pci.
> Thank you, that was incredibly helpful!
> 
> There's just one thing that I couldn't find an answer to and that is how to list the current device IDs of a given PCI device driver.
> 
> I mean I understand there are default ones and that I can use `new_id` to add dynamic ones, but I don't know how to list any of these in order to know if a `new_id` call would even make sense.

Run 'modinfo <name-of-driver>'. For pci drivers, each "alias" line will
show some kind of pci information that the driver binds to. For example:

  # modinfo nvme
  filename: /lib/modules/5.12.0+/kernel/drivers/nvme/host/nvme.ko
  <...>
  alias:          pci:v*d*sv*sd*bc01sc08i02*
  alias:          pci:v0000106Bd00002005sv*sd*bc*sc*i*
  alias:          pci:v0000106Bd00002003sv*sd*bc*sc*i*
  alias:          pci:v0000106Bd00002001sv*sd*bc*sc*i*
  alias:          pci:v00001D0Fd0000CD02sv*sd*bc*sc*i*
  <...>

The first "alias" binds to any vendor device that has a matching class
code. The remaining lines show a specific vendor:device identifier.

Re: How does the "/sys/bus/pci/drivers/*/*" interface work?

[linux.enthusiast]

On Thursday, May 13, 2021 5:35 PM, Keith Busch <kbusch@kernel.org> wrote:
> Run 'modinfo <name-of-driver>'. For pci drivers, each "alias" line will
> show some kind of pci information that the driver binds to.

Thank you, unfortunately there are no `alias` entries or any other entries that contain the ID that I dynamically added for the driver I'm looking at (vfio-pci). Maybe this approach only works for the IDs the driver has by default, not the ones added dynamically via `new_id`?

Only for other drivers like `amdgpu` that have default IDs, I can see the aliases.

Re: How does the "/sys/bus/pci/drivers/*/*" interface work?

[Keith Busch]

On Thu, May 13, 2021 at 03:58:01PM +0000, linux.enthusiast wrote:
> On Thursday, May 13, 2021 5:35 PM, Keith Busch <kbusch@kernel.org> wrote:
> > Run 'modinfo <name-of-driver>'. For pci drivers, each "alias" line will
> > show some kind of pci information that the driver binds to.
> 
> Thank you, unfortunately there are no `alias` entries or any other entries that contain the ID that I dynamically added for the driver I'm looking at (vfio-pci). Maybe this approach only works for the IDs the driver has by default, not the ones added dynamically via `new_id`?

Yes, modinfo shows devices the driver has built-in binding. vfio-pci
doesn't bind to anything by default, so nothing there.

It doesn't look like the kernel provides a way to report a list of
dynamically assigned ids.

Re: How does the "/sys/bus/pci/drivers/*/*" interface work?

[linux.enthusiast]

On Thursday, May 13, 2021 6:08 PM, Keith Busch <kbusch@kernel.org> wrote:
> It doesn't look like the kernel provides a way to report a list of
> dynamically assigned ids.

Thanks for all your help Keith Bush, I really appreciate it.

I guess I'll have to always use `new_id` then and if it yells at me try `bind` instead. Or the other way around.