[PATCH v6 1/8] dt: describe base reset signal binding

[robherring2@gmail.com (Rob Herring)]

On 03/28/2013 11:35 AM, Philipp Zabel wrote:
> From: Stephen Warren <swarren@nvidia.com>
> 
> This binding is intended to represent the hardware reset signals present
> internally in most IC (SoC, FPGA, ...) designs.
> It consists of a binding for a reset controller device (provider), and a
> pair of properties, "resets" and "reset-names", to link a device node
> (consumer) to its reset controller via phandle, similarly to the clock
> and interrupt bindings.
> 
> The reset controller has all information necessary to reset the consumer
> device. That could be provided via device tree, or it could be implemented
> in hardware.
> The aim is to enable device drivers to request a framework API to issue a
> reset simply by providing their struct device pointer as the most common
> case.
> 
> Signed-off-by: Stephen Warren <swarren@nvidia.com>
> Signed-off-by: Philipp Zabel <p.zabel@pengutronix.de>
> Reviewed-by: Shawn Guo <shawn.guo@linaro.org>
> Reviewed-by: Marek Vasut <marex@denx.de>

Looks good.

Acked-by: Rob Herring <rob.herring@calxeda.com>

Rob

> ---
>  Documentation/devicetree/bindings/reset/reset.txt | 75 +++++++++++++++++++++++
>  1 file changed, 75 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/reset/reset.txt
> 
> diff --git a/Documentation/devicetree/bindings/reset/reset.txt b/Documentation/devicetree/bindings/reset/reset.txt
> new file mode 100644
> index 0000000..31db6ff
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/reset/reset.txt
> @@ -0,0 +1,75 @@
> += Reset Signal Device Tree Bindings =
> +
> +This binding is intended to represent the hardware reset signals present
> +internally in most IC (SoC, FPGA, ...) designs. Reset signals for whole
> +standalone chips are most likely better represented as GPIOs, although there
> +are likely to be exceptions to this rule.
> +
> +Hardware blocks typically receive a reset signal. This signal is generated by
> +a reset provider (e.g. power management or clock module) and received by a
> +reset consumer (the module being reset, or a module managing when a sub-
> +ordinate module is reset). This binding exists to represent the provider and
> +consumer, and provide a way to couple the two together.
> +
> +A reset signal is represented by the phandle of the provider, plus a reset
> +specifier - a list of DT cells that represents the reset signal within the
> +provider. The length (number of cells) and semantics of the reset specifier
> +are dictated by the binding of the reset provider, although common schemes
> +are described below.
> +
> +A word on where to place reset signal consumers in device tree: It is possible
> +in hardware for a reset signal to affect multiple logically separate HW blocks
> +at once. In this case, it would be unwise to represent this reset signal in
> +the DT node of each affected HW block, since if activated, an unrelated block
> +may be reset. Instead, reset signals should be represented in the DT node
> +where it makes most sense to control it; this may be a bus node if all
> +children of the bus are affected by the reset signal, or an individual HW
> +block node for dedicated reset signals. The intent of this binding is to give
> +appropriate software access to the reset signals in order to manage the HW,
> +rather than to slavishly enumerate the reset signal that affects each HW
> +block.
> +
> += Reset providers =
> +
> +Required properties:
> +#reset-cells:	Number of cells in a reset specifier; Typically 0 for nodes
> +		with a single reset output and 1 for nodes with multiple
> +		reset outputs.
> +
> +For example:
> +
> +	rst: reset-controller {
> +		#reset-cells = <1>;
> +	};
> +
> += Reset consumers =
> +
> +Required properties:
> +resets:		List of phandle and reset specifier pairs, one pair
> +		for each reset signal that affects the device, or that the
> +		device manages. Note: if the reset provider specifies '0' for
> +		#reset-cells, then only the phandle portion of the pair will
> +		appear.
> +
> +Optional properties:
> +reset-names:	List of reset signal name strings sorted in the same order as
> +		the resets property. Consumers drivers will use reset-names to
> +		match reset signal names with reset specifiers.
> +
> +For example:
> +
> +	device {
> +		resets = <&rst 20>;
> +		reset-names = "reset";
> +	};
> +
> +This represents a device with a single reset signal named "reset".
> +
> +	bus {
> +		resets = <&rst 10> <&rst 11> <&rst 12> <&rst 11>;
> +		reset-names = "i2s1", "i2s2", "dma", "mixer";
> +	};
> +
> +This represents a bus that controls the reset signal of each of four sub-
> +ordinate devices. Consider for example a bus that fails to operate unless no
> +child device has reset asserted.
>