[PATCH v7 1/3] dt-bindings: PCI: brcmstb: Add property "brcm,clkreq-mode"

[Bjorn Helgaas]

On Thu, Nov 09, 2023 at 02:13:52PM -0500, Jim Quinlan wrote:
> The Broadcom STB/CM PCIe HW -- a core that is also used by RPi SOCs --
> requires the driver to deliberately place the RC HW one of three CLKREQ#
> modes.  The "brcm,clkreq-mode" property allows the user to override the
> default setting.  If this property is omitted, the default mode shall be
> "default".
> 
> Signed-off-by: Jim Quinlan <james.quinlan at broadcom.com>
> ---
>  .../bindings/pci/brcm,stb-pcie.yaml           | 21 +++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml b/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml
> index 7e15aae7d69e..992b35e915a5 100644
> --- a/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml
> +++ b/Documentation/devicetree/bindings/pci/brcm,stb-pcie.yaml
> @@ -64,6 +64,27 @@ properties:
>  
>    aspm-no-l0s: true
>  
> +  brcm,clkreq-mode:
> +    description: A string that determines the operating
> +      clkreq mode of the PCIe RC HW WRT controlling the refclk signal.

I assume "WRT" is shorthand for "with respect to", but it's slightly
confusing following all the other acronyms.

> +      There are three different modes --
> +      "safe", which drives the
> +      refclk signal unconditionally and will work for all devices but does
> +      not provide any power savings;
> +      "no-l1ss" -- which provides Clock Power Management, L0s, and
> +      L1, but cannot provide L1 substate (L1SS) power
> +      savings. If the downstream device connected to the RC is
> +      L1SS capable AND the OS enables L1SS, all PCIe traffic
> +      may abruptly halt, potentially hanging the system;
> +      "default" -- which provides L0s, L1, and L1SS, but not
> +      compliant to provide Clock Power Management;
> +      specifically, may not be able to meet the Tclron max
> +      timing of 400ns as specified in "Dynamic Clock Control",
> +      section 3.2.5.2.2 of the PCIe spec.  This situation is
> +      atypical and should happen only with older devices.

These are all weirdly wrapped.  Really no reason to use lines shorter
than 80.

Same spec citation question as in patch 2/3.

> +    $ref: /schemas/types.yaml#/definitions/string
> +    enum: [ safe, no-l1ss, default ]
> +
>    brcm,scb-sizes:
>      description: u64 giving the 64bit PCIe memory
>        viewport size of a memory controller.  There may be up to