1SDHCI MMC Driver 2================ 3 4This driver project is a part of GSoC’18 and is aimed at providing 5support for PCI devices with class 8 and subclass 5 over x86 6architecture. This document will make you familiar with the `code 7produced during GSoC <https://review.haiku-os.org/#/c/haiku/+/318/>`__, 8loading and testing the driver(including hardware emulation), insight 9into the code and future tasks. 10 11For detailed explanations about the project, you can refer the `weekly 12reports <https://www.haiku-os.org/blog/krish_iyer>`__ and comment issues 13if any. For this project we have referred `SD Host Controller Spec 14Version 151.00 <https://www.sdcard.org/downloads/pls/pdf/index.php?p=PartA2_SD_Host_Controller_Simplified_Specification_Ver1.00.jpg&f=PartA2_SD_Host_Controller_Simplified_Specification_Ver1.00.pdf&e=EN_A2100>`__ 16and `Physical Layer Spec Version 171.10 <https://www.sdcard.org/downloads/pls/pdf/index.php?p=Part1_Physical_Layer_Simplified_Specification_Ver1.10.jpg&f=Part1_Physical_Layer_Simplified_Specification_Ver1.10.pdf&e=EN_P1110>`__. 18 19Loading and testing the driver 20------------------------------ 21 22Emulating the hardware 23~~~~~~~~~~~~~~~~~~~~~~ 24 25We will emulate a SDHC device using qemu as all system may not have the 26device. These days systems provide transfer to SD/ MMC card over USB. 27The document will not instruct you on how to build haiku but you can 28refer the link to `compile and build the haiku 29images <https://www.haiku-os.org/guides/building/>`__ or the `week #1 30and 31#2 <https://www.haiku-os.org/blog/krish_iyer/2018-05-06_gsoc_2018_sdhci_mmc_driver_week_1_and_2/>`__ 32project report will also work. 33 34After building the image, we will emulate the hardware and host haiku on 35top of that. 36 37Emulation 38^^^^^^^^^ 39 40For emulating a sdhci-pci device 41 42:: 43 44 qemu-img create sd-card.img 32M 45 qemu-system-x86_64 -drive index=0,file=haiku-nightly-anyboot.iso,format=raw \ 46 -device sdhci-pci -device sd-card,drive=mydrive \ 47 -drive if=sd,index=1,file=sd-card.img,format=raw,id=mydrive 48 -m 512M -enable-kvm -usbdevice tablet -machine q35 49 50This does the following: - Create an SD card image of 32MB - Run qemu 51with a bootable image in an IDE disk, and an SDHCI bus with an SD card 52in it - Have enough memory to boot Haiku, use KVM mode for speed, and a 53tablet for ease of use - Use the Q35 chipset so the mouse and SDHCI 54controllers don’t share an interrupt (not strictly required, but it 55avoids calls to the SDHCI interrupt handler on every mouse move). 56 57Tracing of SD operations can also be added to see how qemu is 58interpreting our commands: 59 60:: 61 62 -trace sdhci* -trace sdbus* -trace sdcard* 63 64Testing and loading the driver 65~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 66 67The code is merged and part of the default Haiku build. 68 69Insight into the code and future tasks 70-------------------------------------- 71 72Bus, bus manager, and drivers 73~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 74 75The MMC stack is a device manager based “new style” driver. This 76requires splitting the driver in different parts but allow easy reuse of 77each part (for example to support eMMC or SDIO with a large part of the 78code in common with plain SD/MMC). 79 80MMC Bus drivers (src/add-ons/kernel/busses/mmc) 81^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 82 83The bus driver provides the low level aspects: interrupts management, 84DMA transfer, accessing the hardware registers. It acts as a platform 85abstraction layer so that the bus manager and disk driver can be written 86independently of the underlying hardare. 87 88Currently there is a single implementation for SDHCI (MMC bus over PCI). 89Later on, other drivers will be added for other ways to access the MMC 90bus (for example on ARM devices where it does not live on a PCI bus, and 91may have a different register layout). 92 93For this reason, the bus drivers should only do the most low-level 94things, trying to keep as much code as possible in the upper layers. 95 96One slightly confusing thing about SDHCI is that it allows a single PCI 97device to implement multiple separate MMC busses (each of which could 98have multiple devices attached). For this reason there is an SDHCI 99“device” that attaches to the PCI device node for the controller, and 100then publishes multiple device nodes for each available bus. The nodes 101then work independently of each other. 102 103The Bus Manager (src/add-ons/kernel/bus_managers/mmc) 104^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 105 106The bus manager is responsible for enumerating devices on the bus, 107assigning them addresses, and keeping track of which card is active at 108any given time. 109 110Essentially it has everything that requires collaboration between 111multiple MMC devices, as well as things that are not specific to a 112device type (common to SDIO, SD and MMC cards, for example) 113 114Disk Driver (src/add-ons/kernel/drivers/disk/mmc) 115^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 116 117This is a mass storage driver for MMC, SD and SDHC cards. Currently only 118SD and SDHC are tested, MMC and eMMC will have to be added (they are 119similar but there are some differences). 120 121Wiring the driver in the device manager (src/system/kernel/device_manager/device_manager.cpp) 122^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 123 124(note: possibly not accurate documentation, I did not check how things 125in the device manager are actually implemented, but this is my 126understanding of it). 127 128The device manager attempts to implement lazy, on-demand scanning of the 129devices. The idea is to speed up booting by not spending a lot of time 130scanning everything first, and only scanning small parts of the device 131tree as they are needed. 132 133The trigger is accesses to the devfs. For example, when an application 134opens /dev/disk, the device manager will start looking for disks so it 135can populate it. This means the device manager needs to know which 136branches of the device tree to explore. Currently this knowledge is 137hardcoded into the device tree sourcecode, and there’s a TODO item about 138moving that knowledge to drivers instead. But it’s tricky, since the 139whole point is to avoid loading all the drivers. 140 141Anyway, currently, the device manager is hardcoded to look for mass 142storage devices under SDHCI busses, both standard ones and some 143non-standard ones (for example, Ricoh provides SDHCI implenentations 144that are conform to the spec, except they don’t have the right device 145type in the PCI registers). 146 147Insight into the code 148~~~~~~~~~~~~~~~~~~~~~ 149 150MMC Bus management overview 151^^^^^^^^^^^^^^^^^^^^^^^^^^^ 152 153The device tree for MMC support looks like this: 154 155- PCI bus manager 156 157 - (other PCI devices) 158 - SDHCI controller 159 160 - SDHCI bus 161 162 - MMC bus manager 163 164 - MMC device 165 166 - mmc_disk device 167 168 - MMC device 169 170 - (other SDIO driver) 171 172 - MMC bus manager (second MMC bus) 173 174 - MMC device 175 176 - mmc_disk device 177 178At the first level, the PCI bus manager publishes a device node for each 179device found. One of them is our SDHCI controller, identified either by 180the PCI device class and subclass, or for not completely SDHCI 181compatible device, by the device and vendor IDs. 182 183The SDHCI bus driver attaches to this device and publishes his own node. 184It then scans the device and publishes an MMC bus node for each slot 185(there may be multiple SD slots attached to a single PCI controller). 186 187The MMC bus manager then attach to each of these slots, and send the 188appropriate commands for enumerating the SD cards (there may be multiple 189cards in a “slot”), and publishes a device node for each of them. 190Finally, the mmc_disk driver can bind itself to one of these device 191nodes, and publish the corresponding disk node, which is also be made 192available in /dev/disk/mmc. 193 194Currently the mmc bus does not publish anything in the devfs, but this 195could be added if sending raw SD/MMC commands to SD cards from userland 196is considered desirable. 197 198SDHCI driver 199^^^^^^^^^^^^ 200 201The SDHCI driver is the lowest level of the MMC stack. It provides 202abstraction of the SDHCI device. Later on, different way to access an SD 203bus may be added, for example for ARM devices which decided to use a 204different register interface. 205 206The entry point is as usual **supports_device()**. This method is called 207only for devices which may be SDHCI controllers, thanks to filtering 208done in the device manager to probe only the relevant devices. The 209probing is done on-demand, currently when the system is enumerating 210/dev/disk in the devfs. Later on, when we have SDIO support, probing 211will also be triggered in other cases. 212 213The function identifies the device by checking the class and subclass, 214as well as a limited set of hardcoded PCI device and vendor IDs for 215devices that do not use the assigned subclass. 216 217Once a compatible device is found, **register_child_devices()** is used 218to publish device nodes for each slot to be controlled by the mmc bus 219manager. The registers for each device are mapped into virtual memory, 220using the information from the PCI bar registers. **struct registers** 221is defined so that it matches the register layout, and provide a little 222abstraction to raw register access. 223 224An SdhciBus object is created to manage each of these busses at the 225SDHCI level. It will be responsible for executing SD commands on that 226bus, and dealing with the resulting interrupts. 227 228The Bus Manager 229^^^^^^^^^^^^^^^ 230 231The MMC bus manager manages the MMC bus (duh). Its tasks are: 232 233- enumerating SD cards on the bus 234- assigning RCAs to the cards for identifying them when sending 235 commands 236- setting the bus clock speed according to what the cards can handle 237- remember which SD card is currently active (CMD7) 238- manage cards state 239- publish device nodes for each card 240 241Disk Driver 242^^^^^^^^^^^ 243 244The disk driver is attached to devices implementing SDSC or SDHC/SDXC 245commands. There will be other drivers for non-storage (SDIO) cards. 246 247To help with this, the MMC bus manager provides the device with the 248information it gathered while initializing the device. According to the 249commands recognized by the card during the initialization sequence, it’s 250possible to know if it’s SDSC, SDHC/SDXC, or something else (SDIO, 251legacy MMC, etc). 252 253The disk driver publishes devfs entries in /dev/disk/mmc and implements 254the usual interface for disk devices. From this point on, the device can 255be used just like any other mass storage device. 256 257Getting everything loaded 258^^^^^^^^^^^^^^^^^^^^^^^^^ 259 260The device manager is not completely implemented yet. As a result, some 261decisions about which drivers to load are hardcoded in 262device_manager.cpp. 263 264It has been adjusted to handover SDHCI devices to the MMC bus. Whenever 265a “disk” device is requested, the MMC busses are searched, which results 266in loading the SDHCI driver and probing for SD cards. When we get 267support for other types of SDIO devices, we will need to adjust the 268device manager to probe the SDHCI bus when these type of devices are 269requested, too. 270 271Tasks to be completed 272~~~~~~~~~~~~~~~~~~~~~ 273 274The SDHCI driver is able to send and receive commands. However it does 275not handle card insertion and removal interrupts yet, so the card must 276be already inserted when the driver is loaded. 277 278The mmc_disk driver is complete and working, but was not tested for MMC 279and eMMC devices. Some changes may be needed. 280 281There is also work to be done for better performance: making sure we 282switch to the high-speed clock when an SD card supports it, and use the 2834-bit data transfer mode instead of the default 1-bit if possible. 284 285Drivers for SDIO devices should also be added. The mmc_bus and SDHCI 286drivers have been tested only with one card on the bus at a time (for 287lack of hardware allowing more complex setups). 288 289If you find it difficult to understand the driver development and it’s 290functioning and role, please refer 291*docs/develop/kernel/device_manager_introduction.html* 292
