summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Documentation/DocBook/u5500_LogicalMailbox.tmpl114
-rw-r--r--arch/arm/mach-ux500/include/mach/mbox_channels-db5500.h73
-rw-r--r--drivers/misc/mbox_channels-db5500.c38
3 files changed, 185 insertions, 40 deletions
diff --git a/Documentation/DocBook/u5500_LogicalMailbox.tmpl b/Documentation/DocBook/u5500_LogicalMailbox.tmpl
new file mode 100644
index 00000000000..71a5d6c7c28
--- /dev/null
+++ b/Documentation/DocBook/u5500_LogicalMailbox.tmpl
@@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
+
+<book id="Mailbox LD">
+ <bookinfo>
+ <title>u5500 Mailbox Logical Driver</title>
+
+ <authorgroup>
+ <author>
+ <firstname>Bibek</firstname>
+ <surname>Basu</surname>
+ <affiliation>
+ <address>
+ <email>bibek.basu@stericsson.com</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <copyright>
+ <year>2011</year>
+ <holder>ST-Ericsson</holder>
+ </copyright>
+
+ <subjectset>
+ <subject>
+ <subjectterm>Linux standard functions</subjectterm>
+ </subject>
+ </subjectset>
+
+ <legalnotice>
+ <!-- Do NOT remove the legal notice below -->
+
+ <para>
+ This documentation is free software; you can redistribute
+ it and/or modify it under the terms of the GNU General Public
+ License as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later
+ version.
+ </para>
+
+ <para>
+ This program is distributed in the hope that it will be
+ useful, but WITHOUT ANY WARRANTY; without even the implied
+ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ </para>
+
+ <para>
+ You should have received a copy of the GNU General Public
+ License along with this program; if not, write to the Free
+ Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ MA 02111-1307 USA
+ </para>
+
+ <para>
+ For more details see the file COPYING in the source
+ distribution of Linux.
+ </para>
+ </legalnotice>
+ </bookinfo>
+
+<toc></toc>
+
+ <chapter id="intro">
+ <title>Introduction</title>
+ <para>
+ This documentation describes the API provided by the U5500 Mailbox Logical Driver.
+ </para>
+ </chapter>
+
+ <chapter id="bugs">
+ <title>Known Bugs And Assumptions</title>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>None</term>
+ <listitem>
+ <para>
+ None.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </chapter>
+
+ <chapter id="structs">
+ <title>Structures</title>
+ <para>
+ This chapter contains the autogenerated documentation of the structures which are
+ used in the U5500 Mailbox Logical Driver.
+ </para>
+!Iarch/arm/mach-ux500/include/mach/mbox_channels-db5500.h
+ </chapter>
+
+ <chapter id="pubfunctions">
+ <title>Public Functions Provided</title>
+ <para>
+ List of public interfaces in stmpe driver
+ </para>
+!Edrivers/misc/mbox_channels-db5500.c
+ </chapter>
+
+ <chapter id="intfunctions">
+ <title>Internal Functions Provided</title>
+ <para>
+ This chapter contains the autogenerated documentation of the internal functions.
+ </para>
+!Idrivers/misc/mbox_channels-db5500.c
+ </chapter>
+
+ </book>
diff --git a/arch/arm/mach-ux500/include/mach/mbox_channels-db5500.h b/arch/arm/mach-ux500/include/mach/mbox_channels-db5500.h
index 829b1708bf1..0b2fc604873 100644
--- a/arch/arm/mach-ux500/include/mach/mbox_channels-db5500.h
+++ b/arch/arm/mach-ux500/include/mach/mbox_channels-db5500.h
@@ -12,27 +12,27 @@
#define MAILBOX_NR_OF_DATAWORDS 3
/**
- * mbox_channel_cb_t - Definition of the mailbox channel callback.
- * @data: Pointer to the data.
- * @length: Length of the data.
- * @priv: The client's private data.
- *
- * This function will be called upon reception of complete mbox channel PDU
- * or after completion of send operation.
- */
+ * mbox_channel_cb_t - Definition of the mailbox channel callback.
+ * @data: Pointer to the data.
+ * @length: Length of the data.
+ * @priv: The client's private data.
+ *
+ * This function will be called upon reception of complete mbox channel PDU
+ * or after completion of send operation.
+ */
typedef void mbox_channel_cb_t (u32 *data, u32 length, void *priv);
/**
- * mbox_channel_msg - Definition of mbox channel message
- * @channel: Channel number.
- * @data: Pointer to data to be sent.
- * @length: Length of data to be sent.
- * @cb: Pointer to the callback function to be called when send
- * operation will be finished.
- * @priv: The client's private data.
- *
- * This structure describes mailbox channel message.
- */
+ * struct mbox_channel_msg - Definition of mbox channel message
+ * @channel: Channel number.
+ * @data: Pointer to data to be sent.
+ * @length: Length of data to be sent.
+ * @cb: Pointer to the callback function to be called when send
+ * operation will be finished.
+ * @priv: The client's private data.
+ *
+ * This structure describes mailbox channel message.
+ */
struct mbox_channel_msg {
u16 channel;
u32 *data;
@@ -41,30 +41,31 @@ struct mbox_channel_msg {
void *priv;
};
-/** mbox_channel_register - Set up a given mailbox channel.
- * @channel: Mailbox channel number.
- * @cb: Pointer to the callback function to be called when a new message
- * is received.
- * @priv: Client user data which will be returned in the callback.
- *
- * Returns 0 on success or a negative error code on error.
- */
+/**
+ * mbox_channel_register - Set up a given mailbox channel.
+ * @channel: Mailbox channel number.
+ * @cb: Pointer to the callback function to be called when a new message
+ * is received.
+ * @priv: Client user data which will be returned in the callback.
+ *
+ * Returns 0 on success or a negative error code on error.
+ */
int mbox_channel_register(u16 channel, mbox_channel_cb_t *cb, void *priv);
/**
- * mbox_channel_send - Send data on given mailbox channel.
- * @msg: Mailbox channel message to be sent.
- *
- * Returns 0 on success or a negative error code on error.
- */
+ * mbox_channel_send - Send data on given mailbox channel.
+ * @msg: Mailbox channel message to be sent.
+ *
+ * Returns 0 on success or a negative error code on error.
+ */
int mbox_channel_send(struct mbox_channel_msg *msg);
/**
- * mbox_channel_revoke_messages - Revoke messages on given mailbox channel.
- * @channel: Mailbox channel number.
- *
- * Returns 0 on success or a negative error code on error.
- */
+ * mbox_channel_revoke_messages - Revoke messages on given mailbox channel.
+ * @channel: Mailbox channel number.
+ *
+ * Returns 0 on success or a negative error code on error.
+ */
int mbox_channel_revoke_messages(u16 channel);
#endif /*INC_STE_MBOX_H*/
diff --git a/drivers/misc/mbox_channels-db5500.c b/drivers/misc/mbox_channels-db5500.c
index 74fdfa7aaae..64aaa29cc4f 100644
--- a/drivers/misc/mbox_channels-db5500.c
+++ b/drivers/misc/mbox_channels-db5500.c
@@ -579,6 +579,17 @@ static void mbox_cb(u32 mbox_msg, void *priv)
}
}
+/**
+ * mbox_channel_register() - Registers for a channel
+ * @channel: Channel Number.
+ * @cb: Pointer to function pointer mbox_channel_cb_t
+ * @priv: Pointer to private data
+ *
+ * This routine is used to register for a logical channel.
+ * It first does sanity check on the requested channel availability
+ * and parameters. Then it prepares internal entry for the channel.
+ * And send a OPEN request for that channel.
+ */
int mbox_channel_register(u16 channel, mbox_channel_cb_t *cb, void *priv)
{
struct channel_status *rx_chan;
@@ -668,6 +679,17 @@ exit:
}
EXPORT_SYMBOL(mbox_channel_register);
+/**
+ * mbox_channel_send() - Send messages
+ * @msg: Pointer to mbox_channel_msg data structure.
+ *
+ * This routine is used to send messages over the registered logical
+ * TX channel. It first does sanity check on the message paramenters.
+ * It registered channel is not found then it just registers for that
+ * channel. If channel found, it puts the message to the pending list.
+ * If channel is OPEN, it then pushes the message to the mailbox in
+ * FIFO manner from the pending list.
+ */
int mbox_channel_send(struct mbox_channel_msg *msg)
{
struct list_head *pos, *tx_list;
@@ -773,7 +795,15 @@ static void revoke_pending_msgs(struct channel_status *tx_chan)
}
}
-/* Clear all pending messages from TX channel */
+/**
+ * mbox_channel_revoke_messages() - Revoke pending messages
+ * @channel: Channel on which action to be taken.
+ *
+ * This routine Clear all pending messages from TX channel
+ * It searches for the channel.Checks if there is pending
+ * messages.Calls if tehre is any registered function. And
+ * deletes the messages for the pending list.
+ */
int mbox_channel_revoke_messages(u16 channel)
{
struct list_head *pos, *tx_list;
@@ -837,14 +867,14 @@ static int registration_done;
* struct mboxtest_data - mbox test via debugfs information
* @rx_buff: Buffer for incomming data
* @rx_pointer: Ptr to actual RX data buff
- * @tx_buff Buffer for outgoing data
+ * @tx_buff: Buffer for outgoing data
* @tx_pointer: Ptr to actual TX data buff
* @tx_done: TX Transfer done indicator
* @rx_done: RX Transfer done indicator
- * @received Received words
+ * @received: Received words
* @xfer_words: Num of bytes in actual trf
* @xfers: Number of transfers
- * @words Number of total words
+ * @words: Number of total words
* @channel: Channel test number
*/
struct mboxtest_data {