DocBook: Add CG2900 template

This patch readds the cg2900.tmpl template file for DocBook,
which for some unknown reason has been removed at a time earlier
on.
This patch also corrects some errors regarding CG2900 driver in
the KernelDoc.

ST-Ericsson Linux next: Not tested, ER282957
ST-Ericsson ID: 327420
ST-Ericsson FOSS-OUT ID: Trivial

Change-Id: If08c0a886007fef0598ebaca905814acc3fef81f
Signed-off-by: Par-Gunnar Hjalmdahl <par-gunnar.p.hjalmdahl@stericsson.com>
Reviewed-on: http://gerrit.lud.stericsson.com/gerrit/17856

2 files changed, 132 insertions, 75 deletions

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 25f19a4240e..ed5f4f63da5 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -19,7 +19,7 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \
 	    ske_keypad.xml ste_ff_vibra.xml ste_timed_vibra.xml \
 	    dma.xml gpio.xml i2s.xml i2c.xml mmc.xml \
 	    prcmu-fw-api.xml msp.xml \
-	    touchp.xml tc_keypad.xml stmpe.xml shrm.xml
+	    touchp.xml tc_keypad.xml stmpe.xml shrm.xml cg2900.xml
 
 ###
 # The build process is as follows (targets):
diff --git a/Documentation/DocBook/cg2900.tmpl b/Documentation/DocBook/cg2900.tmpl
index 5853bc1756b..9521fa7dc2f 100644
--- a/Documentation/DocBook/cg2900.tmpl
+++ b/Documentation/DocBook/cg2900.tmpl
@@ -86,7 +86,7 @@
   <title>Getting Started</title>
   <!-- Do NOT change the chapter id or title! -->
   <para>
-     There are no special compilation flags needed to build the STE connectivity driver.
+     There are no special compilation flags needed to build the CG2900 driver.
   </para>
   <para>
     There must be firmware and settings files that match the used chip version inside the firmware folder.
@@ -113,7 +113,7 @@
     <title>Basic Tutorial</title>
     <para>
       To enable the ST-Ericsson connectivity driver using KConfig go to <constant>Device Drivers -> Multifunction Device Drivers</constant>
-      and enable the STE Connectivity Driver. If BlueZ shall be used as Bluetooth stack also enable the STE HCI Connectivity driver.
+      and enable the CG2900 Driver. If BlueZ shall be used as Bluetooth stack also enable the STE HCI Connectivity driver.
       Depending on choice the driver will either be included as LKM or built into the Kernel.
       If building as LKM, several files will be generated:
       <itemizedlist>
@@ -168,6 +168,24 @@
    <para>
      <variablelist>
        <varlistentry>
+         <term>Platform device handling</term>
+         <listitem>
+         <para>
+           Each H:4 channel is created as a multifunction device. The driver for each channel must register as a platform driver for this channel,
+           supplying <function>probe</function> and <function>remove</function> functions.
+           When a transport is opened to the chip, the CG2900 chip driver will allocate and instantiate a platform device for each channel. This
+           means that at this point the device framework in the Kernel will call the <function>probe</function> function for the platform driver. It is then the responsibility for the platform driver
+           to register its callback functions and save its device to the platform data structure inside the probed device.
+         </para><para>
+           When the transport is removed the CG2900 chip driver will free each platform device and the the platform driver's <function>remove</function> function will then be called.
+         </para><para>
+           For user space, the user space character device will not exist until the character device driver has been probed.
+           The character devices will be removed when the character device driver is removed, i.e. when the transport is removed.
+         </para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
          <term>Opening a channel</term>
          <listitem>
          <para>
@@ -183,9 +201,7 @@
                <term>Opening a channel from Kernel space</term>
                <listitem>
                <para>
-                 When a stack is placed in Kernel space, it shall open a channel by calling the API function <function>cg2900_register_user</function>.
-                 This function will search for the supplied channel by using name look-up and open the channel.
-                 The function will return with a device reference that shall be used when calling the other CG2900 API functions.
+                 When a stack is placed in Kernel space, it shall open a channel by calling the API function <function>open</function> inside the platform data of the device.
                </para>
                </listitem>
              </varlistentry>
@@ -199,7 +215,6 @@
                  When a stack is placed in User space, it shall open a channel by calling the syscall function <function>open</function> on the corresponding file.
                  The files are located in folder <filename>/dev/</filename> and are named <filename>cg2900_gnss</filename> and similar. Each file
                  corresponds to one H:4 channel.
-                 This function will open the channel.
                </para>
                </listitem>
              </varlistentry>
