On Fri, Apr 16, 2021 at 09:54:32PM +0200, Rafał Miłecki wrote: > From: Rafał Miłecki <rafal@xxxxxxxxxx> > > This helps validating DTS files. > > Changes that require mentioning: > 1. Property "clock" was renamed to "clocks" > 2. Duplicated properties (defined in nand-controller.yaml) were dropped > 3. Compatible "brcm,nand-bcm63168" was added > > Examples changes: > 1. Nodes "nand" were renamed to "nand-controller" > 2. Nodes "nandcs" were renamed to "nand" > 3. Dropped partitions as they were using old syntax and are well > documented elsewhere anyway > > This rewritten binding validates cleanly using the "dt_binding_check". > Some Linux stored DTS files will require updating to make "dtbs_check" > happy. > > Signed-off-by: Rafał Miłecki <rafal@xxxxxxxxxx> > --- > V2: Drop example partitions that were using deprecated syntax-thanks Rob > --- > .../devicetree/bindings/mtd/brcm,brcmnand.txt | 186 ------------ > .../bindings/mtd/brcm,brcmnand.yaml | 265 ++++++++++++++++++ > 2 files changed, 265 insertions(+), 186 deletions(-) > delete mode 100644 Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt > create mode 100644 Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml > diff --git a/Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml b/Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml > new file mode 100644 > index 000000000000..c0f1e7747e23 > --- /dev/null > +++ b/Documentation/devicetree/bindings/mtd/brcm,brcmnand.yaml > @@ -0,0 +1,265 @@ > +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause > +%YAML 1.2 > +--- > +$id: http://devicetree.org/schemas/mtd/brcm,brcmnand.yaml# > +$schema: http://devicetree.org/meta-schemas/core.yaml# > + > +title: Broadcom STB NAND Controller > + > +maintainers: > + - Brian Norris <computersforpeace@xxxxxxxxx> > + - Kamal Dasu <kdasu.kdev@xxxxxxxxx> > + > +description: | > + The Broadcom Set-Top Box NAND controller supports low-level access to raw NAND > + flash chips. It has a memory-mapped register interface for both control > + registers and for its data input/output buffer. On some SoCs, this controller > + is paired with a custom DMA engine (inventively named "Flash DMA") which > + supports basic PROGRAM and READ functions, among other features. > + > + This controller was originally designed for STB SoCs (BCM7xxx) but is now > + available on a variety of Broadcom SoCs, including some BCM3xxx, BCM63xx, and > + iProc/Cygnus. Its history includes several similar (but not fully register > + compatible) versions. > + > + -- Additional SoC-specific NAND controller properties -- > + > + The NAND controller is integrated differently on the variety of SoCs on which > + it is found. Part of this integration involves providing status and enable > + bits with which to control the 8 exposed NAND interrupts, as well as hardware > + for configuring the endianness of the data bus. On some SoCs, these features > + are handled via standard, modular components (e.g., their interrupts look like > + a normal IRQ chip), but on others, they are controlled in unique and > + interesting ways, sometimes with registers that lump multiple NAND-related > + functions together. The former case can be described simply by the standard > + interrupts properties in the main controller node. But for the latter > + exceptional cases, we define additional 'compatible' properties and associated > + register resources within the NAND controller node above. > + > +properties: > + compatible: > + oneOf: > + - items: > + - enum: > + - brcm,brcmnand-v2.1 > + - brcm,brcmnand-v2.2 > + - brcm,brcmnand-v4.0 > + - brcm,brcmnand-v5.0 > + - brcm,brcmnand-v6.0 > + - brcm,brcmnand-v6.1 > + - brcm,brcmnand-v6.2 > + - brcm,brcmnand-v7.0 > + - brcm,brcmnand-v7.1 > + - brcm,brcmnand-v7.2 > + - brcm,brcmnand-v7.3 > + - const: brcm,brcmnand > + - description: SoC-specific NAND controller > + items: > + - enum: > + - brcm,nand-bcm63138 > + - brcm,nand-iproc > + - enum: > + - brcm,brcmnand-v2.1 > + - brcm,brcmnand-v2.2 > + - brcm,brcmnand-v4.0 > + - brcm,brcmnand-v5.0 > + - brcm,brcmnand-v6.0 > + - brcm,brcmnand-v6.1 > + - brcm,brcmnand-v6.2 > + - brcm,brcmnand-v7.0 > + - brcm,brcmnand-v7.1 > + - brcm,brcmnand-v7.2 > + - brcm,brcmnand-v7.3 How can a specific SoC have all these different versions? > + - const: brcm,brcmnand > + - description: BCM6368 SoC-specific NAND controller > + items: > + - enum: > + - brcm,nand-bcm63168 > + - const: brcm,nand-bcm6368 > + - enum: > + - brcm,brcmnand-v2.1 > + - brcm,brcmnand-v2.2 > + - brcm,brcmnand-v4.0 > + - brcm,brcmnand-v5.0 > + - brcm,brcmnand-v6.0 > + - brcm,brcmnand-v6.1 > + - brcm,brcmnand-v6.2 > + - brcm,brcmnand-v7.0 > + - brcm,brcmnand-v7.1 > + - brcm,brcmnand-v7.2 > + - brcm,brcmnand-v7.3 > + - const: brcm,brcmnand > + > + reg: > + minItems: 1 > + maxItems: 6 > + > + reg-names: > + minItems: 1 > + maxItems: 6 > + items: > + - const: nand > + - enum: [ flash-dma, flash-edu, nand-cache, nand-int-base, iproc-idm, iproc-ext ] > + - enum: [ flash-dma, flash-edu, nand-cache, nand-int-base, iproc-idm, iproc-ext ] > + - enum: [ flash-dma, flash-edu, nand-cache, nand-int-base, iproc-idm, iproc-ext ] > + - enum: [ flash-dma, flash-edu, nand-cache, nand-int-base, iproc-idm, iproc-ext ] > + - enum: [ flash-dma, flash-edu, nand-cache, nand-int-base, iproc-idm, iproc-ext ] How many actual combinations do you need to support? A reasonable number can be listed out under a 'oneOf'. Given you're already explicit for 3 cases below, I think I'd just do: items: enum: [ nand, flash-dma, flash-edu, nand-cache, nand-int-base, iproc-idm, iproc-ext ] (Without the '-', 'items' is a schema rather than list and is applied to all entries.) > + > + interrupts: > + minItems: 1 > + maxItems: 3 > + items: > + - description: NAND CTLRDY interrupt > + - description: FLASH_DMA_DONE if flash DMA is available > + - description: FLASH_EDU_DONE if EDU is available > + > + interrupt-names: > + minItems: 1 > + maxItems: 3 > + items: > + - const: nand_ctlrdy > + - const: flash_dma_done > + - const: flash_edu_done > + > + clocks: > + maxItems: 1 > + description: reference to the clock for the NAND controller > + > + clock-names: > + const: nand > + > + brcm,nand-has-wp: > + description: > > + Some versions of this IP include a write-protect > + (WP) control bit. It is always available on >= > + v7.0. Use this property to describe the rare > + earlier versions of this core that include WP > + type: boolean > + > +patternProperties: > + "^nand@[a-f0-9]$": > + type: object > + properties: > + compatible: > + const: brcm,nandcs > + > + nand-ecc-step-size: > + enum: [ 512, 1024 ] > + > + brcm,nand-oob-sector-size: > + description: | > + integer, to denote the spare area sector size > + expected for the ECC layout in use. This size, in > + addition to the strength and step-size, > + determines how the hardware BCH engine will lay > + out the parity bytes it stores on the flash. > + This property can be automatically determined by > + the flash geometry (particularly the NAND page > + and OOB size) in many cases, but when booting > + from NAND, the boot controller has only a limited > + number of available options for its default ECC > + layout. > + $ref: /schemas/types.yaml#/definitions/uint32 > + > +allOf: > + - $ref: nand-controller.yaml# > + - if: > + properties: > + compatible: > + contains: > + const: brcm,nand-bcm63138 > + then: > + properties: > + reg-names: > + minItems: 2 > + maxItems: 2 > + items: > + - const: nand > + - const: nand-int-base > + - if: > + properties: > + compatible: > + contains: > + const: brcm,nand-bcm6368 > + then: > + properties: > + reg-names: > + minItems: 2 > + maxItems: 3 > + items: > + - const: nand > + - const: nand-int-base > + - const: nand-cache > + - if: > + properties: > + compatible: > + contains: > + const: brcm,nand-iproc > + then: > + properties: > + reg-names: > + minItems: 2 > + maxItems: 3 > + items: > + - const: nand > + - const: iproc-idm > + - const: iproc-ext > + > +unevaluatedProperties: false > + > +required: > + - reg > + - reg-names > + - interrupts > + > +examples: > + - | > + nand-controller@f0442800 { > + compatible = "brcm,brcmnand-v7.0", "brcm,brcmnand"; > + reg = <0xf0442800 0x600>, > + <0xf0443000 0x100>; > + reg-names = "nand", "flash-dma"; > + interrupt-parent = <&hif_intr2_intc>; > + interrupts = <24>, <4>; > + > + #address-cells = <1>; > + #size-cells = <0>; > + > + nand@1 { > + compatible = "brcm,nandcs"; > + reg = <1>; // Chip select 1 > + nand-on-flash-bbt; > + nand-ecc-strength = <12>; > + nand-ecc-step-size = <512>; > + > + #address-cells = <1>; > + #size-cells = <1>; > + }; > + }; > + - | > + nand-controller@10000200 { > + compatible = "brcm,nand-bcm63168", "brcm,nand-bcm6368", > + "brcm,brcmnand-v4.0", "brcm,brcmnand"; > + reg = <0x10000200 0x180>, > + <0x100000b0 0x10>, > + <0x10000600 0x200>; > + reg-names = "nand", "nand-int-base", "nand-cache"; > + interrupt-parent = <&periph_intc>; > + interrupts = <50>; > + clocks = <&periph_clk 20>; > + clock-names = "nand"; > + > + #address-cells = <1>; > + #size-cells = <0>; > + > + nand@0 { > + compatible = "brcm,nandcs"; > + reg = <0>; > + nand-on-flash-bbt; > + nand-ecc-strength = <1>; > + nand-ecc-step-size = <512>; > + > + #address-cells = <1>; > + #size-cells = <1>; > + }; > + }; > -- > 2.26.2 >
