From: Jassi Brar <jaswinder.singh@linaro.org>
To: devicetree@vger.kernel.org, linux-kernel@vger.kernel.org
Cc: ks.giri@samsung.com, arnd@arndb.de, ijc@hellion.org.uk,
mark.rutland@arm.com, robh@kernel.org, pawel.moll@arm.com,
courtney.cavin@sonymobile.com, mporter@linaro.org,
slapdau@yahoo.com.au, lftan.linux@gmail.com,
loic.pallardy@st.com, s-anna@ti.com, ashwin.chaugule@linaro.org,
bjorn@kryo.se, patches@linaro.org, t.takinishi@jp.fujitsu.com,
broonie@linaro.org, khilman@linaro.org, mollie.wu@linaro.org,
andy.green@linaro.org, lee.jones@linaro.org,
Jassi Brar <jaswinder.singh@linaro.org>
Subject: [PATCHv9 3/4] doc: add documentation for mailbox framework
Date: Wed, 23 Jul 2014 00:27:07 +0530 [thread overview]
Message-ID: <1406055427-29325-1-git-send-email-jaswinder.singh@linaro.org> (raw)
In-Reply-To: <1406055250-29159-1-git-send-email-jaswinder.singh@linaro.org>
Some explanations with examples of how to write to implement users
and providers of the mailbox framework.
Signed-off-by: Jassi Brar <jaswinder.singh@linaro.org>
---
Documentation/mailbox.txt | 122 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 122 insertions(+)
create mode 100644 Documentation/mailbox.txt
diff --git a/Documentation/mailbox.txt b/Documentation/mailbox.txt
new file mode 100644
index 0000000..60f43ff
--- /dev/null
+++ b/Documentation/mailbox.txt
@@ -0,0 +1,122 @@
+ The Common Mailbox Framework
+ Jassi Brar <jaswinder.singh@linaro.org>
+
+ This document aims to help developers write client and controller
+drivers for the API. But before we start, let us note that the
+client (especially) and controller drivers are likely going to be
+very platform specific because the remote firmware is likely to be
+proprietary and implement non-standard protocol. So even if two
+platforms employ, say, PL320 controller, the client drivers can't
+be shared across them. Even the PL320 driver might need to accommodate
+some platform specific quirks. So the API is meant mainly to avoid
+similar copies of code written for each platform. Having said that,
+nothing prevents the remote f/w to also be Linux based and use the
+same api there. However none of that helps us locally because we only
+ever deal at client's protocol level.
+ Some of the choices made during implementation are the result of this
+peculiarity of this "common" framework.
+
+
+
+ Part 1 - Controller Driver (See include/linux/mailbox_controller.h)
+
+ Allocate mbox_controller and the array of mbox_chan.
+Populate mbox_chan_ops, except peek_data() all are mandatory.
+The controller driver might know a message has been consumed
+by the remote by getting an IRQ or polling some hardware flag
+or it can never know (the client knows by way of the protocol).
+The method in order of preference is IRQ -> Poll -> None, which
+the controller driver should set via 'txdone_irq' or 'txdone_poll'
+or neither.
+
+
+ Part 2 - Client Driver (See include/linux/mailbox_client.h)
+
+ The client might want to operate in blocking mode (synchronously
+send a message through before returning) or non-blocking/async mode (submit
+a message and a callback function to the API and return immediately).
+
+
+struct demo_client {
+ struct mbox_client cl;
+ struct mbox_chan *mbox;
+ struct completion c;
+ bool async;
+ /* ... */
+};
+
+/*
+ * This is the handler for data received from remote. The behaviour is purely
+ * dependent upon the protocol. This is just an example.
+ */
+static void message_from_remote(struct mbox_client *cl, void *mssg)
+{
+ struct demo_client *dc = container_of(mbox_client,
+ struct demo_client, cl);
+ if (dc->aysnc) {
+ if (is_an_ack(mssg)) {
+ /* An ACK to our last sample sent */
+ return; /* Or do something else here */
+ } else { /* A new message from remote */
+ queue_req(mssg);
+ }
+ } else {
+ /* Remote f/w sends only ACK packets on this channel */
+ return;
+ }
+}
+
+static void sample_sent(struct mbox_client *cl, void *mssg, int r)
+{
+ struct demo_client *dc = container_of(mbox_client,
+ struct demo_client, cl);
+ complete(&dc->c);
+}
+
+static void client_demo(struct platform_device *pdev)
+{
+ struct demo_client *dc_sync, *dc_async;
+ /* The controller already knows async_pkt and sync_pkt */
+ struct async_pkt ap;
+ struct sync_pkt sp;
+
+ dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL);
+ dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL);
+
+ /* Populate non-blocking mode client */
+ dc_async->cl.dev = &pdev->dev;
+ dc_async->cl.rx_callback = message_from_remote;
+ dc_async->cl.tx_done = sample_sent;
+ dc_async->cl.tx_block = false;
+ dc_async->cl.tx_tout = 0; /* doesn't matter here */
+ dc_async->cl.knows_txdone = false; /* depending upon protocol */
+ dc_async->async = true;
+ init_completion(&dc_async->c);
+
+ /* Populate blocking mode client */
+ dc_sync->cl.dev = &pdev->dev;
+ dc_sync->cl.rx_callback = message_from_remote;
+ dc_sync->cl.tx_done = NULL; /* operate in blocking mode */
+ dc_sync->cl.tx_block = true;
+ dc_sync->cl.tx_tout = 500; /* by half a second */
+ dc_sync->cl.knows_txdone = false; /* depending upon protocol */
+ dc_sync->async = false;
+
+ /* ASync mailbox is listed second in 'mboxes' property */
+ dc_async->mbox = mbox_request_channel(&dc_async->cl, 1);
+ /* Populate data packet */
+ /* ap.xxx = 123; etc */
+ /* Send async message to remote */
+ mbox_send_message(dc_async->mbox, &ap);
+
+ /* Sync mailbox is listed first in 'mboxes' property */
+ dc_sync->mbox = mbox_request_channel(&dc_sync->cl, 0);
+ /* Populate data packet */
+ /* sp.abc = 123; etc */
+ /* Send message to remote in blocking mode */
+ mbox_send_message(dc_sync->mbox, &sp);
+ /* At this point 'sp' has been sent */
+
+ /* Now wait for async chan to be done */
+ wait_for_completion(&dc_async->c);
+}
--
1.8.1.2
next prev parent reply other threads:[~2014-07-22 18:57 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-07-22 18:54 [PATCHv9 0/4] Common Mailbox Framework Jassi Brar
2014-07-22 18:55 ` [PATCHv9 1/4] mailbox: rename pl320-ipc specific mailbox.h Jassi Brar
2014-07-22 18:56 ` [PATCHv9 2/4] mailbox: Introduce framework for mailbox Jassi Brar
2014-07-23 8:54 ` Lee Jones
2014-07-23 15:00 ` Jassi Brar
2014-07-23 15:26 ` Lee Jones
2014-07-31 16:56 ` Jassi Brar
2014-08-01 8:17 ` Lee Jones
2014-07-31 17:32 ` Sudeep Holla
2014-07-22 18:57 ` Jassi Brar [this message]
2014-07-22 18:57 ` [PATCHv9 4/4] dt: mailbox: add generic bindings Jassi Brar
2014-07-28 13:50 ` Grant Likely
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1406055427-29325-1-git-send-email-jaswinder.singh@linaro.org \
--to=jaswinder.singh@linaro.org \
--cc=andy.green@linaro.org \
--cc=arnd@arndb.de \
--cc=ashwin.chaugule@linaro.org \
--cc=bjorn@kryo.se \
--cc=broonie@linaro.org \
--cc=courtney.cavin@sonymobile.com \
--cc=devicetree@vger.kernel.org \
--cc=ijc@hellion.org.uk \
--cc=khilman@linaro.org \
--cc=ks.giri@samsung.com \
--cc=lee.jones@linaro.org \
--cc=lftan.linux@gmail.com \
--cc=linux-kernel@vger.kernel.org \
--cc=loic.pallardy@st.com \
--cc=mark.rutland@arm.com \
--cc=mollie.wu@linaro.org \
--cc=mporter@linaro.org \
--cc=patches@linaro.org \
--cc=pawel.moll@arm.com \
--cc=robh@kernel.org \
--cc=s-anna@ti.com \
--cc=slapdau@yahoo.com.au \
--cc=t.takinishi@jp.fujitsu.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).