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 <bibek.basu@stericsson.com>
Reviewed-on: http://gerrit.lud.stericsson.com/gerrit/23718
Reviewed-by: QATEST
Reviewed-by: Srinidhi KASAGAR <srinidhi.kasagar@stericsson.com>

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 {