]> git.proxmox.com Git - mirror_ubuntu-bionic-kernel.git/blame - Documentation/mailbox.txt
Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/jikos/livep...
[mirror_ubuntu-bionic-kernel.git] / Documentation / mailbox.txt
CommitLineData
15320fbc
JB
1 The Common Mailbox Framework
2 Jassi Brar <jaswinder.singh@linaro.org>
3
4 This document aims to help developers write client and controller
5drivers for the API. But before we start, let us note that the
6client (especially) and controller drivers are likely going to be
7very platform specific because the remote firmware is likely to be
8proprietary and implement non-standard protocol. So even if two
9platforms employ, say, PL320 controller, the client drivers can't
10be shared across them. Even the PL320 driver might need to accommodate
11some platform specific quirks. So the API is meant mainly to avoid
12similar copies of code written for each platform. Having said that,
13nothing prevents the remote f/w to also be Linux based and use the
14same api there. However none of that helps us locally because we only
15ever deal at client's protocol level.
16 Some of the choices made during implementation are the result of this
17peculiarity of this "common" framework.
18
19
20
21 Part 1 - Controller Driver (See include/linux/mailbox_controller.h)
22
23 Allocate mbox_controller and the array of mbox_chan.
24Populate mbox_chan_ops, except peek_data() all are mandatory.
25The controller driver might know a message has been consumed
26by the remote by getting an IRQ or polling some hardware flag
27or it can never know (the client knows by way of the protocol).
28The method in order of preference is IRQ -> Poll -> None, which
29the controller driver should set via 'txdone_irq' or 'txdone_poll'
30or neither.
31
32
33 Part 2 - Client Driver (See include/linux/mailbox_client.h)
34
35 The client might want to operate in blocking mode (synchronously
36send a message through before returning) or non-blocking/async mode (submit
37a message and a callback function to the API and return immediately).
38
39
40struct demo_client {
41 struct mbox_client cl;
42 struct mbox_chan *mbox;
43 struct completion c;
44 bool async;
45 /* ... */
46};
47
48/*
49 * This is the handler for data received from remote. The behaviour is purely
50 * dependent upon the protocol. This is just an example.
51 */
52static void message_from_remote(struct mbox_client *cl, void *mssg)
53{
7bbac697 54 struct demo_client *dc = container_of(cl, struct demo_client, cl);
70c03634 55 if (dc->async) {
15320fbc
JB
56 if (is_an_ack(mssg)) {
57 /* An ACK to our last sample sent */
58 return; /* Or do something else here */
59 } else { /* A new message from remote */
60 queue_req(mssg);
61 }
62 } else {
63 /* Remote f/w sends only ACK packets on this channel */
64 return;
65 }
66}
67
68static void sample_sent(struct mbox_client *cl, void *mssg, int r)
69{
7bbac697 70 struct demo_client *dc = container_of(cl, struct demo_client, cl);
15320fbc
JB
71 complete(&dc->c);
72}
73
74static void client_demo(struct platform_device *pdev)
75{
76 struct demo_client *dc_sync, *dc_async;
77 /* The controller already knows async_pkt and sync_pkt */
78 struct async_pkt ap;
79 struct sync_pkt sp;
80
81 dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL);
82 dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL);
83
84 /* Populate non-blocking mode client */
85 dc_async->cl.dev = &pdev->dev;
86 dc_async->cl.rx_callback = message_from_remote;
87 dc_async->cl.tx_done = sample_sent;
88 dc_async->cl.tx_block = false;
89 dc_async->cl.tx_tout = 0; /* doesn't matter here */
90 dc_async->cl.knows_txdone = false; /* depending upon protocol */
91 dc_async->async = true;
92 init_completion(&dc_async->c);
93
94 /* Populate blocking mode client */
95 dc_sync->cl.dev = &pdev->dev;
96 dc_sync->cl.rx_callback = message_from_remote;
97 dc_sync->cl.tx_done = NULL; /* operate in blocking mode */
98 dc_sync->cl.tx_block = true;
99 dc_sync->cl.tx_tout = 500; /* by half a second */
100 dc_sync->cl.knows_txdone = false; /* depending upon protocol */
101 dc_sync->async = false;
102
103 /* ASync mailbox is listed second in 'mboxes' property */
104 dc_async->mbox = mbox_request_channel(&dc_async->cl, 1);
105 /* Populate data packet */
106 /* ap.xxx = 123; etc */
107 /* Send async message to remote */
108 mbox_send_message(dc_async->mbox, &ap);
109
110 /* Sync mailbox is listed first in 'mboxes' property */
111 dc_sync->mbox = mbox_request_channel(&dc_sync->cl, 0);
112 /* Populate data packet */
113 /* sp.abc = 123; etc */
114 /* Send message to remote in blocking mode */
115 mbox_send_message(dc_sync->mbox, &sp);
116 /* At this point 'sp' has been sent */
117
118 /* Now wait for async chan to be done */
119 wait_for_completion(&dc_async->c);
120}