[PATCH V1] schemas: pci: bridge: Document PCI L0s & L1 entry delay and nfts

[PATCH V1] schemas: pci: bridge: Document PCI L0s & L1 entry delay and nfts

[Krishna Chaitanya Chundru]

Some controllers and endpoints provide provision to program the entry
delays of L0s & L1 which will allow the link to enter L0s & L1 more
aggressively to save power.

As per PCIe spec 6 sec 4.2.5.6, the number of Fast Training Sequence (FTS)
can be programmed by the controllers or endpoints that is used for bit and
Symbol lock when transitioning from L0s to L0 based upon the PCIe data rate
FTS value can vary. So define a array for each data rate for nfts.

These values needs to be programmed before link training.

Signed-off-by: Krishna Chaitanya Chundru <krishna.chundru@oss.qualcomm.com>
---
- This change was suggested in this patch: https://lore.kernel.org/all/20241211060000.3vn3iumouggjcbva@thinkpad/
---
 dtschema/schemas/pci/pci-bus-common.yaml | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/dtschema/schemas/pci/pci-bus-common.yaml b/dtschema/schemas/pci/pci-bus-common.yaml
index 94b648f..f0655ba 100644
--- a/dtschema/schemas/pci/pci-bus-common.yaml
+++ b/dtschema/schemas/pci/pci-bus-common.yaml
@@ -128,6 +128,16 @@ properties:
     $ref: /schemas/types.yaml#/definitions/uint32
     enum: [ 1, 2, 4, 8, 16, 32 ]
 
+  nfts:
+    description:
+      Number of Fast Training Sequence (FTS) used during L0s to L0 exit for bit
+      and Symbol lock.
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    minItems: 1
+    maxItems: 5
+    items:
+      maximum: 255
+
   reset-gpios:
     description: GPIO controlled connection to PERST# signal
     maxItems: 1
@@ -150,6 +160,12 @@ properties:
     description: Disables ASPM L0s capability
     type: boolean
 
+  aspm-l0s-entry-delay-ns:
+    description: Aspm l0s entry delay.
+
+  aspm-l1-entry-delay-ns:
+    description: Aspm l1 entry delay.
+
   vpcie12v-supply:
     description: 12v regulator phandle for the slot
 
-- 
2.34.1

Re: [PATCH V1] schemas: pci: bridge: Document PCI L0s & L1 entry delay and nfts

[Rob Herring]

On Mon, Jan 6, 2025 at 3:33 AM Krishna Chaitanya Chundru
<krishna.chundru@oss.qualcomm.com> wrote:
>
> Some controllers and endpoints provide provision to program the entry
> delays of L0s & L1 which will allow the link to enter L0s & L1 more
> aggressively to save power.
>
> As per PCIe spec 6 sec 4.2.5.6, the number of Fast Training Sequence (FTS)
> can be programmed by the controllers or endpoints that is used for bit and
> Symbol lock when transitioning from L0s to L0 based upon the PCIe data rate
> FTS value can vary. So define a array for each data rate for nfts.
>
> These values needs to be programmed before link training.
>
> Signed-off-by: Krishna Chaitanya Chundru <krishna.chundru@oss.qualcomm.com>
> ---
> - This change was suggested in this patch: https://lore.kernel.org/all/20241211060000.3vn3iumouggjcbva@thinkpad/
> ---
>  dtschema/schemas/pci/pci-bus-common.yaml | 16 ++++++++++++++++

Do these properties apply to any link like downstream ports on a PCIe switch?

>  1 file changed, 16 insertions(+)
>
> diff --git a/dtschema/schemas/pci/pci-bus-common.yaml b/dtschema/schemas/pci/pci-bus-common.yaml
> index 94b648f..f0655ba 100644
> --- a/dtschema/schemas/pci/pci-bus-common.yaml
> +++ b/dtschema/schemas/pci/pci-bus-common.yaml
> @@ -128,6 +128,16 @@ properties:
>      $ref: /schemas/types.yaml#/definitions/uint32
>      enum: [ 1, 2, 4, 8, 16, 32 ]
>
> +  nfts:

