dts/upstream/Bindings/arm/bcm/brcm,brcmstb.txt

ARM Broadcom STB platforms Device Tree Bindings
-----------------------------------------------
Boards with Broadcom Brahma15 ARM-based BCMxxxx (generally BCM7xxx variants)
SoC shall have the following DT organization:

Required root node properties:
    - compatible: "brcm,bcm<chip_id>", "brcm,brcmstb"

example:
/ {
    #address-cells = <2>;
    #size-cells = <2>;
    model = "Broadcom STB (bcm7445)";
    compatible = "brcm,bcm7445", "brcm,brcmstb";

Further, syscon nodes that map platform-specific registers used for general
system control is required:

    - compatible: "brcm,bcm<chip_id>-sun-top-ctrl", "syscon"
    - compatible: "brcm,bcm<chip_id>-cpu-biu-ctrl",
		  "brcm,brcmstb-cpu-biu-ctrl",
		  "syscon"
    - compatible: "brcm,bcm<chip_id>-hif-continuation", "syscon"

cpu-biu-ctrl node
-------------------
SoCs with Broadcom Brahma15 ARM-based and Brahma53 ARM64-based CPUs have a
specific Bus Interface Unit (BIU) block which controls and interfaces the CPU
complex to the different Memory Controller Ports (MCP), one per memory
controller (MEMC). This BIU block offers a feature called Write Pairing which
consists in collapsing two adjacent cache lines into a single (bursted) write
transaction towards the memory controller (MEMC) to maximize write bandwidth.

Required properties:

    - compatible: must be "brcm,bcm7445-cpu-biu-ctrl", "brcm,brcmstb-cpu-biu-ctrl", "syscon"

Optional properties:

    - brcm,write-pairing:
	Boolean property, which when present indicates that the chip
	supports write-pairing.

example:
    rdb {
        #address-cells = <1>;
        #size-cells = <1>;
        compatible = "simple-bus";
        ranges = <0 0x00 0xf0000000 0x1000000>;

        sun_top_ctrl: syscon@404000 {
            compatible = "brcm,bcm7445-sun-top-ctrl", "syscon";
            reg = <0x404000 0x51c>;
        };

        hif_cpubiuctrl: syscon@3e2400 {
            compatible = "brcm,bcm7445-cpu-biu-ctrl", "brcm,brcmstb-cpu-biu-ctrl", "syscon";
            reg = <0x3e2400 0x5b4>;
            brcm,write-pairing;
        };

        hif_continuation: syscon@452000 {
            compatible = "brcm,bcm7445-hif-continuation", "syscon";
            reg = <0x452000 0x100>;
        };
    };

Nodes that allow for support of SMP initialization and reboot are required:

smpboot
-------
Required properties:

    - compatible
        The string "brcm,brcmstb-smpboot".

    - syscon-cpu
        A phandle / integer array property which lets the BSP know the location
        of certain CPU power-on registers.

        The layout of the property is as follows:
            o a phandle to the "hif_cpubiuctrl" syscon node
            o offset to the base CPU power zone register
            o offset to the base CPU reset register

    - syscon-cont
        A phandle pointing to the syscon node which describes the CPU boot
        continuation registers.
            o a phandle to the "hif_continuation" syscon node

example:
    smpboot {
        compatible = "brcm,brcmstb-smpboot";
        syscon-cpu = <&hif_cpubiuctrl 0x88 0x178>;
        syscon-cont = <&hif_continuation>;
    };

reboot
-------
Required properties

    - compatible
        The string property "brcm,brcmstb-reboot" for 40nm/28nm chips with
        the new SYS_CTRL interface, or "brcm,bcm7038-reboot" for 65nm
        chips with the old SUN_TOP_CTRL interface.

    - syscon
        A phandle / integer array that points to the syscon node which describes
        the general system reset registers.
            o a phandle to "sun_top_ctrl"
            o offset to the "reset source enable" register
            o offset to the "software master reset" register

example:
    reboot {
        compatible = "brcm,brcmstb-reboot";
        syscon = <&sun_top_ctrl 0x304 0x308>;
    };



Power management
----------------

For power management (particularly, S2/S3/S5 system suspend), the following SoC
components are needed:

= Always-On control block (AON CTRL)

This hardware provides control registers for the "always-on" (even in low-power
modes) hardware, such as the Power Management State Machine (PMSM).

Required properties:
- compatible     : should contain "brcm,brcmstb-aon-ctrl"
- reg            : the register start and length for the AON CTRL block

Example:

aon-ctrl@410000 {
	compatible = "brcm,brcmstb-aon-ctrl";
	reg = <0x410000 0x400>;
};

= Memory controllers

A Broadcom STB SoC typically has a number of independent memory controllers,
each of which may have several associated hardware blocks, which are versioned
independently (control registers, DDR PHYs, etc.). One might consider
describing these controllers as a parent "memory controllers" block, which
contains N sub-nodes (one for each controller in the system), each of which is
associated with a number of hardware register resources (e.g., its PHY). See
the example device tree snippet below.

== MEMC (MEMory Controller)

Represents a single memory controller instance.

Required properties:
- compatible     : should contain "brcm,brcmstb-memc" and "simple-bus"

Should contain subnodes for any of the following relevant hardware resources:

== DDR PHY control

Control registers for this memory controller's DDR PHY.

Required properties:
- compatible     : should contain one of these
	"brcm,brcmstb-ddr-phy-v71.1"
	"brcm,brcmstb-ddr-phy-v72.0"
	"brcm,brcmstb-ddr-phy-v225.1"
	"brcm,brcmstb-ddr-phy-v240.1"
	"brcm,brcmstb-ddr-phy-v240.2"

- reg            : the DDR PHY register range

== DDR SHIMPHY

Control registers for this memory controller's DDR SHIMPHY.

Required properties:
- compatible     : should contain "brcm,brcmstb-ddr-shimphy-v1.0"
- reg            : the DDR SHIMPHY register range

== MEMC DDR control

Sequencer DRAM parameters and control registers. Used for Self-Refresh
Power-Down (SRPD), among other things.

See Documentation/devicetree/bindings/memory-controllers/brcm,brcmstb-memc-ddr.yaml for a
full list of supported compatible strings and properties.

Example:

memory_controllers {
	ranges;
	compatible = "simple-bus";

	memc@0 {
		compatible = "brcm,brcmstb-memc", "simple-bus";
		ranges;

		ddr-phy@f1106000 {
			compatible = "brcm,brcmstb-ddr-phy-v240.1";
			reg = <0xf1106000 0x21c>;
		};

		shimphy@f1108000 {
			compatible = "brcm,brcmstb-ddr-shimphy-v1.0";
			reg = <0xf1108000 0xe4>;
		};

		memc-ddr@f1102000 {
			reg = <0xf1102000 0x800>;
			compatible = "brcm,brcmstb-memc-ddr";
		};
	};

	memc@1 {
		compatible = "brcm,brcmstb-memc", "simple-bus";
		ranges;

		ddr-phy@f1186000 {
			compatible = "brcm,brcmstb-ddr-phy-v240.1";
			reg = <0xf1186000 0x21c>;
		};

		shimphy@f1188000 {
			compatible = "brcm,brcmstb-ddr-shimphy-v1.0";
			reg = <0xf1188000 0xe4>;
		};

		memc-ddr@f1182000 {
			reg = <0xf1182000 0x800>;
			compatible = "brcm,brcmstb-memc-ddr";
		};
	};

	memc@2 {
		compatible = "brcm,brcmstb-memc", "simple-bus";
		ranges;

		ddr-phy@f1206000 {
			compatible = "brcm,brcmstb-ddr-phy-v240.1";
			reg = <0xf1206000 0x21c>;
		};

		shimphy@f1208000 {
			compatible = "brcm,brcmstb-ddr-shimphy-v1.0";
			reg = <0xf1208000 0xe4>;
		};

		memc-ddr@f1202000 {
			reg = <0xf1202000 0x800>;
			compatible = "brcm,brcmstb-memc-ddr";
		};
	};
};