@@ -224,8 +239,7 @@
                <listitem>
                <para>
                  When a stack is placed in Kernel space, it shall close a channel by calling the API function
-                 <function>cg2900_deregister_user</function>.
-                 This function will close the channel and also free the allocated device that was allocated when registering.
+                 <function>close</function> inside the platform data of the device.
                </para>
                </listitem>
              </varlistentry>
@@ -252,9 +266,9 @@
          <listitem>
          <para>
            When a stack (Bluetooth, FM, or GNSS) wants to send a packet it shall perform a write operation.
-           The packet shall not contain the H:4 header since this is added by the ST-E connectivity driver.
+           The packet shall not contain the H:4 header since this is added by the CG2900 driver.
            All other data in the packet shall however exist in the packet in the format correct for that HCI channel.
-           The ST-E connectivity users need to perform flow control over channels so any ticket handling
+           The CG2900 users need to perform flow control over channels so any ticket handling
            or similar must be handled by respective stack.
 
            <variablelist>
@@ -263,10 +277,10 @@
                <listitem>
                <para>
                  When a stack is placed in Kernel space, it shall start with allocating a packet of the correct size using
-                 <function>cg2900_alloc_skb</function>. This function will return an sk_buff (Socket buffer) structure that
-                 has necessary space reserved for ST-E driver operation.
+                 <function>alloc_skb</function> inside the platform data of the device. This function will return an sk_buff (Socket buffer) structure that
+                 has necessary space reserved for CG2900 driver operation.
                  The stack shall then copy the data, preferrably using <function>skb_put</function>, and then call
-                 <function>cg2900_write</function> to perform the write operation. When the function returns, the buffer has
+                 <function>write</function> inside the platform data of the device to perform the write operation. When the function returns, the buffer has
                  been transferred and there is no need for the calling function to free the buffer. If the operation fails, i.e.
                  an error code is returned, the caller must however free the buffer.
                </para>
@@ -309,9 +323,9 @@
          <listitem>
          <para>
            When a stack (Bluetooth, FM, or GNSS) wants to receive a packet it shall perform a receive operation.
-           The packet returned does not contain the H:4 header since this is removed by the ST-E connectivity driver.
+           The packet returned does not contain the H:4 header since this is removed by the CG2900 driver.
            All other data in the packet in the packet is in the format correct for that HCI channel.
-           The ST-E connectivity driver does not perform any flow control over the H:4 channel so any ticket handling
+           The CG2900 driver does not perform any flow control over the H:4 channel so any ticket handling
            or similar must be handled by respective stack.
 
            <variablelist>
@@ -319,9 +333,9 @@
                <term>Reading from a channel from Kernel space</term>
                <listitem>
                <para>
-                 When a stack is placed in Kernel space, it has to supply a callback function for the receive functionality when calling
-                 <function>cg2900_register_user</function>. This callback function will be called when the ST-E connectivity driver has
-                 received a packet. The packet received will always be a complete HCI packet, i.e. no fragmention on HCI layer.
+                 When a stack is placed in Kernel space, it has to supply a callback function for the receive functionality when being probed.
+                 This callback function will be called when the ST-E connectivity driver has received a packet.
+                 The packet received will always be a complete HCI packet, i.e. no fragmention on HCI layer.
                  When the packet has been received it is the responsability of the receiver to see to that the packet is freed using
                  <function>kfree_skb</function> when it is no more needed.
                </para>
@@ -366,11 +380,11 @@
                <term>Reset handling from Kernel space</term>
                <listitem>
                <para>
-                 When a stack is placed in Kernel space, it initiates a Reset operation by calling <function>cg2900_reset</function>.
+                 When a stack is placed in Kernel space, it initiates a Reset operation by calling <function>reset</function> inside the platform data of the device.
                  This will trigger a hardware reset of the controller. When the hardware reset is finished all registered users will be called
-                 through respective reset callback. When the callback function is finished the registered device will be removed and when all
-                 registered users have been informed and removed, the chip is shutdown. This is similar to a deregistration of all registered
-                 channels. The stack will then have to reregister to the ST-E connectivity driver in order to use the channel once again.
+                 through respective reset callback. When the callback function is finished the registered device will be closed and when all
+                 opened users have been informed and closed, the chip is shutdown. This is similar to a closure of all opened channels.
+                 The stack will then have to open the channel in order to use the channel once again.
                </para>
                </listitem>
              </varlistentry>
@@ -402,51 +416,55 @@
          <term>Example code Kernel space</term>
          <listitem>
          <para>
-           This example will register to the FM channel, write a packet, read a packet and then deregister.
+           This example will open the FM channel, write a packet, read a packet and then close the channel.
 
            <programlisting>
