How to best make include/hw/pci/pcie_sriov.h self-contained

How to best make include/hw/pci/pcie_sriov.h self-contained

[Markus Armbruster]

pcie_sriov.h needs PCI_NUM_REGIONS from pci.h, but doesn't include it.
pci.h must be included before pcie_sriov.h or else compile fails.

Adding #include "pci/pci.h" to pcie_sriov would be wrong, because it
would close an inclusion loop: pci.h includes pcie.h (for
PCIExpressDevice) includes pcie_sriov.h (for PCIESriovPF) includes pci.h
(for PCI_NUM_REGIONS).

The obvious solution is to move PCI_NUM_REGIONS pci.h somewhere
pcie_sriov.h can include without creating a loop.

We already have a few headers that don't include anything: pci_ids.h,
pci_regs.h (includes include/standard-headers/linux/pci_regs.h, which
doesn't count), pcie_regs.h.  Moving PCI_NUM_REGIONS to one of these
would work, but it doesn't feel right.

We could create a new one, say pci_defs.h.  Just for PCI_NUM_REGIONS
feels silly.  So, what else should move there?

Any other ideas?

In case you wonder why I bother you with this...

Back in 2016, we discussed[1] rules for headers, and these were
generally liked:

1. Have a carefully curated header that's included everywhere first.  We
   got that already thanks to Peter: osdep.h.

2. Headers should normally include everything they need beyond osdep.h.
   If exceptions are needed for some reason, they must be documented in
   the header.  If all that's needed from a header is typedefs, put
   those into qemu/typedefs.h instead of including the header.

3. Cyclic inclusion is forbidden.

I'm working on patches to get include/ closer to obeying 2.

[1] Message-ID: <87h9g8j57d.fsf@blackfin.pond.sub.org>
    https://lists.nongnu.org/archive/html/qemu-devel/2016-03/msg03345.html

Re: How to best make include/hw/pci/pcie_sriov.h self-contained

[Philippe Mathieu-Daudé]

On 7/12/22 07:25, Markus Armbruster wrote:
> pcie_sriov.h needs PCI_NUM_REGIONS from pci.h, but doesn't include it.
> pci.h must be included before pcie_sriov.h or else compile fails.
> 
> Adding #include "pci/pci.h" to pcie_sriov would be wrong, because it
> would close an inclusion loop: pci.h includes pcie.h (for
> PCIExpressDevice) includes pcie_sriov.h (for PCIESriovPF) includes pci.h
> (for PCI_NUM_REGIONS).
> 
> The obvious solution is to move PCI_NUM_REGIONS pci.h somewhere
> pcie_sriov.h can include without creating a loop.
> 
> We already have a few headers that don't include anything: pci_ids.h,
> pci_regs.h (includes include/standard-headers/linux/pci_regs.h, which
> doesn't count), pcie_regs.h.  Moving PCI_NUM_REGIONS to one of these
> would work, but it doesn't feel right.
> 
> We could create a new one, say pci_defs.h.  Just for PCI_NUM_REGIONS
> feels silly.  So, what else should move there?

Sounds good to me. Eventually name it pci_standard_defs.h?

We can move the first 100 lines of pci.h there, PCI_ROM_SLOT, 
PCI_NUM_REGIONS, PCI HEADER_TYPE, PCI_NUM_PINS, cap_present, and 
eventually PCIINTxRoute & PCIReqIDType.

> 
> Any other ideas?
> 
> In case you wonder why I bother you with this...
> 
> Back in 2016, we discussed[1] rules for headers, and these were
> generally liked:
> 
> 1. Have a carefully curated header that's included everywhere first.  We
>     got that already thanks to Peter: osdep.h.
> 
> 2. Headers should normally include everything they need beyond osdep.h.
>     If exceptions are needed for some reason, they must be documented in
>     the header.  If all that's needed from a header is typedefs, put
>     those into qemu/typedefs.h instead of including the header.
> 
> 3. Cyclic inclusion is forbidden.
> 
> I'm working on patches to get include/ closer to obeying 2.
> 
> [1] Message-ID: <87h9g8j57d.fsf@blackfin.pond.sub.org>
>      https://lists.nongnu.org/archive/html/qemu-devel/2016-03/msg03345.html
> 
> 

Re: How to best make include/hw/pci/pcie_sriov.h self-contained

[Michael S. Tsirkin]

On Wed, Dec 07, 2022 at 10:02:53AM +0100, Philippe Mathieu-Daudé wrote:
> On 7/12/22 07:25, Markus Armbruster wrote:
> > pcie_sriov.h needs PCI_NUM_REGIONS from pci.h, but doesn't include it.
> > pci.h must be included before pcie_sriov.h or else compile fails.
> > 
> > Adding #include "pci/pci.h" to pcie_sriov would be wrong, because it
> > would close an inclusion loop: pci.h includes pcie.h (for
> > PCIExpressDevice) includes pcie_sriov.h (for PCIESriovPF) includes pci.h
> > (for PCI_NUM_REGIONS).
> > 
> > The obvious solution is to move PCI_NUM_REGIONS pci.h somewhere
> > pcie_sriov.h can include without creating a loop.
> > 
> > We already have a few headers that don't include anything: pci_ids.h,
> > pci_regs.h (includes include/standard-headers/linux/pci_regs.h, which
> > doesn't count), pcie_regs.h.  Moving PCI_NUM_REGIONS to one of these
> > would work, but it doesn't feel right.
> > 
> > We could create a new one, say pci_defs.h.  Just for PCI_NUM_REGIONS
> > feels silly.  So, what else should move there?
> 
> Sounds good to me. Eventually name it pci_standard_defs.h?

standard is not a good name for PCI_NUM_REGIONS. It falls out of
how QEMU represents things not directly out of the standard.
QEMU supports up to 6 BAR registers + 1 expansion ROM.
That's where the number comes from.
Same with PCI_ROM_SLOT - that's a QEMU convention.



> We can move the first 100 lines of pci.h there, PCI_ROM_SLOT,
> PCI_NUM_REGIONS, PCI HEADER_TYPE, PCI_NUM_PINS, cap_present, and eventually
> PCIINTxRoute & PCIReqIDType.

It's a good point that PCI_ROM_SLOT should live with PCI_NUM_REGIONS.

> > 
> > Any other ideas?
> > 
> > In case you wonder why I bother you with this...
> > 
> > Back in 2016, we discussed[1] rules for headers, and these were
> > generally liked:
> > 
> > 1. Have a carefully curated header that's included everywhere first.  We
> >     got that already thanks to Peter: osdep.h.
> > 
> > 2. Headers should normally include everything they need beyond osdep.h.
> >     If exceptions are needed for some reason, they must be documented in
> >     the header.  If all that's needed from a header is typedefs, put
> >     those into qemu/typedefs.h instead of including the header.
> > 
> > 3. Cyclic inclusion is forbidden.
> > 
> > I'm working on patches to get include/ closer to obeying 2.
> > 
> > [1] Message-ID: <87h9g8j57d.fsf@blackfin.pond.sub.org>
> >      https://lists.nongnu.org/archive/html/qemu-devel/2016-03/msg03345.html
> > 
> > 

Re: How to best make include/hw/pci/pcie_sriov.h self-contained

[Michael S. Tsirkin]

On Wed, Dec 07, 2022 at 07:25:49AM +0100, Markus Armbruster wrote:
> pcie_sriov.h needs PCI_NUM_REGIONS from pci.h, but doesn't include it.
> pci.h must be included before pcie_sriov.h or else compile fails.
> 
> Adding #include "pci/pci.h" to pcie_sriov would be wrong, because it
> would close an inclusion loop: pci.h includes pcie.h (for
> PCIExpressDevice) includes pcie_sriov.h (for PCIESriovPF) includes pci.h
> (for PCI_NUM_REGIONS).
> 
> The obvious solution is to move PCI_NUM_REGIONS pci.h somewhere
> pcie_sriov.h can include without creating a loop.
> 
> We already have a few headers that don't include anything: pci_ids.h,
> pci_regs.h (includes include/standard-headers/linux/pci_regs.h, which
> doesn't count), pcie_regs.h.  Moving PCI_NUM_REGIONS to one of these
> would work, but it doesn't feel right.
> 
> We could create a new one, say pci_defs.h.  Just for PCI_NUM_REGIONS
> feels silly.  So, what else should move there?

I'm ok with pci_defs.h
However, I note that most headers including pci.h don't really
need it. Consider include/hw/virtio/virtio-iommu.h all it needs is
PCIBus typedef this is available from qemu/typedefs.h
So if you are poking at this, want to clean that area up generally?

> Any other ideas?
> 
> In case you wonder why I bother you with this...
> 
> Back in 2016, we discussed[1] rules for headers, and these were
> generally liked:
> 
> 1. Have a carefully curated header that's included everywhere first.  We
>    got that already thanks to Peter: osdep.h.
> 
> 2. Headers should normally include everything they need beyond osdep.h.
>    If exceptions are needed for some reason, they must be documented in
>    the header.  If all that's needed from a header is typedefs, put
>    those into qemu/typedefs.h instead of including the header.
> 
> 3. Cyclic inclusion is forbidden.
> 
> I'm working on patches to get include/ closer to obeying 2.
> 
> [1] Message-ID: <87h9g8j57d.fsf@blackfin.pond.sub.org>
>     https://lists.nongnu.org/archive/html/qemu-devel/2016-03/msg03345.html

Re: How to best make include/hw/pci/pcie_sriov.h self-contained

[Markus Armbruster]

"Michael S. Tsirkin" <mst@redhat.com> writes:

> On Wed, Dec 07, 2022 at 07:25:49AM +0100, Markus Armbruster wrote:
>> pcie_sriov.h needs PCI_NUM_REGIONS from pci.h, but doesn't include it.
>> pci.h must be included before pcie_sriov.h or else compile fails.
>> 
>> Adding #include "pci/pci.h" to pcie_sriov would be wrong, because it
>> would close an inclusion loop: pci.h includes pcie.h (for
>> PCIExpressDevice) includes pcie_sriov.h (for PCIESriovPF) includes pci.h
>> (for PCI_NUM_REGIONS).
>> 
>> The obvious solution is to move PCI_NUM_REGIONS pci.h somewhere
>> pcie_sriov.h can include without creating a loop.
>> 
>> We already have a few headers that don't include anything: pci_ids.h,
>> pci_regs.h (includes include/standard-headers/linux/pci_regs.h, which
>> doesn't count), pcie_regs.h.  Moving PCI_NUM_REGIONS to one of these
>> would work, but it doesn't feel right.
>> 
>> We could create a new one, say pci_defs.h.  Just for PCI_NUM_REGIONS
>> feels silly.  So, what else should move there?
>
> I'm ok with pci_defs.h
> However, I note that most headers including pci.h don't really
> need it. Consider include/hw/virtio/virtio-iommu.h all it needs is
> PCIBus typedef this is available from qemu/typedefs.h
> So if you are poking at this, want to clean that area up generally?

I looked into this, which made me reconsider my pci_defs.h idea.
Instead of splitting off pci_defs.h for PCI_NUM_REGIONS and similar
stuff (which stuff exactly?), I'm going to split off pci_device.h for
PCIDevice & friends.

[...]