Documentation/csdio.txt

Introduction
============
The Char SDIO Device Driver is an interface which exposes an SDIO
card/function from kernel space as a char device in user space.

The driver doesn't interact with any HW directly. It relies on SDIO
card/function interface provided as a part of Linux kernel.

Hardware description
====================
Each SDIO device/card contains an SDIO client HW block.
The host interacts with the device by sending byte sequences called
command (CMD). Some commands can be followed by data blocks. The
device sends back a byte sequence called response (R) and a data
block if required. CMD3, CMD5 and CMD7 are used to initialize the
device. CMD52 and CMD53 are used to access the device. Command
format and properties are defined by SDIO Specification document
published by SD Association:
    http://www.sdcard.org/developers/tech/sdio/.

CMD52 and CMD53 can access up to 8 address spaces called Functions.
Function 0 contains system information predefined by SD/SDIO
standard and Functions 1-7 are defined by the SDIO device
manufacturer.

An SDIO device/card can send an interrupt to SDIO host. This
interrupt is intercepted and handled by SDIO host.

Software description
====================
Linux provides a framework for handling SDIO devices. It implements
kind of plug-and-play model in which the Linux SDIO Host Driver is
responsible for initializing an SDIO device upon insertion. It also
reads device/card identification information and enumerates functions
provided by the device and then looks up in the list of
preregistered user SDIO drivers for a suitable one.

During its lifecycle the user SDIO driver interacts with the Linux
SDIO Host Driver in order to send/receive information to/from SDIO
device/card. The user SDIO driver doesn't work with CMD52/CMD53
directly. Instead it uses an abstraction provided by the Linux SDIO
Host Driver.

The Linux SDIO Host Driver is also in charge of handling SDIO
interrupts. User SDIO driver can register its own callback in SDIO
Host Driver and get a notification about interrupt event.

The Char SDIO Device Driver follows the design guidelines mentioned
above. It provides the following functionality:

 - Register itself in the user SDIO drivers list;
 - Handle Probe event upon insertion of supported card/device;
 - Creates and maintains a char device driver for each SDIO Function
   found in the card/device;
 - Translates read/write/ioctl calls to appropriate SDIO call
   sequences;

In order to handle general SDIO configuration functionality and
Function 0 the Char SDIO Device Driver provides additional
simplified char device driver.

The Manufacturer and Device IDs of handled SDIO device should be
provided as parameters for kernel module or as configuration
parameters in case of statically linked driver.

Design
======
The main goal of the Char SDIO Device Driver is to expose an SDIO
card/device from kernel space to user space as a char device driver.
The driver should be generic and simple as far as possible.

The biggest design tradeoff is maintaining a balance between the
system call overhead required to initiate an SDIO transaction from
user space and overall SDIO communication performance. But luckily,
because of nature of SDIO protocol, this overhead is negligible
comparing to time required to execute SDIO transaction itself. So,
each CMD52 (read or write) consists from single ioctl system call.
And each CMD53 invokes single ioctl system call followed by read or
write system call.

The Char SDIO Device Driver registers its own class of the devices
called 'csdio'. This class will serve as a common roof for all SDIO
devices served by different instances of the Char SDIO Device Driver.
Additional benefit from maintaining its own class is the driver
ability to overwrite default permissions of the dev nodes created by
the driver.

Power Management
================
None

SMP/multi-core
==============
The driver does not anticipate any issues related to multi-core
since it is expected to run on one core only.

Security
========
None

Performance
===========
None

Interface
=========
The Char SDIO Device Driver has two char device interfaces:
 - Control Interface;
 - Function Interface.

Char SDIO Device Driver Control Interface consists of:
 - open()   - device node is /dev/csdio0;
 - close()
 - ioctl()  - the following options are available:
   - CSDIO_IOC_ENABLE_HIGHSPEED_MODE;
   - CSDIO_IOC_SET_DATA_TRANSFER_CLOCKS;
   - CSDIO_IOC_ENABLE_ISR;
   - CSDIO_IOC_DISABLE_ISR.

Char SDIO Device Driver Function Interface consists of:
 - open()  - device node is /dev/csdiofX, where X is Function Id;
 - close()
 - read()  - send CMD53 read;
 - write() - send CMD53 write;
 - ioctl() - the following options are available:
   - CSDIO_IOC_SET_OP_CODE - 0 fixed adrress, 1 autoincrement.
   - CSDIO_IOC_FUNCTION_SET_BLOCK_SIZE;
   - CSDIO_IOC_SET_BLOCK_MODE - 0 byte mode, 1 block mode;
   - CSDIO_IOC_CMD52 - execute CMD52, receives the
        following structure as a parameter:
            struct csdio_cmd52_ctrl_t {
	            uint32_t    m_write; // 0 - read, 1 -write
	            uint32_t    m_address;
	            uint32_t    m_data;  // data to write or read data
	            uint32_t    m_ret;   // command execution status
            }__attribute__ ((packed));
   - CSDIO_IOC_CMD53 - setup CMD53 data transfer, receives the
        following structure as a parameter:
            struct csdio_cmd53_ctrl_t {
	            uint32_t    m_block_mode;
	            uint32_t    m_op_code;
	            uint32_t    m_address;
            }__attribute__ ((packed));
   - CSDIO_IOC_CONNECT_ISR;
   - CSDIO_IOC_DISCONNECT_ISR;
   - CSDIO_IOC_GET_VDD;
   - CSDIO_IOC_SET_VDD.

Additionally, user space application can use fcntl system call with
parameters F_SETOWN and F_SETFL in order to set an asynchronous
callback for SDIO interrupt.

Driver parameters
=================
If the driver is compiled as a kernel module, the following
parameters can be used in order to provide Manufacturer and Device IDs
upon module download:
 - csdio_vendor_id;
 - csdio_device_id.
If the driver is intended to work with specific SDIO host the
host_name parameter should be added followed by the name of the MMC
host platform device.

Config options
==============
These are the kernel configuration options:
 - CONFIG_CSDIO_VENDOR_ID;
 - CONFIG_CSDIO_DEVICE_ID.

Dependencies
============
The Char SDIO Device Driver depends on Linux SDIO Host Driver.

User space utilities
====================
None

Other
=====
None

Known issues
============
None

To do
=====
Provide mechanism to support a number of SDIO devices simultaneously
connected to different SDIO hosts.