Kind of short. How about num-fts? Or is "NFTS" a PCI term?

> +    description:
> +      Number of Fast Training Sequence (FTS) used during L0s to L0 exit for bit
> +      and Symbol lock.
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    minItems: 1
> +    maxItems: 5

Need to define what is each entry? Gen 1 to 5?

> +    items:
> +      maximum: 255

Why not use uint8 array then?

> +
>    reset-gpios:
>      description: GPIO controlled connection to PERST# signal
>      maxItems: 1
> @@ -150,6 +160,12 @@ properties:
>      description: Disables ASPM L0s capability
>      type: boolean
>
> +  aspm-l0s-entry-delay-ns:
> +    description: Aspm l0s entry delay.
> +
> +  aspm-l1-entry-delay-ns:
> +    description: Aspm l1 entry delay.
> +
>    vpcie12v-supply:
>      description: 12v regulator phandle for the slot
>
> --
> 2.34.1
>
>

Re: [PATCH V1] schemas: pci: bridge: Document PCI L0s & L1 entry delay and nfts

[Krishna Chaitanya Chundru]

On 1/6/2025 8:37 PM, Rob Herring wrote:
> On Mon, Jan 6, 2025 at 3:33 AM Krishna Chaitanya Chundru
> <krishna.chundru@oss.qualcomm.com> wrote:
>>
>> Some controllers and endpoints provide provision to program the entry
>> delays of L0s & L1 which will allow the link to enter L0s & L1 more
>> aggressively to save power.
>>
>> As per PCIe spec 6 sec 4.2.5.6, the number of Fast Training Sequence (FTS)
>> can be programmed by the controllers or endpoints that is used for bit and
>> Symbol lock when transitioning from L0s to L0 based upon the PCIe data rate
>> FTS value can vary. So define a array for each data rate for nfts.
>>
>> These values needs to be programmed before link training.
>>
>> Signed-off-by: Krishna Chaitanya Chundru <krishna.chundru@oss.qualcomm.com>
>> ---
>> - This change was suggested in this patch: https://lore.kernel.org/all/20241211060000.3vn3iumouggjcbva@thinkpad/
>> ---
>>   dtschema/schemas/pci/pci-bus-common.yaml | 16 ++++++++++++++++
> 
> Do these properties apply to any link like downstream ports on a PCIe switch?
> 
These applies to downstream ports also on a switch.
>>   1 file changed, 16 insertions(+)
>>
>> diff --git a/dtschema/schemas/pci/pci-bus-common.yaml b/dtschema/schemas/pci/pci-bus-common.yaml
>> index 94b648f..f0655ba 100644
>> --- a/dtschema/schemas/pci/pci-bus-common.yaml
>> +++ b/dtschema/schemas/pci/pci-bus-common.yaml
>> @@ -128,6 +128,16 @@ properties:
>>       $ref: /schemas/types.yaml#/definitions/uint32
>>       enum: [ 1, 2, 4, 8, 16, 32 ]
>>
>> +  nfts:
> 
> Kind of short. How about num-fts? Or is "NFTS" a PCI term?
> 
yes, nfts is the PCIe spec term.
>> +    description:
>> +      Number of Fast Training Sequence (FTS) used during L0s to L0 exit for bit
>> +      and Symbol lock.
>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>> +    minItems: 1
>> +    maxItems: 5
> 
> Need to define what is each entry? Gen 1 to 5?
> 
yes there are from Gen1 to Gen 5, I will update this in next patch these
details.
>> +    items:
>> +      maximum: 255
> 
> Why not use uint8 array then?
>
In the previous commits it was suggested to use u32 by the reviewers to
make it uniform withall the properties,it makes sense to use it as uint8
as we are moving to generic properties.

- Krishna Chaitanya.

