From: Cheng Ming Lin <chengminglin@mxic.com.tw>

Add "nand-randomizer-enable" and "nand-randomizer-disable" boolean
properties.

These properties allow enabling or disabling the randomizer feature
via the device tree.

According to JEDEC standard JESD22-A117E, no single data pattern
represents a universal worst-case for all NAND flash failure mechanisms.
Different patterns, such as fully programmed, checkerboard, or mostly
erased, can disproportionately stress specific cells (e.g., programmed,
erased, or those influenced by adjacent states).

Given that no fixed pattern can cover all scenarios, the use of a
randomized data pattern is a practical and effective mitigation strategy.
Our hardware implements a randomizer feature that scrambles user data
before it is written to the flash and restores the original data upon read.

This ensures the data stored on the media is more evenly distributed,
thus reducing pattern-dependent degradation. This is especially crucial
for preventing errors caused by unbalanced data (e.g., all zeros or
all ones) in blocks with high program/erase (P/E) cycle counts.
Ultimately, the randomizer improves the long-term reliability and
endurance of the flash device.

Signed-off-by: Cheng Ming Lin <chengminglin@mxic.com.tw>
---
 .../devicetree/bindings/mtd/nand-chip.yaml     | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/devicetree/bindings/mtd/nand-chip.yaml b/Documentation/devicetree/bindings/mtd/nand-chip.yaml
index 609d4a4ddd80..2559cd97ccc5 100644
--- a/Documentation/devicetree/bindings/mtd/nand-chip.yaml
+++ b/Documentation/devicetree/bindings/mtd/nand-chip.yaml
@@ -67,6 +67,24 @@ properties:
       the secure regions present.
     $ref: /schemas/types.yaml#/definitions/uint64-matrix
 
+  nand-randomizer-enable:
+    description:
+      Enable the randomizer feature. This property is mutually-exclusive
+      with nand-randomizer-disable.
+    type: boolean
+
+  nand-randomizer-disable:
+    description:
+      Disable the randomizer feature. This property is mutually-exclusive
+      with nand-randomizer-enable.
+    type: boolean
+
+dependencies:
+  nand-randomizer-enable:
+    not:
+      required:
+        - nand-randomizer-disable
+
 required:
   - reg
 
-- 
2.25.1

On Thu, Mar 05, 2026 at 03:10:40PM +0800, Cheng Ming Lin wrote:
> From: Cheng Ming Lin <chengminglin@mxic.com.tw>
> 
> Add "nand-randomizer-enable" and "nand-randomizer-disable" boolean
> properties.
> 
> These properties allow enabling or disabling the randomizer feature
> via the device tree.
> 
> According to JEDEC standard JESD22-A117E, no single data pattern
> represents a universal worst-case for all NAND flash failure mechanisms.
> Different patterns, such as fully programmed, checkerboard, or mostly
> erased, can disproportionately stress specific cells (e.g., programmed,
> erased, or those influenced by adjacent states).
> 
> Given that no fixed pattern can cover all scenarios, the use of a
> randomized data pattern is a practical and effective mitigation strategy.
> Our hardware implements a randomizer feature that scrambles user data
> before it is written to the flash and restores the original data upon read.
> 
> This ensures the data stored on the media is more evenly distributed,
> thus reducing pattern-dependent degradation. This is especially crucial
> for preventing errors caused by unbalanced data (e.g., all zeros or
> all ones) in blocks with high program/erase (P/E) cycle counts.
> Ultimately, the randomizer improves the long-term reliability and
> endurance of the flash device.
> 
> Signed-off-by: Cheng Ming Lin <chengminglin@mxic.com.tw>
> ---
>  .../devicetree/bindings/mtd/nand-chip.yaml     | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/mtd/nand-chip.yaml b/Documentation/devicetree/bindings/mtd/nand-chip.yaml
> index 609d4a4ddd80..2559cd97ccc5 100644
> --- a/Documentation/devicetree/bindings/mtd/nand-chip.yaml
> +++ b/Documentation/devicetree/bindings/mtd/nand-chip.yaml
> @@ -67,6 +67,24 @@ properties:
>        the secure regions present.
>      $ref: /schemas/types.yaml#/definitions/uint64-matrix
>  
> +  nand-randomizer-enable:
> +    description:
> +      Enable the randomizer feature. This property is mutually-exclusive
> +      with nand-randomizer-disable.
> +    type: boolean
> +
> +  nand-randomizer-disable:
> +    description:
> +      Disable the randomizer feature. This property is mutually-exclusive
> +      with nand-randomizer-enable.
> +    type: boolean
> +
> +dependencies:
> +  nand-randomizer-enable:
> +    not:
> +      required:
> +        - nand-randomizer-disable

Rather than define this in the schema, make the properties inheritly 
mutually-exclusive with a single property:

nand-randomizer = <0|1>;

That's assuming you need not present to mean a 3rd thing such as use the 
bootloader setting. If you only need enable/disable, then a 
single boolean property works.

Rob

>> +  nand-randomizer-enable:
>> +    description:
>> +      Enable the randomizer feature. This property is mutually-exclusive
>> +      with nand-randomizer-disable.
>> +    type: boolean
>> +
>> +  nand-randomizer-disable:
>> +    description:
>> +      Disable the randomizer feature. This property is mutually-exclusive
>> +      with nand-randomizer-enable.
>> +    type: boolean
>> +
>> +dependencies:
>> +  nand-randomizer-enable:
>> +    not:
>> +      required:
>> +        - nand-randomizer-disable
>
> Rather than define this in the schema, make the properties inheritly 
> mutually-exclusive with a single property:
>
> nand-randomizer = <0|1>;
>
> That's assuming you need not present to mean a 3rd thing such as use the 
> bootloader setting. If you only need enable/disable, then a 
> single boolean property works.

We need the "not present" case, so the single boolean property cannot
be considered here.