Merge "USB: ccid_bridge: Add support for USB smart card class"

Introduction

============

This feature requires supporting Mass Storage and Integrated Circuit Card

interfaces exposed by the UICC (Universal Integrated Circuit Card) device.

The MSM acts as a USB host and UICC acts as a peripheral. The UICC device

that is used here is also referred to as Mega-SIM. This feature will be

supported on MSM8x26.

Hardware description

====================

The USB3503 HSIC (High Speed Inter Chip) hub's down stream port is modified

to support Inter-Chip USB for connecting the UICC device. The USB3503 is

connected to MSM via HSIC interface. The UICC device operates in Full Speed

mode.

The UICC device will support CCID (Integrated Circuit Card interface Device)

specification. This interface supports 1 Bulk In, 1 Bulk Out and 1 Interrupt

endpoint. The Interrupt endpoint is used by the device to send asynchronous

notifications like card insertion/removal and hardware error events.

The Bulk endpoints are used for the data communication.

The UICC device will support the Mass Storage Bulk Only 1.0 specification.

It supports SCSI Transparent subclass '06', corresponding to support of the

SCSI Primary Command set. It implements SCSI Peripheral Device Type '00'

(TYPE_DISK) corresponding to a direct access SCSI block device.

Software description

====================

The MSM HSIC controller driver(drivers/usb/host/ehci-msm-hsic.c)  takes care

of HSIC PHY and link management. The USB3503 HSIC hub is managed by the SMSC

hub driver(drivers/misc/smsc_hubc.c). Both these drivers are well tested on

APQ8074 dragon board and are re-used to support this feature.

The mass storage interface is managed by the standard Linux USB storage driver.

This driver interfaces with SCSI and block layers to export the disk to

user space.

A new USB driver is implemented to manage the CCID interface. This driver is

referred to as USB CCID driver in this document. This driver is implemented

as a pass-through module and provides the character device interface to

user space. The CCID specification is implemented in the user space.

The CCID command and responses are exchanged over the Bulk endpoints. The

user space application uses write() and read() calls to send commands and

receive responses.

The CCID class specific requests are sent over the control endpoint. As

control requests have a specific format, ioctls are implemented.

The UICC device sends asynchronous notifications over the interrupt endpoint.

The card insertion/removal and hardware error events are sent to user space

via an ioctl().

Design Goals:

============

1. Re-use the existing services available in user space. This is achieved

by implementing the kernel USB CCID driver as a pass-through module.

2. Support runtime card insertion/removal.

3. Support runtime power management.

4. Support Multiple card configuration. More than 1 IC can be connected to

the USB UICC device.

Power Management

================

The USB core uses the runtime PM framework to auto suspend the USB devices that

are not in use. The Auto-suspend is forbidden for all devices except hub class

devices. The USB CCID driver enables auto-suspend for the UICC device.

An USB device can be suspended only when all of its interfaces are suspended.

The USB storage interface device acts as a parent device to the underlying

SCSI host, target and block devices. Runtime PM must be enabled for the

SCSI device to allow USB storage interface suspend. The SCSI device runtime

suspend and auto-suspend timeout will be configured from user space via sysfs

files.

The HSIC platform device and USB3503 HUB device will be runtime suspended

only after the USB UICC device is suspended.

SMP/multi-core

==============

The USB CCID driver does not allow multiple clients to open the device file

concurrently. -EBUSY will be returned if open() is attempted when the

file is already opened.

The write() and read() methods are implemented synchronously. If another

write() is called when a previous write() is in progress, -EBUSY is

returned. The same is applicable to read().

Mutexes will be used to prevent concurrent open(), read() and write() access.

Interface

=========

A character device file (/dev/ccid_bridge) will be exposed by the USB CCID

driver. open(), read(), write(), ioctl() and close() methods are implemented.

This device node is accessible only to the root by default.  User space init

or udev scripts should change the permissions of this device file if it needs

to be accessed by non-root applications.

open(): The open() is blocked until the UICC device is detected and the CCID

interface probe is completed. Returns the appropriate error code in case of

failure.

read(): An URB is submitted on the Bulk In endpoint. The read() is blocked

until the URB is completed and the data is copied to the user space buffer

upon success. An appropriate error code is returned in case of failure.

-ENODEV must be treated as a serious error and no further I/O will be

attempted.

write(): An URB is submitted on the Bulk Out endpoint. The write() is blocked

until the URB is completed. An appropriate error code is returned in case of

failure. -ENODEV must be treated as a serious error and no further I/O will be

attempted.

ioctl(): The ioctl() method is required for facilitating Control transfers and

Interrupt transfers.

USB_CCID_GET_CLASS_DESC: This read-only ioctl returns the smart card class

descriptor as described in the 5.1 section of USB smart card class spec.

USB_CCID_ABORT: This write-only ioctl sends A ABORT class specific request on

control endpoint. The class request details are mentioned in section 5.3.1.

USB_CCID_GET_CLOCK_FREQUENCIES: This read and write ioctl returns the clock

frequencies supported by the CCID device. A GET_CLOCK_FREQUENCIES class request

is sent on the control endpoint. The class request details are mentioned in

section 5.3.2.

USB_CCID_GET_DATA_RATES: This read and write ioctl returns the data rates

supported by the CCID device. A GET_DATA_RATES class request is sent on the

control endpoint. The class request details are mentioned in section 5.3.3.

USB_CCID_GET_EVENT: This read-only ioctl returns the asynchronous event sent

by the UICC device. The ioctl() is blocked until such event is received from

the UICC device. This ioctl() returns -ENOENT error code when the device

does not have an interrupt endpoint and does not support remote wakeup

capability.

close(): Cancels any ongoing I/O before it returns.

Config options

==============

Turn on USB_EHCI_MSM_HSIC, USB_HSIC_SMSC_HUB and USB_CCID_BRIDGE configs to

enable this feature.

References

==========

Specification for Integrated Circuit(s) Cards Interface Devices

Smart Cards; UICC-Terminal interface; Physical and logical characteristics

	  To compile this driver as a module, choose M here: the

	  module will be called usbtmc.

config USB_CCID_BRIDGE

	tristate "USB  Smart Card Class (CCID) support"

	help

	  Say Y here if you want to connect a USB Smart Card device that

	  follows the USB.org specification for Integrated Circuit(s) Cards

	  Interface Devices to your computer's USB port.  This module

	  provides a character device interface to exchange the messages.

	  Ioctls facilitate control transfers and interrupt transfers.

	  To compile this driver as a module, choose M here: the

	  module will be called ccid_bridge.

obj-$(CONFIG_USB_PRINTER)	+= usblp.o

obj-$(CONFIG_USB_WDM)		+= cdc-wdm.o

obj-$(CONFIG_USB_TMC)		+= usbtmc.o

obj-$(CONFIG_USB_CCID_BRIDGE)	+= ccid_bridge.o