About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / mailbox.txt




Custom Search

Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1	============================
2	The Common Mailbox Framework
3	============================
4	
5	:Author: Jassi Brar <jaswinder.singh@linaro.org>
6	
7	This document aims to help developers write client and controller
8	drivers for the API. But before we start, let us note that the
9	client (especially) and controller drivers are likely going to be
10	very platform specific because the remote firmware is likely to be
11	proprietary and implement non-standard protocol. So even if two
12	platforms employ, say, PL320 controller, the client drivers can't
13	be shared across them. Even the PL320 driver might need to accommodate
14	some platform specific quirks. So the API is meant mainly to avoid
15	similar copies of code written for each platform. Having said that,
16	nothing prevents the remote f/w to also be Linux based and use the
17	same api there. However none of that helps us locally because we only
18	ever deal at client's protocol level.
19	
20	Some of the choices made during implementation are the result of this
21	peculiarity of this "common" framework.
22	
23	
24	
25	Controller Driver (See include/linux/mailbox_controller.h)
26	==========================================================
27	
28	
29	Allocate mbox_controller and the array of mbox_chan.
30	Populate mbox_chan_ops, except peek_data() all are mandatory.
31	The controller driver might know a message has been consumed
32	by the remote by getting an IRQ or polling some hardware flag
33	or it can never know (the client knows by way of the protocol).
34	The method in order of preference is IRQ -> Poll -> None, which
35	the controller driver should set via 'txdone_irq' or 'txdone_poll'
36	or neither.
37	
38	
39	Client Driver (See include/linux/mailbox_client.h)
40	==================================================
41	
42	
43	The client might want to operate in blocking mode (synchronously
44	send a message through before returning) or non-blocking/async mode (submit
45	a message and a callback function to the API and return immediately).
46	
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;
74			}
75		}
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		}
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.