This patch adds documentation for the ST-Ericsson CG2900 Connectivity controller. Signed-off-by: Par-Gunnar Hjalmdahl <par-gunnar.p.hjalmdahl@xxxxxxxxxxxxxx> --- Documentation/DocBook/Makefile | 2 +- Documentation/DocBook/cg2900.tmpl | 1332 +++++++++++++++++++++++++++++++++++++ 2 files changed, 1333 insertions(+), 1 deletions(-) create mode 100644 Documentation/DocBook/cg2900.tmpl diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 8b6e00a..e8319ec 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -14,7 +14,7 @@ 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 media.xml drm.xml + tracepoint.xml media.xml drm.xml cg2900.xml ### # The build process is as follows (targets): diff --git a/Documentation/DocBook/cg2900.tmpl b/Documentation/DocBook/cg2900.tmpl new file mode 100644 index 0000000..e7eef1b --- /dev/null +++ b/Documentation/DocBook/cg2900.tmpl @@ -0,0 +1,1332 @@ +<?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@xxxxxxxxxxxxxx</email> + </address> + </affiliation> + </author> + <author> + <firstname>Par-Gunnar</firstname> + <surname>Hjalmdahl</surname> + <affiliation> + <address> + <email>par-gunnar.p.hjalmdahl@xxxxxxxxxxxxxx</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 Connectivity Driver for enabling + ST-Ericsson Connectivity 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 STE connectivity driver. + </para> + <para> + There must be firmware and settings files that match the used chip version inside the firmware folder. + The files: + <itemizedlist> + <listitem><para>cg2900_patch_info.fw.org</para></listitem> + <listitem><para>cg2900_settings_info.fw.org</para></listitem> + </itemizedlist> + handle the mapping between chip version and correct firmware file (patch resp static settings file). + The necessary patch and settings 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> + + <!-- 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 connectivity driver using KConfig go to <constant>Device Drivers -> Multifunction Device Drivers</constant> + and enable the STE Connectivity Driver. If BlueZ shall be used as Bluetooth stack also enable the STE HCI Connectivity driver. + Depending on choice the driver will either be included as LKM or built into the Kernel. + If building as LKM, 2 files will be generated: + <itemizedlist> + <listitem><para>cg2900.ko which contains the main 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 Connectivity 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, currently SPI and UART. + Apart from just transporting data between stacks and the chip, the ST-Ericsson Connectivity 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>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>cg2900_register_user</function>. + This function will search for the supplied channel by using name look-up and open the channel. + The function will return with a device reference that shall be used when calling the other CG2900 API functions. + </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. + This function will open the 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 connectivity 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>cg2900_deregister_user</function>. + This function will close the channel and also free the allocated device that was allocated when registering. + </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 ST-E connectivity driver. + All other data in the packet shall however exist in the packet in the format correct for that HCI channel. + The ST-E connectivity users need to perform flow control over channels so any ticket handling + 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>cg2900_alloc_skb</function>. This function will return an sk_buff (Socket buffer) structure that + has necessary space reserved for ST-E driver operation. + The stack shall then copy the data, preferrably using <function>skb_put</function>, and then call + <function>cg2900_write</function> to perform the write operation. When the function returns, the buffer has + 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 ST-E connectivity driver. + All other data in the packet in the packet is in the format correct for that HCI channel. + The ST-E connectivity driver does not perform any flow control over the H:4 channel so any ticket handling + 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 calling + <function>cg2900_register_user</function>. This callback function will be called when the ST-E connectivity driver has + received a packet. The packet received will always be a complete HCI packet, i.e. no fragmention on HCI layer. + When 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 connectivity 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>cg2900_reset</function>. + This will trigger a hardware reset of the controller. When the hardware reset is finished all registered users will be called + through respective reset callback. When the callback function is finished the registered device will be removed and when all + registered users have been informed and removed, the chip is shutdown. This is similar to a deregistration of all registered + channels. The stack will then have to reregister to the ST-E connectivity driver in order to use the channel once again. + </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 register to the FM channel, write a packet, read a packet and then deregister. + + <programlisting> + struct cg2900_device *my_dev; + bool event_received; + + void read_cb(struct cg2900_device *dev, struct sk_buff *skb) + { + event_received = true; + kfree_skb(skb); + } + + void reset_cb(struct cg2900_device *dev) + { + /* Handle reset. Device will be automatically freed by the ST-E driver */ + my_dev = NULL; + } + + static struct cg2900_callbacks my_cb = { + .read_cb = read_cb, + .reset_cb = reset_cb + }; + + void example_open(void) + { + my_dev = cg2900_register_user(CG2900_FM_RADIO, &my_cb); + if (!my_dev) { + printk("Error! Couldn't register!\n"); + } + } + + void example_close(void) + { + cg2900_deregister_user(my_dev); + my_dev = NULL; + } + + void example_write_and_read(uint8_t *data, int len) + { + int err; + struct sk_buff *skb = cg2900_alloc_skb(len, GFP_KERNEL); + + if (skb) { + memcpy(skb_put(skb, len), data, len); + err = cg2900_write(my_dev, skb); + if (!err) { + event_received = false; + + while (!event_received) { + /* Wait for ack event. Received in read_cb() above */ + schedule_timeout_interruptible(jiffies + 50); + } + } else { + printk("Couldn't write to controller (%d)\n", err); + kfree_skb(skb); + } + } + } + </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 Connectivity 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> + For debug purposes the define CG2900_DEBUG_LEVEL in the file cg2900_debug.h can be changed to set how much debug printouts + that shall be generated. + <itemizedlist> + <listitem><para>0 - No debug</para></listitem> + <listitem><para>1 - Error printouts</para></listitem> + <listitem><para>10 - Info printouts such as start of each function</para></listitem> + <listitem><para>20 - Debug printouts such as descriptions of operations</para></listitem> + <listitem><para>25 - Data printouts without content</para></listitem> + <listitem><para>30 - Data printouts with content</para></listitem> + </itemizedlist> + <!-- 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>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 0xEF</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>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>Modifiable</para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The parameter debug_level in cg2900_core.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>0 = No debug</para></listitem> + <listitem><para>1 = Error prints</para></listitem> + <listitem><para>10 = General info, e.g. function entries</para></listitem> + <listitem><para>20 = Debug info, e.g. steps in a functionality</para></listitem> + <listitem><para>25 = Data info, i.e. prints when data is transferred</para></listitem> + <listitem><para>30 = Data content, i.e. contents of the transferred data</para></listitem> + </itemizedlist> + </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>0</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>void</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>void</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>void</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>CG2900_CHAR_DEV_IOCTL_GET_REVISION</constant> IOCTL returns the revision value + of the local connectivity controller if such information is available. + </para><para> + IOCTL value created using <constant>_IOR('U', 213, int)</constant>. + </para><para> + Returned values are according to information that may be retrieved from chip manufacturer. + It is however possible to get indications of the value by looking in the file + <constant>firmware/cg2900_patch_info.fw.org</constant>. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>CG2900_CHAR_DEV_IOCTL_GET_SUB_VER</constant></term> + <listitem> + <variablelist> + <varlistentry> + <term>Direction</term> + <listitem><para>Query</para></listitem> + </varlistentry> + <varlistentry> + <term>Parameter</term> + <listitem><synopsis><type>void</type></synopsis></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para> + The <constant>CG2900_CHAR_DEV_IOCTL_GET_SUB_VER</constant> IOCTL returns the sub-version value + of the local connectivity controller if such information is available. + </para><para> + IOCTL value created using <constant>_IOR('U', 214, int)</constant>. + </para><para> + Returned values are according to information that may be retrieved from chip manufacturer. + It is however possible to get indications of the value by looking in the file + <constant>firmware/cg2900_patch_info.fw.org</constant>. + </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 connectivity driver except for the CCD 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>User Space Control</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_us_ctrl</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_us_ctrl is the device for initialization and control of the STE CONN driver.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>CCD Test stub</term> + <listitem> + <variablelist> + <varlistentry> + <term>File</term> + <listitem><para><filename>/dev/cg2900_ccd_test</filename></para></listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem> + <para>The cg2900_ccd_test is the device for performing module tests of the ST-Ericsson connectivity driver. It acts as a stub replacing the transport towards the chip. It is of the type Misc devices.</para> + </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>CG29XX 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 CG29XX 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 CG29XX 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> + + </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> + </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/mfd/cg2900/cg2900_core.c + </section> + <section id="cg2900_audio.h"> + <title>cg2900_audio.h</title> +!Edrivers/mfd/cg2900/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_core.h"> + <title>cg2900_core.h</title> +!Edrivers/mfd/cg2900/cg2900_core.h + </section> +</chapter> +</book> -- 1.6.3.3 -- To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
