iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

mailbox.txt: standardize document format

Browse Source 
Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- Add markups for section titles;
- Use :Author: for authorship;
- Mark literal block as such and ident it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab 2017-05-14 21:06:34 -03:00 committed by Jonathan Corbet
parent 7b001bff46
commit ad98211ba4
1 changed files with 87 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

165
Documentation/mailbox.txt
View File

@ -1,7 +1,10 @@
The Common Mailbox Framework ============================
Jassi Brar <jaswinder.singh@linaro.org> The Common Mailbox Framework
============================
This document aims to help developers write client and controller :Author: 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 drivers for the API. But before we start, let us note that the
client (especially) and controller drivers are likely going to be client (especially) and controller drivers are likely going to be
very platform specific because the remote firmware is likely to be very platform specific because the remote firmware is likely to be
@ -13,14 +16,17 @@ 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 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 same api there. However none of that helps us locally because we only
ever deal at client's protocol level. ever deal at client's protocol level.
Some of the choices made during implementation are the result of this
Some of the choices made during implementation are the result of this
peculiarity of this "common" framework. peculiarity of this "common" framework.
Part 1 - Controller Driver (See include/linux/mailbox_controller.h) Controller Driver (See include/linux/mailbox_controller.h)
==========================================================
Allocate mbox_controller and the array of mbox_chan.
Allocate mbox_controller and the array of mbox_chan.
Populate mbox_chan_ops, except peek_data() all are mandatory. Populate mbox_chan_ops, except peek_data() all are mandatory.
The controller driver might know a message has been consumed The controller driver might know a message has been consumed
by the remote by getting an IRQ or polling some hardware flag by the remote by getting an IRQ or polling some hardware flag
@ -30,91 +36,94 @@ the controller driver should set via 'txdone_irq' or 'txdone_poll'
or neither. or neither.
Part 2 - Client Driver (See include/linux/mailbox_client.h) Client Driver (See include/linux/mailbox_client.h)
==================================================
The client might want to operate in blocking mode (synchronously
The client might want to operate in blocking mode (synchronously
send a message through before returning) or non-blocking/async mode (submit send a message through before returning) or non-blocking/async mode (submit
a message and a callback function to the API and return immediately). a message and a callback function to the API and return immediately).
::
struct demo_client { struct demo_client {
struct mbox_client cl; struct mbox_client cl;
struct mbox_chan *mbox; struct mbox_chan *mbox;
struct completion c; struct completion c;
bool async; bool async;
/* ... */ /* ... */
}; };
/* /*
* This is the handler for data received from remote. The behaviour is purely * This is the handler for data received from remote. The behaviour is purely
* dependent upon the protocol. This is just an example. * dependent upon the protocol. This is just an example.
*/ */
static void message_from_remote(struct mbox_client *cl, void *mssg) static void message_from_remote(struct mbox_client *cl, void *mssg)
{ {
struct demo_client *dc = container_of(cl, struct demo_client, cl); struct demo_client *dc = container_of(cl, struct demo_client, cl);
if (dc->async) { if (dc->async) {
if (is_an_ack(mssg)) { if (is_an_ack(mssg)) {
/* An ACK to our last sample sent */ /* An ACK to our last sample sent */
return; /* Or do something else here */ return; /* Or do something else here */
} else { /* A new message from remote */ } else { /* A new message from remote */
queue_req(mssg); queue_req(mssg);
}
} else {
/* Remote f/w sends only ACK packets on this channel */
return;
} }
} else {
/* Remote f/w sends only ACK packets on this channel */
return;
} }
}
static void sample_sent(struct mbox_client *cl, void *mssg, int r) static void sample_sent(struct mbox_client *cl, void *mssg, int r)
{ {
struct demo_client *dc = container_of(cl, struct demo_client, cl); struct demo_client *dc = container_of(cl, struct demo_client, cl);
complete(&dc->c); complete(&dc->c);
} }
static void client_demo(struct platform_device *pdev) static void client_demo(struct platform_device *pdev)
{ {
struct demo_client *dc_sync, *dc_async; struct demo_client *dc_sync, *dc_async;
/* The controller already knows async_pkt and sync_pkt */ /* The controller already knows async_pkt and sync_pkt */
struct async_pkt ap; struct async_pkt ap;
struct sync_pkt sp; struct sync_pkt sp;
dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL); dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL);
dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL); dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL);
/* Populate non-blocking mode client */ /* Populate non-blocking mode client */
dc_async->cl.dev = &pdev->dev; dc_async->cl.dev = &pdev->dev;
dc_async->cl.rx_callback = message_from_remote; dc_async->cl.rx_callback = message_from_remote;
dc_async->cl.tx_done = sample_sent; dc_async->cl.tx_done = sample_sent;
dc_async->cl.tx_block = false; dc_async->cl.tx_block = false;
dc_async->cl.tx_tout = 0; /* doesn't matter here */ dc_async->cl.tx_tout = 0; /* doesn't matter here */
dc_async->cl.knows_txdone = false; /* depending upon protocol */ dc_async->cl.knows_txdone = false; /* depending upon protocol */
dc_async->async = true; dc_async->async = true;
init_completion(&dc_async->c); init_completion(&dc_async->c);
/* Populate blocking mode client */ /* Populate blocking mode client */
dc_sync->cl.dev = &pdev->dev; dc_sync->cl.dev = &pdev->dev;
dc_sync->cl.rx_callback = message_from_remote; dc_sync->cl.rx_callback = message_from_remote;
dc_sync->cl.tx_done = NULL; /* operate in blocking mode */ dc_sync->cl.tx_done = NULL; /* operate in blocking mode */
dc_sync->cl.tx_block = true; dc_sync->cl.tx_block = true;
dc_sync->cl.tx_tout = 500; /* by half a second */ dc_sync->cl.tx_tout = 500; /* by half a second */
dc_sync->cl.knows_txdone = false; /* depending upon protocol */ dc_sync->cl.knows_txdone = false; /* depending upon protocol */
dc_sync->async = false; dc_sync->async = false;
/* ASync mailbox is listed second in 'mboxes' property */ /* ASync mailbox is listed second in 'mboxes' property */
dc_async->mbox = mbox_request_channel(&dc_async->cl, 1); dc_async->mbox = mbox_request_channel(&dc_async->cl, 1);
/* Populate data packet */ /* Populate data packet */
/* ap.xxx = 123; etc */ /* ap.xxx = 123; etc */
/* Send async message to remote */ /* Send async message to remote */
mbox_send_message(dc_async->mbox, &ap); mbox_send_message(dc_async->mbox, &ap);
/* Sync mailbox is listed first in 'mboxes' property */ /* Sync mailbox is listed first in 'mboxes' property */
dc_sync->mbox = mbox_request_channel(&dc_sync->cl, 0); dc_sync->mbox = mbox_request_channel(&dc_sync->cl, 0);
/* Populate data packet */ /* Populate data packet */
/* sp.abc = 123; etc */ /* sp.abc = 123; etc */
/* Send message to remote in blocking mode */ /* Send message to remote in blocking mode */
mbox_send_message(dc_sync->mbox, &sp); mbox_send_message(dc_sync->mbox, &sp);
/* At this point 'sp' has been sent */ /* At this point 'sp' has been sent */
/* Now wait for async chan to be done */ /* Now wait for async chan to be done */
wait_for_completion(&dc_async->c); wait_for_completion(&dc_async->c);
} }