LinuxLists.cc - [PATCH 9/9] DocBook: Add ST-Ericsson CG2900 docs

2010-10-22 10:41:00

Subject: [PATCH 9/9] DocBook: Add ST-Ericsson CG2900 docs

This patch adds documentation for the ST-Ericsson CG2900
Connectivity controller.

Signed-off-by: Par-Gunnar Hjalmdahl <[email protected]>
---
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>[email protected]</email>
+ </address>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Par-Gunnar</firstname>
+ <surname>Hjalmdahl</surname>
+ <affiliation>
+ <address>
+ <email>[email protected]</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <copyright>
+ <year>2010</year>
+ <holder>ST-Ericsson SA</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 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
ST-Ericsson Connectivity Driver for enabling
+ ST-Ericsson Connectivity Combo Controller Hardware.
+
+ </para>
+ </chapter>
+
+ <chapter id="gettingstarted">
+ <title>Getting Started</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>
+
+ 
+ 
+
+ <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>
+
+ 
+ </para>
+
+ <para>
+ 
+ </para>
+ </section>
+
+ </chapter>
+
+ <chapter id="concepts">
+ <title>Concepts</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.
+ 
+ 
+ </para>
+ </chapter>
+
+ <chapter id="tasks">
+ <title>Tasks</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>
+
+ 
+ 
+ </para>
+ </chapter>
+
+ <chapter id="driver-configuration">
+ <title>Driver Configuration and Interaction</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>
+ 
+ 
+ 
+ </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 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>
+ 
+ </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>
+ 
+ </para>
+ </section>
+
+ <section id="driver-ioctl">
+ <title>Driver IO Control</title>
+ <para>
+ 
+ </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>
+ 
+ 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>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>
+ 
+ <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.
+ 
+ 
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </chapter>
+
+<chapter id="pubfunctions">
+ <title>Public Functions Provided</title>
+ <para>
+ List of public functions.
+ </para>
+ 
+ 
+ <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>
+ 
+ 
+ <section id="cg2900_core.h">
+ <title>cg2900_core.h</title>
+!Edrivers/mfd/cg2900/cg2900_core.h
+ </section>
+</chapter>
+</book>
--
1.6.3.3