Device Driver Interface of WiLink Solution

From OMAPpedia

Revision as of 21:23, 30 March 2011

Introduction

WL127x and WL128x are two generations of TI connectivity chips for the OMAP platforms. With any particular OMAP processor generation any particular generation of connectivity chip may be used (for a particular product). Generally used OMAP processor and connectivity chip combinations are:

• OMAP3 and WL127x (as in Zoom2, Zoom3 devices) or
• OMAP4 and WL128x (as in Blaze devices)

However, a few customers and internal development teams at TI use and need these (rare) combinations:

• OMAP3 + WL128x and
• OMAP4 + WL127x

The following hints are provided should you have an alternative combination of devices and have chosen not to use the devices on-board (for whatever reason):

Note that for on-board devices that come on a particular platform, i.e Zoom2/3 (with WL127x), Blaze (with WL128x) and Panda (with WL127x), the relevant software releases for the platform (or board) should get WiFi, Bluetooth and FM work out of the box.

It should be clear by now that any OMAP platform can use any TI WiLink device. Below list provides a couple of rare/odd combinations along with a couple of regular:

• OMAP3 + 1271 + 5500 (default for OMAP3)
• OMAP3 + 1283
• OMAP4 + 1283 (default for OMAP4)
• OMAP4 + 1271

Porting shared transport solution

Shared Transport driver is a line discipline driver, which acts a generic transport for Bluetooth, FM and GPS (in case of WL128x). Each such protocol drivers have a register, unregister mechanism with the shared transport driver and upon registration can do a write concurrently, and shared transport would queue up the data and would send it over UART. Upon receiving protocol specific data, shared transport would interpret the data and forward it to protocol driver via callbacks.

Shared transport driver is also a platform device driver and hence any platform which has a WL127x/WL128x device and wants to make use of this driver, need to have an entry of adding the platform device in their architecture specific board file.

Illustration:-

/* wl128x BT, FM, GPS connectivity chip */
struct ti_st_plat_data wilink_pdata = {
        .nshutdown_gpio = 55,
        .dev_name = "/dev/ttyO1",
        .flow_cntrl = 1,
        .baud_rate = 3000000,
};
static struct platform_device wl128x_device = {
        .name           = "kim",
        .id             = -1,
        .dev.platform_data = &wilink_pdata,
};

and in one of the architecture init functions, perform :- platform_device_register(&wl128x_device);

Hardware Interface and MUX mode configuration

The WiLink Connectivity chip's BT/FM/GPS IPs are interfaced with the application processor(OMAP) by UARTs. A GPIO line called "nShutDown" acts as the chip enable line for the connectivity chip. Apart from this the connectivity chip is interfaced to BT core via PCM lines (mcbsp if OMAP) and the FM core via i2S(or PCM). The BT-PCM lines carry the voice data during call scenario, and the FM i2S lines can be used for FM Rx audio (digital) or FM Tx audio.

The mux-mode configurations of these hardware interfaces can be done via the OMAP MUX framework supported by the BSP

Example: On Zoom3 where the N-Shut-Down line is connected to GPIO 109.
In file arch/arm/mach-omap2/board-zoom3.c you would find an entry,
        omap_mux_init_gpio(109, OMAP_PIN_OUTPUT);

The configurations can also be done in the x-loader or u-boot. The configurations might not happen in u-boot, if it is already being done in x-loader.

Example: On OMAP3SDP/Blaze's x-loader, the McBSP1 is connected to the BT-PCM lines,
In file board/omap4430sdp/omap4430sdp.c of the u-boot source code, you would find entries such as,
        MV(CP(ABE_MCBSP1_DX),   (OFF_EN | OFF_OUT_PTD | M0)) /* abe_mcbsp1_dx */ \
        MV(CP(ABE_MCBSP1_FSX),  (IEN | OFF_EN | OFF_PD | OFF_IN | M0)) /* abe_mcbsp1_fsx */ \
and
        MV(CP(ABE_MCBSP1_DX),   (OFF_EN | OFF_OUT_PTD | M0)) /* abe_mcbsp1_dx */ \
        MV(CP(ABE_MCBSP1_FSX),  (IEN | OFF_EN | OFF_PD | OFF_IN | M0)) /* abe_mcbsp1_fsx */ \

Example: On OMAP4SDP/Blaze, the OMAP UART2 is connected to the BT-HCI-UART
        MV(CP(UART2_CTS),       (PTU | IEN | M0)) /* uart2_cts */ \
        MV(CP(UART2_RTS),       (M0)) /* uart2_rts */ \
        MV(CP(UART2_RX),        (IEN | M0)) /* uart2_rx */ \
        MV(CP(UART2_TX),        (M0)) /* uart2_tx */ \