>> +
>>     reset-gpios:
>>       description: GPIO controlled connection to PERST# signal
>>       maxItems: 1
>> @@ -150,6 +160,12 @@ properties:
>>       description: Disables ASPM L0s capability
>>       type: boolean
>>
>> +  aspm-l0s-entry-delay-ns:
>> +    description: Aspm l0s entry delay.
>> +
>> +  aspm-l1-entry-delay-ns:
>> +    description: Aspm l1 entry delay.
>> +
>>     vpcie12v-supply:
>>       description: 12v regulator phandle for the slot
>>
>> --
>> 2.34.1
>>
>>
> 

Re: [PATCH V1] schemas: pci: bridge: Document PCI L0s & L1 entry delay and nfts

[Bjorn Helgaas]

On Tue, Jan 07, 2025 at 07:49:00PM +0530, Krishna Chaitanya Chundru wrote:
> On 1/6/2025 8:37 PM, Rob Herring wrote:
> > On Mon, Jan 6, 2025 at 3:33 AM Krishna Chaitanya Chundru
> > <krishna.chundru@oss.qualcomm.com> wrote:
> > > 
> > > Some controllers and endpoints provide provision to program the entry
> > > delays of L0s & L1 which will allow the link to enter L0s & L1 more
> > > aggressively to save power.
> > > 
> > > As per PCIe spec 6 sec 4.2.5.6, the number of Fast Training Sequence (FTS)
> > > can be programmed by the controllers or endpoints that is used for bit and
> > > Symbol lock when transitioning from L0s to L0 based upon the PCIe data rate
> > > FTS value can vary. So define a array for each data rate for nfts.
> > > 
> > > These values needs to be programmed before link training.

> > Do these properties apply to any link like downstream ports on a
> > PCIe switch?
> > 
> These applies to downstream ports also on a switch.

IIUC every PCIe component with a Link, i.e., Upstream Ports (on a
Switch or Endpoint) and Downstream Ports (a Root Port or Switch), has
an N_FTS value that it advertises during Link training.

I suppose N_FTS depends on the component electrical design and maybe
the Link, and it only makes sense to have this n-fts property for
specific devices that support this kind of configuration, right?  I
don't think we would know what to do with n-fts for random plug-in
Switches or Endpoints because there's no generic way to configure
N_FTS, and we *couldn't* do it before the Link is trained anyway
unless there's some sideband mechanism.

> > > +    description:
> > > +      Number of Fast Training Sequence (FTS) used during L0s to L0 exit for bit
> > > +      and Symbol lock.
> > > +    $ref: /schemas/types.yaml#/definitions/uint32-array
> > > +    minItems: 1
> > > +    maxItems: 5
> > 
> > Need to define what is each entry? Gen 1 to 5?
> > 
> yes there are from Gen1 to Gen 5, I will update this in next patch these
> details.

Components are permitted to advertise different N_FTS values at
different *speeds*, not "GenX" (PCIe r6.0, sec 4.2.5.6)

The spec discourages use of Gen1, etc because they are ambiguous (sec
1.2):

  Terms like "PCIe Gen3" are ambiguous and should be avoided. For
  example, "gen3" could mean (1) compliant with Base 3.0, (2)
  compliant with Base 3.1 (last revision of 3.x), (3) compliant with
  Base 3.0 and supporting 8.0 GT/s, (4) compliant with Base 3.0 or
  later and supporting 8.0 GT/s, ....

We're stuck with the use of genX for max-link-speed, but we should use
speeds when we can for clarity, e.g., in the description here.

Re: [PATCH V1] schemas: pci: bridge: Document PCI L0s & L1 entry delay and nfts

[Krishna Chaitanya Chundru]

