Re: [RFC PATCH v3 18/18]: docs: Document support for PCI segment in dbgp and comN parameter

[Jan Beulich <jbeulich@xxxxxxxx>]

On 29.06.2026 19:21, Teddy Astie wrote:
> Now that we accept full PCI SBDF (with segments), update the documentation
> accordingly.
> 
> Signed-off-by: Teddy Astie <teddy.astie@xxxxxxxxxx>
> ---
> In principle, it's correct, but I don't think ECAM is usable
> at the moment EHCI dbgp is initialized, which would prevent
> the device from being probed correctly if it's not on segment 0.

And if there's no other way to access extended config space (like AMD offers,
for example). In any event, imo this restriction wants calling out in all
affected cases.

The doc updates imo also want merging into respective patches.

> Same remark for comN.

And for XHCI.

> --- a/docs/misc/xen-command-line.pandoc
> +++ b/docs/misc/xen-command-line.pandoc
> @@ -349,7 +349,7 @@ ACPI indicating none to be there.
>  
>  ### com1 (x86)
>  ### com2 (x86)
> -> `= 
> <baud>[/<base-baud>][,[DPS][,[<io-base>|pci|amt][,[<irq>|msi][,[<port-bdf>][,[<bridge-bdf>]]]]]]`
> +> `= 
> <baud>[/<base-baud>][,[DPS][,[<io-base>|pci|amt][,[<irq>|msi][,[<port-sbdf>][,[<bridge-sbdf>]]]]]]`
>  
>  Both option `com1` and `com2` follow the same format.
>  
> @@ -371,10 +371,10 @@ Both option `com1` and `com2` follow the same format.
>    registers.
>  * `<irq>` is the IRQ number to use, or `0` to use the UART in poll
>    mode only, or `msi` to set up a Message Signaled Interrupt.
> -* `<port-bdf>` is the PCI location of the UART, in
> -  `<bus>:<device>.<function>` notation.
> -* `<bridge-bdf>` is the PCI bridge behind which is the UART, in
> -  `<bus>:<device>.<function>` notation.
> +* `<port-sbdf>` is the PCI location of the UART, in
> +  `[<seg>:]<bus>:<device>.<function>` notation.
> +* `<bridge-sbdf>` is the PCI bridge behind which is the UART, in
> +  `[<seg>:]<bus>:<device>.<function>` notation.
>  * `pci` indicates that Xen should scan the PCI bus for the UART,
>    avoiding Intel AMT devices.
>  * `amt` indicated that Xen should scan the PCI bus for the UART,

Instead of explaining how <sbdf> is spelled both here and ...

> @@ -731,11 +731,11 @@ for the `all` value. If that isn't intended, raise
>  the `sched_credit2_max_cpus_runqueue` value.
>  
>  ### dbgp
> -> `= ehci[ <integer> | @pci<bus>:<slot>.<func> ]`
> -> `= xhci[ <integer> | @pci<bus>:<slot>.<func> ][,share=<bool>|hwdom]`
> +> `= ehci[ <integer> | @pci[<seg>:]<bus>:<slot>.<func> ]`
> +> `= xhci[ <integer> | @pci[<seg>:]<bus>:<slot>.<func> 
> ][,share=<bool>|hwdom]`

... here, maybe simply say <sbdf> in all places and add text to the top
of the file?

Jan