Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

Shared Transport Driver

From Texas Instruments Wiki
Jump to: navigation, search

Introduction

This document provides design details of Bluetooth (BT) solution, with Shared Transport for Linux based platforms. Shared Transport (ST) software will enable BT protocol or software components to interact with their respective cores using a single physical port (UART). TI_ST uses logical channels, over physical transport, to communicate with individual cores.

Concept

TI’s Wireless Connectivity chips support Bluetooth (BT), WiFi, and GPS technology cores in a single die. Such a multi-core combo chip will be interfaced to the application processor using a single physical port (like UART). Shared Transport (ST) software will enable BT and GPS protocols or software components to interact with their respective cores over single physical port. ST uses logical channels, over physical transport, to communicate with individual cores. Logical channels 1, 2, 3, and 4 are used for BT packets, channel 8 for FM, channel 9 for GPS and channels 30, 31, 32, and 33 are used for Chip Power Management (PM).

ST Concept NEW.png

System Architecture

Following is the system architecture for BT and GPS combined solution with Shared Transport.
ST Architecture.png

Shared Transport Driver

Shared Transport (ST) driver is a line discipline driver that enables sharing of single physical port (UART) among BT and GPS components. ST driver allows one or more components to register and deregister with it. ST driver uses logical channels for BT and GPS as shown below:

Protocol

Channel #

Usage

Bluetooth

1

Host to send HCI commands to chip

2

Host and chip to exchange ACL data packets

3

Host and chip to exchange SCO data packets

4

Chip to send HCI event packets to host

GPS

9

Host to send GPS commands to chip and for chip to send GPS events to host

Power Management (HCILL)

30

Chip to send sleep indication to host

31

Host to send sleep acknowledge to chip

32

Host/Chip to send wakeup indication to chip/host

33

Host/Chip to send wakeup acknowledgement to chip/host


ST driver includes Kernel Initialization Manager (KIM) that enables communication with BT and GPS cores. As part of this initialization, KIM downloads BT initialization script. Also, KIM enables and disables BT_EN GPIO, when BT and GPS drivers register and de-register with ST driver, respectively. ST driver handles Connectivity chip power management to support Sleep and Wakeup states of Connectivity chip. ST driver uses HCILL protocol messages to control Sleep and Wakeup states of the chip. Shared Transport driver will contain 3 sub-modules: ST Core, ST Kernel space Initialization Manager (ST KIM) and ST HCILL. ST KIM will work in conjunction with User Space Initialization Manager (UIM). This section will also provide details of UIM.

ST Core

ST Core will provide following functionality:

• Core will provide APIs for BT/GPS drivers to register, de-register, and send protocol packets

• If ST Core is busy sending current packet, it will buffer new requests to send protocol packets

• ST Core will provide packets received from chip to BT/GPS drivers by calling callback routines registered by the protocol driver
• ST Core will maintain a finite state machine to handle multiple register, de-register, and send requests

• When first register request is received from the user space, ST Core will interact with KIM to initialize transport and chip. When last de-register request is received, ST Core will interact with KIM to de-initialize transport and chip

• ST Core will interact with ST HCILL to get state information of chip and to wakeup chip when required


ST Core will maintain list of registered protocols to avoid multiple registrations and incorrect de-registrations. This list of unique IDs can be extended to support new protocols.

ST Core will use TTY interface to communicate with TI Connectivity chip. TTY device corresponding to physical port will be opened ONLY when ST Core receives first registration request. TTY device will be closed when last protocol de-registers from ST driver. Thus, ST Core will access TTY device only when at least one protocol wants to communicate with the chip. This concept will ensure more power saving.

While handling first registration request, ST Core will request KIM to access TTY device, enable required GPIOs and download BT initialization script. This operation may take few seconds. While first registration is in progress, if other protocol (in a new process) calls register API of ST driver, ST Core will mark this second registration as pending and return control from register API immediately to caller. After successful completion of first registration, ST Core will complete any pending registration requests by calling “registration complete” callbacks of corresponding protocol drivers.

After registration with ST driver, the protocol driver will be allowed to send its protocol packets to TI Connectivity chip. Send API of ST Core will buffer such packets in a TX queue. Simple First-In-First-Out (FIFO) priority logic is applied to buffered protocol packets. On receiving send request, ST Core will check Connectivity chip state with ST HCILL and will request ST HCILL to awake the chip if required. When ST HCILL indicates that chip is now awake, ST Core will send buffered packets to chip over TTY layer.

On receiving data from chip via TTY interface, ST Core will pack this stream of bytes into BT/GPS packet using packet type and length information. Every receive buffer from TTY may contain data for one or more protocol packets. State machine of ST Core will pack these bytes into valid and complete protocol packets. Then, ST Core will call registered receive callback of corresponding protocol driver to deliver this complete packet.

While handling last de-register request, ST Core will request KIM to disable BT GPIO and close TTY device.


UIM and ST KIM

