diff options
Diffstat (limited to 'Documentation/DocBook')
22 files changed, 5405 insertions, 11 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 66725a3d30d..023616787da 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -14,7 +14,13 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ 80211.xml debugobjects.xml sh.xml regulator.xml \ alsa-driver-api.xml writing-an-alsa-driver.xml \ - tracepoint.xml drm.xml media_api.xml + tracepoint.xml drm.xml media_api.xml \ + shrm.xml touchp.xml \ + tc_keypad.xml prcmu-fw-api.xml cg2900_fm_radio.xml \ + synaptics_rmi4_touchp.xml db5500_keypad.xml \ + u5500_LogicalMailbox.xml cg2900.xml \ + lsm303dlh.xml ske_keypad.xml ste_ff_vibra.xml ux500_usb.xml \ + lps001wp_prs.xml include $(srctree)/Documentation/DocBook/media/Makefile diff --git a/Documentation/DocBook/cg2900.tmpl b/Documentation/DocBook/cg2900.tmpl new file mode 100644 index 00000000000..34667f1b1d9 --- /dev/null +++ b/Documentation/DocBook/cg2900.tmpl @@ -0,0 +1,1381 @@ +<?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="STE-Connectivity-template"> + <bookinfo> + <title>CG2900 Driver</title> + + <authorgroup> + <author> + <firstname>Henrik</firstname> + <surname>Possung</surname> + <affiliation> + <address> + <email>henrik.possung@stericsson.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>Par-Gunnar</firstname> + <surname>Hjalmdahl</surname> + <affiliation> + <address> + <email>par-gunnar.p.hjalmdahl@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2010</year> + <holder>ST-Ericsson SA</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Connectivity</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> + <!-- Do NOT change the chapter id or title! --> + <para> + This documentation describes the functions provided by the ST-Ericsson CG2900 Driver for enabling + ST-Ericsson CG2900 Combo Controller Hardware. + + </para> + </chapter> + + <chapter id="gettingstarted"> + <title>Getting Started</title> + <!-- Do NOT change the chapter id or title! --> + <para> + There are no special compilation flags needed to build the CG2900 driver. + </para> + <para> + There must be patch and settings files that match the used chip version inside the firmware folder. + The files: + <itemizedlist> + <listitem><para>CG2900_XXXX_YYYY_patch.fw</para></listitem> + <listitem><para>CG2900_XXXX_YYYY_settings.fw</para></listitem> + </itemizedlist> + where XXXX is chip revision and YYYY is chip sub-version returned from the HCI Read Local Version command. + </para> + + <!-- TODO: If the driver needs preparations to be used + (special compilation flags, files in the file system, + knowledge about a specific domain etc), specify it here. + Remove this chapter completely if there is nothing + to mention and there is no tutorial needed. + Do NOT change the chapter id or title! --> + <!-- TODO: This guideline for this chapter may be extended + during the user-guide guidelines drop. --> + + <section id="basic-tutorial"> + <title>Basic Tutorial</title> + <para> + To enable the ST-Ericsson CG2900 driver using KConfig go to <constant>Device Drivers -> Staging Drivers</constant> + and enable the CG2900 Driver. If BlueZ shall be used as Bluetooth stack also enable the CG2900 Bluetooth 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> + <listitem><para>cg2900.ko which contains the main driver</para></listitem> + <listitem><para>cg2900_char_devices.ko which contains the character devices</para></listitem> + <listitem><para>cg2900_uart.ko which contains the UART driver</para></listitem> + <listitem><para>cg2900_chip.ko which contains the CG2900 chip specific driver</para></listitem> + <listitem><para>stlc2690_chip.ko which contains the STLC2690 chip specific driver</para></listitem> + <listitem><para>cg2900_audio.ko which contains the CG2900 audio driver</para></listitem> + <listitem><para>btcg2900.ko which contains the registration and mapping towards the BlueZ Bluetooth stack</para></listitem> + </itemizedlist> + + <!-- TODO: Provide a basic tutorial, outlining how + to test the presence of the driver, + for example how to configure, compile and run the + example(s). + Several sections with different tutorials, + all located within the Getting Started + chapter may be provided. --> + </para> + + <para> + <!-- TODO: This guideline for this section may be extended + during the user-guide guidelines drop. --> + </para> + </section> + + </chapter> + + <chapter id="concepts"> + <title>Concepts</title> + <!-- Do NOT change the chapter id or title! --> + <para> + The ST-Ericsson CG2900 driver works as a multiplexer between different users, such as a Bluetooth stack and a FM driver, + and the connectivity chip. The driver supports multiple physical transports, although currently only UART is implemented. + Apart from just transporting data between stacks and the chip, the ST-Ericsson CG2900 driver also deals with power handling, + powering up and down the chip and also downloading necessary patches and settings for the chip to start up properly. + <!-- TODO: A brief introduction about the concepts + which are introduced by the driver. + Remove this chapter completely if there are no + special concepts introduced by this driver. + Do NOT change the chapter id or title! --> + <!-- TODO: This guideline for this chapter may be extended + during the user-guide guidelines drop. --> + </para> + </chapter> + + <chapter id="tasks"> + <title>Tasks</title> + <!-- Do NOT change the chapter id or title! --> + + <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> + In order to be able to send and receive data on an H:4 channel, the user (i.e. respective stack) must open the channel. + Opening a channel will make it possible to send data to and receive data from the connectivity controller. + If the controller were earlier powered down, opening a channel will also cause the controller to be powered up. + When chip is powered up, patches and settings for the ARM subsystem will be downloaded as well. + Other IPs within the controller must however download each respective patches and settings. + If chip was already powered up when opening the channel no patch will be automatically downloaded. + + <variablelist> + <varlistentry> + <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>open</function> inside the platform data of the device. + </para> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>Opening a channel from User space</term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Closing a channel</term> + <listitem> + <para> + When a user, i.e. a stack has no need for a functionality, it should close the corresponding H:4 channel. + This is usually done when a user disables a certain feature, for example Bluetooth. The reason why the channels + need to be closed is that the ST-E CG2900 driver will free the resources and also shutdown the controller if there are + no more active users of the chip. This will lower the power consumption thereby increasing battery life. + + <variablelist> + <varlistentry> + <term>Closing a channel from Kernel space</term> + <listitem> + <para> + When a stack is placed in Kernel space, it shall close a channel by calling the API function + <function>close</function> inside the platform data of the device. + </para> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>Closing a channel from User space</term> + <listitem> + <para> + When a stack is placed in User space, it shall close a channel by calling the syscall function + <function>close</function> on the corresponding file. + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Writing to a channel</term> + <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 CG2900 driver. + All other data in the packet shall however exist in the packet in the format correct for that HCI channel. + The CG2900 users need to perform flow control over channels so any ticket handling + or similar must be handled by respective stack. + + <variablelist> + <varlistentry> + <term>Writing to a channel from Kernel space</term> + <listitem> + <para> + When a stack is placed in Kernel space, it shall start with allocating a packet of the correct size using + <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>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> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>Writing to a channel from User space</term> + <listitem> + <para> + When a stack is placed in User space, it shall call the <function>write</function> function on + the corresponding file to perform a transmit operation. After function returns the data has been + copied and is considered sent. + The caller does not need to preserve the data. + </para> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>Writing to FM_Radio and FM_Audio channel</term> + <listitem> + <para> + CG2900 driver only supports FM legacy commands. The reason is that the FM_Radio and FM_Audio uses the same H4 channel aginst the chip, + in order to multiplex the FM user commands the data pakets are parsed by the CG2900 driver. + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Reading from a channel</term> + <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 CG2900 driver. + All other data in the packet in the packet is in the format correct for that HCI channel. + 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> + <varlistentry> + <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 being probed. + This callback function will be called when the ST-E CG2900 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> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>Reading from a channel from User space</term> + <listitem> + <para> + When a stack is placed in User space, it shall call the <function>read</function> function on + the corresponding file to perform a receive operation. This function will read as many bytes as there are present + up to the size of the supplied buffer. If no data is available the function will hang until data becomes available, reset + occurs, or the channel is closed. + For smooth operation it is recommended to use the <function>poll</function> functionality on the file, preferrably + from a dedicated thread. This way one thread can monitor both read and reset operations in one common thread while transmit + operations may continue unblocked in a separate thread. + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Reset handling</term> + <listitem> + <para> + The stacks shall always try to avoid performing Reset operations. The Reset will result in a hardware reset of the controller + and will therefore cause all existing links and settings to be lost. All stacks using the controller must also be informed + about the reset and handle it in a proper way. + The reset operation should only be used when there is no other option to get the controller into a working state, for example + if the controller has stopped answering to commands. + After the hardware reset, the ST-E CG2900 driver will automatically perform deregister the channel so it has to be reopened again. + + <variablelist> + <varlistentry> + <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>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 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> + </variablelist> + + <variablelist> + <varlistentry> + <term>Reset handling from User space</term> + <listitem> + <para> + When a stack is placed in User space, it shall call the <function>ioctl</function> function on + the corresponding file to perform a reset operation. The command parameter <constant>CG2900_CHAR_DEV_IOCTL_RESET</constant> + shall be used when calling <function>ioctl</function>. + When the <function>ioctl</function> returns, the stack shall close the channel and then re-open it again. This must be done so + the channel is registered correctly in Kernel space. + For smooth operation it is recommended to use the <function>poll</function> functionality on the file, preferrably + from a dedicated thread. This way one thread can monitor both read and reset operations in one common thread while transmit + operations may continue unblocked in a separate thread. + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Example code Kernel space</term> + <listitem> + <para> + This example will open the FM channel, write a packet, read a packet and then close the channel. + + <programlisting> + bool event_received; + + void read_cb(struct cg2900_user_data *dev, struct sk_buff *skb) + { + event_received = true; + kfree_skb(skb); + } + + void reset_cb(struct cg2900_user_data *dev) + { + /* Handle reset. Device will be automatically closed by the CG2900 driver */ + } + + void example_open(struct my_info *info) + { + 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(struct my_info *info) + { + struct cg2900_user_data *user = dev_get_platdata(info->dev); + + if (user->opened) + user->close(user); + } + + void example_write_and_read(struct my_info *info, uint8_t *data, int len) + { + int err; + 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 = user->write(user, skb); + if (!err) { + event_received = false; + + while (!event_received) { + /* Wait for ack event. Received in read_cb() above */ + schedule_timeout_interruptible(jiffies + 50); + } + } else { + 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(&pdev->dev, info); + info->dev = &pdev->dev; + + pf_data = dev_get_platdata(&pdev->dev); + pf_data->dev = &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(&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(&my_driver); + } + + static void __exit my_exit(void) + { + platform_driver_unregister(&my_driver); + } + + module_init(my_init); + module_exit(my_exit); + </programlisting> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Example code User space</term> + <listitem> + <para> + This example will open the GNSS channel, write a packet, read a packet and then close the channel. + In this example all functions are performed in the same thread. + It is however adviced to perform <function>read</function> and <function>ioctl</function> read through a separate thread, + preferrably using <function>poll</function>. + + <programlisting> + struct my_info_t { + int fd; + }; + + static struct my_info_t my_info; + + /* This is a fake command and has nothing to do with real GNSS commands. + * Note that the command does NOT contain the H:4 header. + * The header is added by the ST-E CG2900 driver. + */ + static const uint8_t tx_cmd[] = {0x12, 0x34, 0x56}; + + int main(int argc, char **argv) + { + uint8_t rx_buffer[100]; + int rx_bytes = 0; + int err; + + my_info.fd = open("/dev/cg2900_gnss", O_RDWR); + if (my_info.fd < 0) { + printf("Error on open file: %d (%s)\n", errno, strerror(errno)); + return errno; + } + if (0 > write(my_info.fd, tx_cmd, sizeof(tx_cmd))) { + printf("Error on write file: %d (%s)\n", errno, strerror(errno)); + return errno; + } + /* Read will sleep until there is data available */ + rx_bytes = read(my_info.fd, rx_buffer, 100); + if (rx_bytes >= 0) { + printf("Received %d bytes\n", rx_bytes); + } else { + printf("Error on read file: %d (%s)\n", errno, strerror(errno)); + return errno; + } + err = close(my_info.fd); + if (err) { + printf("Error on close file: %d (%s)\n", errno, strerror(errno)); + return errno; + } + return 0; + } + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + + <!-- TODO: Task descriptions are step by step instructions + for performing specific actions and tasks. + Each task is typically one scenario. + Each task is described in a separate (section). + (section) tags can be nested, which is + especially recommended if + the task consists of several scenarios. + Remove this chapter completely if there are no + tasks to mention and there is no tutorial needed. + Do NOT change the chapter id or title! --> + <!-- TODO: This guideline for this chapter may be extended + during the user-guide guidelines drop. --> + </para> + </chapter> + + <chapter id="driver-configuration"> + <title>Driver Configuration and Interaction</title> + <!-- Do NOT change the chapter id or title! --> + <para> + N/A + <!-- TODO: Use this paragraph as an introduction to driver + configuration and interaction. Describe the big picture. --> + <!-- TODO: This chapter contains driver specific way to perform + configuration and interaction. The chapter includes a + number of sections. They should not be removed and if + the driver does not have the specific support for + configuration or interaction should the text "not + applicable" be inserted. Do NOT change the chapter id + or title! --> + <!-- TODO: This guideline for this chapter may be extended + during the user-guide guidelines drop. --> + </para> + + <section id="driver-implemented-operations"> + <title>Implemented operations in driver</title> + <para> + <!-- TODO: Describe the actual usage of the driver. Specify the actual + implemented operations in struct <structname>file_operations</structname> + and any other set of operations. Create a table with two columns + (see example in intro chapter how to create a table). + Column one list all operations supported (read, + write, open, close, ioctl etc) and column two a description of the + semantics of the operations in the specific context of the device + driver from the users perspective. Document the operations in a way + that a user of the driver can be helped. --> + </para> + <para> + <table> + <title> Supported device driver operations when using character device </title> + <tgroup cols="2"><tbody> + <row><entry> open </entry> <entry> Opening a character device will register the caller to that HCI channel.</entry> </row> + <row><entry> release </entry> <entry> Releasing a character device will deregister the caller from that HCI channel</entry> </row> + <row><entry> poll </entry> <entry> Polling a character device will check if there is data to read on that HCI channel</entry> </row> + <row><entry> read </entry> <entry> Reading from a character device reads from that HCI channel</entry> </row> + <row><entry> write </entry> <entry> Writing to a character device writes to that HCI channel</entry> </row> + <row><entry> unlocked_ioctl </entry> <entry> Performing IO control on a character device will perform special operations such as reset on that HCI channel</entry> </row> + </tbody></tgroup> + </table> + </para> + </section> + + <section id="driver-loading"> + <title>Driver loading parameters</title> + <para> + <!-- TODO: Describe parameters that can be specified at kernel + driver loading with insmod or modprobe. If the driver + has no parameters to be specified at load time, replace this + text with "Not Applicable". --> + </para> + <variablelist> + <varlistentry> + <term>uart_default_baud</term> + <listitem> + <para> + <variablelist> + <varlistentry> + <term>Parameter type</term> + <listitem><synopsis><type>int</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Default value</term> + <listitem><para>115200</para></listitem> + </varlistentry> + <varlistentry> + <term>Runtime readable/modifiable</term> + <listitem><para>Readable</para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The parameter uart_default_baud in cg2900_uart.c defines the baud rate used after a chip has just been powered up. + It shall be set to the default baud rate of the controller. + For ST-Ericsson controllers STLC2690 and CG2900 this value shall be 115200. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>uart_high_baud</term> + <listitem> + <para> + <variablelist> + <varlistentry> + <term>Parameter type</term> + <listitem><synopsis><type>int</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Default value</term> + <listitem><para>3000000</para></listitem> + </varlistentry> + <varlistentry> + <term>Runtime readable/modifiable</term> + <listitem><para>Modifiable</para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The parameter uart_high_baud in cg2900_uart.c defines the baud rate to use for normal data transfer. + This should normally be the highest allowed by the system with regards to flow control, clocks, etc. + For ST-Ericsson controllers STLC2690 and CG2900 the following values are supported: + <itemizedlist> + <listitem><para>57600</para></listitem> + <listitem><para>115200</para></listitem> + <listitem><para>230400</para></listitem> + <listitem><para>460800</para></listitem> + <listitem><para>921600</para></listitem> + <listitem><para>2000000</para></listitem> + <listitem><para>3000000</para></listitem> + <listitem><para>4000000</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>uart_debug</term> + <listitem> + <para> + <variablelist> + <varlistentry> + <term>Parameter type</term> + <listitem><synopsis><type>int</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Default value</term> + <listitem><para>0</para></listitem> + </varlistentry> + <varlistentry> + <term>Runtime readable/modifiable</term> + <listitem><para>Modifiable</para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The parameter uart_debug in cg2900_uart.c enables or disables dumping of all + data transmitted and received through the UART. + 0 means disabled and non-zero value means enabled. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>bd_address</term> + <listitem> + <para> + <variablelist> + <varlistentry> + <term>Parameter type</term> + <listitem><synopsis><type>array (Entered as comma separated value)</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Default value</term> + <listitem><para>0x00 0x80 0xDE 0xAD 0xBE 0x00</para></listitem> + </varlistentry> + <varlistentry> + <term>Runtime readable/modifiable</term> + <listitem><para>Modifiable</para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The parameter bd_address in cg2900_core.c defines the Bluetooth device address to use for the current device. + The value is an array of 6 bytes and shall be entered as a comma separated value. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>sleep_timeout_ms</term> + <listitem> + <para> + <variablelist> + <varlistentry> + <term>Parameter type</term> + <listitem><synopsis><type>int</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Default value</term> + <listitem><para>10000</para></listitem> + </varlistentry> + <varlistentry> + <term>Runtime readable/modifiable</term> + <listitem><para>Modifiable</para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The parameter sleep_timeout_ms in cg2900_core.c defines the sleep timeout for data transmission in milliseconds. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + <!-- TODO: This guideline for this section may be extended + during the user-guide guidelines drop. --> + </para> + </section> + + <section id="driver-ioctl"> + <title>Driver IO Control</title> + <para> + <!-- TODO: Describe driver parameters that can be modified + in runtime. Make a list of all device-dependent request code with + description of arguments, meaning etc. If the driver has no IO control + interface, replace this text with "Not Applicable". --> + </para> + <variablelist> + <varlistentry> + <term><constant>CG2900_CHAR_DEV_IOCTL_RESET</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Set</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>int</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>CG2900_CHAR_DEV_IOCTL_RESET</constant> IOCTL starts a reset + of the connectivity chip. This will affect the current open channel and + all other open channels as well. + </para><para> + IOCTL value created using <constant>_IOW('U', 210, int)</constant>. + </para><para> + Returned values are: + <itemizedlist> + <listitem><para>If reset is performed without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>CG2900_CHAR_DEV_IOCTL_CHECK4RESET</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Query</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>int</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>CG2900_CHAR_DEV_IOCTL_CHECK4RESET</constant> IOCTL checks if a reset + has been performed on a device. + </para><para> + IOCTL value created using <constant>_IOR('U', 212, int)</constant>. + </para><para> + Returned values are: + <itemizedlist> + <listitem><para>If device is still open the IOCTL function will return 0.</para></listitem> + <listitem><para>If reset has occurred the IOCTL function will return 1.</para></listitem> + <listitem><para>If device has been closed the IOCTL function will return 2.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>CG2900_CHAR_DEV_IOCTL_GET_REVISION</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Query</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>struct cg2900_rev_data</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>CG2900_CHAR_DEV_IOCTL_GET_REVISION</constant> IOCTL returns the revision value + and the sub-version value of the local connectivity controller if such information is available. + </para><para> + IOCTL value created using <constant>_IOR('U', 213, struct cg2900_rev_data)</constant>. + </para><para> + Returned values are according to information that may be retrieved from chip manufacturer. + One example is ST-Ericsson CG2900 PG2.0 which have revision 0x0200 and sub-version 0x0000. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + </variablelist> + </section> + + <section id="driver-sysfs"> + <title>Driver Interaction with Sysfs</title> + <para> + <!-- TODO: Describe data available for read and write on the drivers + Sysfs entry. Specify where the entry for the device is located in + Sysfs such as <filename>/sys/devices/*</filename>, <filename>/sys/devices/*</filename> + , etc. + Specify the data types for the attributes. Specify if the + attributes are read-only or write-only. If the driver has no Sysfs + interface, replace this text with "Not Applicable". --> + Not Applicable + </para> + </section> + + <section id="driver-proc"> + <title>Driver Interaction using /proc filesystem</title> + <para> + Not Applicable + <!-- TODO: Describe data available for read and write on the drivers + /proc entry. Specify where the entry for the device is located. + Specify the data types for the attributes. Specify if the + attributes are read-only or writeonly. If the driver has no /proc + interface, replace this text with "Not Applicable". --> + </para> + </section> + + <section id="driver-other"> + <title>Other means for Driver Interaction</title> + <para> + <!-- TODO: Does the driver have any configurations files? Describe other means + for driver status access or configuration. If the driver has no other + means (besides the one in already described in this chapter), replace + this text with "Not Applicable". --> + Not Applicable + </para> + </section> + + <section id="driver-node"> + <title>Driver Node File</title> + <variablelist> + <varlistentry> + <term>CG2900 main device</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_driver0</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_driver represents the main parent node for all other character devices supplied in the ST-Ericsson CG2900 driver except for the Test device. It does not support any operations such as read or write.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>BT Command</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_bt_cmd</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_bt_cmd is the device for the HCI Bluetooth command channel.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>BT ACL</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_bt_acl</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_bt_acl is the device for the HCI Bluetooth ACL channel.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>BT Event</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_bt_evt</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_bt_evt is the device for the HCI Bluetooth event channel.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>FM Radio</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_fm_radio</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_fm_radio is the device for the HCI FM Radio channel.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>GNSS</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_gnss</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_gnss is the device for the HCI GNSS channel.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>Debug</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_debug</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_debug is the device for the HCI Debug channel.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>ST-Ericsson Tools</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_ste_tools</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_ste_tools is the device for the HCI ST-Ericsson tools channel.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>HCI Logger</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_hci_logger</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_hci_logger is the device for the HCI logger channel.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>Test stub</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_test</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <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> + </listitem> + </varlistentry> + + <varlistentry> + <term>BT Audio</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_bt_audio</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_bt_audio is the device for sending HCI BT Audio controll commands to the chip. </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>FM Audio</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_fm_audio</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_fm_audio is the device for sending HCI BT Audio controll commands to the chip.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>Core</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_core</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_core is a device for turn on/off the chip. NOTE other devices will also turn on/off the chip if needed.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>CG2900 Audio</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_audio</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The cg2900_audio is a device for testing the CG2900 Audio driver from User space. + It replicates the normal CG2900 Audio interface through <constant>write/read</constant> operations. + 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 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): + <itemizedlist> + <listitem><para>0x00000001 = CHAR_DEV_OP_CODE_SET_DAI_CONF</para></listitem> + <listitem><para>0x00000002 = CHAR_DEV_OP_CODE_GET_DAI_CONF</para></listitem> + <listitem><para>0x00000003 = CHAR_DEV_OP_CODE_CONFIGURE_ENDPOINT</para></listitem> + <listitem><para>0x00000004 = CHAR_DEV_OP_CODE_CONNECT_AND_START_STREAM</para></listitem> + <listitem><para>0x00000005 = CHAR_DEV_OP_CODE_STOP_STREAM</para></listitem> + </itemizedlist> + + The <constant>read</constant> command is used for the commands <constant>CHAR_DEV_OP_CODE_GET_DAI_CONF</constant> + and <constant>CHAR_DEV_OP_CODE_CONNECT_AND_START_STREAM</constant> if the corresponding commands are successful. + 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 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>. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>HCI Raw</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_hci_raw</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_hci_raw is the device for raw access to HCI interface.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + </variablelist> + </section> + + + </chapter> + + + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <!-- Do NOT change the chapter id or title! --> + <para> + <variablelist> + <varlistentry> + <term>Driver supports only one user per HCI channel.</term> + <listitem> + <para> + To simplify design and limitation as well as keeping the API simple and reliable, the driver only supports + one user per HCI channel. + <!-- TODO: Briefly describe the limitation, unless all + information is already present in the title. + Use full english sentences. + Repeat the varlistentry for each limitation. + If none are known, replace this varlistentry + with the one below. --> + <!-- TODO: This guideline for this chapter may be extended + during the user-guide guidelines drop. --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>HCI Raw channel requires exclusive access to chip.</term> + <listitem> + <para> + cg2900_hci_raw channel cannot be opened if there are any other channels already opened except hci_logger channel. + Also any other channels cannot be opened except hci_logger channel when cg2900_hci_raw is already opened. + This is to guarantee that different users won't interfere with each other and prevent flow control issues. + <!-- TODO: Briefly describe the limitation, unless all + information is already present in the title. + Use full english sentences. + Repeat the varlistentry for each limitation. + If none are known, replace this varlistentry + with the one below. --> + <!-- TODO: This guideline for this chapter may be extended + during the user-guide guidelines drop. --> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </chapter> + +<chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + List of public functions. + </para> + <!-- Do NOT change the chapter id or title! --> + <!-- TODO: Replace with link to appropriate headerfile(s). + One per row, ensure the + exclamation mark is on the first column! If no + appropriate header file exist describing a public interface, + replace the inclusion with a paragraph containing the text + "Not Applicable" --> + <section id="cg2900.h"> + <title>cg2900.h</title> +!Edrivers/staging/cg2900/mfd/cg2900_core.c +!Idrivers/staging/cg2900/include/cg2900.h + </section> + <section id="cg2900_audio.h"> + <title>cg2900_audio.h</title> +!Edrivers/staging/cg2900/mfd/cg2900_audio.c + </section> + +</chapter> + +<chapter id="internal-functions"> + <title>Internal Functions Provided</title> + <para> + List of internal functions. + </para> + <!-- Do NOT change the chapter id or title! --> + <!-- TODO: Replace with link to appropriate headerfile(s), + source file(s), or both. One per row, ensure the + exclamation mark is on the first column! If no + appropriate header or source file exist describing a public interface, + replace the inclusion with a paragraph containing the text + "Not Applicable"--> + <section id="cg2900_lib.h"> + <title>cg2900_lib.h</title> +!Edrivers/staging/cg2900/mfd/cg2900_lib.c + </section> +</chapter> +</book> diff --git a/Documentation/DocBook/cg2900_fm_radio.tmpl b/Documentation/DocBook/cg2900_fm_radio.tmpl new file mode 100644 index 00000000000..2cdbf146ff4 --- /dev/null +++ b/Documentation/DocBook/cg2900_fm_radio.tmpl @@ -0,0 +1,2025 @@ +<!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="STE-CG2900-fm-driver-template"> + <bookinfo> + <title>V4L FM Radio Driver for CG2900</title> + <authorgroup> + <author> + <firstname>Hemant</firstname> + <surname>Gupta</surname> + <affiliation> + <address> + <email>hemant.gupta@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + <copyright> + <year>2010</year> + <holder>ST-Ericsson</holder> + </copyright> + <subjectset> + <subject> + <subjectterm>Connectivity</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> + <!-- Do NOT change the chapter id or title! --> + <para> + This documentation describes the functions provided by the CG2900 FM Driver. + </para> + </chapter> + <chapter id="gettingstarted"> + <title>Getting Started</title> + <!-- Do NOT change the chapter id or title! --> + <para> + There are no special compilation flags needed to build the CG2900 + FM Driver. + </para> + <para> + There must be coeffecient and firmware files that match the used chip version inside the firmware folder. + The files: + <itemizedlist> + <listitem><para>cg2900_fm_bt_src_coeff_info.fw.org</para></listitem> + <listitem><para>cg2900_fm_ext_src_coeff_info.fw.org</para></listitem> + <listitem><para>cg2900_fm_fm_coeff_info.fw.org</para></listitem> + <listitem><para>cg2900_fm_fm_prog_info.fw.org</para></listitem> + </itemizedlist> + handle the mapping between chip version and correct firmware files (firmware and coeffecient files). + The necessary firmware and coeffecient files should be placed with the extension <constant>.fw.org</constant>. + Note that there is a limitation in the Kernel firmware system regarding name length of a file. + </para> + <section id="basic-tutorial"> + <title>Basic Tutorial</title> + <para> + To enable the CG2900 FM Driver using KConfig go to <constant>Device Drivers -> Multimedia devices </constant> + and enable the following: + <itemizedlist> + <listitem><para>Video For Linux</para></listitem> + <listitem><para>Enable Video For Linux API 1 compatible Layer</para></listitem> + <listitem><para>Radio Adapters</para></listitem> + <listitem><para>Radio Adapter -> ST-Ericsson CG2900 FM Radio support</para></listitem> + </itemizedlist> + Select the driver as built in kernel object. + </para> + </section> + </chapter> + <chapter id="concepts"> + <title>Concepts</title> + <!-- Do NOT change the chapter id or title! --> + <para> + The CG2900 FM driver acts as an interface between Video4Linux and CG2900-Protocol Driver. It configures the FM chip in FM Rx or FM Tx mode. It also sends the unformatted RDS data to the application for decoding while in FM rx mode and sends the formatted RDS data to FM Chip while in Tx mode. + </para> + <para> + <variablelist> + <varlistentry> + <term>FM Driver Working</term> + <listitem> + <para> + In order to send and receive data on an H:4 channel, the FM Driver opens the channel by registering with the CG2900 Protocol driver. After this the FM driver encapsulates the user operation into specific HCI comamnds and sends that data to the CG2900 Connectivity Controller and waits till the response for the previous command is received. FM Driver in this way maintains the flow control. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </chapter> + <chapter id="Tasks"> + <title>Tasks</title> + <!-- Do NOT change the chapter id or title! --> + <section id="Switching-On-FM"> + <title>Switch On FM</title> + <para> + FM specific tasks + </para> + <variablelist> + <varlistentry> + <term>Switching On FM</term> + <listitem> + <para> + For switching on FM the character device /dev/radio0 should be opened from user space. This sets the FM Radio in Idle mode. For configuring the FM Radio in Rx or Tx mode the IOCTL's VIDIOC_S_TUNER and VIDIOC_S_MODULATOR respectively. + <programlisting> + int fd; + fd = open("/dev/radio0", O_RDONLY); + if(fd < 0) { + printf("open:error!!!\n"); + goto err; + } + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="Switching-Off-FM"> + <title>Switch Off FM</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>Switching Off FM</term> + <listitem> + <para> + For switching OFF FM the character device /dev/radio0 should be closed from user space. + <programlisting> + if(fd >= 0) + close(fd); + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="Rx-Mode"> + <title>Switching To FM Rx Mode</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>Switching To FM Rx Mode</term> + <listitem> + <para> + For switching on FM Rx mode the IOCTL VIDIOC_S_TUNER should be called with appropriate parameters. + <programlisting> + memset(&tuner, 0, sizeof(tuner)); + tuner.index = 0; + tuner.rxsubchans |= V4L2_TUNER_SUB_STEREO; + if (ioctl(fd, VIDIOC_S_TUNER, &tuner) < 0) { + printf("VIDIOC_S_TUNER:error!!\n"); + return; + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="Tx-Mode"> + <title>Switching To FM Tx Mode</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>Switching To FM Tx Mode</term> + <listitem> + <para> + For switching on FM Tx mode the IOCTL VIDIOC_S_MODULATOR should be + called with appropriate parameters. + <programlisting> + memset(&modulator, 0, sizeof(modulator)); + modulator.index = 0; + modulator.txsubchans |= V4L2_TUNER_SUB_STEREO; + if (ioctl(fd, VIDIOC_S_MODULATOR, &modulator) < 0) { + printf("VIDIOC_S_MODULATOR:error!!\n"); + return; + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="FM-Standby"> + <title>Standby</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>Making the FM Radio go in Standby Mode</term> + <listitem> + <para> + For making the FM Radio go in Standby mode, the IOCTL VIDIOC_S_CTRL should be used. The id of the v4l2_control structure should be set to V4L2_CID_CG2900_RADIO_CHIP_STATE and the value of v4l2_control structure should be set as V4L2_CG2900_RADIO_STANDBY. + <programlisting> + struct v4l2_control sctrl; + int ret; + sctrl.id = V4L2_CID_CG2900_RADIO_CHIP_STATE; + sctrl.value = V4L2_CG2900_RADIO_STANDBY; + ret = ioctl(fd, VIDIOC_S_CTRL, &sctrl); + if (ret < 0) { + printf("VIDIOC_S_CTRL:error!!\n"); + } + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="Powerup-from-standby"> + <title>Powering Up FM From Standby Mode</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>Powering Up FM Radio from Standby Mode</term> + <listitem> + <para> + For powering up FM radio again from standby mode, the IOCTL VIDIOC_S_CTRL should be used. The id of the v4l2_control structure should be set to V4L2_CID_CG2900_RADIO_CHIP_STATE and the value of v4l2_control structure should be set as V4L2_CG2900_RADIO_POWERUP. + <programlisting> + struct v4l2_control sctrl; + int ret; + sctrl.id = V4L2_CID_CG2900_RADIO_CHIP_STATE; + sctrl.value = V4L2_CG2900_RADIO_POWERUP; + ret = ioctl(fd, VIDIOC_S_CTRL, &sctrl); + if (ret < 0) { + printf("VIDIOC_S_CTRL:error!!\n"); + } + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="tune-frequency"> + <title>Tune Channel</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>Tune to a particular station</term> + <listitem> + <para> + for tuning to a particular station, the IOCTL VIDIOC_S_FREQUENCY should be used. The frequency of the v4l2_frequency structure should be converted to V4L2 format. + <programlisting> + struct v4l2_frequency freq; + int ret; + /* Convert frequency in Hz to V4L2 Format */ + freq.frequency = (frequency * 2)/ 125; + ret = ioctl(fd, VIDIOC_S_FREQUENCY, &freq); + if (ret < 0) { + printf("VIDIOC_S_FREQUENCY:error!!\n"); + } + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="get-frequency"> + <title>Get Tuned Channel</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>Get the Currently tuned Station Frequncy</term> + <listitem> + <para> + for tuning to a particular station, the IOCTL VIDIOC_G_FREQUENCY should be used. The frequency returned in the v4l2_frequency structure would be in V4L2 format. + <programlisting> + struct v4l2_frequency freq; + int ret; + ret = ioctl(fd, VIDIOC_G_FREQUENCY, &freq); + if (ret < 0) { + printf("VIDIOC_G_FREQUENCY:error!!\n"); + *frequency = 0; + return; + } + /* Convert frequency to Hz from V4L2 Format */ + *frequency = (freq.frequency * 125)/2; + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="get-signal-strength"> + <title>Retreive Signal Strength</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>Retreive Signal Strength</term> + <listitem> + <para> + For retreiving the Signal strength of the currently tuned channel in FM Rx mode, IOCTL VIDIOC_G_TUNER should be called. The current signal strength would be represented by the parameter signal of the v4l2_tuner strucure. + <programlisting> + void get_signal_strength(int *rssi) + { + struct v4l2_tuner tuner; + int ret; + memset(&tuner, 0, sizeof(tuner)); + tuner.index = 0; + ret = ioctl(fd, VIDIOC_G_TUNER, &tuner); + if (ret < 0) { + printf("VIDIOC_G_TUNER:error!!\n"); + *rssi = 0; + return; + } + *rssi = tuner.signal; + } + </programlisting> +Note: Currently the retrieved signal strength is in decimals and not in "dBuV", proper external conversion required. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="band-scan"> + <title>Band Scan</title> + <para> + <!-- Driver loading Parameters:Not Applicable --> + </para> + <variablelist> + <varlistentry> + <term>Band Scan</term> + <listitem> + <para> + For doing a band scan, ie search for all available stations in the entire FM band, IOCTL VIDIOC_S_CTRL should be used with parameter id of the v4l2_control structure should be set to V4L2_CID_CG2900_RADIO_BANDSCAN and the value of v4l2_control structure should be set as V4L2_CG2900_RADIO_BANDSCAN_START. If the IOCTL returns successfully, a common thread (which should have been created at the start of the application and is already polling to FM driver for multiple other interrupts including events related to Block Scan and Search Frequency operation) which polls with an infinite timeout iteratively until the end of the user-space application, when poll in one iteration is complete. When poll is complete, thread will make an IOCTL call with VIDIOC_G_EXT_CTRLS with parameter id set to V4L2_CID_CG2900_RADIO_GET_INTERRUPT and the data structure FmInterrupt.controls->string associated with V4L2_CID_CG2900_RADIO_GET_INTERRUPT shall contain the interrupt retrieved from FMD. Interrupts received in this manner from FMD can be any of the following. + <itemizedlist> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_UNKNOWN</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_SEARCH_COMPLETED</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_BAND_SCAN_COMPLETED</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_BLOCK_SCAN_COMPLETED</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_SCAN_CANCELLED</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_MONO_STEREO_TRANSITION</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_DEVICE_RESET</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_RDS_RECEIVED</para></listitem> + </itemizedlist> + +For Band Scan it shall be V4L2_CG2900_RADIO_INTERRUPT_BAND_SCAN_COMPLETE, an appropriate handler should be then called from thethread to retrieve the found stations along with RSSI using the IOCTL VIDIOC_G_EXT_CTRLS, this IOCTL should be used with parameters as described in example code. Note that the common thread for capturing synchronous as well asynchronous events used here is FmInterruptMonitoringThread. It shall be used in other sections i.e. Block Scan, Cancel Scan, Search Frequency and Mono Stereo Transition. + <programlisting> + void Band_Scan() + { + struct v4l2_control sctrl + int ret; + sctrl.id = V4L2_CID_CG2900_RADIO_BANDSCAN; + sctrl.value = V4L2_CG2900_RADIO_BANDSCAN_START; + ret = ioctl(fd, VIDIOC_S_CTRL, &sctrl); + if (ret < 0) { + printf("VIDIOC_S_CTRL:error!!\n"); + } + pthread_create(&fmScanThread, NULL, FmScanThread, NULL); + } + + static void *FmInterruptMonitoringThread(void *param) + { + struct v4l2_ext_controls FmInterrupt; + struct pollfd pollFd; + long * p = NULL; + int index, ret, count = 0; + int interrupt, interrupt_reason; + int err; + + while(closeApp) { + pollFd.fd = fd; + pollFd.events = POLLRDNORM; + /* wait infinitely for interrupt */ + timeout = -1; + ret = poll(&pollFd, 1, timeout); + if(!closeApp) + break; + if(ret) { + if(pollFd.revents & POLLRDNORM) + { + /* Get the interrupt */ + FmInterrupt.count = 0; + FmInterrupt.ctrl_class = V4L2_CTRL_CLASS_USER; + FmInterrupt.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + if(!FmInterrupt.controls) + goto error; + FmInterrupt.controls->id = V4L2_CID_CG2900_RADIO_GET_INTERRUPT; + FmInterrupt.controls->size = 2; + FmInterrupt.controls->string = (int *)malloc(sizeof(int) * FmInterrupt.controls->size); + interrupt_buffer_pointer = FmInterrupt.controls->string; + if (ioctl(fd, VIDIOC_G_EXT_CTRLS, &FmInterrupt) < 0) { + printf("VIDIOC_G_EXT_CTRLS:error!!\n"); + ret_val = -1; + goto error_free_ext_control_string; + } + + if(!ret_val) { + interrupt = *interrupt_buffer_pointer; + interrupt_reason = *(interrupt_buffer_pointer + 1); + printf("Interrupt = %d, , Result = %d\n", interrupt, interrupt_reason); + if(interrupt_reason == 0) { + switch(interrupt) + { + case V4L2_CG2900_RADIO_INTERRUPT_BAND_SCAN_COMPLETED: + /* Band Scan Completed */ + HandleBandScanCompletion(); + otherOperationInProgress = 0; + break; + + } + } + } +error_free_ext_control_string: + free(FmInterrupt.controls->string); +error_free_ext_control_control: + free(FmInterrupt.controls); +error: + otherOperationInProgress = 0; + } else { + printf ("FmInterruptMonitoringThread : poll returned = %d\n", ret); + } + } + } + return 0; + } + + static void HandleBandScanCompletion() + { + struct v4l2_ext_controls scanResult; + long * band_scan_pointer = NULL; + int err; + int index, ret, count = 0; + + /* Get the Number Of Channels */ + scanResult.count = 0; + scanResult.ctrl_class = V4L2_CTRL_CLASS_USER; + scanResult.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + if(!scanResult.controls) + goto done; + scanResult.controls->id = V4L2_CID_CG2900_RADIO_BANDSCAN_GET_RESULTS; + scanResult.controls->size = 0; + scanResult.controls->string = NULL; + err = ioctl(fd, VIDIOC_G_EXT_CTRLS, & scanResult); + + if (err < 0 & & errno != ENOSPC) { + printf("VIDIOC_G_EXT_CTRLS:error!!\n"); + goto error_free_ext_control_control; + } + + if(scanResult.controls->size > 0 ) + { + scanResult.controls->string = (long *)malloc(sizeof(long) * 2 * scanResult.controls->size ); + band_scan_pointer = scanResult.controls->string; + printf("\n\n\n==================================\n"); + printf("\nNumber of Channels Found = %d \n", scanResult.controls->size); + printf("\n==================================\n"); + if (ioctl(fd, VIDIOC_G_EXT_CTRLS, &scanResult) < 0) { + printf("VIDIOC_G_EXT_CTRLS:error!!\n"); + goto error_free_ext_control_string; + } + printf("\n================================\n"); + printf("\nSNo. Frequency(MHz) RSSI\n"); + printf("\n================================\n"); + for (index = 0, count = 0; index < scanResult.controls->size; index ++, count +=2) { + printf("%d %d.%d %d\n", index + 1, + MEGAHRTZ((*(band_scan_pointer +count + 0) * 125) / 2), + *(band_scan_pointer + count + 1)); + } + printf("\n================================\n"); + error_free_ext_control_string: + free(band_scan_pointer); + } + else if(scanResult.controls->size == 0) + { + printf("\nNo channels found during scanning!!\n"); + } + error_free_ext_control_control: + free(scanResult.controls); + done: + otherOperationInProgress = 0; + } + + </programlisting> + Note: Currently the retrieved signal strength is in decimals and not in "dBuV", proper external conversion required. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="block-scan"> + <title>Block Scan</title> + <para> + <!-- Driver loading Parameters:Not Applicable --> + </para> + <variablelist> + <varlistentry> + <term>Block Scan</term> + <listitem> + <para> + The Block Scan functionality will take two inputs, start and stop frequency (V4L2 compliance) and enables the host to scan all channels with in that range for RSSI values. The measured channels will be stored in a list in order of channel number and the block scan feature to identify "empty" channels for transmission. And for doing a block scan, IOCTL VIDIOC_S_EXT_CTRL with parameter id of the v4l2_control structure should be set to V4L2_CID_FM_RADIO_BLOCKSCAN_START. If the IOCTL returns successfully, a common thread (which should have been created at the start of the application and is already polling to FM driver for multiple other interrupts including events related to Band Scan and Search Frequency operation) which polls with an infinite timeout iteratively until the end of the user-space application, when poll in one iteration is complete. When poll is complete, thread will make an IOCTL call with VIDIOC_G_EXT_CTRLS with parameter id set to V4L2_CID_CG2900_RADIO_GET_INTERRUPT and the data structure FmInterrupt.controls->string associated with V4L2_CID_CG2900_RADIO_GET_INTERRUPT shall contain the interrupt retrieved from FMD. Interrupts received in this manner from FMD can be any of the following. + <itemizedlist> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_UNKNOWN</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_SEARCH_COMPLETED</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_BAND_SCAN_COMPLETED</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_BLOCK_SCAN_COMPLETED</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_SCAN_CANCELLED</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_MONO_STEREO_TRANSITION</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_DEVICE_RESET</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_INTERRUPT_RDS_RECEIVED</para></listitem> + </itemizedlist> + +For Block Scan it shall be V4L2_CG2900_RADIO_INTERRUPT_BLOCK_SCAN_COMPLETED, an appropriate handler should be then called from thethread to retrieve the found stations along with RSSI using the IOCTL VIDIOC_G_EXT_CTRLS, this IOCTL should be used with parameters as described in example code. Note that the common thread for capturing synchronous as well asynchronous events used here is FmInterruptMonitoringThread. It shall be used in other sections i.e. Band Scan, Cancel Scan, Search Frequency and Mono Stereo Transition. When poll is complete, the found stations along with RSSI should be retrieved using the IOCTL VIDIOC_G_EXT_CTRLS should be used with parameters as described in example code. + <programlisting> + void Block_Scan() + { + struct v4l2_ext_controls ext_ctrl; + long *p = NULL; + int index; + int ret_val; + if(1 == mode) { + otherOperationInProgress = 1; + ext_ctrl.ctrl_class = V4L2_CTRL_CLASS_USER; + ext_ctrl.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + ext_ctrl.count = 0; + ext_ctrl.controls->id = V4L2_CID_CG2900_RADIO_BLOCKSCAN_START; + ext_ctrl.controls->size = 2; + ext_ctrl.controls->string = (long *)malloc(sizeof(long) * ext_ctrl.controls->size); + p = ext_ctrl.controls->string; + *p = (StartFreq * 2)/ 125; + *(p + 1) = (EndFreq * 2)/ 125;; + if (ioctl(fd, VIDIOC_S_EXT_CTRLS, &ext_ctrl) < 0) + printf("APP_BlockScanStart:VIDIOC_S_EXT_CTRLS:error!!\n"); + free(ext_ctrl.controls->string); + free(ext_ctrl.controls); + pthread_create(&fmBlockScanThread, NULL, FmBlockScanThread, NULL); + } + + static void *FmInterruptMonitoringThread(void *param) + { + struct v4l2_ext_controls FmInterrupt; + struct pollfd pollFd; + long * p = NULL; + int index, ret, count = 0; + int interrupt, interrupt_reason; + int err; + + while(closeApp) { + pollFd.fd = fd; + pollFd.events = POLLRDNORM; + /* wait infinitely for interrupt */ + timeout = -1; + ret = poll(&pollFd, 1, timeout); + if(!closeApp) + break; + if(ret) { + if(pollFd.revents & POLLRDNORM) + { + /* Get the interrupt */ + FmInterrupt.count = 0; + FmInterrupt.ctrl_class = V4L2_CTRL_CLASS_USER; + FmInterrupt.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + if(!FmInterrupt.controls) + goto error; + FmInterrupt.controls->id = V4L2_CID_CG2900_RADIO_GET_INTERRUPT; + FmInterrupt.controls->size = 2; + FmInterrupt.controls->string = (int *)malloc(sizeof(int) * FmInterrupt.controls->size); + interrupt_buffer_pointer = FmInterrupt.controls->string; + if (ioctl(fd, VIDIOC_G_EXT_CTRLS, &FmInterrupt) < 0) { + printf("VIDIOC_G_EXT_CTRLS:error!!\n"); + ret_val = -1; + goto error_free_ext_control_string; + } + + if(!ret_val) { + interrupt = *interrupt_buffer_pointer; + interrupt_reason = *(interrupt_buffer_pointer + 1); + printf("Interrupt = %d, , Result = %d\n", interrupt, interrupt_reason); + if(interrupt_reason == 0) { + switch(interrupt) + { + case V4L2_CG2900_RADIO_INTERRUPT_BLOCK_SCAN_COMPLETED: + /* Block Scan Completed */ + HandleBlockScanCompletion(); + otherOperationInProgress = 0; + break; + } + } + } +error_free_ext_control_string: + free(FmInterrupt.controls->string); +error_free_ext_control_control: + free(FmInterrupt.controls); +error: + otherOperationInProgress = 0; + } else { + printf ("FmInterruptMonitoringThread : poll returned = %d\n", ret); + } + } + } + return 0; + } + + static void HandleBlockScanCompletion() + { + struct v4l2_ext_controls blockscanResult; + long * block_scan_pointer = NULL; + int index, ret; + int err; + int current_grid = -1; + FILE *fp; + long start_freq = StartFreq; + long next_freq_offset = 0; + + fp = fopen("/sys/module/radio_cg2900/parameters/grid", "r"); + if(fp != NULL) + { + /* Retrieve the currently set grid to determine the next channel is 50 Khz, 100 Khz or 200 Khz apart */ + fscanf(fp, "%d", &current_grid); + fclose(fp); + } + + if(current_grid == 0) { + next_freq_offset = 50000; + } else if (current_grid == 1) { + next_freq_offset = 100000; + } else if (current_grid == 2) { + next_freq_offset = 200000; + } + + /* Get the Number Of Channels */ + blockscanResult.count = 0; + blockscanResult.ctrl_class = V4L2_CTRL_CLASS_USER; + blockscanResult.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + if(!blockscanResult.controls) + goto done; + blockscanResult.controls->id = V4L2_CID_CG2900_RADIO_BLOCKSCAN_GET_RESULTS; + blockscanResult.controls->size = 0; + + blockscanResult.controls->string = NULL; + err = ioctl(fd, VIDIOC_G_EXT_CTRLS, &blockscanResult); + + if (err < 0 && errno != ENOSPC) { + printf("VIDIOC_G_EXT_CTRLS:error!!\n"); + goto error_free_ext_control_control; + } + + if(blockscanResult.controls->size > 0) + { + blockscanResult.controls->string = (long *)malloc(sizeof(long) * blockscanResult.controls->size ); + block_scan_pointer = blockscanResult.controls->string; + if (ioctl(fd, VIDIOC_G_EXT_CTRLS, &blockscanResult) < 0) { + printf("VIDIOC_G_EXT_CTRLS:error!!\n"); + goto error_free_ext_control_string; + } + printf("\n================================\n"); + printf("\nMHz. RSSI\n"); + printf("\n================================\n"); + for (index = 0; index < blockscanResult.controls->size; index ++) { + printf("%d.%d %d\n", MEGAHRTZ(start_freq), *(block_scan_pointer + index)); + start_freq += next_freq_offset; + } + printf("\n================================\n"); + error_free_ext_control_string: + free(block_scan_pointer); + } + else if(blockscanResult.controls->size == 0) + { + printf("\nNo channels found during Block Scan!!\n"); + } + error_free_ext_control_control: + free(blockscanResult.controls); + done: + otherOperationInProgress = 0; + } + + + </programlisting> + Note: Currently the retrieved signal strength is in decimals and not in "dBuV", proper external conversion required. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="cancel-scan-seek"> + <title>Cancel Scan</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>Cancel Scan/Seek</term> + <listitem> + <para> + This is used for stopping an active Band Scan, Seek operation and Block Scan. IOCTL VIDIOC_S_CTRL should be used with parameter id of the v4l2_control structure. For Eg incase of Band scan the parameter id should be set to V4L2_CID_CG2900_RADIO_BANDSCAN and the value of v4l2_control structure should be set as V4L2_CG2900_RADIO_BANDSCAN_STOP. The example thread shown in following code snippet FmInterruptMonitoringThread shall have already been started as mentioned in Band Scan and Block sections, it shall receive an asynchronous event V4L2_CG2900_RADIO_INTERRUPT_SCAN_CANCELLED. + <programlisting> + struct v4l2_control sctrl; + int ret; + sctrl.id = V4L2_CID_CG2900_RADIO_BANDSCAN; + sctrl.value = V4L2_CG2900_RADIO_BANDSCAN_STOP; + ret = ioctl(fd, VIDIOC_S_CTRL, &sctrl); + if (ret < 0) { + printf("VIDIOC_S_CTRL:error!!\n"); + } + + static void *FmInterruptMonitoringThread(void *param) + { + struct v4l2_ext_controls FmInterrupt; + struct pollfd pollFd; + long * p = NULL; + int index, ret, count = 0; + int interrupt, interrupt_reason; + int err; + + while(closeApp) { + pollFd.fd = fd; + pollFd.events = POLLRDNORM; + /* wait infinitely for interrupt */ + timeout = -1; + ret = poll(&pollFd, 1, timeout); + if(!closeApp) + break; + if(ret) { + if(pollFd.revents & POLLRDNORM) + { + /* Get the interrupt */ + FmInterrupt.count = 0; + FmInterrupt.ctrl_class = V4L2_CTRL_CLASS_USER; + FmInterrupt.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + if(!FmInterrupt.controls) + goto error; + FmInterrupt.controls->id = V4L2_CID_CG2900_RADIO_GET_INTERRUPT; + FmInterrupt.controls->size = 2; + FmInterrupt.controls->string = (int *)malloc(sizeof(int) * FmInterrupt.controls->size); + interrupt_buffer_pointer = FmInterrupt.controls->string; + if (ioctl(fd, VIDIOC_G_EXT_CTRLS, &FmInterrupt) < 0) { + printf("VIDIOC_G_EXT_CTRLS:error!!\n"); + ret_val = -1; + goto error_free_ext_control_string; + } + + if(!ret_val) { + interrupt = *interrupt_buffer_pointer; + interrupt_reason = *(interrupt_buffer_pointer + 1); + printf("Interrupt = %d, , Result = %d\n", interrupt, interrupt_reason); + if(interrupt_reason == 0) { + switch(interrupt) + { + case V4L2_CG2900_RADIO_INTERRUPT_SCAN_CANCELLED: + /* Scan/Search/Block Scan Cancelled */ + printf(" Scan cancelled by user\n"); + otherOperationInProgress = 0; + break; + } + } + } +error_free_ext_control_string: + free(FmInterrupt.controls->string); +error_free_ext_control_control: + free(FmInterrupt.controls); +error: + otherOperationInProgress = 0; + } else { + printf ("FmInterruptMonitoringThread : poll returned = %d\n", ret); + } + } + } + return 0; + } + + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="rds-receive"> + <title>RDS Receive</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>RDS Receive</term> + <listitem> + <para> + For enabling/disabling RDS for FM Rx, IOCTL VIDIOC_S_TUNER should be used with parameter rxsubchans of the v4l2_tuner structure set to V4L2_TUNER_SUB_RDS if rds needs to be enabled and the same value must not be set in case rds is to be disabled. Once RDS data is available, the appplication would be signalled waiting on poll. If the Interrupt retrieved using V4L2_CID_CG2900_RADIO_GET_INTERRUPT is V4L2_CG2900_RADIO_INTERRUPT_RDS_RECEIVED, RDS data can be retrieved using the read() functionality from the CG2900 FM driver. The RDS data received from FM Driver should be parsed in user space to retrive RDS information i.e Radio Text, Program Service Name, Program Identification, Program Type, Alternate Frequency, etc. + <programlisting> + void rds_rx_set(bool enable_rds) + { + struct v4l2_tuner tuner; + int ret; + memset(&tuner, 0, sizeof(tuner)); + tuner.index = 0; + if(enable_rds) + tuner.rxsubchans |= V4L2_TUNER_SUB_RDS; + else + tuner.rxsubchans & = ~V4L2_TUNER_SUB_RDS; + ret = ioctl(fd, VIDIOC_S_TUNER, &tuner); + if (ret < 0) { + printf("VIDIOC_S_TUNER:error!!\n"); + } + } + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="af-update_switch"> + <title>AF Update and Switching</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>AF Update & Switching</term> + <listitem> + <para>Alternate Frequency (AF) Handling needs to be done in user space.</para> + <para>The application should use the AF RDS group data to compose a list of AFs when tuned to a new channel.</para> + <para>When the reception of the currently tuned frequency falls below a set threshold, it can decide to switch to one of the alternative frequencies for this channel. + </para> + <para>The application can perform an AF Update, which returns the RSSI value for all or some of the channel's AFs. Thus allowing the hardware to switch to the AF with the highest RSSI. The AF Update could be designed to stop as soon as it finds an AF with an acceptable RSSI level. In the event that all the AF RSSI values are lower than the base channel, the AF Switch would not be necessary. + </para> + <para>To know the RSSI of the alternative frequencies (V4L2 compliance), the application can use the IOCTL VIDIOC_S_CTRL with parameter id set to V4L2_CID_CG2900_RADIO_RDS_AF_UPDATE_START, and the parameter value be set as the frequency in Hz for a channel from the AF List. If this call returns successfully, the RSSI of the frequency can then be retrieved. Using IOCTL VIDIOC_G_CTRL, with the parameter id set to V4L2_CID_CG2900_RADIO_RDS_AF_UPDATE_GET_RESULT, and the output parameter value will contain the RSSI of the AF frequency. + </para> + <para>If it is still deemed necessary to switch channels, the next step is then to switch to an alternative frequency in the AF list. This can be done using the IOCTL VIDIOC_S_EXT_CTRLS, with: + </para> + <itemizedlist> + <listitem><para>Parameter id set to V4L2_CID_CG2900_RADIO_RDS_AF_SWITCH_START</para></listitem> + <listitem><para>Parameter size set to 2</para></listitem> + <listitem><para>Parameters filled as below (string field of the parameter) </para></listitem> + <listitem><para>Control class parameter set to V4L2_CTRL_CLASS_USER</para></listitem> + <listitem><para>The AF switch frequency in Hz</para></listitem> + <listitem><para>Expected PI code </para></listitem> + </itemizedlist> + <para>The application can check if the AF switch succeeded or not using the IOCTL VIDIOC_G_CTRL, with parameter id set to V4L2_CID_CG2900_RADIO_RDS_AF_SWITCH_GET_RESULT, and the output parameter value will contain the AF switch conclusion. + </para> + <para> The example code below illustrates both the aforementioned functionalities.</para> + <para> + <programlisting> + void PerformAFUpdate(long AF_Frequency, int *AF_Rssi) + { + struct v4l2_control sctrl, gctrl; + int ret; + sctrl.id = V4L2_CID_CG2900_RADIO_RDS_AF_UPDATE_START; + sctrl.value = AF_Frequency; + ret = ioctl(fd, VIDIOC_S_CTRL, & sctrl); + if (ret < 0) { + printf("VIDIOC_S_CTRL:error!!\n"); + } + gctrl.id = V4L2_CID_CG2900_RADIO_RDS_AF_UPDATE_GET_RESULT; + ret = ioctl(fd, VIDIOC_G_CTRL, & gctrl); + if (ret < 0) { + printf("VIDIOC_G_CTRL:error!!\n"); + } + *AF_Rssi = gctrl.value; + } + void PerformAFSwitch(long AF_BestFrequency, int AF_ExpectedPI, int *AF_SwitchConclusion) + { + struct v4l2_control gctrl; + struct v4l2_ext_controls ext_ctrl; + int ret; + int conclusion; + long freq; + long *p = NULL; + ext_ctrl.ctrl_class = V4L2_CTRL_CLASS_USER; + ext_ctrl.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + ext_ctrl.count = 0; + ext_ctrl.controls->id = V4L2_CID_CG2900_RADIO_RDS_AF_SWITCH_START; + ext_ctrl.controls->size = 2; + ext_ctrl.controls->string = (long *)malloc(sizeof(long) * ext_ctrl.controls->size); + p = ext_ctrl.controls->string; + *p = (AF_BestFrequency * 2)/ 125; + *(p+1) = (long)AF_ExpectedPI; + ret = ioctl(fd, VIDIOC_S_EXT_CTRLS, & ext_ctrl); + if (ret < 0) { + printf("VIDIOC_S_EXT_CTRLS:error!!\n"); + } + free(ext_ctrl.controls->string); + free(ext_ctrl.controls); + gctrl.id = V4L2_CID_CG2900_RADIO_RDS_AF_SWITCH_GET_RESULT; + ret = ioctl(fd, VIDIOC_G_CTRL, & gctrl); + if (ret < 0) { + printf("VIDIOC_G_CTRL:error!!\n"); + } + *AF_SwitchConclusion = gctrl.value; + } + </programlisting> + Note: For V4L2_CID_CG2900_RADIO_RDS_AF_SWITCH_GET_RESULT returned values are: + <itemizedlist> + <listitem><para> -1 AF Switch failed, the AF-RSSI was too low.</para></listitem> + <listitem><para> -2 AF Switch failed, the AF-PI Doesn't correlate.</para></listitem> + <listitem><para> -3 AF Switch failed, the AF-RDS SYNC Lost.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="rds-transmit"> + <title>RDS Transmit</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>RDS Transmit</term> + <listitem> + <para> + For enabling/disabling RDS for FM Tx, IOCTL VIDIOC_S_MODULATOR should be used with parameter txsubchans of the v4l2_modulator structure set to V4L2_TUNER_SUB_RDS if rds needs to be enabled and the same value must not be set in case rds is to be disabled. For Trasmitting RDS Data like PI, PTY, PSN, RT, VIDIOC_S_EXT_CTRLS IOCTL should be used with the id set to V4L2_CID_RDS_TX_PI, V4L2_CID_RDS_TX_PTY, V4L2_CID_RDS_TX_PS_NAME and V4L2_CID_RDS_TX_RADIO_TEXT respectively. Below example shows how to transmit various RDS functionalities. + <programlisting> + void rds_tx_set(bool enable_rds) + { + struct v4l2_modulator modulator; + int ret; + memset(&modulator, 0, sizeof(modulator)); + modulator.index = 0; + if(enable_rds) + modulator.txsubchans |= V4L2_TUNER_SUB_RDS; + else + modulator.txsubchans & = ~V4L2_TUNER_SUB_RDS; + ret = ioctl(fd, VIDIOC_S_MODULATOR, & modulator); + if (ret < 0) { + printf("VIDIOC_S_MODULATOR:error!!\n"); + } + } + void rds_tx_PI(void *value) + { + struct v4l2_ext_controls ext_ctrl; + int ret; + unsigned short *pi_code = (unsigned short *)value; + ext_ctrl.ctrl_class = V4L2_CTRL_CLASS_FM_TX; + ext_ctrl.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + ext_ctrl.count = 0; + ext_ctrl.controls->id = V4L2_CID_RDS_TX_PI; + ext_ctrl.controls->size = 0; + ext_ctrl.controls->string = NULL; + ext_ctrl.controls->value = *pi_code; + ret = ioctl(fd, VIDIOC_S_EXT_CTRLS, & ext_ctrl); + if (ret < 0) { + printf("VIDIOC_S_EXT_CTRLS:error!!\n"); + } + free(ext_ctrl.controls); + } + void rds_tx_PTY(void *value) + { + struct v4l2_ext_controls ext_ctrl; + int ret; + unsigned short *pty_code = (unsigned short *)value; + ext_ctrl.ctrl_class = V4L2_CTRL_CLASS_FM_TX; + ext_ctrl.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + ext_ctrl.count = 0; + ext_ctrl.controls->id = V4L2_CID_RDS_TX_PTY; + ext_ctrl.controls->size = 0; + ext_ctrl.controls->string = NULL; + ext_ctrl.controls->value = *pty_code; + ret = ioctl(fd, VIDIOC_S_EXT_CTRLS, & ext_ctrl); + if (ret < 0) { + printf("VIDIOC_S_EXT_CTRLS:error!!\n"); + } + free(ext_ctrl.controls); + } + void rds_tx_PSN(void *value) + { + struct v4l2_ext_controls ext_ctrl; + int ret; + char *psn = (char *)value; + ext_ctrl.ctrl_class = V4L2_CTRL_CLASS_FM_TX; + ext_ctrl.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + ext_ctrl.count = 0; + ext_ctrl.controls->id = V4L2_CID_RDS_TX_PS_NAME; + ext_ctrl.controls->size = strlen(psn); + ext_ctrl.controls->value = 0; + ext_ctrl.controls->string = (char *)malloc(ext_ctrl.controls->size); + memcpy(ext_ctrl.controls->string, psn, ext_ctrl.controls->size); + ret = ioctl(fd, VIDIOC_S_EXT_CTRLS, & ext_ctrl); + if (ret < 0) { + printf("VIDIOC_S_EXT_CTRLS:error!!\n"); + } + free(ext_ctrl.controls->string); + free(ext_ctrl.controls); + } + void rds_tx_RT(void *value) + { + struct v4l2_ext_controls ext_ctrl; + int ret; + char *radio_text = (char *)value; + ext_ctrl.ctrl_class = V4L2_CTRL_CLASS_FM_TX; + ext_ctrl.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + ext_ctrl.count = 0; + ext_ctrl.controls->id = V4L2_CID_RDS_TX_RADIO_TEXT; + ext_ctrl.controls->size = strlen(radio_text); + ext_ctrl.controls->value = 0; + ext_ctrl.controls->string = (char *)malloc(ext_ctrl.controls->size); + memcpy(ext_ctrl.controls->string, radio_text, ext_ctrl.controls->size); + ret = ioctl(fd, VIDIOC_S_EXT_CTRLS, & ext_ctrl); + if (ret < 0) { + printf("VIDIOC_S_EXT_CTRLS:error!!\n"); + } + free(ext_ctrl.controls->string); + free(ext_ctrl.controls); + } + </programlisting> + Note: RDS default parameters + <itemizedlist> + <listitem><para>Programme Identification code[PI]: Default value -> 0x1234</para></listitem> + <listitem><para>Programme Type[PTY]: Default value -> OTHER_MUSIC</para></listitem> + <listitem><para>Music/Speech switch[M/S]: Default value -> Music</para></listitem> + <listitem><para>Programme Service name[PS]: Default value -> FM Xmit</para></listitem> + <listitem><para>Radio text[RT]: Default value -> Default Radio Text</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="internal-test-tone-generator"> + <title>Test Tone Generation</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>1. Enabling-Disabling test tone</term> + <listitem> + <para> + 1. For setting the test tone status, application should use IOCTL VIDIOC_S_CTRL with its parameter id set to V4L2_CID_CG2900_RADIO_TEST_TONE_GENERATOR_SET_STATUS and parameter value set to any of the following : + <itemizedlist> + <listitem><para>Turn off test tone - use V4L2_CG2900_RADIO_TEST_TONE_GEN_OFF</para></listitem> + <listitem><para>Turn on test tone - use V4L2_CG2900_RADIO_TEST_TONE_GEN_ON_WO_SRC</para></listitem> + <listitem><para>Turn on with sample rate correction - use V4L2_CG2900_RADIO_TEST_TONE_GEN_ON_W_SRC</para></listitem> + </itemizedlist> + <programlisting> + void SetTestToneStatus(int state) + { + struct v4l2_control sctrl; + int ret; + sctrl.id = V4L2_CID_CG2900_RADIO_TEST_TONE_GENERATOR_SET_STATUS; + sctrl.value = state; + ret = ioctl(fd, VIDIOC_S_CTRL, & sctrl); + if (ret < 0) { + printf("VIDIOC_S_CTRL:error!!\n"); + } + } + </programlisting> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>2. Test Tone Connect</term> + <listitem> + <para> + 2. The internal test tone can be used following modes: FMR (receiver mode) and FMT (transmitter mode). Each of the waves, or the sum of them, can be used as audio source for the receiver audio outputs, or for the transmitter audio input. This can be done by means of command "Test Tone Connect". For the receiver, all available audio outputs will be connected to the tone generator. After switching FM to another mode, the command "Test Tone Connect" must be executed again to set up a connection in the new mode. + </para> + + <para> + The IOCTL VIDIOC_S_EXT_CTRLS is used to perform Test Tone Connect operation, with following parameters: + </para> + <itemizedlist> + <listitem><para>Parameter id set to V4L2_CID_CG2900_RADIO_TEST_TONE_CONNECT</para></listitem> + <listitem><para>Parameter size set to 2</para></listitem> + <listitem><para>Control class parameter set to V4L2_CTRL_CLASS_USER</para></listitem> + <listitem><para>Parameters value filled as below in code snippet(string field of the parameter) </para></listitem> + <listitem><para>First byte of Parameter value shall contain connect parameter for left audio output </para></listitem> + <listitem><para>Second byte of Parameter value shall contain connect parameter forright audio output </para></listitem> + </itemizedlist> + + <para> + Value of either of Parameter values (for left or right audio outputs)can assume values: + </para> + <itemizedlist> + <listitem><para>V4L2_CG2900_RADIO_TEST_TONE_NORMAL_AUDIO - Normal Audio</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_TEST_TONE_ZERO - Zero</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_TEST_TONE_TONE_1 - Tone_1</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_TEST_TONE_TONE_2 - Tone_2</para></listitem> + <listitem><para>V4L2_CG2900_RADIO_TEST_TONE_TONE_SUM - Tone_Sum</para></listitem> + </itemizedlist> + + <programlisting> + void TestToneConnect(u8 left_audio_mode, u8 right_audio_mode) + { + u8 *test_tone_connect_ptr = NULL; + ext_ctrl.ctrl_class = V4L2_CTRL_CLASS_USER; + ext_ctrl.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + ext_ctrl.count = 0; + ext_ctrl.controls->id = V4L2_CID_CG2900_RADIO_TEST_TONE_CONNECT; + ext_ctrl.controls->size = 2; + ext_ctrl.controls->string = (u8 *)malloc(sizeof(u8) * ext_ctrl.controls->size); + test_tone_connect_ptr = ext_ctrl.controls->string; + *(test_tone_connect_ptr) = left_audio_mode; + *(test_tone_connect_ptr + 1) = right_audio_mode; + + ret = ioctl(fd, VIDIOC_S_EXT_CTRLS, & ext_ctrl); + if (ret < 0) { + printf("VIDIOC_S_EXT_CTRL:error!!\n"); + } + } + </programlisting> + + </listitem> + </varlistentry> + + <varlistentry> + <term>3. Test Tone Set Parameters</term> + <listitem> + <para> + 3. The tone generator is capable of generating two different sine waves with adjustable offset, amplitude, phase offset and frequency. These properties can be changed with command "Test Tone Set Params" + </para> + + <para> + The IOCTL VIDIOC_S_EXT_CTRLS is used to perform Test Tone Set Parameters operation, with following parameters: + </para> + <itemizedlist> + <listitem><para>Parameter id set to V4L2_CID_CG2900_RADIO_TEST_TONE_SET_PARAMS</para></listitem> + <listitem><para>Parameter size set to 6</para></listitem> + <listitem><para>Control class parameter set to V4L2_CTRL_CLASS_USER</para></listitem> + <listitem><para>Parameters value filled as below in code snippet(string field of the parameter) </para></listitem> + <listitem><para>First word of Parameter value shall contain tone_gen (0: tone_1, 1:tone_2)</para></listitem> + <listitem><para>Second word of Parameter value shall contain frequency ([0x0000..0x7FFF], (default = 0x064D))</para></listitem> + <listitem><para>Third word of Parameter value shall contain volume ([0x0000..0x7FFF], (default = 0x0CCD))</para></listitem> + <listitem><para>Fourth word of Parameter value shall contain phase offset([0x8000..0x7FFF], (default = 0x0000))</para></listitem> + <listitem><para>Fifth word of Parameter value shall contain DC to add to tone([0x8000..0x7FFF], (default = 0x0000))</para></listitem> + <listitem><para>Sixth word of Parameter value shall contain waveform type(0=sine shaped, 1=Pulse shaped)</para></listitem> + </itemizedlist> + + <programlisting> + void Sample_TestToneSetParams() + { + u8 *test_tone_connect_ptr = NULL; + u8 tone_gen =0, waveform = 1; /* Tone_Gen = Tone_1, waveform type = pulse shaped */ + u16 frequency = 0x064D, volume = 0x0CCD, phase_offset = 0x0000, dc=0x0000; + + ext_ctrl.ctrl_class = V4L2_CTRL_CLASS_USER; + ext_ctrl.controls = (struct v4l2_ext_control *) malloc(sizeof(struct v4l2_ext_control)); + ext_ctrl.count = 0; + ext_ctrl.controls->id = V4L2_CID_CG2900_RADIO_TEST_TONE_CONNECT; + ext_ctrl.controls->size = 6; + ext_ctrl.controls->string = (u16 *)malloc(sizeof(u16) * ext_ctrl.controls->size); + test_tone_connect_ptr = ext_ctrl.controls->string; + *(test_tone_connect_ptr) = tone_gen; + *(test_tone_connect_ptr + 1) = frequency; + *(test_tone_connect_ptr + 2) = volume; + *(test_tone_connect_ptr + 3) = phase_offset; + *(test_tone_connect_ptr + 4) = dc; + *(test_tone_connect_ptr + 5) = waveform; + + ret = ioctl(fd, VIDIOC_S_EXT_CTRLS, & ext_ctrl); + if (ret < 0) { + printf("VIDIOC_S_EXT_CTRL:error!!\n"); + } + } + </programlisting> + + </listitem> + + </varlistentry> + </variablelist> + </section> + <section id="de-emphasis-filter"> + <title>Test Tone Generation</title> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + <variablelist> + <varlistentry> + <term>Set De-Emphasis Filter</term> + <listitem> + <para> + To apply de-emphasis filter to the FM received signal to compansate for + preemphasis that has been applied to the signal by the FM transmitter. IOCTL VIDIOC_S_CTRL is used in with parameter id set to V4L2_CID_CG2900_RADIO_TUNE_DEEMPHASIS and parameter value can take following values: + <itemizedlist> + <listitem><para>Disable de-emphasis - use V4L2_CG2900_RADIO_DEEMPHASIS_DISABLED</para></listitem> + <listitem><para>De-emphasis with 50 micro seconds - use V4L2_CG2900_RADIO_DEEMPHASIS_50_uS</para></listitem> + <listitem><para>De-emphasis filter with 75 micro seconds - use V4L2_CG2900_RADIO_DEEMPHASIS_75_uS</para></listitem> + </itemizedlist> + + <programlisting> + void SetDeemphasisLevel(int deemphasis_level) + { + struct v4l2_control sctrl; + int ret; + sctrl.id = V4L2_CID_CG2900_RADIO_TUNE_DEEMPHASIS ; + sctrl.value = deemphasis_level; + ret = ioctl(fd, VIDIOC_S_CTRL, & sctrl); + if (ret < 0) { + printf("VIDIOC_S_CTRL:error!!\n"); + } + } + </programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + </chapter> + <chapter id="driver-configuration"> + <title>Driver Configuration and Interaction</title> + <!-- Do NOT change the chapter id or title! --> + <para> + For debug purposes the variable cg2900_fm_debug_level in the file cg2900_fm_driver.c can be changed to set how much debug printouts + that shall be generated. + <itemizedlist> + <listitem><para>1 = Error logs</para></listitem> + <listitem><para>2 = Info logs, e.g. function entries</para></listitem> + <listitem><para>3 = Debug logs</para></listitem> + <listitem><para>4 = HCI logs, i.e. contents of the transferred data</para></listitem> + </itemizedlist> + </para> + <section id="driver-implemented-operations"> + <title>Implemented operations in driver</title> + <para> + </para> + <para> + <table> + <title> Supported device driver operations when using character device </title> + <tgroup cols="2"><tbody> + <row><entry> open </entry> <entry> Opening a character device will Initialize the FM Chip and download the firmware files.</entry> </row> + <row><entry> close </entry> <entry> Closes a character device will deinitialize the FM Chip.</entry> </row> + <row><entry> poll </entry> <entry> Polling a character device will check if there is requested data is available or not.</entry> </row> + <row><entry> read </entry> <entry> Reading from a character device reads RDS data from the Chip</entry> </row> + </tbody></tgroup> + </table> + </para> + </section> + <section id="driver-loading"> + <title>Driver loading parameters</title> + <para> + </para> + <variablelist> + <varlistentry> + <term>radio_nr</term> + <listitem> + <para> + <variablelist> + <varlistentry> + <term>Parameter type</term> + <listitem><synopsis><type>int</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Default value</term> + <listitem><para>0</para></listitem> + </varlistentry> + <varlistentry> + <term>Runtime readable/modifiable</term> + <listitem><para>Readable</para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The parameter radio_nr in radio-cg2900.c can be set to register a particular minor number with Video4Linux. Currently this parameter is set to 0 by default, signifying that the "\dev\radio0" is the character device assigned to CG2900 FM Driver in Video4Linux. + If the Platform has more than 1 radio drivers, the radio_nr parameter should be changed in file radio-cg2900.c. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Checking the Radio Number</term> + <listitem> + <para> + cat sys/module/radio_cg2900/parameters/radio_nr + </para> + <para> + The above command gets the radio number registered with + Video4Linux. This is used for opening the FM Radio + character device from user space. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>grid</term> + <listitem> + <para> + <variablelist> + <varlistentry> + <term>Parameter type</term> + <listitem><synopsis><type>int</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Default value</term> + <listitem><para>1</para></listitem> + </varlistentry> + <varlistentry> + <term>Runtime readable/modifiable</term> + <listitem><para>Readable</para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The parameter grid in radio-cg2900.c defines the spacing to be used in Khz while switching on FM Radio. + <itemizedlist> + <listitem><para>0: 50 kHz (China)</para></listitem> + <listitem><para>1: 100 kHz (Europe, Japan)</para></listitem> + <listitem><para>2: 200 kHz (USA)</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Changing the Grid</term> + <listitem> + <para> + echo 1 > /sys/module/radio_cg2900/parameters/grid. + </para> + <para> + The above command sets the radio band spacing between + two adjacent radio channels, in this case sets to 100KHz + suitable for Europe. The change is applicable before + switching on FM Radio, otherwise the change takes effect + from next FM switch on. + </para> + <para> + Note: The Grid parameter cannot be changed during FM radio is operational. + </para> + <para> + The user must change the grid value and restart the FM radio when moving into a different radio region. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Checking the current Grid Value</term> + <listitem> + <para> + cat sys/module/radio_cg2900/parameters/grid. + </para> + <para> + The above command gets the radio band spacing + between two adjacent radio channels currently set. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>band</term> + <listitem> + <para> + <variablelist> + <varlistentry> + <term>Parameter type</term> + <listitem><synopsis><type>int</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Default value</term> + <listitem><para>0</para></listitem> + </varlistentry> + <varlistentry> + <term>Runtime readable/modifiable</term> + <listitem><para>Readable</para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The parameter band in radio-cg2900.c defines the band to be used while switching on FM Radio. + <itemizedlist> + <listitem><para>0: 87.5 - 108 MHz (USA, Europe)</para></listitem> + <listitem><para>1: 76 - 90 MHz (Japan)</para></listitem> + <listitem><para>2: 70 - 108 MHz (China wide band)</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Changing the Band</term> + <listitem> + <para> + echo 0 > /sys/module/radio_cg2900/parameters/band. + </para> + <para> + The above command sets the FM band to be used. + In this case, it sets the FM band 87.5 - 100 MHz. + The change is applicable before switching on FM Radio, + otherwise the change takes effect from next FM switch on. + </para> + <para> + Note: The band parameter cannot be changed during FM radio is operational. + </para> + <para> + The user must change the band value and restart the FM radio when moving into a different radio region. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Checking the current Band Value</term> + <listitem> + <para> + cat sys/module/radio_cg2900/parameters/band. + </para> + <para> + The above command gets the current radio band set. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>cg2900_fm_debug_level</term> + <listitem> + <para> + <variablelist> + <varlistentry> + <term>Parameter type</term> + <listitem><synopsis><type>int</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Default value</term> + <listitem><para>1</para></listitem> + </varlistentry> + <varlistentry> + <term>Runtime readable/modifiable</term> + <listitem><para>Readable</para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The parameter CG2900_fm_debug_level in platformosapi.c defines the debug level that is currently used. + The higher the debug level the more print-outs are received in the terminal window. + The following values are supported: + <itemizedlist> + <listitem><para>1 = Error logs</para></listitem> + <listitem><para>2 = Info logs, e.g. function entries</para></listitem> + <listitem><para>3 = Debug logs</para></listitem> + <listitem><para>4 = HCI logs, i.e. contents of the transferred data</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Changing the Log Level</term> + <listitem> + <para> + echo 3 > /sys/module/radio_cg2900/parameters/cg2900_fm_debug_level. + </para> + <para> + The above command sets the Logging level of FM Driver. + In this case, it set will print all the debug messages + except the HCI commands exchanged with FM Chip. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Checking the current Log Level</term> + <listitem> + <para> + cat sys/module/radio_cg2900/parameters/cg2900_fm_debug_level. + </para> + <para> + The above command gets the current debug log level set. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + </para> + </section> + <section id="driver-ioctl"> + <title>Driver IO Control</title> + <para> + Describes the FM driver IO control parameters + </para> + <variablelist> + <varlistentry> + <term><constant>VIDIOC_QUERYCAP</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Get</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>v4l2_capability</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>VIDIOC_QUERYCAP</constant> IOCTL is used to query the capabilities supported by FM Driver. IF the FM Driver supports FM Rx it should set the capabilities field bit should be bitwise OR'd with V4L2_CAP_TUNER, otherwise if it supports FM Tx, the capabilities field bit should be bitwise OR'd with V4L2_CAP_MODULATOR. + Returned values are: + <itemizedlist> + <listitem><para>If IOCTL is able to retrive the Capabilities successfully without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>VIDIOC_G_TUNER</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Get</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>v4l2_tuner</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>VIDIOC_G_TUNER</constant> IOCTL gets the FM Radio Tuner properties supported by FM Radio. It is also used to retrieve RDS status, mono/stereo status and Signal strength of the tuned channel. These values are valid when FM is configured using IOCTL VIDIOC_S_TUNER, i.e in FM Rx mode. + Returned values are: + <itemizedlist> + <listitem><para>If IOCTL is able to retrive the tuner properties successfully without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + Note: Currently the retrieved signal strength is in decimals and not in "dBuV", proper external conversion required. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>VIDIOC_S_TUNER</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Set</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>v4l2_tuner</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>VIDIOC_S_TUNER</constant> IOCTL configures the FM radio in Rx mode. Only 1 FM Tuner is supported by FM Driver. + Returned values are: + <itemizedlist> + <listitem><para>If IOCTL is able to set the tuner properties successfully without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>VIDIOC_G_MODULATOR</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Get</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>v4l2_tuner</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>VIDIOC_G_MODULATOR</constant> IOCTL gets the FM Radio Modulator properties supported by FM Radio. It is also used to retrieve RDS status and mono/stereo status. These values are valid when FM is configured using IOCTL VIDIOC_S_MODULATOR, i.e in FM Tx mode. + Returned values are: + <itemizedlist> + <listitem><para>If IOCTL is able to retrive the tuner properties successfully without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>VIDIOC_S_MODULATOR</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Set</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>v4l2_modulator</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>VIDIOC_S_MODULATOR</constant> IOCTL configures the FM radio in Tx mode. Only 1 FM Modulator is supported by FM Driver. + Returned values are: + <itemizedlist> + <listitem><para>If IOCTL is able to set the modulator properties successfully without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>VIDIOC_S_FREQUENCY</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Set</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>v4l2_frequency</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>VIDIOC_S_FREQUENCY</constant> IOCTL sets the frequency on FM radio in Rx or Tx mode. The frequency parameter passed is in V4L2 format. + Returned values are: + <itemizedlist> + <listitem><para>If IOCTL is able to set the frequency successfully without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>VIDIOC_G_FREQUENCY</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Set</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>v4l2_modulator</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>VIDIOC_G_FREQUENCY</constant> IOCTL retrives the currently set frequency on FM Radio in Rx or Tx mode. + Returned values are: + <itemizedlist> + <listitem><para>If IOCTL is able to get the frequency successfully without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>VIDIOC_S_HW_FREQ_SEEK</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Set</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>v4l2_hw_freq_seek</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>VIDIOC_S_HW_FREQ_SEEK</constant> IOCTL starts the seek operation when FM Radio is configured in Rx mode. The direction parameter indicates the direction of seeking from the current station. At present the FM Driver ignores the wrap_Around parameter and unconditional wrap around is supported. If the operation is started successfully, the application should use poll() to identify when the seek is over. + Returned values are: + <itemizedlist> + <listitem><para>If IOCTL is able to start the seek successfully without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>VIDIOC_G_CTRL</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Get</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>v4l2_control</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>VIDIOC_G_CTRL</constant> IOCTL to retrive value of a paticular control. The following controls are supported by FM Driver: + <itemizedlist> + <listitem><para> + V4L2_CID_AUDIO_VOLUME + </para></listitem> + <listitem><para> + V4L2_CID_AUDIO_MUTE + </para></listitem> + <listitem><para> + V4L2_CID_AUDIO_BALANCE + </para></listitem> + <listitem><para> + V4L2_CID_CG2900_RADIO_RSSI_THRESHOLD + </para></listitem> + <listitem><para> + V4L2_CID_CG2900_RADIO_SELECT_ANTENNA + </para></listitem> + <listitem><para> + V4L2_CID_CG2900_RADIO_RDS_AF_UPDATE_GET_RESULT + </para></listitem> + <listitem><para> + V4L2_CID_CG2900_RADIO_RDS_AF_SWITCH_GET_RESULT + </para></listitem> + </itemizedlist> + Generic returned values are: + <itemizedlist> + <listitem><para>If IOCTL is able to retrive the value of the control successfully without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + Note: For V4L2_CID_CG2900_RADIO_RDS_AF_SWITCH_GET_RESULT returned values are: + <itemizedlist> + <listitem><para> -1 AF Switch failed, the AF-RSSI was too low.</para></listitem> + <listitem><para> -2 AF Switch failed, the AF-PI Doesn't correlate.</para></listitem> + <listitem><para> -3 AF Switch failed, the AF-RDS SYNC Lost.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>VIDIOC_S_CTRL</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Set</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>v4l2_control</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>VIDIOC_S_CTRL</constant> IOCTL to set value of a paticular control. The following controls are supported by FM Driver: + <itemizedlist> + <listitem><para> + V4L2_CID_CG2900_RADIO_CHIP_STATE + </para></listitem> + <listitem><para> + V4L2_CID_CG2900_RADIO_BANDSCAN + </para></listitem> + <listitem><para> + V4L2_CID_CG2900_RADIO_BLOCKSCAN_START + </para></listitem> + <listitem><para> + V4L2_CID_CG2900_RADIO_SELECT_ANTENNA + </para></listitem> + <listitem><para> + V4L2_CID_CG2900_RADIO_RSSI_THRESHOLD + </para></listitem> + <listitem><para> + V4L2_CID_CG2900_RADIO_RDS_AF_UPDATE_START + </para></listitem> + </itemizedlist> + Returned values are: + <itemizedlist> + <listitem><para>If IOCTL is able to set the value of the control successfully without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>VIDIOC_G_EXT_CTRLS</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Get</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>v4l2_ext_controls</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>VIDIOC_G_EXT_CTRLS</constant> IOCTL to retrive value of a paticular control. This is used when a control class is defined or when the value to be retrieved is more than 1 parameter(s). Only V4L2_CTRL_CLASS_FM_TX class is supported for this IOCTL in FM Driver. The following controls are supported by FM Driver: + <itemizedlist> + <listitem><para> + V4L2_CID_RDS_TX_DEVIATION + </para></listitem> + <listitem><para> + V4L2_CID_PILOT_TONE_ENABLED + </para></listitem> + <listitem><para> + V4L2_CID_PILOT_TONE_DEVIATION + </para></listitem> + <listitem><para> + V4L2_CID_TUNE_PREEMPHASIS + </para></listitem> + <listitem><para> + V4L2_CID_TUNE_POWER_LEVEL + </para></listitem> + </itemizedlist> + Returned values are: + <itemizedlist> + <listitem><para>If IOCTL is able to retrive the value(s) of the control successfully without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>VIDIOC_S_EXT_CTRLS</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Set</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>v4l2_ext_controls</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>VIDIOC_S_CTRL</constant> IOCTL to set value of a paticular control when the parameters to be set are more than 1 parameter or when a control class is defined. At present only the V4L2_CTRL_CLASS_FM_TX and V4L2_CTRL_CLASS_USER control classes are supported by FM Driver. The following controls are supported by FM Driver: + <itemizedlist> + <listitem><para> + V4L2_CID_RDS_TX_DEVIATION + </para></listitem> + <listitem><para> + V4L2_CID_RDS_TX_PI + </para></listitem> + <listitem><para> + V4L2_CID_RDS_TX_PTY + </para></listitem> + <listitem><para> + V4L2_CID_RDS_TX_PS_NAME + </para></listitem> + <listitem><para> + V4L2_CID_RDS_TX_RADIO_TEXT + </para></listitem> + <listitem><para> + V4L2_CID_PILOT_TONE_ENABLED + </para></listitem> + <listitem><para> + V4L2_CID_PILOT_TONE_DEVIATION + </para></listitem> + <listitem><para> + V4L2_CID_TUNE_PREEMPHASIS + </para></listitem> + <listitem><para> + V4L2_CID_TUNE_POWER_LEVEL + </para></listitem> + <listitem><para> + V4L2_CID_CG2900_RADIO_RDS_AF_SWITCH_START + </para></listitem> + </itemizedlist> + Returned values are: + <itemizedlist> + <listitem><para>If IOCTL is able to set the value of the control successfully without errors the IOCTL function will return 0.</para></listitem> + <listitem><para>A negative value will indicate error.</para></listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="driver-sysfs"> + <title>Driver Interaction with Sysfs</title> + <para> + Not Applicable + </para> + </section> + <section id="driver-proc"> + <title>Driver Interaction using /proc filesystem</title> + <para> + Not Applicable + </para> + </section> + <section id="driver-other"> + <title>Other means for Driver Interaction</title> + <para> + Not Applicable + </para> + </section> + <section id="driver-node"> + <title>Driver Node File</title> + <variablelist> + <varlistentry> + <term>FM Radio Device</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/radio0</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The radio device for FM Radio.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </section> + </chapter> + <chapter id="bugs"> + <title>Known Bugs And Limitations</title> + <para> + <variablelist> + <varlistentry> + <term>No known issues.</term> + <listitem> + <para> + <!-- Do NOT change the chapter id or title! --> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </chapter> + <chapter id="internal-functions"> + <title>Internal Functions Provided</title> + <para> + List of internal functions used in FM Driver. + </para> + <!-- Do NOT change the chapter id or title! --> + <section id="radio-cg2900.c"> + <title>radio-cg2900.c</title> +!Idrivers/media/radio/CG2900/radio-cg2900.c + </section> + <section id="cg2900_fm_api.h"> + <title>cg2900_fm_api.h</title> +!Idrivers/media/radio/CG2900/cg2900_fm_api.h + </section> + <section id="cg2900_fm_api.c"> + <title>cg2900_fm_api.c</title> +!Idrivers/media/radio/CG2900/cg2900_fm_api.c + </section> + <section id="cg2900_fm_driver.h"> + <title>cg2900_fm_driver.h</title> +!Idrivers/media/radio/CG2900/cg2900_fm_driver.h + </section> + <section id="cg2900_fm_driver.c"> + <title>cg2900_fm_driver.c</title> +!Idrivers/media/radio/CG2900/cg2900_fm_driver.c + </section> + </chapter> +</book> diff --git a/Documentation/DocBook/db5500_keypad.tmpl b/Documentation/DocBook/db5500_keypad.tmpl new file mode 100644 index 00000000000..a25fc990516 --- /dev/null +++ b/Documentation/DocBook/db5500_keypad.tmpl @@ -0,0 +1,91 @@ +<?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="keypad-API-Guide"> + <bookinfo> + <title>DB5500 Keypad</title> + + <authorgroup> + <author> + <firstname>NaveenKumar</firstname> + <surname>Gaddipati</surname> + <affiliation> + <address> + <email>naveen.gaddipati@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2010</year> + <holder>ST-Ericsson</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Linux standard functions</subjectterm> + </subject> + </subjectset> + + <legalnotice> + <para> + License terms: GNU General Public License (GPL) version 2. + </para> + + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="intro"> + <title>Introduction</title> + <para> + This documentation describes the API provided by the keypad + driver for internal keypad. + </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="pubfunctions"> + <title>Public Functions Provided</title> + <para> + This db5500-keypad driver doesn't export any functions. + </para> + </chapter> + + <chapter id="structs"> + <title>Structures</title> + <para> + This chapter contains the autogenerated documentation of the + structures which are used in the keypad driver. + </para> +!Iarch/arm/mach-ux500/include/mach/db5500-keypad.h + </chapter> + + <chapter id="intfunctions"> + <title>Internal Functions Provided</title> + <para> + This chapter contains the autogenerated documentation of the + internal functions. + </para> +!Idrivers/input/keyboard/db5500_keypad.c + </chapter> + + </book> diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 9c27e5125dd..7514dbf0a67 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -446,4 +446,21 @@ X!Idrivers/video/console/fonts.c !Edrivers/i2c/i2c-core.c </chapter> + <chapter id="hsi"> + <title>High Speed Synchronous Serial Interface (HSI)</title> + + <para> + High Speed Synchronous Serial Interface (HSI) is a + serial interface mainly used for connecting application + engines (APE) with cellular modem engines (CMT) in cellular + handsets. + + HSI provides multiplexing for up to 16 logical channels, + low-latency and full duplex communication. + </para> + +!Iinclude/linux/hsi/hsi.h +!Edrivers/hsi/hsi.c + </chapter> + </book> diff --git a/Documentation/DocBook/gpio.tmpl b/Documentation/DocBook/gpio.tmpl new file mode 100644 index 00000000000..b69c2770210 --- /dev/null +++ b/Documentation/DocBook/gpio.tmpl @@ -0,0 +1,112 @@ +<?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="GPIO"> + <bookinfo> + <title>GPIO1B</title> + + <authorgroup> + <author> + <firstname>Alessandro</firstname> + <surname>Rubini</surname> + <affiliation> + <address> + <email>rubini@unipv.it</email> + </address> + </affiliation> + </author> + <author> + <firstname>Prafulla</firstname> + <surname>WADASKAR</surname> + <affiliation> + <address> + <email>prafulla.wadaskar@st.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2008-2010</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's provided by the GPIO controller Driver. + </para> + <para> + Only the API specific to the Ux500 platform is listed here. For the generic GPIO + API, see <filename>Documentation/gpio.txt</filename> in the kernel source tree. + </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="pubfunctions"> + <title> Public Interface </title> + <para> + This Section lists the API's provided by the GPIO controller driver to client drivers. + </para> + <para> + Only the API specific to the Ux500 platform is listed here. For the generic GPIO + API, see <filename>Documentation/gpio.txt</filename> in the kernel source tree. + </para> +!Earch/arm/plat-nomadik/gpio.c + </chapter> +</book> diff --git a/Documentation/DocBook/i2c.tmpl b/Documentation/DocBook/i2c.tmpl new file mode 100644 index 00000000000..8a4cb49204e --- /dev/null +++ b/Documentation/DocBook/i2c.tmpl @@ -0,0 +1,116 @@ +<?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="I2C"> + <bookinfo> + <title>I2C</title> + + <authorgroup> + <author> + <firstname>Srinidhi</firstname> + <surname>Kasagar</surname> + <affiliation> + <address> + <email>srinidhi.kasagar@stericsson.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>Sachin</firstname> + <surname>Verma</surname> + <affiliation> + <address> + <email>sachin.verma@st.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2009-2010</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's provided by the I2C controller Driver. + Since this driver registers the transferfunction with kernel framework, there + are only private functions in this I2C bus driver. This driver currently + works only in master mode and does 7 bit adderssing only. There is no support + for 10 bit addressing. The driver currently supports standard mode (100KHz) + and Fast mode (400KHz) operation. + </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="pubfunctions"> + <title>Public Functions Provided</title> + <para> + Not Applicable + </para> + </chapter> + + <chapter id="private"> + <title>Private Functions</title> + <para> + This Section lists the functions used internally by the I2C controller driver. + </para> +!Idrivers/i2c/busses/i2c-nomadik.c + </chapter> + +</book> diff --git a/Documentation/DocBook/i2s.tmpl b/Documentation/DocBook/i2s.tmpl new file mode 100644 index 00000000000..6b6c50572e2 --- /dev/null +++ b/Documentation/DocBook/i2s.tmpl @@ -0,0 +1,97 @@ +<?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="I2S"> + <bookinfo> + <title>I2S</title> + + <authorgroup> + <author> + <firstname>Sandeep</firstname> + <surname>Kaushik</surname> + <affiliation> + <address> + <email>sandeep.kaushik@st.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2008-2009</year> + <holder>STMicroelectronics Pvt Ltd</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 APIs provided by the I2S Bus Driver. I2S bus supports different + protocols like I2S, PCM, SPI etc. + </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="pubfunctions"> + <title>Public Functions Provided</title> + <para> + This Section lists the functions exported by the I2S bus driver. These functions cater to all the protocols + supported namely: I2S, PCM, SPI. + </para> +!Edrivers/misc/i2s/i2s.c + </chapter> +</book> diff --git a/Documentation/DocBook/lps001wp_prs.tmpl b/Documentation/DocBook/lps001wp_prs.tmpl new file mode 100644 index 00000000000..4b3f69ab967 --- /dev/null +++ b/Documentation/DocBook/lps001wp_prs.tmpl @@ -0,0 +1,89 @@ +<?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="LPS001WP-API-Guide"> + <bookinfo> + <title>LPS001WP Pressure and temperature</title> + + <authorgroup> + <author> + <firstname> Matteo Dameno,Carmine Iascone </firstname> + <surname></surname> + <affiliation> + <address> + <email>matteo.dameno@st.com,carmine.iascone@st.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> + <para> + License terms: GNU General Public License (GPL) version 2. + </para> + + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="intro"> + <title>Introduction</title> + <para> + This documentation describes the pressure and temperature sensor driver for LPS001WP chip. + </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 pressure/temperature sensor driver. + </para> +!Iinclude/linux/input/lps001wp.h + </chapter> + + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + This pressure/temperature drivers don't export any functions. + </para> + </chapter> + + <chapter id="intfunctions"> + <title>Internal Functions Provided</title> + <para> + This chapter contains the autogenerated documentation of the internal functions. + </para> +!Idrivers/input/misc/lps001wp_prs.c + </chapter> + + </book> diff --git a/Documentation/DocBook/lsm303dlh.tmpl b/Documentation/DocBook/lsm303dlh.tmpl new file mode 100644 index 00000000000..1000481e205 --- /dev/null +++ b/Documentation/DocBook/lsm303dlh.tmpl @@ -0,0 +1,91 @@ +<?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="LSM303DLH-API-Guide"> + <bookinfo> + <title>LSM303DLH Accelerometer and Magnetometer</title> + + <authorgroup> + <author> + <firstname>Chethan Krishna</firstname> + <surname>N</surname> + <affiliation> + <address> + <email>chethan.krishna@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2010</year> + <holder>ST-Ericsson</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Linux standard functions</subjectterm> + </subject> + </subjectset> + + <legalnotice> + <para> + License terms: GNU General Public License (GPL) version 2. + </para> + + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="intro"> + <title>Introduction</title> + <para> + This documentation describes the accelerometer and magnetometer drivers for lsm303dlh sensor chip. + </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="pubfunctions"> + <title>Public Functions Provided</title> + <para> + This accelerometer/magnetometer drivers don't export any functions. + </para> + </chapter> + + <chapter id="structs"> + <title>Structures</title> + <para> + This chapter contains the autogenerated documentation of the structures which are + used in the accelerometer/magnetometer drivers. + </para> +!Iinclude/linux/lsm303dlh.h + </chapter> + + <chapter id="intfunctions"> + <title>Internal Functions Provided</title> + <para> + This chapter contains the autogenerated documentation of the internal functions. + </para> +!Idrivers/hwmon/lsm303dlh_a.c +!Idrivers/hwmon/lsm303dlhc_a.c +!Idrivers/hwmon/lsm303dlh_m.c + </chapter> + + </book> diff --git a/Documentation/DocBook/msp.tmpl b/Documentation/DocBook/msp.tmpl new file mode 100644 index 00000000000..55cec352a76 --- /dev/null +++ b/Documentation/DocBook/msp.tmpl @@ -0,0 +1,104 @@ +<?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="MSP"> + <bookinfo> + <title>MSP</title> + + <authorgroup> + <author> + <firstname>Sandeep</firstname> + <surname>Kaushik</surname> + <affiliation> + <address> + <email>sandeep.kaushik@st.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2008-2009</year> + <holder>STMicroelectronics Pvt Ltd</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's provided by the MSP controller Driver. + MSP controller supports different protocols like I2S, PCM, SPI etc. + </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="pubfunctions"> + <title>Public Functions Provided</title> + <para> + Not Applicable. + </para> + </chapter> + + <chapter id="private"> + <title>Private Functions</title> + <para> + This Section lists the functions used by the MSP controller driver. + These functions cater to all the protocols supported namely: I2S, PCM, SPI. + </para> +!Idrivers/misc/i2s/msp_i2s.c + </chapter> +</book> diff --git a/Documentation/DocBook/prcmu-fw-api.tmpl b/Documentation/DocBook/prcmu-fw-api.tmpl new file mode 100644 index 00000000000..445a277933c --- /dev/null +++ b/Documentation/DocBook/prcmu-fw-api.tmpl @@ -0,0 +1,109 @@ +<?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="STw4500"> + <bookinfo> + <title>PRCMU Driver</title> + + <authorgroup> + <author> + <firstname>Sudeep Karkada</firstname> + <surname>Nagesha</surname> + <affiliation> + <address> + <email>sudeepkarkada.nagesha@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2009-2010</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 PRCMU firmware interface 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="enum"> + <title>Enumerations</title> + <para> + This chapter contains the autogenerated documentation of the structures + and enumerations which are used in the PRCMU firmware interface driver. + It is also required by the client drivers. + </para> +!Iinclude/linux/mfd/dbx500-prcmu.h + </chapter> + + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + This chapter contains the autogenerated documentation of the kernel + API functions which are exported to the client drivers. + </para> +!Edrivers/mfd/db8500-prcmu.c + </chapter> + + + </book> diff --git a/Documentation/DocBook/shrm.tmpl b/Documentation/DocBook/shrm.tmpl new file mode 100644 index 00000000000..b93bb065172 --- /dev/null +++ b/Documentation/DocBook/shrm.tmpl @@ -0,0 +1,139 @@ +<?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="SHRM"> + <bookinfo> + <title>Shared Memory</title> + <authorgroup> + <author> + <firstname>Biju</firstname> + <surname>Das</surname> + <affiliation> + <address> + <email>biju.das@stericsson.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>Kumar</firstname> + <surname>Sanghvi</surname> + <affiliation> + <address> + <email>kumar.sanghvi@stericsson.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>Arun</firstname> + <surname>Murthy</surname> + <affiliation> + <address> + <email>arun.murthy@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2009-2010</year> + <holder>ST-Ericsson</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Linux standard functions</subjectterm> + </subject> + </subjectset> + + <legalnotice> + <!-- Do NOT remove the legal notice below --> + <para> + Licence terms: GNU General Public Licence (GPL) version 2. + </para> + </legalnotice> + </bookinfo> + +<toc></toc> + <chapter id="intro"> + <title>Introduction</title> + <para> + This Documentation describes the ST-Ericsson's adaptation on protocol used for CMT/APE communication when SHaRedMemory is used as IPC link. + </para> + </chapter> + + <chapter id="design"> + <title>Design</title> + <para> + The APE consists Cortex A9 dual core SMP, a multimedia DSP and PRCMU. Modem consists of 2 Cortex R4 ARM processor. + The exchange of messages between CMT(Cellular Mobile Terminal) and APE includes copying the data to a shared area DDR. This region is accessible by both CMT and APE. The design includes 2 channels common and audio. Common channel is used for exchanging ISI, RPC and SECURITY messages. Audio channel is used for exchanging AUDIO messages. Each channel consists of 2 FIFO. One FIFO for sending message from CMT to APE and other from APE to CMT. Each of these FIFO have write and read pointer shared between APE and CMT. Writer pointer is updated on copying the message to FIFO and reader will read the messages from the read pointer upto the writer pointer. Writer and reader notifications are used to notify the completion of read/write operation(seperate for APE and CMT). Driver includes 4 queues. Once the messages are sent from CMT to APE it resides in the FIFO and then copied to one of the 4 queues based on the message type(ISI, RPC, AUDIO, SECURITY) and then the net/char device interface fetches this message from the queue and copies to the user space buffer. + </para> + </chapter> + + <chapter id="concepts"> + <title>Concepts</title> + <para> + The user space application sends ISI/RPC/AUDIO/SECURITY messages. ISI is sent through the phonet to shrm driver. For achieving this there are 2 interfaces to the shrm driver. Net interface used for exchanging the ISI message and char interface for RPC, AUDIO and SECURITY messages. On receiving any of these messages from the user space application, it is copied to a memory in kernel space. From here it is then copied to respective FIFO from where the CMT reads the message. + CMT(Cellular Mobile Terminal) writes messages to the respective FIFO and thereafter to respective queue. The net/char device copies this message from the queue to the user space buffer. + </para> + </chapter> + + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <para> + <variablelist> + <varlistentry> + <term>None</term> + <listitem> + <para> + Assumptions + 1. ApeShmFifo#0 is of 128kB in size. As this is used for transmission except CS audio call data. Expected message size is 1.5kB with a max of 16kB. + 2. ApeShmFifo#1 is of 4kB in size. This is used for transmission of CS audio call data. Expected message size is 24kb. + 3. CmtShmFifo#0 is of 128kB in size. As this is used for transmission except CS audio call data. Expected message size is 1.5kB with a max of 16kB. + 4. CmtShmFifo#1 is of 4kB in size. This is used for transmission of CS audio call data. Expected message size is 24kb. + The total size of the FIFO is 264 kB. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </chapter> + + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + This Section lists the API's provided by the SHRM driver to phonet drivers. + </para> +!Edrivers/modem/shrm/shrm_fifo.c + <para> + This Section lists the API's provided by the SHRM driver used in transmission of RPC, AUDIO and SECURITY messages. + </para> +!Edrivers/char/shrm_char.c + + </chapter> + + <chapter id="private"> + <title>Private Functions</title> + <para> + This Section lists the functions used internally by the SHRM driver to implement FIFO management. It physically reads/writes data to/from memory. + </para> +!Idrivers/modem/shrm/shrm_fifo.c + <para> + This Section lists the functions used internally by the SHRM driver to implement the SHM protocol and handle all interrupt callback. + </para> +!Idrivers/modem/shrm/shrm_protocol.c + <para> + This Section lists the functions used internally by the SHRM driver to implement Modem-Host communication L1 interface specifications. + </para> +!Idrivers/modem/shrm/modem_shrm_driver.c + </chapter> + + <chapter id="Other"> + <title>Other Data Structures</title> + <para> + This Section lists some of the Data structure used by the SHRM driver. + </para> +!Iinclude/linux/modem/shrm/shrm_driver.h +!Iinclude/linux/modem/shrm/shrm_private.h + </chapter> +</book> diff --git a/Documentation/DocBook/ske_keypad.tmpl b/Documentation/DocBook/ske_keypad.tmpl new file mode 100644 index 00000000000..030d5201990 --- /dev/null +++ b/Documentation/DocBook/ske_keypad.tmpl @@ -0,0 +1,89 @@ +<?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="keypad-API-Guide"> + <bookinfo> + <title>SKE Keypad</title> + + <authorgroup> + <author> + <firstname>NaveenKumar</firstname> + <surname>Gaddipati</surname> + <affiliation> + <address> + <email>naveen.gaddipati@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2010</year> + <holder>ST-Ericsson</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Linux standard functions</subjectterm> + </subject> + </subjectset> + + <legalnotice> + <para> + License terms: GNU General Public License (GPL) version 2. + </para> + + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="intro"> + <title>Introduction</title> + <para> + This documentation describes the API provided by the keypad driver for internal keypad. + </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 keypad driver. + </para> +!Iarch/arm/plat-nomadik/include/plat/ske.h + </chapter> + + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + This ske keypad driver doesn't export any functions. + </para> + </chapter> + + <chapter id="intfunctions"> + <title>Internal Functions Provided</title> + <para> + This chapter contains the autogenerated documentation of the internal functions. + </para> +!Idrivers/input/keyboard/nomadik-ske-keypad.c + </chapter> + + </book> diff --git a/Documentation/DocBook/ste_ff_vibra.tmpl b/Documentation/DocBook/ste_ff_vibra.tmpl new file mode 100644 index 00000000000..cf5f159bed0 --- /dev/null +++ b/Documentation/DocBook/ste_ff_vibra.tmpl @@ -0,0 +1,217 @@ +<!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="STE-Force-Feedback-Vibrator-API-Guide"> + <bookinfo> + <title>Force Feedback Vibrator Driver</title> + + <authorgroup> + <author> + <firstname>Marcin</firstname> + <surname>Mielczarczyk</surname> + <affiliation> + <address> + <email>marcin.mielczarczyk@tieto.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2010</year> + <holder>ST-Ericsson</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Linux standard functions</subjectterm> + </subject> + </subjectset> + + <legalnotice> + + <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 implementation of ST-Ericsson's + Force Feedback Vibrator driver for the ST-Ericsson Linux platforms. + </para> + </chapter> + + <chapter id="gettingstarted"> + <title>Getting Started</title> + <para> + There are no special compilation flags needed to build the + Force Feedback Vibrator driver. + </para> + + <section id="basic-tutorial"> + <title>Basic Tutorial</title> + <para> + To enable the Force Feedback Vibrator driver using Kconfig, go to + <constant> Device Drivers -> Input Device Support -> Miscellaneous devices </constant> + and enable the following: + <itemizedlist> + <listitem><para>ST-Ericsson Force Feedback Vibrator</para></listitem> + </itemizedlist> + </para> + </section> + + </chapter> + + <chapter id="concepts"> + <title>Concepts</title> + <para> + Vibrator driver registers as memless force feedback input device. + </para> + </chapter> + + <chapter id="driver-configuration"> + <title>Driver Configuration and Interaction</title> + <para> + There are no configuration parameters for Force Feedback Vibrator driver. + </para> + <section id="driver-implemented-operations"> + <title>Implemented operations in driver</title> + <para> + All available operations are provided by Memless Input Device class driver. + </para> + <para> + <table> + <title> Supported device driver operations </title> + <tgroup cols="2"><tbody> + <row><entry> open </entry> <entry> Calls ste_ff_vibra_open() function which initializaes workqueue </entry> </row> + <row><entry> close </entry> <entry> Calls ste_ff_vibra_close() function which cancels and destroys workqueue </entry> </row> + </tbody></tgroup> + </table> + </para> + </section> + <section id="driver-loading"> + <title>Driver loading parameters</title> + <para> + Not Applicable. + </para> + </section> + <section id="driver-ioctl"> + <title>Driver IO Control</title> + <para> + Not Applicable. + </para> + </section> + + <section id="driver-sysfs"> + <title>Driver Interaction with Sysfs</title> + <para> + Not Applicable. + </para> + </section> + <section id="driver-proc"> + <title>Driver Interaction using /proc filesystem</title> + <para> + Not Applicable. + </para> + </section> + + <section id="driver-other"> + <title>Other means for Driver Interaction</title> + <para> + Not Applicable. + </para> + </section> + + <section id="driver-node"> + <title>Driver Node File</title> + <para> + Force Feedback Vibrator driver provides following node files: + </para> + <variablelist> + <varlistentry> + <term>eventX - Force Feedback Vibrator node file</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/input/eventX</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>Node file of Force Feedback Vibrator driver</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + </variablelist> + </section> + + + </chapter> + + + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <para> + <variablelist> + <varlistentry> + <term>None.</term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + + </variablelist> + + </para> + </chapter> + +<chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + Not Applicable. + </para> + +</chapter> + +<chapter id="internal-functions"> + <title>Internal Functions Provided</title> + <para> + This chapter contains the autogenerated documentation of the internal functions. + </para> +!Edrivers/input/misc/ste_ff_vibra.c +</chapter> + +</book> diff --git a/Documentation/DocBook/stmpe.tmpl b/Documentation/DocBook/stmpe.tmpl new file mode 100644 index 00000000000..9e64a00f6b3 --- /dev/null +++ b/Documentation/DocBook/stmpe.tmpl @@ -0,0 +1,115 @@ +<?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="STMPE MFD devices"> + <bookinfo> + <title>STMPE IO-Port Expander guide</title> + + <authorgroup> + <author> + <firstname>Rabin</firstname> + <surname>Vincent</surname> + <affiliation> + <address> + <email>rabin.vincent@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2010</year> + <holder>ST-Ericsson</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Linux standard functions</subjectterm> + </subject> + </subjectset> + + <legalnotice> + <para> + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License version 2 as published by the Free Software Foundation. + </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 driver for STMicroelectronics + STMPExxxx port expander devices. + </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="pubfunctions"> + <title>Public Functions Provided</title> + <para> + List of public interfaces in stmpe driver + </para> +!Edrivers/mfd/stmpe.c + </chapter> + + <chapter id="private"> + <title>Private Functions</title> + <para> + STMPE Keypad driver + STMPE GPIO driver + </para> + <section id="stmpe-keypad.c"> + <title>stmpe-keypad.c</title> +!Idrivers/input/keyboard/stmpe-keypad.c + </section> + </chapter> + + <chapter id="Other"> + <title>Other Data Structures</title> + <para> + This Section lists some of the Data structure used by the stmpe driver and client drivers. + </para> +!Iinclude/linux/mfd/stmpe.h +!Idrivers/mfd/stmpe.h +</chapter> +</book> diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl index 85b25275196..b2769ce5c8f 100644..100755 --- a/Documentation/DocBook/stylesheet.xsl +++ b/Documentation/DocBook/stylesheet.xsl @@ -1,10 +1,18 @@ -<?xml version="1.0" encoding="UTF-8"?> -<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0"> -<param name="chunk.quietly">1</param> -<param name="funcsynopsis.style">ansi</param> -<param name="funcsynopsis.tabular.threshold">80</param> -<param name="callout.graphics">0</param> -<!-- <param name="paper.type">A4</param> --> -<param name="generate.section.toc.level">2</param> -<param name="use.id.as.filename">1</param> -</stylesheet> +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:fo="http://www.w3.org/1999/XSL/Format" + version="1.0"> + <xsl:param name="use.id.as.filename" select="'1'"/> + <xsl:param name="admon.graphics" select="'1'"/> + <xsl:param name="admon.graphics.path"></xsl:param> + <xsl:param name="chunk.section.depth" select="2"></xsl:param> + <xsl:param name="chunk.quietly">1</xsl:param> + <xsl:param name="html.stylesheet" + select="'style.css'"/> + <xsl:param name="section.autolabel" select="1"/> + <xsl:param name="table.section.depth" select="1"/> + <xsl:param name="toc.section.depth" select="5"/> + <xsl:template name="user.header.content"> + <link href="../style.css" title="walsh" rel="stylesheet" type="text/css"/> + </xsl:template> +</xsl:stylesheet>
\ No newline at end of file diff --git a/Documentation/DocBook/synaptics_rmi4_touchp.tmpl b/Documentation/DocBook/synaptics_rmi4_touchp.tmpl new file mode 100644 index 00000000000..bc104eb4840 --- /dev/null +++ b/Documentation/DocBook/synaptics_rmi4_touchp.tmpl @@ -0,0 +1,106 @@ +<?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="Synaptics RMI4 API Guide"> + <bookinfo> + <title>Synaptics RMI4 Touch screen</title> + + <authorgroup> + <author> + <firstname>Naveen Kumar</firstname> + <surname>Gaddipati</surname> + <affiliation> + <address> + <email>naveen.gaddipati@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2010</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 functions provided by the + driver of touch panel for Synaptics RMI4 controller + </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="pubfunctions"> + <title>Public Functions Provided</title> + <para> + Not Applicable. + </para> + </chapter> + + <chapter id="intfunctions"> + <title>Internal Functions Provided</title> + <para> + This chapter contains the autogenerated documentation of the internal + functions of the Tocuh panel driver. + </para> +!Idrivers/staging/ste_rmi4/synaptics_i2c_rmi4.c + </chapter> + + </book> diff --git a/Documentation/DocBook/tc_keypad.tmpl b/Documentation/DocBook/tc_keypad.tmpl new file mode 100644 index 00000000000..3f2630d9d6c --- /dev/null +++ b/Documentation/DocBook/tc_keypad.tmpl @@ -0,0 +1,113 @@ +<?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="TC35893"> + <bookinfo> + <title>TC35893 Keypad</title> + + <authorgroup> + <author> + <firstname>Jayeeta</firstname> + <surname>Banerjee</surname> + <affiliation> + <address> + <email>jayeeta.banerjee@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2010</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 keypad driver for TC35893 controller + </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 keypad driver. + </para> +!Iinclude/linux/mfd/tc3589x.h + </chapter> + + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + Not Applicable. + </para> + </chapter> + + <chapter id="intfunctions"> + <title>Internal Functions Provided</title> + <para> + This chapter contains the autogenerated documentation of the internal functions. + </para> +!Idrivers/input/keyboard//tc3589x-keypad.c + </chapter> + + </book> diff --git a/Documentation/DocBook/touchp.tmpl b/Documentation/DocBook/touchp.tmpl new file mode 100644 index 00000000000..4301b23bfc0 --- /dev/null +++ b/Documentation/DocBook/touchp.tmpl @@ -0,0 +1,104 @@ +<?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="bu21013_ts"> + <bookinfo> + <title>Touch screen ROHM BU21013MWV</title> + + <authorgroup> + <author> + <firstname>Naveen Kumar</firstname> + <surname>Gaddipati</surname> + <affiliation> + <address> + <email>naveen.gaddipati@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2009</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 functions provided by the driver of touch panel for BU21013 controller + </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="pubfunctions"> + <title>Public Functions Provided</title> + <para> + Not Applicable. + </para> + </chapter> + + <chapter id="intfunctions"> + <title>Internal Functions Provided</title> + <para> + This chapter contains the autogenerated documentation of the internal functions of the Tocuh panel driver. + </para> +!Idrivers/input/touchscreen/bu21013_ts.c + </chapter> + + </book> 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/Documentation/DocBook/ux500_usb.tmpl b/Documentation/DocBook/ux500_usb.tmpl new file mode 100644 index 00000000000..71b744386d4 --- /dev/null +++ b/Documentation/DocBook/ux500_usb.tmpl @@ -0,0 +1,151 @@ +<?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="USB-FUNCTION-Guide"> + <bookinfo> + <title>USB Driver Function guide</title> + + <authorgroup> + <author> + <firstname>Praveena</firstname> + <surname>Nadahally</surname> + <affiliation> + <address> + <email>praveen.nadahally@stericsson.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>Rajaram</firstname> + <surname>Ragupathy</surname> + <affiliation> + <address> + <email>ragupathy.rajaram@stericsson.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>SakethRam</firstname> + <surname>Bommisetti</surname> + <affiliation> + <address> + <email>sakethram.bommisetti@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2011</year> + <holder>ST-Ericsson</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Connectivity</subjectterm> + </subject> + </subjectset> + + <legalnotice> + <para> + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License version 2 as published by the Free Software Foundation. + </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 ST-Ericsson's adaptation on USB external DMA and communication between Mentor USB IP controller and the USB + transreceiver + </para> + </chapter> + + <chapter id="concepts"> + <title>Concepts</title> + <!-- Do NOT change the chapter id or title! --> + <para> + In ST-Ericsson's USB driver, the open source linux gadget stack and Mentor IP USB 2.0 driver is used. Since the USB Transceiver and Mentor USB IP controller are on different hardware, API's are defined for the communication between them. These API's are available in ux500.c file. + The ST-Ericsson's USB driver doesn't have the internal DMA dedicated for USB. So, the external system DMA is used. The integration of external DMA with the mentor chip is available in ux500_dma.c file. + Changes have been made in the musb_core.c file where endpoints are configured as per the platform and also integrated DMA specific chnages in the musb_gadget.c file. + <!-- TODO: A brief introduction about the concepts + which are introduced by the driver. + Remove this chapter completely if there are no + special concepts introduced by this driver. + Do NOT change the chapter id or title! --> + <!-- TODO: This guideline for this chapter may be extended + during the user-guide guidelines drop. --> + </para> + </chapter> + + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <!-- Do NOT change the chapter id or title! --> + <para> + <variablelist> + + <varlistentry> + <term>None.</term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + + </variablelist> + + </para> + </chapter> + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + The musb driver doesn't export any functions. + </para> + </chapter> + <chapter id="intfunctions"> + <title>Internal Functions Provided</title> + <para> + List of internal functions + </para> + <!-- Do NOT change the chapter id or title! --> + <!-- TODO: Replace with link to appropriate headerfile(s), + source file(s), or both. One per row, ensure the + exclamation mark is on the first column! If no + appropriate header or source file exist describing a public interface, + replace the inclusion with a paragraph containing the text + "Not Applicable"--> + <section id="ux500_dma.c"> + <title>ux500_dma.c</title> +!Idrivers/usb/musb/ux500_dma.c + </section> + <section id="ux500.c"> + <title>ux500.c</title> +!Idrivers/usb/musb/ux500.c + </section> +</chapter> +</book> |