On 1/8/2025 2:12 AM, Bjorn Helgaas wrote:
> On Tue, Jan 07, 2025 at 07:49:00PM +0530, Krishna Chaitanya Chundru wrote:
>> On 1/6/2025 8:37 PM, Rob Herring wrote:
>>> On Mon, Jan 6, 2025 at 3:33 AM Krishna Chaitanya Chundru
>>> <krishna.chundru@oss.qualcomm.com> wrote:
>>>>
>>>> Some controllers and endpoints provide provision to program the entry
>>>> delays of L0s & L1 which will allow the link to enter L0s & L1 more
>>>> aggressively to save power.
>>>>
>>>> As per PCIe spec 6 sec 4.2.5.6, the number of Fast Training Sequence (FTS)
>>>> can be programmed by the controllers or endpoints that is used for bit and
>>>> Symbol lock when transitioning from L0s to L0 based upon the PCIe data rate
>>>> FTS value can vary. So define a array for each data rate for nfts.
>>>>
>>>> These values needs to be programmed before link training.
> 
>>> Do these properties apply to any link like downstream ports on a
>>> PCIe switch?
>>>
>> These applies to downstream ports also on a switch.
> 
> IIUC every PCIe component with a Link, i.e., Upstream Ports (on a
> Switch or Endpoint) and Downstream Ports (a Root Port or Switch), has
> an N_FTS value that it advertises during Link training.
> 
> I suppose N_FTS depends on the component electrical design and maybe
> the Link, and it only makes sense to have this n-fts property for
> specific devices that support this kind of configuration, right?  I
> don't think we would know what to do with n-fts for random plug-in
> Switches or Endpoints because there's no generic way to configure
> N_FTS, and we *couldn't* do it before the Link is trained anyway
> unless there's some sideband mechanism.
yes I agree with it, we have one such type of PCIe switch which has i2c
sideband mechanism = to program it before enabling link training. This
properties can be used for the switches which has side band mechanism.
> 
>>>> +    description:
>>>> +      Number of Fast Training Sequence (FTS) used during L0s to L0 exit for bit
>>>> +      and Symbol lock.
>>>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>>>> +    minItems: 1
>>>> +    maxItems: 5
>>>
>>> Need to define what is each entry? Gen 1 to 5?
>>>
>> yes there are from Gen1 to Gen 5, I will update this in next patch these
>> details.
> 
> Components are permitted to advertise different N_FTS values at
> different *speeds*, not "GenX" (PCIe r6.0, sec 4.2.5.6)
> 
> The spec discourages use of Gen1, etc because they are ambiguous (sec
> 1.2):
> 
>    Terms like "PCIe Gen3" are ambiguous and should be avoided. For
>    example, "gen3" could mean (1) compliant with Base 3.0, (2)
>    compliant with Base 3.1 (last revision of 3.x), (3) compliant with
>    Base 3.0 and supporting 8.0 GT/s, (4) compliant with Base 3.0 or
>    later and supporting 8.0 GT/s, ....
> 
> We're stuck with the use of genX for max-link-speed, but we should use
> speeds when we can for clarity, e.g., in the description here.
Ack, that's why I tried to mention data rates instead of gen in the
commit text.

- Krishna Chaitanya.

Re: [PATCH V1] schemas: pci: bridge: Document PCI L0s & L1 entry delay and nfts

[Bjorn Helgaas]

On Mon, Jan 06, 2025 at 03:03:04PM +0530, Krishna Chaitanya Chundru wrote:
> Some controllers and endpoints provide provision to program the entry
> delays of L0s & L1 which will allow the link to enter L0s & L1 more
> aggressively to save power.

Although these are sort of related because FTS is used during L0s->L1
transitions, I think these are subtle enough that it's worth splitting
this into two patches.

> As per PCIe spec 6 sec 4.2.5.6, the number of Fast Training Sequence (FTS)
> can be programmed by the controllers or endpoints that is used for bit and
> Symbol lock when transitioning from L0s to L0 based upon the PCIe data rate
> FTS value can vary. So define a array for each data rate for nfts.
>
> These values needs to be programmed before link training.

