Documentation/usb/uicc.txt - kernel/msm - Git at Google

 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
	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