Skip to contentSkip to conversation

pciutils: add new readpci utility

PATCH Superseded Jesse Brandeburg 2 participants 3 messages Oct 11, 2022

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 pciutils: add new readpci utility

Add the new utility 'readpci' in order to allow users to read and write the register address space located in the BAR designator + offset.

The reason that this app is better than what is generally available on the internet (there are several) is that this app integrates with the libpci and further benefits from pciutils like arguments and device specifications.

help output:

$ sudo ./readpci -h
./readpci: invalid option -- 'h'
Usage: ./readpci [options] [device]   (/usr/local/share/pci.ids.gz)

Options:

-w <value>              Value to write to the address
-W <value>              Value to write to the address (no read)
-a <value>              Register address
-b <value>              BAR to access other than BAR 0
-m                      Access MSI-X BAR instead of BAR 0
-D                      PCI debugging
-q                      Quiet mode, no banner
-v                      Enable more verbose output

Device:
-d [<vendor>]:[<device>] Show selected devices
-s [[[[<domain>]:]<bus>]:][<slot>][.[<func>]] Show devices in selected slots

basic usage to read a register:

$ sudo ./readpci -s 17:0.0 -a 0xb8000
17:00.0 (8086:1592) - Device 8086:1592
0xb8000 == 0x1

This program was originally written by Shannon Nelson, and extended by me.

Limitations
===========
Currently the utility only allows reading or writing one 32 bit address at a time. The utility must be run as root.

Future options
==============
- Implement machine readable output
- Implement multiple register reads (ranges)
- Implement multiple device match (same register multiple devices of a match)

This change also contains a tiny Makefile optimization to allow overriding the compiler at build time on the command line, which made it easier to test with multiple compilers.

---
 .gitignore  |   1 +
 Makefile    |  19 ++--
 readpci.c   | 310 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 readpci.man |  98 +++++++++++++++++
 4 files changed, 421 insertions(+), 7 deletions(-)
.gitignore +1 -0
index 4a25863a1504..d2b57902900e 100644
@@ -6,5 +6,6 @@
 lspci
 setpci
 example
+readpci
 update-pciids
 pci.ids.gz
Makefile +12 -7
index 9319bb495b21..549457c47229 100644
@@ -47,9 +47,9 @@ INSTALL=install
 DIRINSTALL=install -d
 STRIP=-s
 ifdef CROSS_COMPILE
-CC=$(CROSS_COMPILE)gcc
+CC:=$(CROSS_COMPILE)gcc
 else
-CC=cc
+CC:=cc
 endif
 AR=$(CROSS_COMPILE)ar
 RANLIB=$(CROSS_COMPILE)ranlib
@@ -64,7 +64,7 @@ PCIINC_INS=lib/config.h lib/header.h lib/pci.h lib/types.h
 
 export
 
-all: lib/$(PCILIB) lspci$(EXEEXT) setpci$(EXEEXT) example$(EXEEXT) lspci.8 setpci.8 pcilib.7 pci.ids.5 update-pciids update-pciids.8 $(PCI_IDS)
+all: lib/$(PCILIB) lspci$(EXEEXT) setpci$(EXEEXT) readpci$(EXEEXT) example$(EXEEXT) lspci.8 setpci.8 readpci.8  pcilib.7 pci.ids.5 update-pciids update-pciids.8 $(PCI_IDS)
 
 lib/$(PCILIB): $(PCIINC) force
 	$(MAKE) -C lib all
@@ -103,6 +103,10 @@ update-pciids: update-pciids.sh
 	sed <$< >$@ "s@^DEST=.*@DEST=$(IDSDIR)/$(PCI_IDS)@;s@^PCI_COMPRESSED_IDS=.*@PCI_COMPRESSED_IDS=$(PCI_COMPRESSED_IDS)@"
 	chmod +x $@
 
+# add the readpci executable
+readpci$(EXEEXT): readpci.o lib/$(PCILIB)
+readpci.o: readpci.c pciutils.h $(PCIINC)
+
 # The example of use of libpci
 example$(EXEEXT): example.o lib/$(PCILIB)
 example.o: example.c $(PCIINC)
@@ -123,7 +127,7 @@ TAGS:
 
 clean:
 	rm -f `find . -name "*~" -o -name "*.[oa]" -o -name "\#*\#" -o -name TAGS -o -name core -o -name "*.orig"`
