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