diff options
| -rw-r--r-- | Documentation/DocBook/u5500_LogicalMailbox.tmpl | 114 | ||||
| -rw-r--r-- | arch/arm/mach-ux500/include/mach/mbox_channels-db5500.h | 73 | ||||
| -rw-r--r-- | drivers/misc/mbox_channels-db5500.c | 38 |
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 { |