| 1 | ============================
|
| 2 | The Common Mailbox Framework
|
| 3 | ============================
|
| 4 |
|
| 5 | :Author: Jassi Brar <[email protected]>
|
| 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 flush() and 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_obj(*dc_sync);
|
| 91 | dc_async = kzalloc_obj(*dc_async);
|
| 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 | }
|