RE: [PATCH 5/6] dt-bindings: crypto: Add bindings for Starfive crypto driver

[JiaJie Ho <jiajie.ho@starfivetech.com>]

> -----Original Message-----
> From: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> Sent: Wednesday, November 30, 2022 9:21 PM
> To: JiaJie Ho <jiajie.ho@starfivetech.com>; Herbert Xu
> <herbert@gondor.apana.org.au>; David S . Miller <davem@davemloft.net>;
> Rob Herring <robh+dt@kernel.org>; Krzysztof Kozlowski
> <krzysztof.kozlowski+dt@linaro.org>
> Cc: linux-crypto@vger.kernel.org; devicetree@vger.kernel.org; linux-
> kernel@vger.kernel.org; linux-riscv@lists.infradead.org
> Subject: Re: [PATCH 5/6] dt-bindings: crypto: Add bindings for Starfive crypto
> driver
> 
> On 30/11/2022 06:52, Jia Jie Ho wrote:
> > Add documentation to describe Starfive crypto driver bindings.
> 
> Please wrap commit message according to Linux coding style / submission
> process:
> https://elixir.bootlin.com/linux/v5.18-
> rc4/source/Documentation/process/submitting-patches.rst#L586
> 
> 
> Subject: drop second, redundant "bindings".
> 
> 

I'll fix the commit title and message in the next version.

> >
> > Signed-off-by: Jia Jie Ho <jiajie.ho@starfivetech.com>
> > Signed-off-by: Huan Feng <huan.feng@starfivetech.com>
> > ---
> >  .../bindings/crypto/starfive-crypto.yaml      | 109 ++++++++++++++++++
> >  1 file changed, 109 insertions(+)
> >  create mode 100644
> > Documentation/devicetree/bindings/crypto/starfive-crypto.yaml
> >
> > diff --git
> > a/Documentation/devicetree/bindings/crypto/starfive-crypto.yaml
> > b/Documentation/devicetree/bindings/crypto/starfive-crypto.yaml
> > new file mode 100644
> > index 000000000000..6b852f774c32
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/crypto/starfive-crypto.yaml
> 
> Filename based on compatible, so starfive,jh7110-crypto.yaml
> 

Will update filename.

> > @@ -0,0 +1,109 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/crypto/starfive-crypto.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: StarFive Crypto Controller Device Tree Bindings
> 
> Drop "Device Tree Bindings"
> 

Will update title.

> > +
> > +maintainers:
> > +  - Jia Jie Ho <jiajie.ho@starfivetech.com>
> > +  - William Qiu <william.qiu@starfivetech.com>
> > +
> > +properties:
> > +  compatible:
> > +    const: starfive,jh7110-crypto
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  reg-names:
> > +    items:
> > +      - const: secreg
> 
> Why do you need reg-names for one entry?
> 

Will remove need of reg-names and update probe function accordingly.

> > +
> > +  clocks:
> > +    items:
> > +      - description: Hardware reference clock
> > +      - description: AHB reference clock
> > +
> > +  clock-names:
> > +    items:
> > +      - const: sec_hclk
> > +      - const: sec_ahb
> 
> sec seems redundant, so just "ahb". The first clock then "hclk" or "ref"?
> 

Will fix in next version.

> > +
> > +  interrupts:
> > +    items:
> > +      - description: Interrupt pin for algo completion
> > +      - description: Interrupt pin for DMA transfer completion
> > +
> > +  interrupt-names:
> > +    items:
> > +      - const: secirq
> > +      - const: dmairq
> 
> Drop "irq" from both.
> 

Will fix.

> > +
> > +  resets:
> > +    items:
> > +      - description: STG domain reset line
> > +
> > +  reset-names:
> > +    items:
> > +      - const: sec_hre
> 
> Drop "sec". Why do you need the names for one entry?
> 

Will remove names.

> > +
> > +  enable-side-channel-mitigation:
> > +    description: Enable side-channel-mitigation feature for AES module.
> > +        Enabling this feature will affect the speed performance of
> > +        crypto engine.
> > +    type: boolean
> 
> Why exactly this is a hardware (DT) property, not runtime?
> 

This is a hardware setting provided in StarFive crypto engine only.
The crypto API doesn't control this setting during runtime and leaving this always on will impact speed performance.
So, I added this property to allow user to control this in dtb.

> > +
> > +  enable-dma:
> > +    description: Enable data transfer using dedicated DMA controller.
> > +    type: boolean
> 
> Usually the presence of dmas indicates whether to use or not to use DMA.
> Do you expect a case where DMA channels are provided by you don't want
> DMA? Explain such case and describe why it is a hardware/system integration
> property.
> 

I'll remove this property as DMA is always enabled.

> > +
> > +  dmas:
> > +    items:
> > +      - description: TX DMA channel
> > +      - description: RX DMA channel
> > +
> > +  dma-names:
> > +    items:
> > +      - const: sec_m
> 
> tx
> 

Will fix.

> > +      - const: sec_p
> 
> rx
> 

Will fix.

> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - reg-names
> > +  - clocks
> > +  - clock-names
> > +  - resets
> > +  - reset-names
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/clock/starfive-jh7110.h>
> > +    #include <dt-bindings/reset/starfive-jh7110.h>
> > +
> > +    soc {
> > +            #address-cells = <2>;
> > +            #size-cells = <2>;
> 
> Use 4 spaces for example indentation.

I'll fix the indentation.

Thank you for taking time to review and provide helpful comments for this patch.

Best regards,
Jia Jie