-	rm -f update-pciids lspci$(EXEEXT) setpci$(EXEEXT) example$(EXEEXT) lib/config.* *.[578] pci.ids.gz lib/*.pc lib/*.so lib/*.so.* tags
+	rm -f update-pciids lspci$(EXEEXT) setpci$(EXEEXT) readpci$(EXEEXT) example$(EXEEXT) lib/config.* *.[578] pci.ids.gz lib/*.pc lib/*.so lib/*.so.* tags
 	rm -rf maint/dist
 
 distclean: clean
@@ -133,9 +137,10 @@ install: all
 	$(DIRINSTALL) -m 755 $(DESTDIR)$(BINDIR) $(DESTDIR)$(SBINDIR) $(DESTDIR)$(IDSDIR) $(DESTDIR)$(MANDIR)/man8 $(DESTDIR)$(MANDIR)/man7 $(DESTDIR)/$(MANDIR)/man5
 	$(INSTALL) -c -m 755 $(STRIP) lspci$(EXEEXT) $(DESTDIR)$(LSPCIDIR)
 	$(INSTALL) -c -m 755 $(STRIP) setpci$(EXEEXT) $(DESTDIR)$(SBINDIR)
+	$(INSTALL) -c -m 755 $(STRIP) readpci$(EXEEXT) $(DESTDIR)$(SBINDIR)
 	$(INSTALL) -c -m 755 update-pciids $(DESTDIR)$(SBINDIR)
 	$(INSTALL) -c -m 644 $(PCI_IDS) $(DESTDIR)$(IDSDIR)
-	$(INSTALL) -c -m 644 lspci.8 setpci.8 update-pciids.8 $(DESTDIR)$(MANDIR)/man8
+	$(INSTALL) -c -m 644 lspci.8 setpci.8 readpci.8 update-pciids.8 $(DESTDIR)$(MANDIR)/man8
 	$(INSTALL) -c -m 644 pcilib.7 $(DESTDIR)$(MANDIR)/man7
 	$(INSTALL) -c -m 644 pci.ids.5 $(DESTDIR)$(MANDIR)/man5
 ifeq ($(SHARED),yes)
@@ -169,9 +174,9 @@ endif
 endif
 
 uninstall: all
-	rm -f $(DESTDIR)$(SBINDIR)/lspci$(EXEEXT) $(DESTDIR)$(SBINDIR)/setpci$(EXEEXT) $(DESTDIR)$(SBINDIR)/update-pciids
+	rm -f $(DESTDIR)$(SBINDIR)/lspci$(EXEEXT) $(DESTDIR)$(SBINDIR)/setpci$(EXEEXT) $(DESTDIR)$(SBINDIR)/readpci$(EXEEXT) $(DESTDIR)$(SBINDIR)/update-pciids
 	rm -f $(DESTDIR)$(IDSDIR)/$(PCI_IDS)
-	rm -f $(DESTDIR)$(MANDIR)/man8/lspci.8 $(DESTDIR)$(MANDIR)/man8/setpci.8 $(DESTDIR)$(MANDIR)/man8/update-pciids.8
+	rm -f $(DESTDIR)$(MANDIR)/man8/lspci.8 $(DESTDIR)$(MANDIR)/man8/setpci.8 $(DESTDIR)$(MANDIR)/man8/readpci.8 $(DESTDIR)$(MANDIR)/man8/update-pciids.8
 	rm -f $(DESTDIR)$(MANDIR)/man7/pcilib.7
 	rm -f $(DESTDIR)$(MANDIR)/man5/pci.ids.5
 	rm -f $(DESTDIR)$(LIBDIR)/$(PCILIB)
readpci.c new file +310 -0

310 lines not on this page · raw message

readpci.man new file +98 -0

98 lines not on this page · raw message

base-commit: 0478e1f3928bfaa34eb910ba2cbaf1dda8f84aab

Signature · 1 line
2.31.1
#1 lore raw
Quoted 24 lines · Jesse Brandeburg

Add the new utility 'readpci' in order to allow users to read and write the register address space located in the BAR designator + offset.

The reason that this app is better than what is generally available on the internet (there are several) is that this app integrates with the libpci and further benefits from pciutils like arguments and device specifications.

help output:

$ sudo ./readpci -h
./readpci: invalid option -- 'h'
Usage: ./readpci [options] [device]   (/usr/local/share/pci.ids.gz)

Options:

(quoted diff) +0 -8
-w <value>              Value to write to the address
-W <value>              Value to write to the address (no read)
-a <value>              Register address
-b <value>              BAR to access other than BAR 0
-m                      Access MSI-X BAR instead of BAR 0
-D                      PCI debugging
-q                      Quiet mode, no banner
-v                      Enable more verbose output

Device:

Review

Quoted 2 lines
(quoted diff) +0 -2
-d [<vendor>]:[<device>]                        Show selected devices
-s [[[[<domain>]:]<bus>]:][<slot>][.[<func>]]   Show devices in selected slots

I like this idea. I often use rdwrmem, which is more general-purpose, but it's a bit of a hassle that it's not commonly installed like pciutils is, and you have to manually come up with the physical address of a BAR.

The names:
"setpci" -- read and write PCI config space
"readpci" -- read and write PCI MMIO BARs
are slightly confusing since both support reads *and* writes, and there's no clear config space vs BAR connection in the names.

Would it make any sense to integrate this into setpci, e.g., by adding an address format for BAR MMIO offsets?

Quoted 5 lines

basic usage to read a register:

$ sudo ./readpci -s 17:0.0 -a 0xb8000
17:00.0 (8086:1592) - Device 8086:1592
0xb8000 == 0x1

Possibly annotate with the BAR # and the complete physical address (to correlate with lspci or dmesg output, especially when debugging via email)? Maybe also useful with reading MSI-X BAR. Looks like maybe it already does some of this with "v".

Possibly fill out the value to indicate the access width, e.g., 0x00000001 in this case?

Quoted 2 lines

Currently the utility only allows reading or writing one 32 bit address at a time. The utility must be run as root.

Does this mean the *address* is limited to 32 bits, or the access size is 32 bits?

Quoted 3 lines

+++ b/readpci.man

+Access to read and write registers in PCI configuration space is restricted to root,

IIUC, readpci is for MMIO, not config space. But I guess readpci still needs data from config space to figure out *where* to read? But I assume that would normally come from sysfs, not config space directly, so we can account for _TRA offsets. I assume that info is sysfs is also root-only, so it amounts to the same thing. And /dev/mem itself is also root-only.

I guess I would say either just "readpci can only be used by root" or list the items actually required (sysfs config info and /dev/mem) in case access to them requires different CAP_SYS_* things.

readpci.man line 46

Quoted 7 lines
readpci.man new file +6 -0
+So,
+.I readpci
+isn't available to normal users.
 
+.B -b [<value>]
+Optional parameter, defaults to 0 if not specified. BAR number to access if
+other than BAR0.

Maybe move the main point ("BAR number") first, mention the "optional" part later?

readpci.man line 66

Quoted 2 lines
readpci.man new file +2 -0
+on any bus, "0.3" selects third function of device 0 on all buses and ".4" shows only
+the fourth function of each device.

Isn't "0.3" the *fourth* function? 0.0, 0.1, 0.2, 0.3? Maybe reword to avoid the question of whether we start with "zeroth" or "first", e.g., "0.3 selects function 3 of device 0 on all buses"?

readpci.man line 87

Quoted 2 lines
readpci.man new file +2 -0
+There might be some, but none known at this time. If you find one please
+let the list know.

Does this man page say what "the list" refers to?

Bjorn

[1] https://cmp.felk.cvut.cz/~pisa/linux/rdwrmem.c

#2 lore raw
Quoted 4 lines · Bjorn Helgaas

I like this idea. I often use rdwrmem, which is more general-purpose, but it's a bit of a hassle that it's not commonly installed like pciutils is, and you have to manually come up with the physical address of a BAR.

I think that's a lot of the advantage of this tool. And yes, there are a lot of other versions of this program around that just read/write /dev/mem. Having it come with the pciutils makes the most sense to me, which is why I'm here.

Quoted 5 lines

The names:
"setpci" -- read and write PCI config space "readpci" -- read and write PCI MMIO BARs
are slightly confusing since both support reads *and* writes, and there's no clear config space vs BAR connection in the names.

Yeah, naming is super hard. I chose the *pci name to just keep it consistent with the tools in this package, but if Martin or you has some other suggestions, we can rabbit down that hole. I'm not super opposed to something like:
"mmio_write_pci"
or even
"mmio_pci"

Quoted 2 lines

Would it make any sense to integrate this into setpci, e.g., by adding an address format for BAR MMIO offsets?

I hadn't thought of that, but it's not a horrible idea. My feeling in general is that I like to differentiate the tools to having "one job" sort of unix/posix style, and since this one reads/writes mmio, offset from the BAR, I prefer that setpci keep the job of reading/writing PCI registers, and this new thing does mmio.

Quoted 10 lines
Quoted 5 lines

basic usage to read a register:

$ sudo ./readpci -s 17:0.0 -a 0xb8000
17:00.0 (8086:1592) - Device 8086:1592
0xb8000 == 0x1

Possibly annotate with the BAR # and the complete physical address (to correlate with lspci or dmesg output, especially when debugging via email)? Maybe also useful with reading MSI-X BAR. Looks like maybe it already does some of this with "v".

I think your point is reasonable, here is the -v output currently:

$ sudo ./readpci -s 17:0.0 -a 0xb8000 -v
17:00.0 (8086:1592) - Device 8086:1592
BAR0: len 0x02000000
0xb8000 == 0x1

Maybe I should print the BAR0 address as well, basically yielding the bits of math that were used to find the final offset and printing that too in verbose mode?

Maybe something like (proposal)

$ sudo ./readpci -s 17:0.0 -a 0xb8000 -v
17:00.0 (8086:1592) - Device 8086:1592
BAR0: Memory at 387ffa000000 (64-bit, prefetchable) [size=32M]
Final address:  387ffa0b8000
0xb8000 == 0x00000001

<the BAR0 string is like the one from lspci -vvv>

Quoted 3 lines

Possibly fill out the value to indicate the access width, e.g., 0x00000001 in this case?

yes, good point.

Quoted 6 lines
Quoted 3 lines

Currently the utility only allows reading or writing one 32 bit address at a time. The utility must be run as root.

Does this mean the *address* is limited to 32 bits, or the access size is 32 bits?

Yeah, I should clarify that, it's the size of the target register, not the address, however, I don't have any devices with > 4GB of registers to try it out on to see if larger addresses will work.

Quoted 11 lines
Quoted 4 lines

+++ b/readpci.man

+Access to read and write registers in PCI configuration space is restricted to root,

IIUC, readpci is for MMIO, not config space. But I guess readpci still needs data from config space to figure out *where* to read? But I assume that would normally come from sysfs, not config space directly, so we can account for _TRA offsets. I assume that info is sysfs is also root-only, so it amounts to the same thing. And /dev/mem itself is also root-only.

I think this is a copy/paste error, so will fix. It was meant to be saying Access to read and write registers via /dev/mem is restricted to root.

Quoted 3 lines

I guess I would say either just "readpci can only be used by root" or list the items actually required (sysfs config info and /dev/mem) in case access to them requires different CAP_SYS_* things.

In this case the app actually checks it's being run by UID 0, since we'll get all sorts of chained failures if you run it as a regular user. But simplifying the text as you suggested is best.

Quoted 11 lines

readpci.man line 46

Quoted 8 lines
readpci.man new file +6 -0
+So,
+.I readpci
+isn't available to normal users.
 
+.B -b [<value>]
+Optional parameter, defaults to 0 if not specified. BAR number to access if
+other than BAR0.

Maybe move the main point ("BAR number") first, mention the "optional" part later?

OK, will fix

Quoted 6 lines

readpci.man line 66

Quoted 2 lines
readpci.man new file +2 -0
+on any bus, "0.3" selects third function of device 0 on all buses and ".4" shows only
+the fourth function of each device.

Isn't "0.3" the *fourth* function? 0.0, 0.1, 0.2, 0.3? Maybe reword to avoid the question of whether we start with "zeroth" or "first", e.g., "0.3 selects function 3 of device 0 on all buses"?

Good point, will fix.

Quoted 5 lines

readpci.man line 87

Quoted 3 lines
readpci.man new file +2 -0
+There might be some, but none known at this time. If you find one please
+let the list know.

Does this man page say what "the list" refers to?

I'll expand it!
Thanks for the review!