Re: [PATCH 06/10] dt-bindings: ufs: Add compatibles for S32N79 Host Controller platform driver

[Larisa Ileana Grigore <larisa.grigore@oss.nxp.com>]

On 8/26/2026 5:35 PM, Frank Li wrote:
> On Wed, Aug 26, 2026 at 03:40:44PM +0200, Larisa Grigore wrote:
>> [You don't often get email from larisa.grigore@oss.nxp.com. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
>>
>> Document the device tree binding for the NXP S32N79 DWC-based UFS host
>> controller which is compliant with JESD-223D "Universal Flash Storage Host
>> Controller Interface" v3.0.
>>
>> The controller requires access to the SCM register block and the core
>> clock rate when M-PHY initialization is performed. Add the optional
>> nxp,mphy-boot-mode property to select the M-PHY firmware execution
>> environment.
>> Currently, the M-PHY firmware can only run from ROM. If the property is
>> omitted, M-PHY initialization is assumed to be handled externally.
>>
>> Signed-off-by: Larisa Grigore <larisa.grigore@oss.nxp.com>
>> ---
>>   .../bindings/ufs/nxp,s32n7-ufshc.yaml         | 99 +++++++++++++++++++
>>   1 file changed, 99 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/ufs/nxp,s32n7-ufshc.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/ufs/nxp,s32n7-ufshc.yaml b/Documentation/devicetree/bindings/ufs/nxp,s32n7-ufshc.yaml
>> new file mode 100644
>> index 000000000000..d9d5669be313
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/ufs/nxp,s32n7-ufshc.yaml
>> @@ -0,0 +1,99 @@
>> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/ufs/nxp,s32n7-ufshc.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: NXP S32N79 Universal Flash Storage (UFS) Controller
>> +
>> +maintainers:
>> +  - Larisa Grigore <larisa.grigore@oss.nxp.com>
>> +
>> +# Select only our matches, not all jedec,ufs
>> +select:
>> +  properties:
>> +    compatible:
>> +      contains:
>> +        const: nxp,s32n79-ufshc
>> +  required:
>> +    - compatible
>> +
>> +properties:
>> +  compatible:
>> +    items:
>> +      - const: nxp,s32n79-ufshc
>> +      - const: jedec,ufs-3.0
> 
> Any place actually use this fallback?

You're right Frank! I will switch to `jedec,ufs-2.0` in v2.

> 
>> +
>> +  reg:
>> +    minItems: 1
>> +    items:
>> +      - description: UFS Host Controller registers
>> +      - description: System Control Module registers
>> +
>> +  reg-names:
>> +    description: |
>> +      Names for the register regions. The first entry must be "ufshc".
>> +      The second entry "scm" is mandatory only when nxp,mphy-boot-mode
>> +      property is present.
> 
> you already us if - else branch to restrict this limition, needn't
> description here.

Thank you! Will drop reg-names description in v2.

>> +    minItems: 1
>> +    items:
>> +      - const: ufshc
>> +      - const: scm
>> +
>> +  clocks:
>> +    maxItems: 1
>> +    description: UFS core clock
>> +
>> +  clock-names:
>> +    items:
>> +      - const: core_clk
> 
> Needn't suffix _clk, just "core", generally needn't clock-names if only
> one clocks.

I will rename it to "core" in v2, if that works for you.

>> +
>> +  nxp,mphy-boot-mode:
>> +    description: |
>> +      MPHY initialization mode. Defines how the MPHY firmware should be
>> +      initialized and executed during UFS controller startup.
>> +      If this property is not specified, MPHY initialization will be skipped.
>> +    $ref: /schemas/types.yaml#/definitions/string
>> +    enum:
>> +      - rom
> 
> why not use standard "phy" property, if no "phy" means ROM init it.

First, apologies for not including enough background in the commit message.

On the S32N79, the M-PHY firmware can be brought up in one of three 
ways, selected through the SoC's SCM MPHY_RAM_CONFIG_STATUS register:

1. running MPHY from internal FW ROM,
2. running MPHY from a (modified) FW ROM copy in external SRAM, or
3. running MPHY from a FW image in external SRAM.

`nxp,mphy-boot-mode` was introduced to select which of these boot 
sequences the controller driver programs. Today only option 1, "rom", is 
implemented and validated, but the property was meant to leave room for 
the two SRAM-based modes.

Given this setup, what would you suggest as the appropriate DT 
representation? I would greatly appreciate any guidance you can provide.

> Frank
>> +
>> +required:
>> +  - compatible
>> +  - reg
>> +
>> +allOf:
>> +  - $ref: ufs-common.yaml
>> +  - if:
>> +      required:
>> +        - nxp,mphy-boot-mode
>> +    then:
>> +      properties:
>> +        reg:
>> +          minItems: 2
>> +        reg-names:
>> +          minItems: 2
>> +      required:
>> +        - reg-names
>> +        - clocks
>> +        - clock-names
>> +    else:
>> +      properties:
>> +        reg:
>> +          maxItems: 1
>> +        reg-names:
>> +          maxItems: 1
>> +
>> +unevaluatedProperties: false
>> +
>> +examples:
>> +  - |
>> +    ufshc@4ac80000 {
>> +        compatible = "nxp,s32n79-ufshc", "jedec,ufs-3.0";
>> +        reg = <0x4ac80000 0x1000>, <0x4ac40000 0x1000>;
>> +        reg-names = "ufshc", "scm";
>> +        interrupt-parent = <&irqsteer_coss>;
>> +        interrupts = <211>;
>> +        clocks = <&sys_clk>;
>> +        clock-names = "core_clk";
>> +        nxp,mphy-boot-mode = "rom";
>> +    };
>> --
>> 2.43.0
>>
>>