Note: Since there lacks a standard way to configure the hardware interfaces, please look into relevant BSP or contact the email ID mentioned below.

btwilink driver

BTWILINK driver at drivers/bluetooth/btwilink.c provides the bluetooth driver which makes use of the shared transport driver which talks to the bluetooth core on the WiLink chipsets. Enable this driver either as a module or as a built-in component along with necessary bluetooth functionality in the kernel.

Similar to the TI ST driver, this is also a platform device driver and requires a relevant platform device registration,

static struct platform_device btwilink_device = {
       .name = "btwilink",
       .id = -1,
};

The above platform device along with addition in one of the architecture init functions, would enable the Bluetooth driver for WiLink chipsets.

User Space components

A utility known as UIM is very much required for the shared transport [TI_ST] driver to be working. Most line disciplines if not all require a user-space daemon to be opening the UART and installing the line discipline thereby giving out the control to the line discipline driver.

UIM can be found @ http://git.omapzoom.org/?p=platform/hardware/ti/wpan.git;a=summary The latest can be found at gingerbread branch by name uim-sysfs, http://git.omapzoom.org/?p=platform/hardware/ti/wpan.git;a=tree;f=ti_st/uim-sysfs;h=12ce6bafd461474ad90d41a0b9523a94534e4c0a;hb=refs/heads/gingerbread

UIM needs to be run at boot, Since linux flavors might require Bluetooth or GPS to be turned on at boot. For this have the UIM entry in your either one of your rc.S files or you can have special udev rule based on the platform driver addition of device "kim". For Android, the following entry in init.rc should suffice,

service uim /system/bin/uim-sysfs
    user root
    group media bluetooth
    oneshot

firmware

Bluetooth, FM and GPS all require their own firmware files, with the Bluetooth firmware being required to be downloaded before any of the other cores are made use of in WiLink. https://gforge.ti.com/gf/project/wilink_drivers/ - Should point to the latest firmware files that are released.

Shared Transport driver uses the firmware class sub-system to download firmware and hence the firmware ".bts" files need to exist in /system/etc/firmware/ for Android and /lib/firmware/ for ubuntu.

On boot check

Since there are many versions of the drivers floating around and a lot needs to be done to get them all working fine. A few things below can be checked if the port went well.

• If you intend to build the TI ST driver, btwilink driver, FM and GPS drivers as modules, then st_drv.ko, btwilink.ko, fm_drv.ko and gps_drv.ko should exist in the file-system [at "/" for Android]
• The modules needs to be inserted manually if the UIM does not do the job at boot, and can be checked for by $lsmod
• sysfs directory /sys/devices/platform/kim should exist with important entries like install, dev_name, baud_rate present. These entries should also represent at which UART the WiLink is connected on platform.
• /sys/devices/platform/btwilink should exist. If this does then the hci0 interface can be checked for by simple bluez commands such as $hciconfig -a
• FM driver initialization can be confirmed by checking the device node /dev/radio0
• GPS driver initialization can be confirmed by checking the device node /dev/tigps

Enabling profiles on Android

• GAP - Generic Access Profile
  Bluetooth-Settings under Wireless Setting menu of the Setting Application in Android, allows you to Scan, Pair and Connect to devices, upon Scanning, the type of device is detected by Android and connection is made upon user's request.
• A2DP - Audio Streaming via Bluetooth
  This is one of those profiles, which has android has support for in its profile and is expected to work out of the box as soon as you have Bluetooth working. Apart from the baud-rate on UART no other factor should generally cause the A2DP profile to break on android.
• AVRCP - Audio Video Remote Control Profile
  This requires the uInput to be enabled in the kernel - make menuconfig for more details.
• HFP/HSP - Head Set and Hands Free (In-Call operation)
  While all other kind of bluetooth data goes over UART, this one goes over from the OMAP, to the BT via the McBSP. Different platforms have different configurations for the McBSP that has been interfaced with BT-PCM lines. Even without the Modem, the BT-PCM lines are verified by streaming music and record voice from the BT-headset.
• HID
  On connection to a Bluetooth Keyboard or Mouse, the HID functionality should work out of the box.
• PBAP/OPP
  Object push, Vcard listing should also work out of box, since Android provides them
• FTP
  3rd party applications like BlueFTP are available from Android App Market which should work without modifications upon installation.

Important Notes

The platform data and its structure tend to keep changing, and hence before adding the platform device, please make sure the platform data matches in type and structure of the platform data defined in include/linux/ti_wilink_st.h

Support Contacts

Write your queries to WCG Leads