From 7fd6e650c4aeacd1221e30082f955baa70f887c7 Mon Sep 17 00:00:00 2001 From: Philippe Langlais Date: Fri, 14 Oct 2011 11:13:35 +0200 Subject: u5500 : kernel-doc for Mailbox Logical Driver Kernle-Doc created for u5500 Mailbox Logical Driver ST-Ericsson ID: 277198 Change-Id: I6e1298615a3943177fa05342a9ff8215e521fa72 Signed-off-by: Bibek Basu Reviewed-on: http://gerrit.lud.stericsson.com/gerrit/23718 Reviewed-by: QATEST Reviewed-by: Srinidhi KASAGAR --- Documentation/DocBook/u5500_LogicalMailbox.tmpl | 114 +++++++++++++++++++++ .../mach-ux500/include/mach/mbox_channels-db5500.h | 73 ++++++------- drivers/misc/mbox_channels-db5500.c | 38 ++++++- 3 files changed, 185 insertions(+), 40 deletions(-) create mode 100644 Documentation/DocBook/u5500_LogicalMailbox.tmpl 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 @@ + + + + + + u5500 Mailbox Logical Driver + + + + Bibek + Basu + +
+ bibek.basu@stericsson.com +
+ + + + + + 2011 + ST-Ericsson + + + + + Linux standard functions + + + + + + + + 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. + + + + 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. + + + + 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 + + + + For more details see the file COPYING in the source + distribution of Linux. + + + + + + + + Introduction + + This documentation describes the API provided by the U5500 Mailbox Logical Driver. + + + + + Known Bugs And Assumptions + + + + None + + + None. + + + + + + + + + Structures + + This chapter contains the autogenerated documentation of the structures which are + used in the U5500 Mailbox Logical Driver. + +!Iarch/arm/mach-ux500/include/mach/mbox_channels-db5500.h + + + + Public Functions Provided + + List of public interfaces in stmpe driver + +!Edrivers/misc/mbox_channels-db5500.c + + + + Internal Functions Provided + + This chapter contains the autogenerated documentation of the internal functions. + +!Idrivers/misc/mbox_channels-db5500.c + + + 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 { -- cgit v1.2.3