Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
dt-bindings: mtd: refactor NAND bindings and add nand-controller-legacy.yaml
The modern NAND controller binding requires NAND chips to be described as
child nodes of the controller, for example:
nand-controller {
...
nand@0 {
/* raw NAND chip properties */
};
};
However, many existing device trees place NAND chip properties directly
within the controller node because those controllers support only a single
chip. This layout is still widely used by older platforms and by other DT
consumers such as U-Boot. Migrating all existing users to the new layout
will take time.
Several kernel drivers, such as ams-delta.c, davinci_nand.c and
fsmc_nand.c, still expect the legacy layout where raw NAND properties are
defined in the controller node.
To support both layouts during the transition:
- Extract NAND chip-related properties into separate schemas
(nand-property.yaml and raw-nand-property.yaml) from
nand-chip.yaml and raw-nand-chip.yaml.
- Introduce nand-controller-legacy.yaml to allow both the
legacy and modern layouts.
- Add a select condition in nand-controller.yaml to prevent
node name pattern matching for fsl,* NAND controllers.
Keep compatibility with existing device trees while allowing gradual
migration to the modern binding structure.
Signed-off-by: Frank Li <Frank.Li@nxp.com>
Reviewed-by: Rob Herring (Arm) <robh@kernel.org>
Signed-off-by: Miquel Raynal <miquel.raynal@bootlin.com>
authored by
Frank Li
and committed by
Miquel Raynal
0ba8da2f
25a915fa
+231
-118
+1
-45
Documentation/devicetree/bindings/mtd/nand-chip.yaml
+1
-45
Documentation/devicetree/bindings/mtd/nand-chip.yaml
···
11
11
12
12
allOf:
13
13
- $ref: mtd.yaml#
14
+
- $ref: nand-property.yaml
14
15
15
16
description: |
16
17
This file covers the generic description of a NAND chip. It implies that the
···
22
21
reg:
23
22
description:
24
23
Contains the chip-select IDs.
25
-
26
-
nand-ecc-engine:
27
-
description: |
28
-
A phandle on the hardware ECC engine if any. There are
29
-
basically three possibilities:
30
-
1/ The ECC engine is part of the NAND controller, in this
31
-
case the phandle should reference the parent node.
32
-
2/ The ECC engine is part of the NAND part (on-die), in this
33
-
case the phandle should reference the node itself.
34
-
3/ The ECC engine is external, in this case the phandle should
35
-
reference the specific ECC engine node.
36
-
$ref: /schemas/types.yaml#/definitions/phandle
37
-
38
-
nand-use-soft-ecc-engine:
39
-
description: Use a software ECC engine.
40
-
type: boolean
41
-
42
-
nand-no-ecc-engine:
43
-
description: Do not use any ECC correction.
44
-
type: boolean
45
-
46
-
nand-ecc-algo:
47
-
description:
48
-
Desired ECC algorithm.
49
-
$ref: /schemas/types.yaml#/definitions/string
50
-
enum: [hamming, bch, rs]
51
-
52
-
nand-ecc-strength:
53
-
description:
54
-
Maximum number of bits that can be corrected per ECC step.
55
-
$ref: /schemas/types.yaml#/definitions/uint32
56
-
minimum: 1
57
-
58
-
nand-ecc-step-size:
59
-
description:
60
-
Number of data bytes covered by a single ECC step.
61
-
$ref: /schemas/types.yaml#/definitions/uint32
62
-
minimum: 1
63
-
64
-
secure-regions:
65
-
description:
66
-
Regions in the NAND chip which are protected using a secure element
67
-
like Trustzone. This property contains the start address and size of
68
-
the secure regions present.
69
-
$ref: /schemas/types.yaml#/definitions/uint64-matrix
70
24
71
25
required:
72
26
- reg
+65
Documentation/devicetree/bindings/mtd/nand-controller-legacy.yaml
+65
Documentation/devicetree/bindings/mtd/nand-controller-legacy.yaml
···
1
+
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2
+
%YAML 1.2
3
+
---
4
+
$id: http://devicetree.org/schemas/mtd/nand-controller-legacy.yaml#
5
+
$schema: http://devicetree.org/meta-schemas/core.yaml#
6
+
7
+
title: NAND Controller Common Properties
8
+
9
+
maintainers:
10
+
- Miquel Raynal <miquel.raynal@bootlin.com>
11
+
- Richard Weinberger <richard@nod.at>
12
+
13
+
description: >
14
+
The NAND controller should be represented with its own DT node, and
15
+
all NAND chips attached to this controller should be defined as
16
+
children nodes of the NAND controller. This representation should be
17
+
enforced even for simple controllers supporting only one chip.
18
+
19
+
This is only for legacy nand controller, new controller should use
20
+
nand-controller.yaml
21
+
22
+
properties:
23
+
24
+
"#address-cells":
25
+
const: 1
26
+
27
+
"#size-cells":
28
+
enum: [0, 1]
29
+
30
+
ranges: true
31
+
32
+
cs-gpios:
33
+
description:
34
+
Array of chip-select available to the controller. The first
35
+
entries are a 1:1 mapping of the available chip-select on the
36
+
NAND controller (even if they are not used). As many additional
37
+
chip-select as needed may follow and should be phandles of GPIO
38
+
lines. 'reg' entries of the NAND chip subnodes become indexes of
39
+
this array when this property is present.
40
+
minItems: 1
41
+
maxItems: 8
42
+
43
+
partitions:
44
+
type: object
45
+
46
+
required:
47
+
- compatible
48
+
49
+
patternProperties:
50
+
"^nand@[a-f0-9]$":
51
+
type: object
52
+
$ref: raw-nand-chip.yaml#
53
+
54
+
"^partition@[0-9a-f]+$":
55
+
type: object
56
+
$ref: /schemas/mtd/partitions/partition.yaml#/$defs/partition-node
57
+
deprecated: true
58
+
59
+
allOf:
60
+
- $ref: raw-nand-property.yaml#
61
+
- $ref: nand-property.yaml#
62
+
63
+
# This is a generic file other binding inherit from and extend
64
+
additionalProperties: true
65
+
+2
Documentation/devicetree/bindings/mtd/nand-controller.yaml
+2
Documentation/devicetree/bindings/mtd/nand-controller.yaml
+64
Documentation/devicetree/bindings/mtd/nand-property.yaml
+64
Documentation/devicetree/bindings/mtd/nand-property.yaml
···
1
+
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2
+
%YAML 1.2
3
+
---
4
+
$id: http://devicetree.org/schemas/mtd/nand-property.yaml#
5
+
$schema: http://devicetree.org/meta-schemas/core.yaml#
6
+
7
+
title: NAND Chip Common Properties
8
+
9
+
maintainers:
10
+
- Miquel Raynal <miquel.raynal@bootlin.com>
11
+
12
+
description: |
13
+
This file covers the generic properties of a NAND chip. It implies that the
14
+
bus interface should not be taken into account: both raw NAND devices and
15
+
SPI-NAND devices are concerned by this description.
16
+
17
+
properties:
18
+
nand-ecc-engine:
19
+
description: |
20
+
A phandle on the hardware ECC engine if any. There are
21
+
basically three possibilities:
22
+
1/ The ECC engine is part of the NAND controller, in this
23
+
case the phandle should reference the parent node.
24
+
2/ The ECC engine is part of the NAND part (on-die), in this
25
+
case the phandle should reference the node itself.
26
+
3/ The ECC engine is external, in this case the phandle should
27
+
reference the specific ECC engine node.
28
+
$ref: /schemas/types.yaml#/definitions/phandle
29
+
30
+
nand-use-soft-ecc-engine:
31
+
description: Use a software ECC engine.
32
+
type: boolean
33
+
34
+
nand-no-ecc-engine:
35
+
description: Do not use any ECC correction.
36
+
type: boolean
37
+
38
+
nand-ecc-algo:
39
+
description:
40
+
Desired ECC algorithm.
41
+
$ref: /schemas/types.yaml#/definitions/string
42
+
enum: [hamming, bch, rs]
43
+
44
+
nand-ecc-strength:
45
+
description:
46
+
Maximum number of bits that can be corrected per ECC step.
47
+
$ref: /schemas/types.yaml#/definitions/uint32
48
+
minimum: 1
49
+
50
+
nand-ecc-step-size:
51
+
description:
52
+
Number of data bytes covered by a single ECC step.
53
+
$ref: /schemas/types.yaml#/definitions/uint32
54
+
minimum: 1
55
+
56
+
secure-regions:
57
+
description:
58
+
Regions in the NAND chip which are protected using a secure element
59
+
like Trustzone. This property contains the start address and size of
60
+
the secure regions present.
61
+
$ref: /schemas/types.yaml#/definitions/uint64-matrix
62
+
63
+
# This file can be referenced by more specific devices (like spi-nands)
64
+
additionalProperties: true
+1
-73
Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml
+1
-73
Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml
···
11
11
12
12
allOf:
13
13
- $ref: nand-chip.yaml#
14
+
- $ref: raw-nand-property.yaml#
14
15
15
16
description: |
16
17
The ECC strength and ECC step size properties define the user
···
31
30
reg:
32
31
description:
33
32
Contains the chip-select IDs.
34
-
35
-
nand-ecc-placement:
36
-
description:
37
-
Location of the ECC bytes. This location is unknown by default
38
-
but can be explicitly set to "oob", if all ECC bytes are
39
-
known to be stored in the OOB area, or "interleaved" if ECC
40
-
bytes will be interleaved with regular data in the main area.
41
-
$ref: /schemas/types.yaml#/definitions/string
42
-
enum: [ oob, interleaved ]
43
-
deprecated: true
44
-
45
-
nand-ecc-mode:
46
-
description:
47
-
Legacy ECC configuration mixing the ECC engine choice and
48
-
configuration.
49
-
$ref: /schemas/types.yaml#/definitions/string
50
-
enum: [none, soft, soft_bch, hw, hw_syndrome, on-die]
51
-
deprecated: true
52
-
53
-
nand-bus-width:
54
-
description:
55
-
Bus width to the NAND chip
56
-
$ref: /schemas/types.yaml#/definitions/uint32
57
-
enum: [8, 16]
58
-
default: 8
59
-
60
-
nand-on-flash-bbt:
61
-
description:
62
-
With this property, the OS will search the device for a Bad
63
-
Block Table (BBT). If not found, it will create one, reserve
64
-
a few blocks at the end of the device to store it and update
65
-
it as the device ages. Otherwise, the out-of-band area of a
66
-
few pages of all the blocks will be scanned at boot time to
67
-
find Bad Block Markers (BBM). These markers will help to
68
-
build a volatile BBT in RAM.
69
-
$ref: /schemas/types.yaml#/definitions/flag
70
-
71
-
nand-ecc-maximize:
72
-
description:
73
-
Whether or not the ECC strength should be maximized. The
74
-
maximum ECC strength is both controller and chip
75
-
dependent. The ECC engine has to select the ECC config
76
-
providing the best strength and taking the OOB area size
77
-
constraint into account. This is particularly useful when
78
-
only the in-band area is used by the upper layers, and you
79
-
want to make your NAND as reliable as possible.
80
-
$ref: /schemas/types.yaml#/definitions/flag
81
-
82
-
nand-is-boot-medium:
83
-
description:
84
-
Whether or not the NAND chip is a boot medium. Drivers might
85
-
use this information to select ECC algorithms supported by
86
-
the boot ROM or similar restrictions.
87
-
$ref: /schemas/types.yaml#/definitions/flag
88
-
89
-
nand-rb:
90
-
description:
91
-
Contains the native Ready/Busy IDs.
92
-
$ref: /schemas/types.yaml#/definitions/uint32-array
93
-
94
-
rb-gpios:
95
-
description:
96
-
Contains one or more GPIO descriptor (the numper of descriptor
97
-
depends on the number of R/B pins exposed by the flash) for the
98
-
Ready/Busy pins. Active state refers to the NAND ready state and
99
-
should be set to GPIOD_ACTIVE_HIGH unless the signal is inverted.
100
-
101
-
wp-gpios:
102
-
description:
103
-
Contains one GPIO descriptor for the Write Protect pin.
104
-
Active state refers to the NAND Write Protect state and should be
105
-
set to GPIOD_ACTIVE_LOW unless the signal is inverted.
106
-
maxItems: 1
107
33
108
34
required:
109
35
- reg
+98
Documentation/devicetree/bindings/mtd/raw-nand-property.yaml
+98
Documentation/devicetree/bindings/mtd/raw-nand-property.yaml
···
1
+
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2
+
%YAML 1.2
3
+
---
4
+
$id: http://devicetree.org/schemas/mtd/raw-nand-property.yaml#
5
+
$schema: http://devicetree.org/meta-schemas/core.yaml#
6
+
7
+
title: Raw NAND Chip Common Properties
8
+
9
+
maintainers:
10
+
- Miquel Raynal <miquel.raynal@bootlin.com>
11
+
12
+
description: |
13
+
The ECC strength and ECC step size properties define the user
14
+
desires in terms of correction capability of a controller. Together,
15
+
they request the ECC engine to correct {strength} bit errors per
16
+
{size} bytes for a particular raw NAND chip.
17
+
18
+
The interpretation of these parameters is implementation-defined, so
19
+
not all implementations must support all possible
20
+
combinations. However, implementations are encouraged to further
21
+
specify the value(s) they support.
22
+
23
+
properties:
24
+
nand-ecc-placement:
25
+
description:
26
+
Location of the ECC bytes. This location is unknown by default
27
+
but can be explicitly set to "oob", if all ECC bytes are
28
+
known to be stored in the OOB area, or "interleaved" if ECC
29
+
bytes will be interleaved with regular data in the main area.
30
+
$ref: /schemas/types.yaml#/definitions/string
31
+
enum: [ oob, interleaved ]
32
+
deprecated: true
33
+
34
+
nand-ecc-mode:
35
+
description:
36
+
Legacy ECC configuration mixing the ECC engine choice and
37
+
configuration.
38
+
$ref: /schemas/types.yaml#/definitions/string
39
+
enum: [none, soft, soft_bch, hw, hw_syndrome, on-die]
40
+
deprecated: true
41
+
42
+
nand-bus-width:
43
+
description:
44
+
Bus width to the NAND chip
45
+
$ref: /schemas/types.yaml#/definitions/uint32
46
+
enum: [8, 16]
47
+
default: 8
48
+
49
+
nand-on-flash-bbt:
50
+
description:
51
+
With this property, the OS will search the device for a Bad
52
+
Block Table (BBT). If not found, it will create one, reserve
53
+
a few blocks at the end of the device to store it and update
54
+
it as the device ages. Otherwise, the out-of-band area of a
55
+
few pages of all the blocks will be scanned at boot time to
56
+
find Bad Block Markers (BBM). These markers will help to
57
+
build a volatile BBT in RAM.
58
+
$ref: /schemas/types.yaml#/definitions/flag
59
+
60
+
nand-ecc-maximize:
61
+
description:
62
+
Whether or not the ECC strength should be maximized. The
63
+
maximum ECC strength is both controller and chip
64
+
dependent. The ECC engine has to select the ECC config
65
+
providing the best strength and taking the OOB area size
66
+
constraint into account. This is particularly useful when
67
+
only the in-band area is used by the upper layers, and you
68
+
want to make your NAND as reliable as possible.
69
+
$ref: /schemas/types.yaml#/definitions/flag
70
+
71
+
nand-is-boot-medium:
72
+
description:
73
+
Whether or not the NAND chip is a boot medium. Drivers might
74
+
use this information to select ECC algorithms supported by
75
+
the boot ROM or similar restrictions.
76
+
$ref: /schemas/types.yaml#/definitions/flag
77
+
78
+
nand-rb:
79
+
description:
80
+
Contains the native Ready/Busy IDs.
81
+
$ref: /schemas/types.yaml#/definitions/uint32-array
82
+
83
+
rb-gpios:
84
+
description:
85
+
Contains one or more GPIO descriptor (the numper of descriptor
86
+
depends on the number of R/B pins exposed by the flash) for the
87
+
Ready/Busy pins. Active state refers to the NAND ready state and
88
+
should be set to GPIOD_ACTIVE_HIGH unless the signal is inverted.
89
+
90
+
wp-gpios:
91
+
description:
92
+
Contains one GPIO descriptor for the Write Protect pin.
93
+
Active state refers to the NAND Write Protect state and should be
94
+
set to GPIOD_ACTIVE_LOW unless the signal is inverted.
95
+
maxItems: 1
96
+
97
+
# This is a generic file other binding inherit from and extend
98
+
additionalProperties: true