Return-Path: MIME-Version: 1.0 Reply-To: pghatwork@gmail.com Date: Fri, 22 Oct 2010 12:41:00 +0200 Message-ID: Subject: [PATCH 9/9] DocBook: Add ST-Ericsson CG2900 docs From: Par-Gunnar Hjalmdahl To: linus.walleij@stericsson.com, linux-bluetooth@vger.kernel.org, linux-kernel@vger.kernel.org Content-Type: text/plain; charset=ISO-8859-1 Sender: linux-bluetooth-owner@vger.kernel.org List-ID: This patch adds documentation for the ST-Ericsson CG2900 Connectivity controller. Signed-off-by: Par-Gunnar Hjalmdahl --- 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 @@ + + + + + + CG2900 Driver + + + + Henrik + Possung + +
+ henrik.possung@stericsson.com +
+ + + + Par-Gunnar + Hjalmdahl + +
+ par-gunnar.p.hjalmdahl@stericsson.com +
+ + + + + + 2010 + ST-Ericsson SA + + + + + Connectivity + + + + + + + + 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. + + + + 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. + + + + 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 + + + + For more details see the file COPYING in the source + distribution of Linux. + + + + + + + + Introduction + + + This documentation describes the functions provided by the ST-Ericsson Connectivity Driver for enabling + ST-Ericsson Connectivity Combo Controller Hardware. + + + + + + Getting Started + + + There are no special compilation flags needed to build the STE connectivity driver. + + + There must be firmware and settings files that match the used chip version inside the firmware folder. + The files: + + cg2900_patch_info.fw.org + cg2900_settings_info.fw.org + + 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 .fw.org.. + Note that there is a limitation in the Kernel firmware system regarding name length of a file. + + + + + +
+ Basic Tutorial + + To enable the ST-Ericsson connectivity driver using KConfig go to Device Drivers -> Multifunction Device Drivers + 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: + + cg2900.ko which contains the main driver + btcg2900.ko which contains the registration and mapping towards the BlueZ Bluetooth stack + + + + + + + + +
+ + + + + Concepts + + + 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. + + + + + + + Tasks + + + + + + Opening a channel + + + 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. + + + + Opening a channel from Kernel space + + + When a stack is placed in Kernel space, it shall open a channel by calling the API function cg2900_register_user. + 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. + + + + + + + + Opening a channel from User space + + + When a stack is placed in User space, it shall open a channel by calling the syscall function open on the corresponding file. + The files are located in folder /dev/ and are named cg2900_gnss and similar. Each file + corresponds to one H:4 channel. + This function will open the channel. + + + + + + + + + + + Closing a channel + + + 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. + + + + Closing a channel from Kernel space + + + When a stack is placed in Kernel space, it shall close a channel by calling the API function + cg2900_deregister_user. + This function will close the channel and also free the allocated device that was allocated when registering. + + + + + + + + Closing a channel from User space + + + When a stack is placed in User space, it shall close a channel by calling the syscall function + close on the corresponding file. + + + + + + + + + + + Writing to a channel + + + 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. + + + + Writing to a channel from Kernel space + + + When a stack is placed in Kernel space, it shall start with allocating a packet of the correct size using + cg2900_alloc_skb. 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 skb_put, and then call + cg2900_write 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. + + + + + + + + Writing to a channel from User space + + + When a stack is placed in User space, it shall call the write 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. + + + + + + + + Writing to FM_Radio and FM_Audio channel + + + 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. + + + + + + + + + + + Reading from a channel + + + 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. + + + + Reading from a channel from Kernel space + + + When a stack is placed in Kernel space, it has to supply a callback function for the receive functionality when calling + cg2900_register_user. 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 + kfree_skb when it is no more needed. + + + + + + + + Reading from a channel from User space + + + When a stack is placed in User space, it shall call the read 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 poll 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. + + + + + + + + + + + Reset handling + + + 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. + + + + Reset handling from Kernel space + + + When a stack is placed in Kernel space, it initiates a Reset operation by calling cg2900_reset. + 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. + + + + + + + + Reset handling from User space + + + When a stack is placed in User space, it shall call the ioctl function on + the corresponding file to perform a reset operation. The command parameter CG2900_CHAR_DEV_IOCTL_RESET + shall be used when calling ioctl. + When the ioctl 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 poll 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. + + + + + + + + + + + Example code Kernel space + + + This example will register to the FM channel, write a packet, read a packet and then deregister. + + + 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); + } + } + } + + + + + + + Example code User space + + + 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 read and ioctl read through a separate thread, + preferrably using poll. + + + 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; + } + + + + + + + + + + + + + Driver Configuration and Interaction + + + 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. + + 0 - No debug + 1 - Error printouts + 10 - Info printouts such as start of each function + 20 - Debug printouts such as descriptions of operations + 25 - Data printouts without content + 30 - Data printouts with content + + + + + + +
+ Implemented operations in driver + + + + + + Supported device driver operations when using character device + + open Opening a character device will register the caller to that HCI channel. + release Releasing a character device will deregister the caller from that HCI channel + poll Polling a character device will check if there is data to read on that HCI channel + read Reading from a character device reads from that HCI channel + write Writing to a character device writes to that HCI channel + unlocked_ioctl Performing IO control on a character device will perform special operations such as reset on that HCI channel + +
+ +
+ +
+ Driver loading parameters + + + + + + uart_default_baud + + + + + Parameter type + int + + + Default value + 115200 + + + Runtime readable/modifiable + Readable + + + Description + + + 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. + + + + + + + + + + uart_high_baud + + + + + Parameter type + int + + + Default value + 3000000 + + + Runtime readable/modifiable + Modifiable + + + Description + + + 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: + + 57600 + 115200 + 230400 + 460800 + 921600 + 2000000 + 3000000 + 4000000 + + + + + + + + + + + bd_address + + + + + Parameter type + array (Entered as comma separated value) + + + Default value + 0x00 0x80 0xDE 0xAD 0xBE 0xEF + + + Runtime readable/modifiable + Modifiable + + + Description + + + 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. + + + + + + + + + + debug_level + + + + + Parameter type + int + + + Default value + 1 + + + Runtime readable/modifiable + Modifiable + + + Description + + + 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: + + 0 = No debug + 1 = Error prints + 10 = General info, e.g. function entries + 20 = Debug info, e.g. steps in a functionality + 25 = Data info, i.e. prints when data is transferred + 30 = Data content, i.e. contents of the transferred data + + + + + + + + + + sleep_timeout_ms + + + + + Parameter type + int + + + Default value + 0 + + + Runtime readable/modifiable + Modifiable + + + Description + + + The parameter sleep_timeout_ms in cg2900_core.c defines the sleep timeout for data transmission in milliseconds. + + + + + + + + + + + +
+ +
+ Driver IO Control + + + + + + CG2900_CHAR_DEV_IOCTL_RESET + + + + Direction + Set + + + Parameter + void + + + Description + + + The CG2900_CHAR_DEV_IOCTL_RESET IOCTL starts a reset + of the connectivity chip. This will affect the current open channel and + all other open channels as well. + + IOCTL value created using _IOW('U', 210, int). + + Returned values are: + + If reset is performed without errors the IOCTL function will return 0. + A negative value will indicate error. + + + + + + + + + + CG2900_CHAR_DEV_IOCTL_CHECK4RESET + + + + Direction + Query + + + Parameter + void + + + Description + + + The CG2900_CHAR_DEV_IOCTL_CHECK4RESET IOCTL checks if a reset + has been performed on a device. + + IOCTL value created using _IOR('U', 212, int). + + Returned values are: + + If device is still open the IOCTL function will return 0. + If reset has occurred the IOCTL function will return 1. + If device has been closed the IOCTL function will return 2. + A negative value will indicate error. + + + + + + + + + + CG2900_CHAR_DEV_IOCTL_GET_REVISION + + + + Direction + Query + + + Parameter + void + + + Description + + + The CG2900_CHAR_DEV_IOCTL_GET_REVISION IOCTL returns the revision value + of the local connectivity controller if such information is available. + + IOCTL value created using _IOR('U', 213, int). + + 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 + firmware/cg2900_patch_info.fw.org. + + + + + + + + + CG2900_CHAR_DEV_IOCTL_GET_SUB_VER + + + + Direction + Query + + + Parameter + void + + + Description + + + The CG2900_CHAR_DEV_IOCTL_GET_SUB_VER IOCTL returns the sub-version value + of the local connectivity controller if such information is available. + + IOCTL value created using _IOR('U', 214, int). + + 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 + firmware/cg2900_patch_info.fw.org. + + + + + + + + +
+ +
+ Driver Interaction with Sysfs + + + Not Applicable + +
+ +
+ Driver Interaction using /proc filesystem + + Not Applicable + + +
+ +
+ Other means for Driver Interaction + + + Not Applicable + +
+ +
+ Driver Node File + + + CG2900 main device + + + + File + /dev/cg2900_driver0 + + + Description + + 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. + + + + + + + + BT Command + + + + File + /dev/cg2900_bt_cmd + + + Description + + The cg2900_bt_cmd is the device for the HCI Bluetooth command channel. + + + + + + + + BT ACL + + + + File + /dev/cg2900_bt_acl + + + Description + + The cg2900_bt_acl is the device for the HCI Bluetooth ACL channel. + + + + + + + + BT Event + + + + File + /dev/cg2900_bt_evt + + + Description + + The cg2900_bt_evt is the device for the HCI Bluetooth event channel. + + + + + + + + FM Radio + + + + File + /dev/cg2900_fm_radio + + + Description + + The cg2900_fm_radio is the device for the HCI FM Radio channel. + + + + + + + + GNSS + + + + File + /dev/cg2900_gnss + + + Description + + The cg2900_gnss is the device for the HCI GNSS channel. + + + + + + + + Debug + + + + File + /dev/cg2900_debug + + + Description + + The cg2900_debug is the device for the HCI Debug channel. + + + + + + + + ST-Ericsson Tools + + + + File + /dev/cg2900_ste_tools + + + Description + + The cg2900_ste_tools is the device for the HCI ST-Ericsson tools channel. + + + + + + + + HCI Logger + + + + File + /dev/cg2900_hci_logger + + + Description + + The cg2900_hci_logger is the device for the HCI logger channel. + + + + + + + + User Space Control + + + + File + /dev/cg2900_us_ctrl + + + Description + + The cg2900_us_ctrl is the device for initialization and control of the STE CONN driver. + + + + + + + + CCD Test stub + + + + File + /dev/cg2900_ccd_test + + + Description + + 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. + + + + + + + + BT Audio + + + + File + /dev/cg2900_bt_audio + + + Description + + The cg2900_bt_audio is the device for sending HCI BT Audio controll commands to the chip. + + + + + + + + FM Audio + + + + File + /dev/cg2900_fm_audio + + + Description + + The cg2900_fm_audio is the device for sending HCI BT Audio controll commands to the chip. + + + + + + + + Core + + + + File + /dev/cg2900_core + + + Description + + The cg2900_core is a device for turn on/off the chip. NOTE other devices will also turn on/off the chip if needed. + + + + + + + + CG29XX Audio + + + + File + /dev/cg2900_audio + + + Description + + + The cg2900_audio is a device for testing the CG2900 Audio driver from User space. + It replicates the normal CG2900 Audio interface through write/read operations. + The write command is used as following: + + 4 byte op code (see below) + Data field according to respective CG29XX Audio function (no session ID needed) + + If the operation fails the write command operation will return the error. + Op codes are (4 bytes size): + + 0x00000001 = CHAR_DEV_OP_CODE_SET_DAI_CONF + 0x00000002 = CHAR_DEV_OP_CODE_GET_DAI_CONF + 0x00000003 = CHAR_DEV_OP_CODE_CONFIGURE_ENDPOINT + 0x00000004 = CHAR_DEV_OP_CODE_CONNECT_AND_START_STREAM + 0x00000005 = CHAR_DEV_OP_CODE_STOP_STREAM + + + The read command is used for the commands CHAR_DEV_OP_CODE_GET_DAI_CONF + and CHAR_DEV_OP_CODE_CONNECT_AND_START_STREAM if the corresponding commands are successful. + The returned data will be formatted accordingly: + + 4 byte op code (see below) + Data field according to normal CG29XX Audio functions, e.g. stream handle or configuration + + The CHAR_DEV_OP_CODE_GET_DAI_CONF is a bit special since it require an endpoint in-parameter + (when calling write) to return the corresponding DAI configuration when calling read. + + + + + + + + +
+ + + + + + + Known Bugs And Assumptions + + + + + Driver supports only one user per HCI channel. + + + To simplify design and limitation as well as keeping the API simple and reliable, the driver only supports one user per HCI channel. + + + + + + + + + + + Public Functions Provided + + List of public functions. + + + +
+ cg2900.h +!Edrivers/mfd/cg2900/cg2900_core.c +
+
+ cg2900_audio.h +!Edrivers/mfd/cg2900/cg2900_audio.c +
+ + + + + Internal Functions Provided + + List of internal functions. + + + +
+ cg2900_core.h +!Edrivers/mfd/cg2900/cg2900_core.h +
+ + -- 1.6.3.3