dt-bindings: mtd: document Broadcom's BCM47xx partitions

(2) we can't just scan for all supported parsers (like the block system does), since there is a wide diversity of "formats" (no standardization), and it is not always safe or efficient to attempt to do so, particularly since many of them allow their data structures to be placed anywhere on the flash, and so require scanning the entire flash device to find them.

From: Rafał Miłecki <[email protected]>

Broadcom based home router devices use partitions which have to be discovered in a specific way. They are not fixed and there is not any standard partition table. This commit adds and describes a new custom binding for such devices.

Signed-off-by Rafał Miłecki <[email protected]>

---
This commit documents a new binding for describing partitions. Just as a
reminder: we agreed to use "compatible" for that purpose to avoid /guessing/. There are too many cases, devices and /formats/ to just blindly try every possible parser.

This was e.g. described by Boris in his patchset 2+ years ago:
[RFC PATCH 0/7] mtd: partitions: add of_match_table support
http://lists.infradead.org/pipermail/linux-mtd/2015-December/064076.html

Quote:

Quoted 5 lines

(2) we can't just scan for all supported parsers (like the block system does), since there is a wide diversity of "formats" (no standardization), and it is not always safe or efficient to attempt to do so, particularly since many of them allow their data structures to be placed anywhere on the flash, and so require scanning the entire flash device to find them.

I believe this solution was also acked back then by Rob:
[RFC PATCH 3/7] doc: dt: mtd: partition: add on-flash format binding
http://lists.infradead.org/pipermail/linux-mtd/2015-December/064100.html

V2: Move documentation to the new brcm,bcm947xx-cfe-partitions.txt file
as suggested by Rob (we don't want to bloat partition.txt). Slightly update commit message.

I guess this is fine. Can you resend as I don't have the original patch.

I think it should be a separate file though as partition.txt would become very long if every vendor partitioning was added there.

From: Rafał Miłecki <[email protected]>

Broadcom based home router devices use partitions which have to be discovered in a specific way. They are not fixed and there is not any standard partition table. This commit adds and describes a new custom binding for such devices.

Signed-off-by Rafał Miłecki <[email protected]>

---
This commit documents a new binding for describing partitions. Just as a
reminder: we agreed to use "compatible" for that purpose to avoid /guessing/. There are too many cases, devices and /formats/ to just blindly try every possible parser.

This was e.g. described by Boris in his patchset 2+ years ago:
[RFC PATCH 0/7] mtd: partitions: add of_match_table support
http://lists.infradead.org/pipermail/linux-mtd/2015-December/064076.html

Quote:

Quoted 5 lines

(2) we can't just scan for all supported parsers (like the block system does), since there is a wide diversity of "formats" (no standardization), and it is not always safe or efficient to attempt to do so, particularly since many of them allow their data structures to be placed anywhere on the flash, and so require scanning the entire flash device to find them.

I believe this solution was also acked back then by Rob:
[RFC PATCH 3/7] doc: dt: mtd: partition: add on-flash format binding
http://lists.infradead.org/pipermail/linux-mtd/2015-December/064100.html

V2: Move documentation to the new brcm,bcm947xx-cfe-partitions.txt file
as suggested by Rob (we don't want to bloat partition.txt). Slightly update commit message.

---
 .../devicetree/bindings/mtd/partition.txt          |  2 +-
 .../partitions/brcm,bcm947xx-cfe-partitions.txt    | 42 ++++++++++++++++++++++
 2 files changed, 43 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/devicetree/bindings/mtd/partitions/brcm,bcm947xx-cfe-partitions.txt

From: Rafał Miłecki <[email protected]>

Broadcom based home router devices use partitions which have to be discovered in a specific way. They are not fixed and there is not any standard partition table. This commit adds and describes a new custom binding for such devices.

Signed-off-by Rafał Miłecki <[email protected]>

---
This commit documents a new binding for describing partitions. Just as a
reminder: we agreed to use "compatible" for that purpose to avoid /guessing/. There are too many cases, devices and /formats/ to just blindly try every possible parser.

This was e.g. described by Boris in his patchset 2+ years ago:
[RFC PATCH 0/7] mtd: partitions: add of_match_table support
http://lists.infradead.org/pipermail/linux-mtd/2015-December/064076.html

Quote:

Quoted 5 lines

(2) we can't just scan for all supported parsers (like the block system does), since there is a wide diversity of "formats" (no standardization), and it is not always safe or efficient to attempt to do so, particularly since many of them allow their data structures to be placed anywhere on the flash, and so require scanning the entire flash device to find them.

I believe this solution was also acked back then by Rob:
[RFC PATCH 3/7] doc: dt: mtd: partition: add on-flash format binding
http://lists.infradead.org/pipermail/linux-mtd/2015-December/064100.html

V2: Move documentation to the new brcm,bcm947xx-cfe-partitions.txt file
as suggested by Rob (we don't want to bloat partition.txt). Slightly update commit message.

---
 .../devicetree/bindings/mtd/partition.txt          |  2 +-
 .../partitions/brcm,bcm947xx-cfe-partitions.txt    | 42 ++++++++++++++++++++++
 2 files changed, 43 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/devicetree/bindings/mtd/partitions/brcm,bcm947xx-cfe-partitions.txt

Documentation/devicetree/bindings/mtd/partition.txt +1 -1

index 36f3b769a626..a8f382642ba9 100644
@@ -14,7 +14,7 @@ method is used for a given flash device. To describe the method there should be
 a subnode of the flash device that is named 'partitions'. It must have a
 'compatible' property, which is used to identify the method to use.
 
-We currently only document a binding for fixed layouts.
+Available bindings are listed in the "partitions" subdirectory.
 
 
 Fixed Partitions

Documentation/devicetree/bindings/mtd/partitions/brcm,bcm947xx-cfe-partitions.txt new file +32 -0

new file mode 100644
index 000000000000..1d61a029395e
@@ -0,0 +1,42 @@
+Broadcom BCM47xx Partitions
+===========================
+
+Broadcom is one of hardware manufacturers providing SoCs (BCM47xx) used in
+home routers. Their BCM947xx boards using CFE bootloader have several partitions
+without any on-flash partition table. On some devices their sizes and/or
+meanings can also vary so fixed partitioning can't be used.
+
+Discovering partitions on these devices is possible thanks to having a special
+header and/or magic signature at the beginning of each of them. They are also
+block aligned which is important for determinig a size.
+
+Most of partitions use ASCII text based magic for determining a type. More
+complex partitions (like TRX with its HDR0 magic) may include extra header
+containing some details, including a length.
+
+A list of supported partitions includes:
+1) Bootloader with Broadcom's CFE (Common Firmware Environment)
+2) NVRAM with configuration/calibration data
+3) Device manufacturer's data with some default values (e.g. SSIDs)
+4) TRX firmware container which can hold up to 4 subpartitions
+5) Backup TRX firmware used after failed upgrade
+
+As mentioned earlier, role of some partitions may depend on extra configuration.
+For example both: main firmware and backup firmware use the same TRX format with
+the same header. To distinguish currently used firmware a CFE's environment
+variable "bootpartition" is used.
+
+
+Devices using Broadcom partitions described above should should have flash node
+with a subnode named "partitions" using following properties:
+