diff mbox

[PATCHv10,4/4] dt: mailbox: add generic bindings

Message ID 1406896365-4971-1-git-send-email-jaswinder.singh@linaro.org
State New
Headers show

Commit Message

Jassi Brar Aug. 1, 2014, 12:32 p.m. UTC
Define generic bindings for the framework clients to
request mailbox channels.

Signed-off-by: Jassi Brar <jaswinder.singh@linaro.org>
---
 .../devicetree/bindings/mailbox/mailbox.txt        | 36 ++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mailbox/mailbox.txt

Comments

Mark Brown Aug. 1, 2014, 6:43 p.m. UTC | #1
On Fri, Aug 01, 2014 at 06:02:45PM +0530, Jassi Brar wrote:

> +Optional property:
> +- mbox-names: List of identifier strings for each mailbox channel
> +		required by the client. The use of this property
> +		is discouraged in favor of using index in list of
> +		'mboxes' while requesting a mailbox.

Can I suggest that if we do want to avoid strings for some reason (it's
not obvious to me why) then we include a recommendation to provide
defines in a header file in order to improve legibility.  That's pretty
minor, though.

Reviewed-by: Mark Brown <broonie@linaro.org>
Jassi Brar Aug. 2, 2014, 7:47 a.m. UTC | #2
On 2 August 2014 00:13, Mark Brown <broonie@kernel.org> wrote:
> On Fri, Aug 01, 2014 at 06:02:45PM +0530, Jassi Brar wrote:
>
>> +Optional property:
>> +- mbox-names: List of identifier strings for each mailbox channel
>> +             required by the client. The use of this property
>> +             is discouraged in favor of using index in list of
>> +             'mboxes' while requesting a mailbox.
>
> Can I suggest that if we do want to avoid strings for some reason (it's
> not obvious to me why)
>
The string and index are both to be taken from DT node of client.

    pwr_cntrl: power {
               ...
               mbox-names = "pwr-ctrl", "rpc";
               mboxes = <&mailbox 0
                       &mailbox 1>;
    };

The xlate() will map string onto index. So rather than the client
driver specify, say, "rpc" while requesting mailbox channel, it can
directly specify index 1.

> then we include a recommendation to provide
> defines in a header file in order to improve legibility.  That's pretty
> minor, though.
>
Sorry I don't understand.

> Reviewed-by: Mark Brown <broonie@linaro.org>
>
Thanks a lot!
-Jassi
Mark Brown Aug. 4, 2014, 2:40 p.m. UTC | #3
On Sat, Aug 02, 2014 at 01:17:18PM +0530, Jassi Brar wrote:
> On 2 August 2014 00:13, Mark Brown <broonie@kernel.org> wrote:
> > On Fri, Aug 01, 2014 at 06:02:45PM +0530, Jassi Brar wrote:

> > Can I suggest that if we do want to avoid strings for some reason (it's
> > not obvious to me why)

> The string and index are both to be taken from DT node of client.

>     pwr_cntrl: power {
>                ...
>                mbox-names = "pwr-ctrl", "rpc";
>                mboxes = <&mailbox 0
>                        &mailbox 1>;
>     };

> The xlate() will map string onto index. So rather than the client
> driver specify, say, "rpc" while requesting mailbox channel, it can
> directly specify index 1.

The whole point with specifying an array of names as well as the array
of mboxes is that you don't then need to do that in the driver code, it
provides a layer of indirection between the array indexes and the
identification of the resources.  This improves the legibility of the
driver (since you're asking for things by name rather than random
number) and DT (since there's a bit less of counting through potentially
long lists and making sure you edit the right entry.  It also makes life
easier if a future version of the binding allows one of the existing
mailboxes to be omitted since you don't need to have blank entries.

> > then we include a recommendation to provide
> > defines in a header file in order to improve legibility.  That's pretty
> > minor, though.

> Sorry I don't understand.

If there's defines in the DT header files (which would hopefully go
along with the bindings in some future where we actually split the
bindings out) then the driver can use those names rather than having
numbers in it.

While I think about it it would be good to be able to encourage people
to have things like <&mailbox 0> being able to be written as <&mailbox
NAME>.
diff mbox

Patch

diff --git a/Documentation/devicetree/bindings/mailbox/mailbox.txt b/Documentation/devicetree/bindings/mailbox/mailbox.txt
new file mode 100644
index 0000000..bb79678
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/mailbox.txt
@@ -0,0 +1,36 @@ 
+* Generic Mailbox Controller and client driver bindings
+
+Generic binding to provide a way for Mailbox controller drivers to
+assign appropriate mailbox channel to client drivers.
+
+* Mailbox Controller
+
+Required property:
+- #mbox-cells: Must be at least 1. Number of cells in a mailbox
+		specifier.
+
+Example:
+	mailbox: mailbox {
+		...
+		#mbox-cells = <1>;
+	};
+
+
+* Mailbox Client
+
+Required property:
+- mboxes: List of phandle and mailbox channel specifiers.
+
+Optional property:
+- mbox-names: List of identifier strings for each mailbox channel
+		required by the client. The use of this property
+		is discouraged in favor of using index in list of
+		'mboxes' while requesting a mailbox.
+
+Example:
+	pwr_cntrl: power {
+		...
+		mbox-names = "pwr-ctrl", "rpc";
+		mboxes = <&mailbox 0
+			&mailbox 1>;
+	};