Broadcom Devicetree Selection

The bootloader (BOLT) has the ability to select a devicetree blob (.dtb file)
from a tarball (can be gzip'd) file that matches the platform. This
selection process requires each blob in the tarball to have a specific node
named "platform-match", child nodes, and properties specified below. BOLT scans
the tarball evaluating the platform-match node in each blob to determine if the
blob should be used.

BOLT also supports devicetree overlays. Overlays are also blobs but they only
contain references to nodes and/or properties in another blob. The idea behind
overlays is that one begins with a base blob containing nodes & properties
common to all platforms, such as the core parts of the SoC, and then modifies
the base blob by applying overlays. Each overlay is applied to the composite
of the base and any previously applied overlays. The base and each overlay is
selected from the tarball using the platform-match node. One can think of an
overlay blob as the runtime form of a devicetree source include file (.dtsi).

Overlay blobs and monolithic blobs can be mixed in the same tarball. BOLT will
first scan the tarball looking for a matching base blob or a monolithic
blob, then continue scanning looking for any overlay blobs to apply. There
are not any restrictions on the number of base blobs or monolithic
blobs that can exist in a tarball, but only the first one of either that is
found that matches the platform will be selected. Thus when mixing overlay
and monolithic blobs the platform-match nodes for the overlay and monolithic
blobs should be orthogonal to ensure that the overlay blobs are not applied
to a monolithic blob.


Required properties for platform-match node:
- layer:
	Integer value between 0 and 255.
	The tarball is scanned 256 times (once for each possible layer value)
	starting with 0 and ending with 255 looking for blobs matching the
	current layer. Base and monolithic blobs must have a value of 0.
	Layer 0 scanning will end once a match is found while scanning for
	the layers > 0 will always scan the entire tarball as these layers
	are overlays. Even if a monolithic blob is found, scanning for
	layers > 0 will still occur.
- match:
	String specifying a boolean logic expression. BOLT will evaluate this
	expression to determine its boolean value and if true will select the
	blob. The expression variables and operators must be only one character
	each. The following operators may be used:
		(	left parenthesis
		)	right parenthesis
		&	logical AND
		|	logical OR
		!	logical NOT
	The expression string can be as long as desired and parentheses nesting
	can be as deep as desired.


A child node must exist for each unique variable specified in the match
string. When evaluating the match string expression BOLT will first
evaluate each child node to determine the variable's boolean value.

Required properties for match variable child nodes:
- type:
	String value specifying how the match variable boolean value is to be
	determined. Must be one of the following:
		"rdb"	examine a register
		"rpc"	examine the response to an RPC request
		"env"	examine the value of a BOLT environment variable
		"mem"	examine a location in memory
		"true"	force the variable value to true
		"false"	force the variable value to false
	The remaining properties of a child node are dependent on the value of
	the type property. Child noides with type values of "true" or "false"
	do not require any additional properties.

Required properties for child nodes with type "rdb":
- rdb:
	RDB register offset from the base address of all RDB registers. This is
	limited to a 32-bit offset and should match the value in the "Offset"
	column of the RDB web page. A 32-bit value is read from the register
	at this address and bitwise AND'd with the mask value specified in the
	"mask" property. If the result is equal to the value specified in the
	"val" property then the match variable is true; otherwise it is false.
- mask:
	32-bit mask value to be AND'd with the value read from the RDB register.
- val:
	32-bit value compared to the result of the value read from the RDB
	register with the mask applied.

Required properties for child nodes with type "rpc":
- request:
	Specifies 4 32-bit integer values to be used for the words 0 to 3,
	respectively, of an RPC request. BOLT will perform the RPC request
	and bitwise AND'd the 4 response words with the 4 mask values
	specified in the "mask" property. If the 4 word result is equal to
	the 4 word values specified in the "val" property then the match
	variable is true; otherwise it is false.
- mask:
	4 32-bit word mask values to be AND'd with the 4 word response from the
	RPC call.
- val:
	4 32-bit word values compared to the result of the 4 word response with
	mask applied.

Required properties for child nodes with type "mem":
- mem:
	32-bit memory address. A 32-bit value is read from memory at this
	address and bitwise AND'd with the mask value specified in the
	"mask" property. If the result is equal to the value specified in the
	"val" property then the match variable is true; otherwise it is false.
- mask:
	32-bit mask value to be AND'd with the value read memory.
- val:
	32-bit value compared to the result of the value read from memory
	with the mask applied.

Required properties for child nodes with type "env":
- env-var:
	A string specifying the name of the BOLT environment variable. If
	the environment variable does not exist then the match variable
	value will be false.

Optional properties for child nodes with type "env":
- val:
	A string value compared to the result of the value read from the
	environment variable. If this property is not specified then the match
	variable's boolean value is determined by the presence (true) or
	absence (false) of the environment variable. If it is specified then
	the match variable is true if the environment variable matches the
	string specified in this property; otherwise the match variable is
	false.


Example:
	platform-match {
		layer = <0x81>;
		match = "a & !b";

		a { /* any 3162 chip on bcm93162-v10 board */
			type	= "rpc";
			/* RPC:         hdr    rc/mfgid/bid  famid      prodid   */
			request	= < 0x020f0000 0x00000000 0x00000000 0x00000000 >;
			mask	= < 0xffffff00 0xff0000ff 0xffffffff 0x00000000 >;
			val	= < 0x030f0000 0x00000020 0x00316200 0x00000000 >;
		};

		b { /* CMTS_TYPE environment variable exists? */
			type	= "env";
			env-var = "CMTS_TYPE";
		};
	};
