Re: [PATCH v17 04/15] dt-bindings: PCI: pci-ep: Add support for iommu-map and msi-map

[Rob Herring <robh@kernel.org>]

On Mon, Apr 07, 2025 at 03:50:54PM -0400, Frank Li wrote:
> Document the use of (msi|iommu)-map for PCI Endpoint (EP) controllers,
> which can use MSI as a doorbell mechanism. Each EP controller can support
> up to 8 physical functions and 65,536 virtual functions.
> 
> Define how to construct device IDs using function bits [2:0] and virtual
> function index bits [31:3], enabling (msi|iommu)-map to associate each
> child device with a specific (msi|iommu)-specifier.
> 
> The EP cannot rely on PCI Requester ID (RID) because the RID is determined
> by the PCI topology of the host system. Since the EP may be connected to
> different PCI hosts, the RID can vary between systems and is therefore not
> a reliable identifier.
> 
> Signed-off-by: Frank Li <Frank.Li@nxp.com>
> ---
> Change from v16 to v17
> - new patch
> ---
>  Documentation/devicetree/bindings/pci/pci-ep.yaml | 67 +++++++++++++++++++++++
>  1 file changed, 67 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/pci/pci-ep.yaml b/Documentation/devicetree/bindings/pci/pci-ep.yaml
> index f75000e3093db..a1a5b9b8ef859 100644
> --- a/Documentation/devicetree/bindings/pci/pci-ep.yaml
> +++ b/Documentation/devicetree/bindings/pci/pci-ep.yaml
> @@ -53,6 +53,73 @@ properties:
>        must be unique.
>      $ref: /schemas/types.yaml#/definitions/uint32
>  
> +  msi-map:

Not that the rest of the file is alphabetized, but put i before m.

> +    description: |
> +      Maps a Device ID to an MSI and associated MSI specifier data.
> +
> +      A PCI Endpoint (EP) can use MSI as a doorbell function. This is achieved by
> +      mapping the MSI controller's address into PCI BAR<n>. The PCI Root Complex
> +      can write to this BAR<n>, triggering the EP to generate IRQ. This notifies
> +      the EP-side driver of an event, eliminating the need for the driver to
> +      continuously poll for status changes.
> +
> +      However, the EP cannot rely on Requester ID (RID) because the RID is
> +      determined by the PCI topology of the host system. Since the EP may be
> +      connected to different PCI hosts, the RID can vary between systems and is
> +      therefore not a reliable identifier.
> +
> +      Each EP can support up to 8 physical functions and up to 65,536 virtual
> +      functions. To uniquely identify each child device, a device ID is defined
> +      as
> +         - Bits [2:0] for the function number (func)
> +         - Bits [18:3] for the virtual function index (vfunc)
> +
> +      The resulting device ID is computed as:
> +
> +        (func & 0x7) | (vfunc << 3)
> +
> +      The property is an arbitrary number of tuples of
> +      (device-id-base, msi, msi-base,length).
> +
> +      Any Device ID id in the interval [id-base, id-base + length) is
> +      associated with the listed MSI, with the MSI specifier
> +      (id - id-base + msi-base).
> +    $ref: /schemas/types.yaml#/definitions/uint32-matrix
> +    items:
> +      items:
> +        - description: The Device ID base matched by the entry
> +          maximum: 0x7ffff
> +        - description: phandle to msi-controller node
> +        - description: (optional) The msi-specifier produced for the first
> +            Device ID matched by the entry. Currently, msi-specifier is 0 or
> +            1 cells.
> +        - description: The length of consecutive Device IDs following the
> +            Device ID base
> +          maximum: 0x80000
> +
> +  msi-map-mask:
> +    description: A mask to be applied to each Device ID prior to being
> +      mapped to an msi-specifier per the msi-map property.
> +    $ref: /schemas/types.yaml#/definitions/uint32

maximum: 0x7ffff ?

> +
> +  iommu-map:
> +    $ref: /schemas/types.yaml#/definitions/uint32-matrix
> +    items:
> +      items:
> +        - description: Device ID (see msi-map) base
> +          maximum: 0x7ffff
> +        - description: phandle to IOMMU
> +        - description: IOMMU specifier base (currently always 1 cell)
> +        - description: Number of Device IDs
> +          maximum: 0x80000
> +
> +  iommu-map-mask:
> +    description:
> +      A mask to be applied to each Device ID prior to being mapped to an
> +      IOMMU specifier per the iommu-map property.
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    maximum: 0xffff

0x7ffff ?

> +
>  required:
>    - compatible
>  
> 
> -- 
> 2.34.1
>