Commit 43d451f1 authored by Linus Torvalds's avatar Linus Torvalds

Merge branch 'mailbox-for-linus' of git://git.linaro.org/landing-teams/working/fujitsu/integration

Pull mailbox framework from Jassi Brar:
 "A framework for Mailbox controllers and clients have been cooking for
  more than a year now.

  Everybody in the CC list had been copied on patchset revisions and
  most of them have made sounds of approval, though just one concrete
  Reviewed-by.  The patchset has also been in linux-next for a couple of
  weeks now and no conflict has been reported.  The framework has the
  backing of at least 5 platforms, though I can't say if/when they
  upstream their drivers (some businesses have 'changed')"

(Further acked-by by Arnd Bergmann and Suman Anna in the pull request
thread)

* 'mailbox-for-linus' of git://git.linaro.org/landing-teams/working/fujitsu/integration:
  dt: mailbox: add generic bindings
  doc: add documentation for mailbox framework
  mailbox: Introduce framework for mailbox
  mailbox: rename pl320-ipc specific mailbox.h
parents 21d2271f 9f3e3cac
* Generic Mailbox Controller and client driver bindings
Generic binding to provide a way for Mailbox controller drivers to
assign appropriate mailbox channel to client drivers.
* Mailbox Controller
Required property:
- #mbox-cells: Must be at least 1. Number of cells in a mailbox
specifier.
Example:
mailbox: mailbox {
...
#mbox-cells = <1>;
};
* Mailbox Client
Required property:
- mboxes: List of phandle and mailbox channel specifiers.
Optional property:
- mbox-names: List of identifier strings for each mailbox channel
required by the client. The use of this property
is discouraged in favor of using index in list of
'mboxes' while requesting a mailbox. Instead the
platforms may define channel indices, in DT headers,
to something legible.
Example:
pwr_cntrl: power {
...
mbox-names = "pwr-ctrl", "rpc";
mboxes = <&mailbox 0
&mailbox 1>;
};
The Common Mailbox Framework
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
client (especially) and controller drivers are likely going to be
very platform specific because the remote firmware is likely to be
proprietary and implement non-standard protocol. So even if two
platforms employ, say, PL320 controller, the client drivers can't
be shared across them. Even the PL320 driver might need to accommodate
some platform specific quirks. So the API is meant mainly to avoid
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
same api there. However none of that helps us locally because we only
ever deal at client's protocol level.
Some of the choices made during implementation are the result of this
peculiarity of this "common" framework.
Part 1 - Controller Driver (See include/linux/mailbox_controller.h)
Allocate mbox_controller and the array of mbox_chan.
Populate mbox_chan_ops, except peek_data() all are mandatory.
The controller driver might know a message has been consumed
by the remote by getting an IRQ or polling some hardware flag
or it can never know (the client knows by way of the protocol).
The method in order of preference is IRQ -> Poll -> None, which
the controller driver should set via 'txdone_irq' or 'txdone_poll'
or neither.
Part 2 - Client Driver (See include/linux/mailbox_client.h)
The client might want to operate in blocking mode (synchronously
send a message through before returning) or non-blocking/async mode (submit
a message and a callback function to the API and return immediately).
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(mbox_client,
struct demo_client, cl);
if (dc->aysnc) {
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(mbox_client,
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);
}
...@@ -5834,6 +5834,14 @@ S: Maintained ...@@ -5834,6 +5834,14 @@ S: Maintained
F: drivers/net/macvlan.c F: drivers/net/macvlan.c
F: include/linux/if_macvlan.h F: include/linux/if_macvlan.h
MAILBOX API
M: Jassi Brar <jassisinghbrar@gmail.com>
L: linux-kernel@vger.kernel.org
S: Maintained
F: drivers/mailbox/
F: include/linux/mailbox_client.h
F: include/linux/mailbox_controller.h
MAN-PAGES: MANUAL PAGES FOR LINUX -- Sections 2, 3, 4, 5, and 7 MAN-PAGES: MANUAL PAGES FOR LINUX -- Sections 2, 3, 4, 5, and 7
M: Michael Kerrisk <mtk.manpages@gmail.com> M: Michael Kerrisk <mtk.manpages@gmail.com>
W: http://www.kernel.org/doc/man-pages W: http://www.kernel.org/doc/man-pages
......
...@@ -20,7 +20,7 @@ ...@@ -20,7 +20,7 @@
#include <linux/input.h> #include <linux/input.h>
#include <linux/io.h> #include <linux/io.h>
#include <linux/irqchip.h> #include <linux/irqchip.h>
#include <linux/mailbox.h> #include <linux/pl320-ipc.h>
#include <linux/of.h> #include <linux/of.h>
#include <linux/of_irq.h> #include <linux/of_irq.h>
#include <linux/of_platform.h> #include <linux/of_platform.h>
......
...@@ -19,7 +19,7 @@ ...@@ -19,7 +19,7 @@
#include <linux/cpu.h> #include <linux/cpu.h>
#include <linux/err.h> #include <linux/err.h>
#include <linux/of.h> #include <linux/of.h>
#include <linux/mailbox.h> #include <linux/pl320-ipc.h>
#include <linux/platform_device.h> #include <linux/platform_device.h>
#define HB_CPUFREQ_CHANGE_NOTE 0x80000001 #define HB_CPUFREQ_CHANGE_NOTE 0x80000001
......
# Generic MAILBOX API
obj-$(CONFIG_MAILBOX) += mailbox.o
obj-$(CONFIG_PL320_MBOX) += pl320-ipc.o obj-$(CONFIG_PL320_MBOX) += pl320-ipc.o
obj-$(CONFIG_OMAP2PLUS_MBOX) += omap-mailbox.o obj-$(CONFIG_OMAP2PLUS_MBOX) += omap-mailbox.o
This diff is collapsed.
...@@ -26,7 +26,7 @@ ...@@ -26,7 +26,7 @@
#include <linux/device.h> #include <linux/device.h>
#include <linux/amba/bus.h> #include <linux/amba/bus.h>
#include <linux/mailbox.h> #include <linux/pl320-ipc.h>
#define IPCMxSOURCE(m) ((m) * 0x40) #define IPCMxSOURCE(m) ((m) * 0x40)
#define IPCMxDSET(m) (((m) * 0x40) + 0x004) #define IPCMxDSET(m) (((m) * 0x40) + 0x004)
......
/*
* Copyright (C) 2013-2014 Linaro Ltd.
* Author: Jassi Brar <jassisinghbrar@gmail.com>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation.
*/
#ifndef __MAILBOX_CLIENT_H
#define __MAILBOX_CLIENT_H
#include <linux/of.h>
#include <linux/device.h>
struct mbox_chan;
/**
* struct mbox_client - User of a mailbox
* @dev: The client device
* @tx_block: If the mbox_send_message should block until data is
* transmitted.
* @tx_tout: Max block period in ms before TX is assumed failure
* @knows_txdone: If the client could run the TX state machine. Usually
* if the client receives some ACK packet for transmission.
* Unused if the controller already has TX_Done/RTR IRQ.
* @rx_callback: Atomic callback to provide client the data received
* @tx_done: Atomic callback to tell client of data transmission
*/
struct mbox_client {
struct device *dev;
bool tx_block;
unsigned long tx_tout;
bool knows_txdone;
void (*rx_callback)(struct mbox_client *cl, void *mssg);
void (*tx_done)(struct mbox_client *cl, void *mssg, int r);
};
struct mbox_chan *mbox_request_channel(struct mbox_client *cl, int index);
int mbox_send_message(struct mbox_chan *chan, void *mssg);
void mbox_client_txdone(struct mbox_chan *chan, int r); /* atomic */
bool mbox_client_peek_data(struct mbox_chan *chan); /* atomic */
void mbox_free_channel(struct mbox_chan *chan); /* may sleep */
#endif /* __MAILBOX_CLIENT_H */
/*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation.
*/
#ifndef __MAILBOX_CONTROLLER_H
#define __MAILBOX_CONTROLLER_H
#include <linux/of.h>
#include <linux/types.h>
#include <linux/timer.h>
#include <linux/device.h>
#include <linux/completion.h>
struct mbox_chan;
/**
* struct mbox_chan_ops - methods to control mailbox channels
* @send_data: The API asks the MBOX controller driver, in atomic
* context try to transmit a message on the bus. Returns 0 if
* data is accepted for transmission, -EBUSY while rejecting
* if the remote hasn't yet read the last data sent. Actual
* transmission of data is reported by the controller via
* mbox_chan_txdone (if it has some TX ACK irq). It must not
* sleep.
* @startup: Called when a client requests the chan. The controller
* could ask clients for additional parameters of communication
* to be provided via client's chan_data. This call may
* block. After this call the Controller must forward any
* data received on the chan by calling mbox_chan_received_data.
* The controller may do stuff that need to sleep.
* @shutdown: Called when a client relinquishes control of a chan.
* This call may block too. The controller must not forward
* any received data anymore.
* The controller may do stuff that need to sleep.
* @last_tx_done: If the controller sets 'txdone_poll', the API calls
* this to poll status of last TX. The controller must
* give priority to IRQ method over polling and never
* set both txdone_poll and txdone_irq. Only in polling
* mode 'send_data' is expected to return -EBUSY.
* The controller may do stuff that need to sleep/block.
* Used only if txdone_poll:=true && txdone_irq:=false
* @peek_data: Atomic check for any received data. Return true if controller
* has some data to push to the client. False otherwise.
*/
struct mbox_chan_ops {
int (*send_data)(struct mbox_chan *chan, void *data);
int (*startup)(struct mbox_chan *chan);
void (*shutdown)(struct mbox_chan *chan);
bool (*last_tx_done)(struct mbox_chan *chan);
bool (*peek_data)(struct mbox_chan *chan);
};
/**
* struct mbox_controller - Controller of a class of communication channels
* @dev: Device backing this controller
* @ops: Operators that work on each communication chan
* @chans: Array of channels
* @num_chans: Number of channels in the 'chans' array.
* @txdone_irq: Indicates if the controller can report to API when
* the last transmitted data was read by the remote.
* Eg, if it has some TX ACK irq.
* @txdone_poll: If the controller can read but not report the TX
* done. Ex, some register shows the TX status but
* no interrupt rises. Ignored if 'txdone_irq' is set.
* @txpoll_period: If 'txdone_poll' is in effect, the API polls for
* last TX's status after these many millisecs
* @of_xlate: Controller driver specific mapping of channel via DT
* @poll: API private. Used to poll for TXDONE on all channels.
* @node: API private. To hook into list of controllers.
*/
struct mbox_controller {
struct device *dev;
struct mbox_chan_ops *ops;
struct mbox_chan *chans;
int num_chans;
bool txdone_irq;
bool txdone_poll;
unsigned txpoll_period;
struct mbox_chan *(*of_xlate)(struct mbox_controller *mbox,
const struct of_phandle_args *sp);
/* Internal to API */
struct timer_list poll;
struct list_head node;
};
/*
* The length of circular buffer for queuing messages from a client.
* 'msg_count' tracks the number of buffered messages while 'msg_free'
* is the index where the next message would be buffered.
* We shouldn't need it too big because every transfer is interrupt
* triggered and if we have lots of data to transfer, the interrupt
* latencies are going to be the bottleneck, not the buffer length.
* Besides, mbox_send_message could be called from atomic context and
* the client could also queue another message from the notifier 'tx_done'
* of the last transfer done.
* REVISIT: If too many platforms see the "Try increasing MBOX_TX_QUEUE_LEN"
* print, it needs to be taken from config option or somesuch.
*/
#define MBOX_TX_QUEUE_LEN 20
/**
* struct mbox_chan - s/w representation of a communication chan
* @mbox: Pointer to the parent/provider of this channel
* @txdone_method: Way to detect TXDone chosen by the API
* @cl: Pointer to the current owner of this channel
* @tx_complete: Transmission completion
* @active_req: Currently active request hook
* @msg_count: No. of mssg currently queued
* @msg_free: Index of next available mssg slot
* @msg_data: Hook for data packet
* @lock: Serialise access to the channel
* @con_priv: Hook for controller driver to attach private data
*/
struct mbox_chan {
struct mbox_controller *mbox;
unsigned txdone_method;
struct mbox_client *cl;
struct completion tx_complete;
void *active_req;
unsigned msg_count, msg_free;
void *msg_data[MBOX_TX_QUEUE_LEN];
spinlock_t lock; /* Serialise access to the channel */
void *con_priv;
};
int mbox_controller_register(struct mbox_controller *mbox); /* can sleep */
void mbox_controller_unregister(struct mbox_controller *mbox); /* can sleep */
void mbox_chan_received_data(struct mbox_chan *chan, void *data); /* atomic */
void mbox_chan_txdone(struct mbox_chan *chan, int r); /* atomic */
#endif /* __MAILBOX_CONTROLLER_H */
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment