The Common Mailbox Framework

Common Mailbox Framework 개요

문서 제목은 `The Common Mailbox Framework`이며 저자는 Jassi Brar입니다. 이 문서는 API용 client driver와 controller driver 작성자를 돕습니다.

Remote firmware가 proprietary이고 non-standard protocol을 구현하는 경우가 많으므로 client driver와 controller driver는 대체로 platform-specific입니다. 두 platform이 같은 PL320 controller를 사용해도 client driver를 공유할 수 없고 PL320 driver 자체에도 platform quirk 처리가 필요할 수 있습니다.

이 API의 주목적은 platform마다 비슷한 code copy를 반복하는 일을 줄이는 것입니다. Remote firmware가 Linux와 같은 API를 사용할 수도 있지만 local side는 client protocol level만 다루므로 그 사실만으로 local implementation을 공유할 수는 없습니다. Framework 구현 선택 일부는 이런 특성에서 비롯됩니다.

Controller driver

Controller driver는 `include/linux/mailbox_controller.h`를 따릅니다. `mbox_controller`와 `mbox_chan` array를 allocate하고 `mbox_chan_ops`를 채웁니다. `peek_data()`만 optional이고 나머지 operation은 필수입니다.

Remote가 message를 consume했다는 사실을 controller가 IRQ로 알거나 hardware flag polling으로 알 수 있으며, protocol을 아는 client만 완료를 알고 controller는 전혀 모를 수도 있습니다. 선호 순서는 IRQ, polling, none입니다. Driver는 각각 `txdone_irq`, `txdone_poll`, 둘 다 설정하지 않음으로 표시합니다.

Client driver mode

Client driver는 `include/linux/mailbox_client.h`를 사용합니다. Blocking mode에서는 message 전송을 완료한 뒤 caller로 돌아옵니다. Non-blocking 또는 asynchronous mode에서는 message와 callback을 API에 제출하고 즉시 반환합니다.

Client structure와 callback 예제

예제 `struct demo_client`는 `struct mbox_client`, channel pointer, completion, async flag를 보관합니다. 실제 packet format과 ACK 구분은 framework가 아니라 remote protocol에 달려 있습니다.

`message_from_remote()`는 async client에서 ACK면 마지막 sample의 acknowledgment로 처리하고, 새 remote message면 `queue_req()`로 넘깁니다. Synchronous channel 예시는 remote firmware가 ACK packet만 보낸다고 가정합니다.

`sample_sent()`는 async transmission이 끝나면 client의 completion을 signal합니다.

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);
}

Sync·async channel 사용 예제

`client_demo()`는 synchronous client와 asynchronous client를 각각 allocate합니다. Controller는 `async_pkt`과 `sync_pkt`의 format을 이미 알고 있다고 가정합니다.

Async client는 `rx_callback=message_from_remote`, `tx_done=sample_sent`, `tx_block=false`, `tx_tout=0`, protocol에 따라 `knows_txdone=false`, `async=true`로 설정하고 completion을 initialize합니다.

Blocking client는 같은 RX callback을 쓰지만 `tx_done=NULL`, `tx_block=true`, timeout 500ms, `knows_txdone=false`, `async=false`로 설정합니다.

Device tree 등의 `mboxes` property에서 async mailbox가 두 번째이므로 channel index 1을, sync mailbox가 첫 번째이므로 index 0을 `mbox_request_channel()`로 요청합니다. 각 packet을 채운 뒤 `mbox_send_message()`로 전송합니다.

Blocking send가 반환한 시점에는 `sp`가 전송된 상태입니다. Async channel은 별도로 `wait_for_completion()`을 호출해 `sample_sent()`의 signal을 기다립니다.

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);
}