Bryan Huntsman | 3f2bc4d | 2011-08-16 17:27:22 -0700 | [diff] [blame^] | 1 | Introduction |
| 2 | ============ |
| 3 | The Char SDIO Device Driver is an interface which exposes an SDIO |
| 4 | card/function from kernel space as a char device in user space. |
| 5 | |
| 6 | The driver doesn't interact with any HW directly. It relies on SDIO |
| 7 | card/function interface provided as a part of Linux kernel. |
| 8 | |
| 9 | Hardware description |
| 10 | ==================== |
| 11 | Each SDIO device/card contains an SDIO client HW block. |
| 12 | The host interacts with the device by sending byte sequences called |
| 13 | command (CMD). Some commands can be followed by data blocks. The |
| 14 | device sends back a byte sequence called response (R) and a data |
| 15 | block if required. CMD3, CMD5 and CMD7 are used to initialize the |
| 16 | device. CMD52 and CMD53 are used to access the device. Command |
| 17 | format and properties are defined by SDIO Specification document |
| 18 | published by SD Association: |
| 19 | http://www.sdcard.org/developers/tech/sdio/. |
| 20 | |
| 21 | CMD52 and CMD53 can access up to 8 address spaces called Functions. |
| 22 | Function 0 contains system information predefined by SD/SDIO |
| 23 | standard and Functions 1-7 are defined by the SDIO device |
| 24 | manufacturer. |
| 25 | |
| 26 | An SDIO device/card can send an interrupt to SDIO host. This |
| 27 | interrupt is intercepted and handled by SDIO host. |
| 28 | |
| 29 | Software description |
| 30 | ==================== |
| 31 | Linux provides a framework for handling SDIO devices. It implements |
| 32 | kind of plug-and-play model in which the Linux SDIO Host Driver is |
| 33 | responsible for initializing an SDIO device upon insertion. It also |
| 34 | reads device/card identification information and enumerates functions |
| 35 | provided by the device and then looks up in the list of |
| 36 | preregistered user SDIO drivers for a suitable one. |
| 37 | |
| 38 | During its lifecycle the user SDIO driver interacts with the Linux |
| 39 | SDIO Host Driver in order to send/receive information to/from SDIO |
| 40 | device/card. The user SDIO driver doesn't work with CMD52/CMD53 |
| 41 | directly. Instead it uses an abstraction provided by the Linux SDIO |
| 42 | Host Driver. |
| 43 | |
| 44 | The Linux SDIO Host Driver is also in charge of handling SDIO |
| 45 | interrupts. User SDIO driver can register its own callback in SDIO |
| 46 | Host Driver and get a notification about interrupt event. |
| 47 | |
| 48 | The Char SDIO Device Driver follows the design guidelines mentioned |
| 49 | above. It provides the following functionality: |
| 50 | |
| 51 | - Register itself in the user SDIO drivers list; |
| 52 | - Handle Probe event upon insertion of supported card/device; |
| 53 | - Creates and maintains a char device driver for each SDIO Function |
| 54 | found in the card/device; |
| 55 | - Translates read/write/ioctl calls to appropriate SDIO call |
| 56 | sequences; |
| 57 | |
| 58 | In order to handle general SDIO configuration functionality and |
| 59 | Function 0 the Char SDIO Device Driver provides additional |
| 60 | simplified char device driver. |
| 61 | |
| 62 | The Manufacturer and Device IDs of handled SDIO device should be |
| 63 | provided as parameters for kernel module or as configuration |
| 64 | parameters in case of statically linked driver. |
| 65 | |
| 66 | Design |
| 67 | ====== |
| 68 | The main goal of the Char SDIO Device Driver is to expose an SDIO |
| 69 | card/device from kernel space to user space as a char device driver. |
| 70 | The driver should be generic and simple as far as possible. |
| 71 | |
| 72 | The biggest design tradeoff is maintaining a balance between the |
| 73 | system call overhead required to initiate an SDIO transaction from |
| 74 | user space and overall SDIO communication performance. But luckily, |
| 75 | because of nature of SDIO protocol, this overhead is negligible |
| 76 | comparing to time required to execute SDIO transaction itself. So, |
| 77 | each CMD52 (read or write) consists from single ioctl system call. |
| 78 | And each CMD53 invokes single ioctl system call followed by read or |
| 79 | write system call. |
| 80 | |
| 81 | The Char SDIO Device Driver registers its own class of the devices |
| 82 | called 'csdio'. This class will serve as a common roof for all SDIO |
| 83 | devices served by different instances of the Char SDIO Device Driver. |
| 84 | Additional benefit from maintaining its own class is the driver |
| 85 | ability to overwrite default permissions of the dev nodes created by |
| 86 | the driver. |
| 87 | |
| 88 | Power Management |
| 89 | ================ |
| 90 | None |
| 91 | |
| 92 | SMP/multi-core |
| 93 | ============== |
| 94 | The driver does not anticipate any issues related to multi-core |
| 95 | since it is expected to run on one core only. |
| 96 | |
| 97 | Security |
| 98 | ======== |
| 99 | None |
| 100 | |
| 101 | Performance |
| 102 | =========== |
| 103 | None |
| 104 | |
| 105 | Interface |
| 106 | ========= |
| 107 | The Char SDIO Device Driver has two char device interfaces: |
| 108 | - Control Interface; |
| 109 | - Function Interface. |
| 110 | |
| 111 | Char SDIO Device Driver Control Interface consists of: |
| 112 | - open() - device node is /dev/csdio0; |
| 113 | - close() |
| 114 | - ioctl() - the following options are available: |
| 115 | - CSDIO_IOC_ENABLE_HIGHSPEED_MODE; |
| 116 | - CSDIO_IOC_SET_DATA_TRANSFER_CLOCKS; |
| 117 | - CSDIO_IOC_ENABLE_ISR; |
| 118 | - CSDIO_IOC_DISABLE_ISR. |
| 119 | |
| 120 | Char SDIO Device Driver Function Interface consists of: |
| 121 | - open() - device node is /dev/csdiofX, where X is Function Id; |
| 122 | - close() |
| 123 | - read() - send CMD53 read; |
| 124 | - write() - send CMD53 write; |
| 125 | - ioctl() - the following options are available: |
| 126 | - CSDIO_IOC_SET_OP_CODE - 0 fixed adrress, 1 autoincrement. |
| 127 | - CSDIO_IOC_FUNCTION_SET_BLOCK_SIZE; |
| 128 | - CSDIO_IOC_SET_BLOCK_MODE - 0 byte mode, 1 block mode; |
| 129 | - CSDIO_IOC_CMD52 - execute CMD52, receives the |
| 130 | following structure as a parameter: |
| 131 | struct csdio_cmd52_ctrl_t { |
| 132 | uint32_t m_write; // 0 - read, 1 -write |
| 133 | uint32_t m_address; |
| 134 | uint32_t m_data; // data to write or read data |
| 135 | uint32_t m_ret; // command execution status |
| 136 | }__attribute__ ((packed)); |
| 137 | - CSDIO_IOC_CMD53 - setup CMD53 data transfer, receives the |
| 138 | following structure as a parameter: |
| 139 | struct csdio_cmd53_ctrl_t { |
| 140 | uint32_t m_block_mode; |
| 141 | uint32_t m_op_code; |
| 142 | uint32_t m_address; |
| 143 | }__attribute__ ((packed)); |
| 144 | - CSDIO_IOC_CONNECT_ISR; |
| 145 | - CSDIO_IOC_DISCONNECT_ISR; |
| 146 | - CSDIO_IOC_GET_VDD; |
| 147 | - CSDIO_IOC_SET_VDD. |
| 148 | |
| 149 | Additionally, user space application can use fcntl system call with |
| 150 | parameters F_SETOWN and F_SETFL in order to set an asynchronous |
| 151 | callback for SDIO interrupt. |
| 152 | |
| 153 | Driver parameters |
| 154 | ================= |
| 155 | If the driver is compiled as a kernel module, the following |
| 156 | parameters can be used in order to provide Manufacturer and Device IDs |
| 157 | upon module download: |
| 158 | - csdio_vendor_id; |
| 159 | - csdio_device_id. |
| 160 | If the driver is intended to work with specific SDIO host the |
| 161 | host_name parameter should be added followed by the name of the MMC |
| 162 | host platform device. |
| 163 | |
| 164 | Config options |
| 165 | ============== |
| 166 | These are the kernel configuration options: |
| 167 | - CONFIG_CSDIO_VENDOR_ID; |
| 168 | - CONFIG_CSDIO_DEVICE_ID. |
| 169 | |
| 170 | Dependencies |
| 171 | ============ |
| 172 | The Char SDIO Device Driver depends on Linux SDIO Host Driver. |
| 173 | |
| 174 | User space utilities |
| 175 | ==================== |
| 176 | None |
| 177 | |
| 178 | Other |
| 179 | ===== |
| 180 | None |
| 181 | |
| 182 | Known issues |
| 183 | ============ |
| 184 | None |
| 185 | |
| 186 | To do |
| 187 | ===== |
| 188 | Provide mechanism to support a number of SDIO devices simultaneously |
| 189 | connected to different SDIO hosts. |