Re: [PATCH v3 12/23] dt-bindings: ata: ahci: Add platform capability properties

[Rob Herring <robh@kernel.org>]

On Thu, May 12, 2022 at 02:17:59AM +0300, Serge Semin wrote:
> In case if the platform doesn't have BIOS or a comprehensive firmware
> installed then the HBA capability flags will be left uninitialized. As a
> good alternative we can define a set AHCI DT-node properties to describe
> all of HW-init capabilities flags. Luckily there aren't too many of them.
> SSS - Staggered Spin-up support and MPS - Mechanical Presence Switch
> support determine the corresponding feature availability for whole HBA by
> means of the "hba-sss" and "hba-smps" properties.  Each port can have the
> "hba-{hpcp,mpsp,cpd,esp,fbscp}" defined indicatating that the port
> supports the next functionality: HPCP - HotPlug capable port, MPSP -
> Mechanical Presence Switch attached to a port, CPD - Cold Plug detection,
> ESP - External SATA Port (eSATA), FBSCP - FIS-based switching capable
> port.
> 
> Signed-off-by: Serge Semin <Sergey.Semin@baikalelectronics.ru>
> 
> ---
> 
> Alternatively we could define them as a bitfield, but having a set of
> boolean properties seemed a better idea since in that case we can
> implement a simple inter-dependency rules for them, which can't be done
> should we take the bitfields path.

I would just provide a CAP register override and be done with it.

The boolean fields only let you set a capability, but not unset one. 
They would need to be tristate.

> ---
>  .../devicetree/bindings/ata/ahci-common.yaml  | 66 +++++++++++++++++++
>  .../bindings/ata/ahci-platform.yaml           | 11 ++++
>  2 files changed, 77 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/ata/ahci-common.yaml b/Documentation/devicetree/bindings/ata/ahci-common.yaml
> index a7d1a8353de3..a29edfbb25db 100644
> --- a/Documentation/devicetree/bindings/ata/ahci-common.yaml
> +++ b/Documentation/devicetree/bindings/ata/ahci-common.yaml
> @@ -75,6 +75,19 @@ properties:
>    phy-names:
>      const: sata-phy
>  
> +  hba-sss:
> +    type: boolean
> +    description:
> +      Staggered Spin-up Support. Indicates whether the HBA supports the
> +      staggered spin-up on its ports, for use in balancing power spikes.
> +
> +  hba-smps:
> +    type: boolean
> +    description:
> +      Mechanical Presence Switch Support. Indicates whether the HBA supports
> +      mechanical presence switches on its ports for use in hot plug
> +      operations.
> +
>    ports-implemented:
>      $ref: '/schemas/types.yaml#/definitions/uint32'
>      description:
> @@ -97,6 +110,40 @@ patternProperties:
>          minimum: 0
>          maximum: 31
>  
> +      hba-hpcp:
> +        type: boolean
> +        description:
> +          Hot Plug Capable Port. Indicates that this port’s signal and power
> +          connectors are externally accessible via a joint signal and power
> +          connector for blindmate device hot plug. It is mutually exclusive
> +          with the ESP feature.
> +
> +      hba-mpsp:
> +        type: boolean
> +        description:
> +          Mechanical Presence Switch Attached to Port. Indicates whether
> +          the platform an mechanical presence switch attached to this
> +          port.
> +
> +      hba-cpd:
> +        type: boolean
> +        description:
> +          Cold Presence Detection. Indicates whether the platform supports
> +          cold presence detection on this port.
> +
> +      hba-esp:
> +        type: boolean
> +        description:
> +          External SATA Port. Indicates that this port’s signal connector
> +          is externally accessible on a signal only connector (e.g. eSATA
> +          connector).
> +
> +      hba-fbscp:
> +        type: boolean
> +        description:
> +          FIS-based Switching Capable Port. Indicates whether this port
> +          supports Port Multiplier FIS-based switching.
> +
>        phys:
>          description: Individual AHCI SATA port PHY
>          maxItems: 1
> @@ -111,6 +158,25 @@ patternProperties:
>      required:
>        - reg
>  
> +    # eSATA can't be enabled together with the HotPlug capability
> +    oneOf:
> +      - required:
> +          - hba-hpcp
> +      - required:
> +          - hba-esp
> +      - not:
> +          anyOf:
> +            - required:
> +                - hba-hpcp
> +            - required:
> +                - hba-esp
> +
> +    # HotPlug capability must be enabled together with Cold Plug
> +    # Detection and Mechanical Presence Switching.
> +    dependencies:
> +      hba-cpd: ["hba-hpcp"]
> +      hba-mpsp: ["hba-hpcp"]
> +
>      additionalProperties: true
>  
>  required:
> diff --git a/Documentation/devicetree/bindings/ata/ahci-platform.yaml b/Documentation/devicetree/bindings/ata/ahci-platform.yaml
> index 76075d3c8987..6cad7e86f3bb 100644
> --- a/Documentation/devicetree/bindings/ata/ahci-platform.yaml
> +++ b/Documentation/devicetree/bindings/ata/ahci-platform.yaml
> @@ -117,14 +117,25 @@ examples:
>          #address-cells = <1>;
>          #size-cells = <0>;
>  
> +        hba-smps;
> +
>          sata0: sata-port@0 {
>              reg = <0>;
> +
> +            hba-fbscp;
> +            hba-esp;
> +
>              phys = <&sata_phy 0>;
>              target-supply = <&reg_sata0>;
>          };
>  
>          sata1: sata-port@1 {
>              reg = <1>;
> +
> +            hba-fbscp;
> +            hba-hpcp;
> +            hba-mpsp;
> +
>              phys = <&sata_phy 1>;
>              target-supply = <&reg_sata1>;
>          };
> -- 
> 2.35.1
> 
>