IIUC, the point of this is to program the N_FTS value ("number of Fast
Training Sequences required by the Receiver" as described in PCIe
r6.0, sec 4.2.5.1, tables 4-25, 4-26, 4-27 for TS1, TS2, and Modified
TS1/TS2 Ordered Sets).

During Link training, all PCIe components transmit the N_FTS value
they require.  Sec 4.2.5.6 only describes the Fast Training Sequence
from a protocol perspective.  The fact that the N_FTS value of a
device may be programmable is device-specific.

Possible text:

  Per PCIe r6.0, sec 4.2.5.1, during Link training, a PCIe component
  captures the N_FTS value it receives.  Per 4.2.5.6, when
  transitioning the Link from L0s to L0, it must transmit N_FTS Fast
  Training Sequences to enable the receiver to obtain bit and Symbol
  lock.

  Components may have device-specific ways to configure N_FTS values
  to advertise during Link training.  Define an n_fts array with an
  entry for each supported data rate.

> Signed-off-by: Krishna Chaitanya Chundru <krishna.chundru@oss.qualcomm.com>
> ---
> - This change was suggested in this patch: https://lore.kernel.org/all/20241211060000.3vn3iumouggjcbva@thinkpad/
> ---
>  dtschema/schemas/pci/pci-bus-common.yaml | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)
> 
> diff --git a/dtschema/schemas/pci/pci-bus-common.yaml b/dtschema/schemas/pci/pci-bus-common.yaml
> index 94b648f..f0655ba 100644
> --- a/dtschema/schemas/pci/pci-bus-common.yaml
> +++ b/dtschema/schemas/pci/pci-bus-common.yaml
> @@ -128,6 +128,16 @@ properties:
>      $ref: /schemas/types.yaml#/definitions/uint32
>      enum: [ 1, 2, 4, 8, 16, 32 ]
>  
> +  nfts:
> +    description:
> +      Number of Fast Training Sequence (FTS) used during L0s to L0 exit for bit
> +      and Symbol lock.

I think it's worth using the "number of Fast Training Sequences
required by the Receiver" language from the spec to hint that these
values will be used to program a component with the number of FTSs
that it requires as a Receiver, and the component will advertise this
number as N_FTS during Link training.

  n_fts:
    description:
      The number of Fast Training Sequences (N_FTS) required by the
      Receiver (this component) when transitioning the Link from L0s
      to L0; advertised during initial Link training

> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    minItems: 1
> +    maxItems: 5
> +    items:
> +      maximum: 255
> +
>    reset-gpios:
>      description: GPIO controlled connection to PERST# signal
>      maxItems: 1
> @@ -150,6 +160,12 @@ properties:
>      description: Disables ASPM L0s capability
>      type: boolean
>  
> +  aspm-l0s-entry-delay-ns:
> +    description: Aspm l0s entry delay.
> +
> +  aspm-l1-entry-delay-ns:
> +    description: Aspm l1 entry delay.

s/Aspm/ASPM/
s/l0s/L0s/
s/l1/L1/

(I mentioned these earlier in the conversation you pointed to above,
but they got missed)

Also, to match surrounding items:
s/\.$//

>    vpcie12v-supply:
>      description: 12v regulator phandle for the slot
>  
> -- 
> 2.34.1
> 

Re: [PATCH V1] schemas: pci: bridge: Document PCI L0s & L1 entry delay and nfts

[Krishna Chaitanya Chundru]

On 1/7/2025 5:02 AM, Bjorn Helgaas wrote:
> On Mon, Jan 06, 2025 at 03:03:04PM +0530, Krishna Chaitanya Chundru wrote:
>> Some controllers and endpoints provide provision to program the entry
>> delays of L0s & L1 which will allow the link to enter L0s & L1 more
>> aggressively to save power.
> 
> Although these are sort of related because FTS is used during L0s->L1
> transitions, I think these are subtle enough that it's worth splitting
> this into two patches.
>
Ack I will split the patches as suggested in next series.