ST UIM and ST KIM together provide following functionality:

• Initialize and de-initialize TI Connectivity chip when requested by ST Core

• Ensure actual physical port is used only when at least one protocol wants to communicate with the Connectivity chip

• As part Connectivity chip initialization, UIM will open TTY device and set ST line discipline. While, KIM will enable BT GPIO and download BT initialization script

• As part chip de-initialization, KIM will disable BT GPIO. While, UIM will restore TTY line discipline and close TTY device


ST UIM will start at boot and will run as a daemon. On start, UIM will install ST driver (if driver is built as individual kernel object). During installation of ST driver, ST Core will initialize ST KIM module.

At init, ST KIM will create sysfs entries in: “/sys/devices/kim.X/”

Starting uim-sysfs daemon.
uim:@ main
uim:install = /sys/./devices/kim.12/install
uim:dev_name = /sys/./devices/kim.12/dev_name
uim:baud_rate = /sys/./devices/kim.12/baud_rate
uim:flow_cntrl = /sys/./devices/kim.12/flow_cntrl

After installing ST driver, UIM will wait for signal from KIM to open TTY device corresponding to physical port and install ST line discipline. If UIM is opening TTY device for a UART port, it will set UART baud as 115200, as TI Connectivity chip will start with this baud. Then, UIM will send a HCI Vendor Specific (VS) command to set higher baud (say 3 Mbps) specified by user (in the kernel board file or dts). Before UIM reads response for HCI VS command, it will configure local UART for this new higher baud, and then read response for VS command on new baud. Then, UIM will install ST line discipline by calling TTY function. Now, UIM will be waiting for signal from KIM to restore TTY line discipline and close TTY device.

During module init of ST driver, KIM will be initialized. As explained above, during init, KIM will create a sysfs entry “/sys/devices/kim.X/”. When handling first protocol register request, ST Core will request KIM to initialize chip. At this point, KIM will enable BT GPIO using GPIO sub-system interface and signal UIM to open TTY device via the sysfs entry: “install”. The UIM keeps polling on the “install” sysfs entry. Once it is set by the KIM, UIM will set the baud rate as per the “baud_rate” sysfs entry and install the ST line discipline.

Continuing with chip initialization, KIM will download Bluetooth initialization script as explained below:


• Send init script commands as channel 1 vendor specific commands and wait for response in the form of channel 4 events. If proper response is not received within expected time, it will stop downloading of init script and inform ST Core

• Ignore all remarks in the init script file

• Make host to sleep for some amount of time (as (if) mentioned in init script)

• The rest of the commands in init script, which are related to host (like command for configuring host UART baud) configuration, will be ignored in KIM.

While handling de-register request for last protocol, ST Core will request KIM to de-initialize chip. At this point, KIM will disable BT GPIO and signal UIM to restore TTY line discipline and close TTY device.


ST HCILL

