通用郵箱框架

作者:

Jassi Brar <jaswinder.singh@linaro.org>

本文件旨在幫助開發人員編寫 API 的客戶端和控制器驅動程式。但在開始之前，讓我們注意到，客戶端（特別是）和控制器驅動程式很可能非常依賴於平臺，因為遠端韌體很可能是專有的並實現非標準協議。因此，即使兩個平臺都使用 PL320 控制器，客戶端驅動程式也無法在它們之間共享。即使是 PL320 驅動程式也可能需要適應一些特定於平臺的怪癖。因此，API 主要用於避免為每個平臺編寫類似的程式碼副本。話雖如此，沒有什麼可以阻止遠端韌體也是基於 Linux 的並使用相同的 api。然而，這些都對我們沒有幫助，因為我們只處理客戶端的協議級別。

在實施過程中所做的一些選擇是這種“通用”框架的特殊性的結果。

控制器驅動程式（參見 include/linux/mailbox_controller.h）

分配 mbox_controller 和 mbox_chan 陣列。填充 mbox_chan_ops，除了 peek_data() 之外，所有都是必需的。控制器驅動程式可能知道遠端是否已使用訊息，透過獲取 IRQ 或輪詢某些硬體標誌，或者它可能永遠不知道（客戶端透過協議知道）。首選方法是 IRQ -> 輪詢 -> 無，控制器驅動程式應透過“txdone_irq”或“txdone_poll”或兩者都不設定。

客戶端驅動程式（參見 include/linux/mailbox_client.h）

客戶端可能希望在阻塞模式下執行（同步傳送一條訊息，然後返回）或非阻塞/非同步模式（提交一條訊息和一個回撥函式到 API 並立即返回）。

struct demo_client {
        struct mbox_client cl;
        struct mbox_chan *mbox;
        struct completion c;
        bool async;
        /* ... */
};

/*
* This is the handler for data received from remote. The behaviour is purely
* dependent upon the protocol. This is just an example.
*/
static void message_from_remote(struct mbox_client *cl, void *mssg)
{
        struct demo_client *dc = container_of(cl, struct demo_client, cl);
        if (dc->async) {
                if (is_an_ack(mssg)) {
                        /* An ACK to our last sample sent */
                        return; /* Or do something else here */
                } else { /* A new message from remote */
                        queue_req(mssg);
                }
        } else {
                /* Remote f/w sends only ACK packets on this channel */
                return;
        }
}

static void sample_sent(struct mbox_client *cl, void *mssg, int r)
{
        struct demo_client *dc = container_of(cl, struct demo_client, cl);
        complete(&dc->c);
}

static void client_demo(struct platform_device *pdev)
{
        struct demo_client *dc_sync, *dc_async;
        /* The controller already knows async_pkt and sync_pkt */
        struct async_pkt ap;
        struct sync_pkt sp;

        dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL);
        dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL);

        /* Populate non-blocking mode client */
        dc_async->cl.dev = &pdev->dev;
        dc_async->cl.rx_callback = message_from_remote;
        dc_async->cl.tx_done = sample_sent;
        dc_async->cl.tx_block = false;
        dc_async->cl.tx_tout = 0; /* doesn't matter here */
        dc_async->cl.knows_txdone = false; /* depending upon protocol */
        dc_async->async = true;
        init_completion(&dc_async->c);

        /* Populate blocking mode client */
        dc_sync->cl.dev = &pdev->dev;
        dc_sync->cl.rx_callback = message_from_remote;
        dc_sync->cl.tx_done = NULL; /* operate in blocking mode */
        dc_sync->cl.tx_block = true;
        dc_sync->cl.tx_tout = 500; /* by half a second */
        dc_sync->cl.knows_txdone = false; /* depending upon protocol */
        dc_sync->async = false;

        /* ASync mailbox is listed second in 'mboxes' property */
        dc_async->mbox = mbox_request_channel(&dc_async->cl, 1);
        /* Populate data packet */
        /* ap.xxx = 123; etc */
        /* Send async message to remote */
        mbox_send_message(dc_async->mbox, &ap);

        /* Sync mailbox is listed first in 'mboxes' property */
        dc_sync->mbox = mbox_request_channel(&dc_sync->cl, 0);
        /* Populate data packet */
        /* sp.abc = 123; etc */
        /* Send message to remote in blocking mode */
        mbox_send_message(dc_sync->mbox, &sp);
        /* At this point 'sp' has been sent */

        /* Now wait for async chan to be done */
        wait_for_completion(&dc_async->c);
}