-             struct cg2900_device *my_dev;
              bool event_received;
 
-             void read_cb(struct cg2900_device *dev, struct sk_buff *skb)
+             void read_cb(struct cg2900_user_data *dev, struct sk_buff *skb)
              {
                event_received = true;
                kfree_skb(skb);
              }
 
-             void reset_cb(struct cg2900_device *dev)
+             void reset_cb(struct cg2900_user_data *dev)
              {
-               /* Handle reset. Device will be automatically freed by the ST-E driver */
-               my_dev = NULL;
+               /* Handle reset. Device will be automatically closed by the CG2900 driver */
              }
 
-             static struct cg2900_callbacks my_cb = {
-               .read_cb = read_cb,
-               .reset_cb = reset_cb
-             };
-
-             void example_open(void)
+             void example_open(struct my_info *info)
              {
-               my_dev = cg2900_register_user(CG2900_FM_RADIO, &amp;my_cb);
-               if (!my_dev) {
-                 printk("Error! Couldn't register!\n");
+               struct cg2900_user_data *user = dev_get_platdata(info->dev);
+               int err;
+
+               if (user->opened) {
+                 dev_err(info->dev, "Error! Channel already opened!\n");
+                 return;
+               }
+
+               err = user->open(user);
+               if (err) {
+                 dev_err(info->dev, "Error (%d)! Couldn't register!\n", err);
                }
              }
 
-             void example_close(void)
+             void example_close(struct my_info *info)
              {
-               cg2900_deregister_user(my_dev);
-               my_dev = NULL;
+               struct cg2900_user_data *user = dev_get_platdata(info->dev);
+
+               if (user->opened)
+                 user->close(user);
              }
 
-             void example_write_and_read(uint8_t *data, int len)
+             void example_write_and_read(struct my_info *info, uint8_t *data, int len)
              {
                int err;
-               struct sk_buff *skb = cg2900_alloc_skb(len, GFP_KERNEL);
+               struct cg2900_user_data *user = dev_get_platdata(info->dev);
+               struct sk_buff *skb = user->alloc_skb(len, GFP_KERNEL);
 
                if (skb) {
                  memcpy(skb_put(skb, len), data, len);
-                 err = cg2900_write(my_dev, skb);
+                 err = user->write(user, skb);
                  if (!err) {
                    event_received = false;
 
@@ -455,11 +473,67 @@
                      schedule_timeout_interruptible(jiffies + 50);
                    }
                  } else {
-                   printk("Couldn't write to controller (%d)\n", err);
+                   dev_err(info->dev, "Couldn't write to controller (%d)\n", err);
                    kfree_skb(skb);
                  }
                }
              }
+
+             static int __devinit my_probe(struct platform_device *pdev)
+             {
+               struct my_info *info;
+               struct cg2900_user_data *pf_data;
+
+               info = kzalloc(sizeof(*info));
+               if (!info)
+                 return -ENOMEM;
+
+               dev_set_drvdata(&amp;pdev->dev, info);
+               info->dev = &amp;pdev->dev;
+
+               pf_data = dev_get_platdata(&amp;pdev->dev);
+               pf_data->dev = &amp;pdev->dev;
+               pf_data->read_cb = read_cb;
+               pf_data->reset_cb = reset_cb;
+
+               /*
+                * Alert my user that we are ready to start and give
+                * it my info pointer.
+                */
+               return my_user_start(info);
+             }
+
+             static int __devexit my_remove(struct platform_device *pdev)
+             {
+               struct my_info *info;
+
+               info = dev_get_drvdata(&amp;pdev->dev);
+               my_user_stop(info);
+               kfree(info);
+               return 0;
+             }
+
+             static struct platform_driver my_driver = {
+               .driver = {
+                 .name	= "cg2900-fm",
+                 .owner	= THIS_MODULE,
+               },
+               .probe	= my_probe,
+               .remove	= __devexit_p(my_remove),
+             };
+
+             static int __init my_init(void)
+             {
+               return platform_driver_register(&amp;my_driver);
+             }
+
+             static void __exit my_exit(void)
+             {
+               platform_driver_unregister(&amp;my_driver);
+             }
+
+             module_init(my_init);
+             module_exit(my_exit);
            </programlisting>
          </para>
          </listitem>
@@ -710,7 +784,7 @@
              </varlistentry>
              <varlistentry>
                <term>Default value</term>
-               <listitem><para>0x00 0x80 0xDE 0xAD 0xBE 0xEF</para></listitem>
+               <listitem><para>0x00 0x80 0xDE 0xAD 0xBE 0x00</para></listitem>
              </varlistentry>
              <varlistentry>
                <term>Runtime readable/modifiable</term>