>> As per PCIe spec 6 sec 4.2.5.6, the number of Fast Training Sequence (FTS)
>> can be programmed by the controllers or endpoints that is used for bit and
>> Symbol lock when transitioning from L0s to L0 based upon the PCIe data rate
>> FTS value can vary. So define a array for each data rate for nfts.
>>
>> These values needs to be programmed before link training.
> 
> IIUC, the point of this is to program the N_FTS value ("number of Fast
> Training Sequences required by the Receiver" as described in PCIe
> r6.0, sec 4.2.5.1, tables 4-25, 4-26, 4-27 for TS1, TS2, and Modified
> TS1/TS2 Ordered Sets).
> 
> During Link training, all PCIe components transmit the N_FTS value
> they require.  Sec 4.2.5.6 only describes the Fast Training Sequence
> from a protocol perspective.  The fact that the N_FTS value of a
> device may be programmable is device-specific.
> 
> Possible text:
> 
>    Per PCIe r6.0, sec 4.2.5.1, during Link training, a PCIe component
>    captures the N_FTS value it receives.  Per 4.2.5.6, when
>    transitioning the Link from L0s to L0, it must transmit N_FTS Fast
>    Training Sequences to enable the receiver to obtain bit and Symbol
>    lock.
> 
>    Components may have device-specific ways to configure N_FTS values
>    to advertise during Link training.  Define an n_fts array with an
>    entry for each supported data rate.
> 
Ack
>> Signed-off-by: Krishna Chaitanya Chundru <krishna.chundru@oss.qualcomm.com>
>> ---
>> - This change was suggested in this patch: https://lore.kernel.org/all/20241211060000.3vn3iumouggjcbva@thinkpad/
>> ---
>>   dtschema/schemas/pci/pci-bus-common.yaml | 16 ++++++++++++++++
>>   1 file changed, 16 insertions(+)
>>
>> diff --git a/dtschema/schemas/pci/pci-bus-common.yaml b/dtschema/schemas/pci/pci-bus-common.yaml
>> index 94b648f..f0655ba 100644
>> --- a/dtschema/schemas/pci/pci-bus-common.yaml
>> +++ b/dtschema/schemas/pci/pci-bus-common.yaml
>> @@ -128,6 +128,16 @@ properties:
>>       $ref: /schemas/types.yaml#/definitions/uint32
>>       enum: [ 1, 2, 4, 8, 16, 32 ]
>>   
>> +  nfts:
>> +    description:
>> +      Number of Fast Training Sequence (FTS) used during L0s to L0 exit for bit
>> +      and Symbol lock.
> 
> I think it's worth using the "number of Fast Training Sequences
> required by the Receiver" language from the spec to hint that these
> values will be used to program a component with the number of FTSs
> that it requires as a Receiver, and the component will advertise this
> number as N_FTS during Link training.
> 
>    n_fts:
>      description:
>        The number of Fast Training Sequences (N_FTS) required by the
>        Receiver (this component) when transitioning the Link from L0s
>        to L0; advertised during initial Link training
>
Ack

>> +    $ref: /schemas/types.yaml#/definitions/uint32-array
>> +    minItems: 1
>> +    maxItems: 5
>> +    items:
>> +      maximum: 255
>> +
>>     reset-gpios:
>>       description: GPIO controlled connection to PERST# signal
>>       maxItems: 1
>> @@ -150,6 +160,12 @@ properties:
>>       description: Disables ASPM L0s capability
>>       type: boolean
>>   
>> +  aspm-l0s-entry-delay-ns:
>> +    description: Aspm l0s entry delay.
>> +
>> +  aspm-l1-entry-delay-ns:
>> +    description: Aspm l1 entry delay.
> 
> s/Aspm/ASPM/
> s/l0s/L0s/
> s/l1/L1/
> 
Ack
> (I mentioned these earlier in the conversation you pointed to above,
> but they got missed)
> 
Sorry I missed these to update I will update these in the next patch.
and thanks for reviewing and suggestions for the descriptions and commit
text.