ST HCILL will handle Connectivity chip power management (PM) using TI’s HCILL protocol (see: http://processors.wiki.ti.com/index.php/CC256x_eHCILL_Low_Power_Protocol ). It supports Sleep and Wakeup states of TI Connectivity chip. As defined in HCILL protocol, it uses logical channels 30, 31, 32, and 33 to exchange PM messages with the chip.

ST HCILL will maintain the Sleep and Wakeup states of the chip. When chip sends a “sleep indication” or “wakeup indication” message, ST HCILL will send acknowledgement and will update its state information. Before sending any packet to chip via TTY, ST Core will request ST HCILL to wakeup chip, if chip is asleep.


Bluetooth Driver

In addition to the TI Bluetooth Stack, the Shared Transport driver allows the integration of other proprietary stacks that run exclusively on the user space.
This is done by making use of the hci_tty driver (CONFIG_ST_HCI)

There is also an option to integrate the shared transport with the BlueZ stack. For this, the btwilink (CONFIG_BT_WILINK) driver is used. This will register with the hci_core, and handle all requests to the hci0 interface from user space.

Depending on which stack is used, only either of the below drivers/configs are required.

Hci_tty driver

The hci_tty driver will be a new kernel module that will register with the ST driver and provide a character driver for use with both the TI Bluetooth Stack and other proprietary stacks that runs in the user space.

During driver initialization, the hci_tty will expose the “/dev/tty_hci” interface for use by the userspace stacks. Opening “/dev/tty_hci” will start the BT ON procedure. While handling “open” request, the hci_tty driver will register with ST. As ST driver enables BT GPIO and downloads BT init script when first protocol registers with ST, the hci_tty driver will NOT download BT init script as part of BT ON.

Hci_tty driver will use send function of ST driver to send packets to chip. When ST driver calls receive callback provided, hci_tty driver will queue received packet for handling in different context. Closing of the /dev/tty_hci device is considered as BT OFF operation. While handling this request, hci_tty will de-register from ST driver.

Handling of chip power management messages, received from Connectivity chip, will be handled by the new ST HCILL module.

Btwilink driver

During module initialization, BT driver will request HCI core to expose “hci0” interface for user space libraries or applications. Receiving IOCTL “HCIDEVUP” on “hci0” device will be the start of BT ON operation. While handling this request, BT driver will register with ST driver. Receiving IOCTL “HCIDEVDOWN” is considered as BT OFF operation. While handling this request, btwilink will de-register from ST driver.

GPS Character Driver

GPS Character device driver will be a new kernel module that exposes device “/dev/tigps”. User space GPS Host software will use this device to communicate with Connectivity chip. GPS driver will register with ST driver to communicate with Connectivity chip.

During initialization, GPS driver will expose “/dev/tigps” device for user space GPS software. Opening device “/dev/tigps” will be the start of GPS ON operation. While handling open request, GPS driver will register with ST driver. As part of GPS registration, ST driver will enable BT_EN GPIO.

GPS driver will frame GPS commands as Channel 9 packets. GPS driver will use send function of ST driver to send GPS commands to chip. When ST driver calls receive callback provided, GPS driver will queue received packet for handling in different context.

Also, GPS driver will consume flow control packets received (from GPS core) for GPS commands sent from user space GPS software. This is required as user space GPS software doesn’t handle flow control packets. Closing device “/dev/tigps” is considered as GPS OFF operation. While handling close request, GPS driver will de-register from ST driver.

Kernel changes for ST

This section deals with the kernel changes that are required to integrate and enable the shared transport driver.

Configuration changes (defconfig)

Following configuration are required to enable Shared Transport Driver.

#Shared Transport Driver
CONFIG_TI_ST=y
CONFIG_ST_HCI=y

#For BlueZ
CONFIG_BT_WILINK=y

Platform changes

Pre-Device Tree kernel

• The platform data for Bluetooth holds information about the BT_EN line, the UART device used for Bluetooth, Flow Control Enable/Disable and the Baud Rate.

• In the below example for AM335x platform, we are setting the BT_EN GPIO as 117, flow control is enabled, and baud rate is set as 3M.

• am335xevm_init_st_platform_data() is called during the wl12xx_init() routine.

struct ti_st_plat_data wilink_pdata = {
	.nshutdown_gpio = GPIO_TO_PIN(3, 21),  /* default setting for AM335x EVM and SK */
	.dev_name = "/dev/ttyO1",
	.flow_cntrl = 1,
	.baud_rate = 3000000,
};

static struct platform_device wl12xx_device = {
	.name		= "kim",
	.id		= -1,
	.dev.platform_data = &wilink_pdata,
};

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

static inline void __init am335xevm_init_st_platform_data(void)
{
	platform_device_register(&wl12xx_device);
	platform_device_register(&btwilink_device);
}

Device Tree kernel

kim {
	compatible = "kim";
	nshutdown_gpio = <117>; /* Bank3, pin21 */
	dev_name = "/dev/ttyO1";
	flow_cntrl = <1>;
	baud_rate = <3000000>;
};

btwilink {
	compatible = "btwilink";
};

UART Initialization

On the AM335x-EVM UART1 is used and we need to mux its pins into UART mode in order to work with it.

Pre-Device Tree kernel

The structure below is used for performing this pin muxing. In strucure we mux the four UART pins (Rx,Tx,CTS,RTS)

static struct pinmux_config uart1_wl12xx_pin_mux[] = {
	{"uart1_ctsn.uart1_ctsn", OMAP_MUX_MODE0 | AM33XX_PIN_INPUT},
	{"uart1_rtsn.uart1_rtsn", OMAP_MUX_MODE0 | AM33XX_PIN_OUTPUT},
	{"uart1_rxd.uart1_rxd",	  OMAP_MUX_MODE0 | AM33XX_PIN_INPUT_PULLUP},
	{"uart1_txd.uart1_txd",   OMAP_MUX_MODE0 | AM33XX_PULL_ENBL},
	{NULL, 0},
};

The uart1_wl12xx_init() functions use this structure for performing the UART pin muxing:

static void uart1_wl12xx_init(int evm_id, int profile)
{
	setup_pin_mux(uart1_wl12xx_pin_mux);
}

Device Tree kernel

Use the below for muxing the pins in UART mode for kernels that make use of the Device Tree mechanism ( "CONFIG_OF=y" )

uart1_pins_default: pinmux_uart1_pins_default {
	pinctrl-single,pins = <
		0x178 (PIN_INPUT | MUX_MODE0)		/* uart1_ctsn.uart1_ctsn */
		0x17C (PIN_OUTPUT_PULLDOWN | MUX_MODE0)	/* uart1_rtsn.uart1_rtsn */
		0x180 (PIN_INPUT_PULLUP | MUX_MODE0)	/* uart1_rxd.uart1_rxd */
		0x184 (PIN_OUTPUT_PULLDOWN | MUX_MODE0) /* uart1_txd.uart1_txd */
	>;
};

See Also