@@ -741,7 +815,7 @@
              </varlistentry>
              <varlistentry>
                <term>Default value</term>
-               <listitem><para>0</para></listitem>
+               <listitem><para>10000</para></listitem>
              </varlistentry>
              <varlistentry>
                <term>Runtime readable/modifiable</term>
@@ -960,7 +1034,7 @@
            <varlistentry>
              <term>Description</term>
              <listitem>
-             <para>The cg2900_driver represents the main parent node for all other character devices supplied in the ST-Ericsson connectivity driver except for the CCD Test device. It does not support any operations such as read or write.</para>
+             <para>The cg2900_driver represents the main parent node for all other character devices supplied in the ST-Ericsson connectivity driver except for the Test device. It does not support any operations such as read or write.</para>
              </listitem>
            </varlistentry>
          </variablelist>
@@ -1112,35 +1186,17 @@
      </varlistentry>
 
      <varlistentry>
-       <term>User Space Control</term>
-       <listitem>
-         <variablelist>
-           <varlistentry>
-             <term>File</term>
-             <listitem><para><filename>/dev/cg2900_us_ctrl</filename></para></listitem>
-           </varlistentry>
-           <varlistentry>
-             <term>Description</term>
-             <listitem>
-             <para>The cg2900_us_ctrl is the device for initialization and control of the STE CONN driver.</para>
-             </listitem>
-           </varlistentry>
-         </variablelist>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry>
-       <term>CCD Test stub</term>
+       <term>Test stub</term>
        <listitem>
          <variablelist>
            <varlistentry>
              <term>File</term>
-             <listitem><para><filename>/dev/cg2900_ccd_test</filename></para></listitem>
+             <listitem><para><filename>/dev/cg2900_test</filename></para></listitem>
            </varlistentry>
            <varlistentry>
              <term>Description</term>
              <listitem>
-             <para>The cg2900_ccd_test is the device for performing module tests of the ST-Ericsson connectivity driver. It acts as a stub replacing the transport towards the chip. It is of the type Misc devices.</para>
+             <para>The cg2900_test is the device for performing module tests of the ST-Ericsson CG2900 driver. It acts as a stub replacing the transport towards the chip. It is of the type Misc devices.</para>
              </listitem>
            </varlistentry>
          </variablelist>
@@ -1202,7 +1258,7 @@
      </varlistentry>
 
      <varlistentry>
-       <term>CG29XX Audio</term>
+       <term>CG2900 Audio</term>
        <listitem>
          <variablelist>
            <varlistentry>
@@ -1218,7 +1274,7 @@
                The <constant>write</constant> command is used as following:
                <itemizedlist>
                  <listitem><para>4 byte op code (see below)</para></listitem>
-                 <listitem><para>Data field according to respective CG29XX Audio function (no session ID needed)</para></listitem>
+                 <listitem><para>Data field according to respective CG2900 Audio function (no session ID needed)</para></listitem>
                </itemizedlist>
                If the operation fails the <constant>write</constant> command operation will return the error.
                Op codes are (4 bytes size):
@@ -1235,7 +1291,7 @@
                The returned data will be formatted accordingly:
                <itemizedlist>
                  <listitem><para>4 byte op code (see below)</para></listitem>
-                 <listitem><para>Data field according to normal CG29XX Audio functions, e.g. stream handle or configuration</para></listitem>
+                 <listitem><para>Data field according to normal CG2900 Audio functions, e.g. stream handle or configuration</para></listitem>
                </itemizedlist>
                The <constant>CHAR_DEV_OP_CODE_GET_DAI_CONF</constant> is a bit special since it require an endpoint in-parameter
                (when calling <constant>write</constant>) to return the corresponding DAI configuration when calling <constant>read</constant>.
@@ -1293,6 +1349,7 @@
   <section id="cg2900.h">
     <title>cg2900.h</title>
 !Edrivers/mfd/cg2900/cg2900_core.c
+!Iinclude/linux/mfd/cg2900.h
   </section>
   <section id="cg2900_audio.h">
     <title>cg2900_audio.h</title>
@@ -1313,9 +1370,9 @@
         appropriate header or source file exist describing a public interface,
         replace the inclusion with a paragraph containing the text
         "Not Applicable"-->
-  <section id="cg2900_core.h">
-    <title>cg2900_core.h</title>
-!Edrivers/mfd/cg2900/cg2900_core.h
+  <section id="cg2900_lib.h">
+    <title>cg2900_lib.h</title>
+!Edrivers/mfd/cg2900/cg2900_lib.c
   </section>
 </chapter>
 </book>