- Krishna Chaitanya.
> Also, to match surrounding items:
> s/\.$//
> 
>>     vpcie12v-supply:
>>       description: 12v regulator phandle for the slot
>>   
>> -- 
>> 2.34.1
>>
> 

Re: [PATCH V1] schemas: pci: bridge: Document PCI L0s & L1 entry delay and nfts

[Rob Herring]

On Mon, Jan 6, 2025 at 5:32 PM Bjorn Helgaas <helgaas@kernel.org> wrote:
>
> On Mon, Jan 06, 2025 at 03:03:04PM +0530, Krishna Chaitanya Chundru wrote:
> > Some controllers and endpoints provide provision to program the entry
> > delays of L0s & L1 which will allow the link to enter L0s & L1 more
> > aggressively to save power.
>
> Although these are sort of related because FTS is used during L0s->L1
> transitions, I think these are subtle enough that it's worth splitting
> this into two patches.
>
> > As per PCIe spec 6 sec 4.2.5.6, the number of Fast Training Sequence (FTS)
> > can be programmed by the controllers or endpoints that is used for bit and
> > Symbol lock when transitioning from L0s to L0 based upon the PCIe data rate
> > FTS value can vary. So define a array for each data rate for nfts.
> >
> > These values needs to be programmed before link training.
>
> IIUC, the point of this is to program the N_FTS value ("number of Fast
> Training Sequences required by the Receiver" as described in PCIe
> r6.0, sec 4.2.5.1, tables 4-25, 4-26, 4-27 for TS1, TS2, and Modified
> TS1/TS2 Ordered Sets).
>
> During Link training, all PCIe components transmit the N_FTS value
> they require.  Sec 4.2.5.6 only describes the Fast Training Sequence
> from a protocol perspective.  The fact that the N_FTS value of a
> device may be programmable is device-specific.
>
> Possible text:
>
>   Per PCIe r6.0, sec 4.2.5.1, during Link training, a PCIe component
>   captures the N_FTS value it receives.  Per 4.2.5.6, when
>   transitioning the Link from L0s to L0, it must transmit N_FTS Fast
>   Training Sequences to enable the receiver to obtain bit and Symbol
>   lock.
>
>   Components may have device-specific ways to configure N_FTS values
>   to advertise during Link training.  Define an n_fts array with an
>   entry for each supported data rate.
>
> > Signed-off-by: Krishna Chaitanya Chundru <krishna.chundru@oss.qualcomm.com>
> > ---
> > - This change was suggested in this patch: https://lore.kernel.org/all/20241211060000.3vn3iumouggjcbva@thinkpad/
> > ---
> >  dtschema/schemas/pci/pci-bus-common.yaml | 16 ++++++++++++++++
> >  1 file changed, 16 insertions(+)
> >
> > diff --git a/dtschema/schemas/pci/pci-bus-common.yaml b/dtschema/schemas/pci/pci-bus-common.yaml
> > index 94b648f..f0655ba 100644
> > --- a/dtschema/schemas/pci/pci-bus-common.yaml
> > +++ b/dtschema/schemas/pci/pci-bus-common.yaml
> > @@ -128,6 +128,16 @@ properties:
> >      $ref: /schemas/types.yaml#/definitions/uint32
> >      enum: [ 1, 2, 4, 8, 16, 32 ]
> >
> > +  nfts:
> > +    description:
> > +      Number of Fast Training Sequence (FTS) used during L0s to L0 exit for bit
> > +      and Symbol lock.
>
> I think it's worth using the "number of Fast Training Sequences
> required by the Receiver" language from the spec to hint that these
> values will be used to program a component with the number of FTSs
> that it requires as a Receiver, and the component will advertise this
> number as N_FTS during Link training.
>
>   n_fts:

n-fts

Underscores are discouraged.