1. 前言
2. MMC host驱动介绍
3. 主要数据结构
3.1 struct mmc_host
3.2 struct mmc_host_ops
3.2.1 数据传输有关的函数
3.2.2 总线参数的配置以及卡状态的获取函数
3.2.3 其它一些非主流函数,都是optional的,用到的时候再去细看即可
3.3 struct mmc_pwrseq
3.4 Host capabilities
3.5 struct mmc_ios
3.6 struct mmc_supply
3.7 struct mmc_request
3.7.1 MMC bus protocol
3.7.2 struct mmc_request
3.7.3 struct mmc_command
3.7.4 struct mmc_data
4. 主要API
4.1 向MMC host controller driver提供的用于操作struct mmc_host的API
4.1.1mmc_alloc_host
4.1.2mmc_add_host
4.1.3 其他
4.2 用于判断MMC host controller所具备的能力的API
5. MMC host驱动的编写步骤
5.1 struct mmc_host的填充和注册
5.2 数据传输的实现
5.2.1 Sectors(扇区)、Blocks(块)以及Segments(段)的理解
5.2.2 struct mmc_data中的sg
6. 参考文档
1. 前言
本文是Linux MMC framework的第二篇,将从驱动工程师的角度,介绍MMC host controller driver有关的知识,学习并掌握如何在MMC framework的框架下,编写MMC控制器的驱动程序。同时,通过本篇文章,我们会进一步的理解MMC、SD、SDIO等有关的基础知识。
2. MMC host驱动介绍
MMC的host driver,是用于驱动MMC host控制器的程序,位于“drivers/mmc/host”目录。从大的流程上看,编写一个这样的驱动非常简单,只需要三步:
1)调用mmc_alloc_host,分配一个struct mmc_host类型的变量,用于描述某一个具体的MMC host控制器。
2)根据MMC host控制器的硬件特性,填充struct mmc_host变量的各个字段,例如MMC类型、电压范围、操作函数集等等。
3)调用mmc_add_host接口,将正确填充的MMC host注册到MMC core中。
当然,看着简单,一牵涉到实现细节,还是很麻烦的,后面我们会慢慢分析。
注1:分析MMC host driver的时候,Linux kernel中有大把大把的例子(例如drivers/mmc/host/pxamci.c),大家可尽情参考、学习,不必谦虚(这是学习Linux的最佳方法)。
注2:由于MMC host driver牵涉到具体的硬件controller,分析的过程中需要一些具体的硬件辅助理解,本文将以“X Project”所使用Bubblegum-96平台为例,具体的硬件spec可参考[1]。
3. 主要数据结构
3.1 struct mmc_host
MMC core使用struct mmc_host结构抽象具体的MMC host controller,该结构的定义位于“include/linux/mmc/host.h”中,它既可以用来描述MMC控制器所具有的特性、能力(host driver关心的内容),也保存了host driver运行过程中的一些状态、参数(MMC core关心的内容)。需要host driver关心的部分的具体的介绍如下:
parent,一个struct device类型的指针,指向该MMC host的父设备,一般是注册该host的那个platform设备;
class_dev,一个struct device类型的变量,是该MMC host在设备模型中作为一个“设备”的体现。当然,人如其名,该设备从属于某一个class(mmc_host_class);
ops,一个struct mmc_host_ops类型的指针,保存了该MMC host有关的操作函数集,具体可参考3.2小节的介绍;
pwrseq,一个struct mmc_pwrseq类型的指针,保存了该MMC host电源管理有关的操作函数集,具体可参考3.2小节的介绍;
f_min、f_max、f_init,该MMC host支持的时钟频率范围,最小频率、最大频率以及初始频率;
ocr_avail,该MMC host可支持的操作电压范围(具体可参考include/linux/mmc/host.h中MMC_VDD_开头的定义);
注3:OCR(Operating Conditions Register)是MMC/SD/SDIO卡的一个32-bit的寄存器,其中有些bit指明了该卡的操作电压。MMC host在驱动这些卡的时候,需要和Host自身所支持的电压范围匹配之后,才能正常操作,这就是ocr_avail的存在意义。
ocr_avail_sdio、ocr_avail_sd、ocr_avail_mmc,如果MMC host针对SDIO、SD、MMC等不同类型的卡,所支持的电压范围不同的话,需要通过这几个字段特别指定。否则,不需要赋值(初始化为0);
pm_notify,一个struct notifier_block类型的变量,用于支持power management有关的notify实现;
max_current_330、max_current_300、max_current_180,当工作电压分别是3.3v、3v以及1.8v的时候,所支持的最大操作电流(如果MMC host没有特别的限制,可以不赋值);
caps、caps2,指示该MMC host所支持的功能特性,具体可参考3.4小节的介绍;
pm_caps,mmc_pm_flag_t类型的变量,指示该MMC host所支持的电源管理特性;
max_seg_size、max_segs、max_req_size、max_blk_size、max_blk_count、max_busy_timeout,和块设备(如MMC、SD、eMMC等)有关的参数,在古老的磁盘时代,这些参数比较重要。对基于MMC技术的块设备来说,硬件的性能大大提升,这些参数就没有太大的意义了。具体可参考5.2章节有关MMC数据传输的介绍;
lock,一个spin lock,是MMC host driver的私有变量,可用于保护host driver的临界资源;
ios,一个struct mmc_ios类型的变量,用于保存MMC bus的当前配置,具体可参考3.5小节的介绍;
supply,一个struct mmc_supply类型的变量,用于描述MMC系统中的供电信息,具体可参考3.6小节的介绍;
……
private,一个0长度的数组,可以在mmc_alloc_host时指定长度,由host controller driver自行支配。
3.2 struct mmc_host_ops
struct mmc_host_ops抽象并集合了MMC host controller所有的操作函数集,包括:
3.2.1 数据传输有关的函数
/** It is optional for the host to implement pre_req and post_req in* order to support double buffering of requests (prepare one* request while another request is active).* pre_req() must always be followed by a post_req().* To undo a call made to pre_req(), call post_req() with* a nonzero err condition.*/void (*post_req)(struct mmc_host *host, struct mmc_request *req,int err);void (*pre_req)(struct mmc_host *host, struct mmc_request *req,bool is_first_req);void (*request)(struct mmc_host *host, struct mmc_request *req);
pre_req和post_req是非必需的,host driver可以利用它们实现诸如双buffer之类的高级功能。
数据传输的主题是struct mmc_request类型的指针,具体可参考3.7小节的介绍。
3.2.2 总线参数的配置以及卡状态的获取函数
/** Avoid calling these three functions too often or in a "fast path",* since underlaying controller might implement them in an expensive* and/or slow way.** Also note that these functions might sleep, so don't call them* in the atomic contexts!** Return values for the get_ro callback should be:* 0 for a read/write card* 1 for a read-only card* -ENOSYS when not supported (equal to NULL callback)* or a negative errno value when something bad happened** Return values for the get_cd callback should be:* 0 for a absent card* 1 for a present card* -ENOSYS when not supported (equal to NULL callback)* or a negative errno value when something bad happened*/void (*set_ios)(struct mmc_host *host, struct mmc_ios *ios);int(*get_ro)(struct mmc_host *host);int(*get_cd)(struct mmc_host *host);
set_ios用于设置bus的参数(ios,可参考3.5小节的介绍);get_ro可获取card的读写状态(具体可参考上面的注释);get_cd用于检测卡的存在状态。
注4:注释中特别说明了,这几个函数可以sleep,耗时较长,没事别乱用。
3.2.3 其它一些非主流函数,都是optional的,用到的时候再去细看即可
void(*enable_sdio_irq)(struct mmc_host *host, int enable);void(*ack_sdio_irq)(struct mmc_host *host);/* optional callback for HC quirks */void(*init_card)(struct mmc_host *host, struct mmc_card *card);int(*start_signal_voltage_switch)(struct mmc_host *host, struct mmc_ios *ios);/* Check if the card is pulling dat[0:3] low */int(*card_busy)(struct mmc_host *host);/* The tuning command opcode value is different for SD and eMMC cards */int(*execute_tuning)(struct mmc_host *host, u32 opcode);/* Prepare HS400 target operating frequency depending host driver */int(*prepare_hs400_tuning)(struct mmc_host *host, struct mmc_ios *ios);/* Prepare enhanced strobe depending host driver */void(*hs400_enhanced_strobe)(struct mmc_host *host,struct mmc_ios *ios);int(*select_drive_strength)(struct mmc_card *card,unsigned int max_dtr, int host_drv,int card_drv, int *drv_type);void(*hw_reset)(struct mmc_host *host);void(*card_event)(struct mmc_host *host);/** Optional callback to support controllers with HW issues for multiple* I/O. Returns the number of supported blocks for the request.*/int(*multi_io_quirk)(struct mmc_card *card,unsigned int direction, int blk_size);
3.3 struct mmc_pwrseq
MMC framework的power sequence是一个比较有意思的功能,它提供一个名称为struct mmc_pwrseq_ops的操作函数集,集合了power on、power off等操作函数,用于控制MMC系统的供电,如下:
struct mmc_pwrseq_ops {void (*pre_power_on)(struct mmc_host *host);void (*post_power_on)(struct mmc_host *host);void (*power_off)(struct mmc_host *host);void (*reset)(struct mmc_host *host);};struct mmc_pwrseq {const struct mmc_pwrseq_ops *ops;struct device *dev;struct list_head pwrseq_node;struct module *owner;};
与此同时,MMC core提供了一个通用的pwrseq的管理模块(drivers/mmc/core/pwrseq.c),以及一些简单的pwrseq策略(如drivers/mmc/core/pwrseq_simple.c、drivers/mmc/core/pwrseq_emmc.c),最终的目的是,通过一些简单的dts配置,即可正确配置MMC的供电,例如:
/* arch/arm/boot/dts/omap3-igep0020.dts */mmc2_pwrseq: mmc2_pwrseq {compatible = "mmc-pwrseq-simple";reset-gpios = <&gpio5 11 GPIO_ACTIVE_LOW>,/* gpio_139 - RESET_N_W */<&gpio5 10 GPIO_ACTIVE_LOW>;/* gpio_138 - WIFI_PDN */};/* arch/arm/boot/dts/rk3288-veyron.dtsi */emmc_pwrseq: emmc-pwrseq {compatible = "mmc-pwrseq-emmc";pinctrl-0 = <&emmc_reset>;pinctrl-names = "default";reset-gpios = <&gpio2 9 GPIO_ACTIVE_HIGH>;};
具体的细节,在需要的时候,阅读代码即可,这里不再赘述。
3.4 Host capabilities
通过的caps和caps2两个字段,MMC host driver可以告诉MMC core控制器的一些特性、能力,包括(具体可参考include/linux/mmc/host.h中相关的宏定义,更为细致的使用场景和指南,需要结合实际的硬件,具体分析):
MMC_CAP_4_BIT_DATA,支持4-bit的总线传输;
MMC_CAP_MMC_HIGHSPEED,支持“高速MMC时序”;
MMC_CAP_SD_HIGHSPEED,支持“高速SD时序”;
MMC_CAP_SDIO_IRQ,可以产生SDIO有关的中断;
MMC_CAP_SPI,仅仅支持SPI协议(可参考“drivers/mmc/host/mmc_spi.c”中有关的实现);
MMC_CAP_NEEDS_POLL,表明需要不停的查询卡的插入状态(如果需要支持热拔插的卡,则需要设置该feature);
MMC_CAP_8_BIT_DATA,支持8-bit的总线传输;
MMC_CAP_AGGRESSIVE_PM,支持比较积极的电源管理策略(kernel的注释为“Suspend (e)MMC/SD at idle”);
MMC_CAP_NONREMOVABLE,表明该MMC控制器所连接的卡是不可拆卸的,例如eMMC;
MMC_CAP_WAIT_WHILE_BUSY,表面Host controller在向卡发送命令时,如果卡处于busy状态,是否等待。如果不等待,MMC core在一些流程中(如查询busy状态),需要额外做一些处理;
MMC_CAP_ERASE,表明该MMC控制器允许执行擦除命令;
MMC_CAP_1_8V_DDR,支持工作电压为1.8v的DDR(Double Data Rate)mode[3];
MMC_CAP_1_2V_DDR,支持工作电压为1.2v的DDR(Double Data Rate)mode[3];
MMC_CAP_POWER_OFF_CARD,可以在启动之后,关闭卡的供电(一般只有在SDIO的应用场景中才可能用到,因为SDIO所连接的设备可能是一个独立的设备);
MMC_CAP_BUS_WIDTH_TEST,支持通过CMD14和CMD19进行总线宽度的测试,以便选择一个合适的总线宽度进行通信;
MMC_CAP_UHS_SDR12、MMC_CAP_UHS_SDR25、MMC_CAP_UHS_SDR50、MMC_CAP_UHS_SDR104,它们是SD3.0的速率模式,分别表示支持25MHz、50MHz、100MHz和208MHz的SDR(Single Data Rate,相对[3]中的DDR)模式;
MMC_CAP_UHS_DDR50,它也是SD3.0的速率模式,表示支持50MHz的DDR(Double Data Rate[3])模式;
MMC_CAP_DRIVER_TYPE_A、MMC_CAP_DRIVER_TYPE_C、MMC_CAP_DRIVER_TYPE_D,分别表示支持A/C/D类型的driver strength(驱动能力,具体可参考相应的spec);
MMC_CAP_CMD23,表示该controller支持multiblock transfers(通过CMD23);
MMC_CAP_HW_RESET,支持硬件reset;
MMC_CAP2_FULL_PWR_CYCLE,表示该controller支持从power off到power on的完整的power cycle;
MMC_CAP2_HS200_1_8V_SDR、MMC_CAP2_HS200_1_2V_SDR,HS200是eMMC5.0支持的一种速率模式,200是200MHz的缩写,分别表示支持1.8v和1.2v的SDR模式;
MMC_CAP2_HS200,表示同时支持MMC_CAP2_HS200_1_8V_SDR和MMC_CAP2_HS200_1_2V_SDR;
MMC_CAP2_HC_ERASE_SZ,支持High-capacity erase size;
MMC_CAP2_CD_ACTIVE_HIGH,CD(Card-detect)信号高有效;
MMC_CAP2_RO_ACTIVE_HIGH,RO(Write-protect)信号高有效;
MMC_CAP2_PACKED_RD、MMC_CAP2_PACKED_WR,允许packed read、packed write;
MMC_CAP2_PACKED_CMD,同时支持DMMC_CAP2_PACKED_RD和MMC_CAP2_PACKED_WR;
MMC_CAP2_NO_PRESCAN_POWERUP,在scan之前不要上电;
MMC_CAP2_HS400_1_8V、MMC_CAP2_HS400_1_2V,HS400是eMMC5.0支持的一种速率模式,400是400MHz的缩写,分别表示支持1.8v和1.2v的HS400模式;
MMC_CAP2_HS400,同时支持MMC_CAP2_HS400_1_8V和MMC_CAP2_HS400_1_2V;
MMC_CAP2_HSX00_1_2V,同时支持MMC_CAP2_HS200_1_2V_SDR和MMC_CAP2_HS400_1_2V;
MMC_CAP2_SDIO_IRQ_NOTHREAD,SDIO的IRQ的处理函数,不能在线程里面执行;
MMC_CAP2_NO_WRITE_PROTECT,没有物理的RO管脚,意味着任何时候都是可以读写的;
MMC_CAP2_NO_SDIO,在初始化的时候,不会发送SDIO相关的命令(也就是说不支持SDIO模式)。
3.5 struct mmc_ios
struct mmc_ios中保存了MMC总线当前的配置情况,包括如下信息:
struct mmc_ios {unsigned intclock;/* clock rate */unsigned shortvdd;/* vdd stores the bit number of the selected voltage range from below. */unsigned charbus_mode;/* command output mode */#define MMC_BUSMODE_OPENDRAIN1#define MMC_BUSMODE_PUSHPULL2unsigned charchip_select;/* SPI chip select */#define MMC_CS_DONTCARE0#define MMC_CS_HIGH1#define MMC_CS_LOW2unsigned charpower_mode;/* power supply mode */#define MMC_POWER_OFF0#define MMC_POWER_UP1#define MMC_POWER_ON2#define MMC_POWER_UNDEFINED3unsigned charbus_width;/* data bus width */#define MMC_BUS_WIDTH_10#define MMC_BUS_WIDTH_42#define MMC_BUS_WIDTH_83unsigned chartiming;/* timing specification used */#define MMC_TIMING_LEGACY0#define MMC_TIMING_MMC_HS1#define MMC_TIMING_SD_HS2#define MMC_TIMING_UHS_SDR123#define MMC_TIMING_UHS_SDR254#define MMC_TIMING_UHS_SDR505#define MMC_TIMING_UHS_SDR1046#define MMC_TIMING_UHS_DDR507#define MMC_TIMING_MMC_DDR528#define MMC_TIMING_MMC_HS#define MMC_TIMING_MMC_HS40010unsigned charsignal_voltage;/* signalling voltage (1.8V or 3.3V) */#define MMC_SIGNAL_VOLTAGE_3300#define MMC_SIGNAL_VOLTAGE_1801#define MMC_SIGNAL_VOLTAGE_1202unsigned chardrv_type;/* driver type (A, B, C, D) */#define MMC_SET_DRIVER_TYPE_B0#define MMC_SET_DRIVER_TYPE_A1#define MMC_SET_DRIVER_TYPE_C2#define MMC_SET_DRIVER_TYPE_D3bool enhanced_strobe;/* hs400es selection */};
1)clock,时钟频率。
2)vdd,卡的供电电压,通过“1 << vdd”可以得到MMC_VDD_x_x(具体可参考include/linux/mmc/host.h中MMC_VDD_开头的定义),进而得到电压信息。
3)bus_mode,两种信号模式,open-drain(MMC_BUSMODE_OPENDRAIN)和push-pull(MMC_BUSMODE_PUSHPULL),对应不同的高低电平(可参考相应的spec,例如[2])。
4)chip_select,只针对SPI模式,指定片选信号的有效模式,包括没有片选信号(MMC_CS_DONTCARE)、高电平有效(MMC_CS_HIGH)、低电平有效(MMC_CS_LOW)。
5)power_mode,当前的电源状态,包括MMC_POWER_OFF、MMC_POWER_UP、MMC_POWER_ON和MMC_POWER_UNDEFINED。
6)bus_width,总线的宽度,包括1-bit(MMC_BUS_WIDTH_1)、4-bit(MMC_BUS_WIDTH_4)和8-bit(MMC_BUS_WIDTH_8)。
7)timing,符合哪一种总线时序(大多对应某一类MMC规范),包括:
MMC_TIMING_LEGACY,旧的、不再使用的规范;
MMC_TIMING_MMC_HS,High speed MMC规范(具体可参考相应的spec,这里不再详细介绍,下同);
MMC_TIMING_SD_HS,High speed SD;
MMC_TIMING_UHS_SDR12;
MMC_TIMING_UHS_SDR25
MMC_TIMING_UHS_SDR50
MMC_TIMING_UHS_SDR104
MMC_TIMING_UHS_DDR50
MMC_TIMING_MMC_DDR52
MMC_TIMING_MMC_HS200
MMC_TIMING_MMC_HS400
8)signal_voltage,总线信号使用哪一种电压,3.3v(MMC_SIGNAL_VOLTAGE_330)、1.8v(MMC_SIGNAL_VOLTAGE_180)或者1.2v(MMC_SIGNAL_VOLTAGE_120)。
9)drv_type,驱动能力,包括:
MMC_SET_DRIVER_TYPE_B
MMC_SET_DRIVER_TYPE_A
MMC_SET_DRIVER_TYPE_C
MMC_SET_DRIVER_TYPE_D
3.6 struct mmc_supply
struct mmc_supply中保存了两个struct regulator指针(如下),用于控制MMC子系统有关的供电(vmmc和vqmmc)。
struct mmc_supply {struct regulator *vmmc;/* Card power supply */struct regulator *vqmmc;/* Optional Vccq supply */};
关于vmmc和vqmmc,说明如下:
vmmc是卡的供电电压,一般连接到卡的VDD管脚上。而vqmmc则用于上拉信号线(CMD、CLK和DATA[6])。
通常情况下vqmmc使用和vmmc相同的regulator,同时供电即可。
后来,一些高速卡(例如UHS SD)要求在高速模式下,vmmc为3.3v,vqmmc为1.8v,这就需要两个不同的regulator独立控制。
3.7 struct mmc_request
struct mmc_request封装了一次传输请求,定义如下:
struct mmc_request {struct mmc_command*sbc;/* SET_BLOCK_COUNT for multiblock */struct mmc_command*cmd;struct mmc_data*data;struct mmc_command*stop;struct completioncompletion;struct completioncmd_completion;void(*done)(struct mmc_request *);/* completion function *//** Notify uppers layers (e.g. mmc block driver) that recovery is needed* due to an error associated with the mmc_request. Currently used only* by CQE.*/void(*recovery_notifier)(struct mmc_request *);struct mmc_host*host;/* Allow other commands during this ongoing data transfer or busy wait */boolcap_cmd_during_tfr;inttag;};
要理解这个数据结构,需要先了解MMC的总线协议(bus protocol),这里以eMMC[2]为例进行简单的介绍(更为详细的解释,可参考相应的spec以及本站的文章--“eMMC 原理 4 :总线协议[7]”)。
3.7.1 MMC bus protocol
在eMMC的spec中,称总线协议为“message-based MultiMediaCard bus protocol”,这里的message由三种信标(token)组成:
Command,用于启动(或者停止)一次传输,由Host通过CMD line向Card发送;
Response,用于应答上一次的Command,由Card通过CMD line想Host发送;
Data,传输数据,由Host(或者Card)通过DATA lines向Card(或者Host发送)。
以上token除了Command之外,剩余的两个(Response和Data)都是非必需的,也就是说,一次传输可以是:不需要应答、不需要数据传输的Command;需要应答、不需要数据传输的Command;不需要应答、需要数据传输的Command;不需要应答、不需要数据传输的Command。
Command token的格式只有一种(具体可参考[2]中“Command token format”有关的表述),长度为48bits,包括Start bit(0)、Transmitter bit(1, host command)、Content(38bits)、CRC checksum(7bits)、Stop bit(1)。
根据内容的不同,Response token的格式有5中,分别简称为R1/R3/R4/R5/R2,其中R1/R3/R4/R5的长度为48bits,R2为136bits(具体可参考[2]中“Response token format”有关的表述)。
对于包含了Data token的Command,有两种类型:
Sequential commands,发送Start command之后,数据以stream的形式传输,直到Stop command为止。这种方式只支持1-bit总线模式,主要为了兼容旧的技术,一般不使用;
Block-oriented commands,发送Start command之后,数据以block的形式传输(每个block的大小是固定的,且都由CRC保护)。
最后,以block为单位的传输,大体上也分为两类:
在传输开始的时候(Start command),没有指定需要传输的block数目,直到发送Stop command为止。这种方法在spec中称作“Open-ended”;
在传输开始的时候(Start command),指定需要传输的block数据,当达到数据之后,Card会自动停止传输,这样可以省略Stop command。这种方法在spec中称作pre-defined block count。
3.7.2 struct mmc_request
了解MMC bus protocol之后,再来看一次MMC传输请求(struct mmc_request )所包含的内容:
cmd,Start command,为struct mmc_command类型(具体请参考3.7.3中的介绍)的指针,在一次传输的过程中是必须的;
data,传输的数据,为struct mmc_data类型(具体请参考3.7.4中的介绍)的指针,不是必须要的;
stop、sbc,如果需要进行数据传输,根据数据传输的方式(参考3.7.1中的介绍):如果是“Open-ended”,则需要stop命令(stop指针,或者data->stop指针);如果是pre-defined block count,则需要sbc指针(用于发送SET_BLOCK_COUNT--CMD23命令);
completion,一个struct completion变量,用于等待此次传输完成,host controller driver可以根据需要使用;
done,传输完成时的回调,用于通知传输请求的发起者;
host,对应的mmc host controller指针。
3.7.3 struct mmc_command
struct mmc_command结构抽象了一个MMC command,包括如下内容:
/* include/linux/mmc/core.h */
opcode,Command的操作码,用于标识该命令是哪一个命令,具体可参考相应的spec(例如[2]);
arg,一个Command可能会携带参数,具体可参考相应的spec(例如[2]);
resp[4],Command发出后,如果需要应答,结果保存在resp数组中,该数组是32-bit的,因此最多可以保存128bits的应答;
flags,是一个bitmap,保存该命令所期望的应答类型,例如:
MMC_RSP_PRESENT(1 << 0),是否需要应答,如果该bit为0,则表示该命令不需要应答,否则,需要应答;
MMC_RSP_136(1 << 1),如果为1,表示需要136bits的应答;
MMC_RSP_CRC(1 << 2),如果为1,表示需要对该命令进行CRC校验;
等等,具体可参考include/linux/mmc/core.h中“MMC_RSP_”开头的定义;
retries,如果命令发送出错,可以重新发送,该字段向host driver指明最多可重发的次数;
error,如果最终还是出错,host driver需要通过该字段返回错误的原因,kernel定义了一些标准错误,例如ETIMEDOUT、EILSEQ、EINVAL、ENOMEDIUM等,具体含义可参考include/linux/mmc/core.h中注释;
busy_timeout,如果card具有busy检测的功能,该字段指定等待card返回busy状态的超时时间,单位为ms;
data,和该命令对应的struct mmc_data指针;
mrq,和该命令对应的struct mmc_request指针。
3.7.4 struct mmc_data
struct mmc_data结构包含了数据传输有关的内容:
/* include/linux/mmc/core.h */
timeout_ns、timeout_clks,这一笔数据传输的超时时间(单位分别为ns和clks),如果超过这个时间host driver还无法成功发送,则要将状态返回给mmc core;
blksz、blocks,该笔数据包含多少block(blocks),每个block的size多大(blksz),这两个值不会大于struct mmc_host中上报的max_blk_size和max_blk_count;
error,如果数据传输出错,错误值保存在该字段,具体意义和struct mmc_command中的一致;
flags,一个bitmap,指明该笔传说的方向(MMC_DATA_WRITE或者MMC_DATA_READ);
sg,一个struct scatterlist类型的数组,保存了需要传输的数据(可以通过dma_相关的接口,获得相应的物理地址);
sg_len,sg数组的size;
sg_count,通过sg map出来的实际的entry的个数(可能由于物理地址的连续、IOMMU的干涉等,map出来的entry的个数,可能会小于sg的size);
注5:有关scatterlist的介绍,可参考本站另外的文章(TODO)。有关struct mmc_data的使用场景,可参考5.2小节的介绍;
host_cookie,host driver的私有数据,怎么用由host driver自行决定。
4. 主要API
第3章花了很大的篇幅介绍了用于抽象MMC host的数据结构----struct mmc_host,并详细说明了和mmc_host相关的mmc request、mmc command、mmc data等结构。基于这些知识,本章将介绍MMC core提供的和struct mmc_host有关的操作函数,主要包括如下几类
4.1 向MMC host controller driver提供的用于操作struct mmc_host的API
struct mmc_host *mmc_alloc_host(int extra, struct device *);int mmc_add_host(struct mmc_host *);void mmc_remove_host(struct mmc_host *);void mmc_free_host(struct mmc_host *);int mmc_of_parse(struct mmc_host *host);static inline void *mmc_priv(struct mmc_host *host) {return (void *)host->private;}
mmc_alloc_host,动态分配一个struct mmc_host变量。extra是私有数据的大小,可通过host->private指针访问(也可通过mmc_priv接口直接获取)。mmc_free_host执行相反动作。
mmc_add_host,将已初始化好的host变量注册到kernel中。mmc_remove_host执行相反动作。
为了方便,host controller driver可以在dts中定义host的各种特性,然后在代码中调用mmc_of_parse解析并填充到struct mmc_host变量中。dts属性关键字可参考mmc_of_parse的source code(drivers/mmc/core/host.c),并结合第三章的内容自行理解。
4.1.1mmc_alloc_host
/***mmc_alloc_host - initialise the per-host structure.*@extra: sizeof private data structure*@dev: pointer to host device model structure**Initialise the per-host structure.*//* *参数说明:* extra: mmc_host的私有数据的长度,会和mmc_host结构体一起分配* dev: 底层host controller的device结构体,*用于作为mmc_host的device的父设备*/struct mmc_host *mmc_alloc_host(int extra, struct device *dev){int err;struct mmc_host *host;/* 分配内存空间,其中多分配了extra字节作为私有数据 */host = kzalloc(sizeof(struct mmc_host) + extra, GFP_KERNEL);if (!host)return NULL;/* scanning will be enabled when we're ready *//* 因为只是分配了一个mmc_host,host还没有准备好,所以这里禁用rescan,也就是设置mmc_host->rescan_disable */host->rescan_disable = 1;/* 为该mmc_host分配一个唯一的id号,设置到host->index */err = ida_simple_get(&mmc_host_ida, 0, 0, GFP_KERNEL);if (err < 0) {kfree(host);return NULL;}host->index = err;/* 设置mmc_host name */dev_set_name(&host->class_dev, "mmc%d", host->index);/* 关联mmc_host class_dev并进行初始化 */// 将mmc_host的parent设置成对应host controller节点转化出来的devicehost->parent = dev;/* class_dev就代表了mmc_host 的device结构体,是其在设备驱动模型中的体现 */host->class_dev.parent = dev;// 将mmc_host的device(class_dev)的parent设置成对应host controller节点转化出来的device// 注册到sysfs之后,会相应生成/sys/bus/platform/devices/7824900.sdhci/mmc_host/mmc0// 其中7824900.sdhci表示qcom的host controller节点转化出来的devicehost->class_dev.class = &mmc_host_class;// 将mmc_device(class_dev)的类设置为mmc_host_class// 注册到sysfs之后,会相应生成/sys/class/mmc_host/mmc0device_initialize(&host->class_dev);device_enable_async_suspend(&host->class_dev);if (mmc_gpio_alloc(host)) {put_device(&host->class_dev);return NULL;}spin_lock_init(&host->lock);init_waitqueue_head(&host->wq);/* !!!!这个很重要!!!!初始化detect工作为mmc_rescan,* 后续调度host->detect来检测是否有card插入时,*就会调用到mmc_rescan。*/INIT_DELAYED_WORK(&host->detect, mmc_rescan);INIT_DELAYED_WORK(&host->sdio_irq_work, sdio_irq_work);setup_timer(&host->retune_timer, mmc_retune_timer, (unsigned long)host);/** By default, hosts do not support SGIO or large requests.* They have to set these according to their abilities.*/host->max_segs = 1;// 初始化段大小,(由host自己根据硬件进行修改)host->max_seg_size = PAGE_SIZE;host->max_req_size = PAGE_SIZE;host->max_blk_size = 512; // 一个块的最大字节数host->max_blk_count = PAGE_SIZE / 512; // 一次MMC请求的最大块数量return host;}
底层host controller驱动调用,用来分配一个struct mmc_host结构体,将其于mmc_host_class关联,并且做部分初始化操作。
主要工作:
(1) 分配内存空间
(2) 初始化其class device(对应/sys/class/mmc0节点)
(3) clock gate、锁、工作队列、wakelock、detect工作的初始化
(4) 初始化detect成员(也就是检测工作)为mmc_rescan
(5) 初始化sdio_irq_work为sdio_irq_work。
这边重点强调一个mmc_host->detect=mmc_rescan,当mmc_host的detect work被执行时,就会调用到mmc_rescan中。
相关节点,以mmc_host0为例:
/sys/bus/platform/devices/7824900.sdhci/mmc_host/mmc0/sys/class/mmc_host/mmc0
4.1.2mmc_add_host
/***mmc_add_host - initialise host hardware*@host: mmc host**Register the host with the driver model. The host must be*prepared to start servicing requests before this function*completes.*/int mmc_add_host(struct mmc_host *host){int err;WARN_ON((host->caps & MMC_CAP_SDIO_IRQ) &&!host->ops->enable_sdio_irq);/* 通过device_add将mmc_host->class_dev添加到设备驱动模型中,在sys下生成相应节点 */err = device_add(&host->class_dev);// 通过mmc_alloc_host中关于mmc_host的class_dev的关联,可以生成如下两个节点// /sys/bus/platform/devices/7824900.sdhci/mmc_host/mmc0// /sys/class/mmc_host/mmc0if (err)return err;led_trigger_register_simple(dev_name(&host->class_dev), &host->led);#ifdef CONFIG_DEBUG_FSmmc_add_host_debugfs(host);#endif/* 调用mmc_start_host,也就调用到了mmc core主模块的启动host部分,在mmc core主模块的时候说明 */mmc_start_host(host);mmc_register_pm_notifier(host);return 0;}
底层host controller驱动调用,注册mmc_host到设备驱动中,添加到sys类下面,并设置相应的debug目录。然后启动mmc_host。
主要工作:
使能pm runtime功能
将mmc_host的class_dev添加到设备驱动模型中,在sysfs中生成相应的节点
初始化mmc_host相关的debug目录
设置mmc_host的class_dev的属性
调用mmc_start_host启动host(进入mmc core主模块的部分)
4.1.3 其他
int mmc_power_save_host(struct mmc_host *host); int mmc_power_restore_host(struct mmc_host *host);
从mmc host的角度进行电源管理,进入/退出power save状态。
void mmc_detect_change(struct mmc_host *, unsigned long delay);
当host driver检测到总线上的设备有变动的话(例如卡的插入和拔出等),需要调用这个接口,让MMC core帮忙做后续的工作,例如检测新插入的卡到底是个什么东东……
另外,可以通过delay参数告诉MMC core延时多久(单位为jiffies)开始处理,通常可以用来对卡的拔插进行去抖动。
void mmc_request_done(struct mmc_host *, struct mmc_request *);
当host driver处理完成一个mmc request之后,需要调用该函数通知MMC core,MMC core会进行一些善后的操作,例如校验结果、调用mmc request的.done回调等等。
static inline void mmc_signal_sdio_irq(struct mmc_host *host)void sdio_run_irqs(struct mmc_host *host);
对于SDIO类型的总线,这两个函数用于操作SDIO irqs,后面用到的时候再分析。
int mmc_regulator_get_ocrmask(struct regulator *supply);int mmc_regulator_set_ocr(struct mmc_host *mmc,struct regulator *supply,unsigned short vdd_bit);int mmc_regulator_set_vqmmc(struct mmc_host *mmc, struct mmc_ios *ios);int mmc_regulator_get_supply(struct mmc_host *mmc);
regulator有关的辅助函数:
mmc_regulator_get_ocrmask可根据传入的regulator指针,获取该regulator支持的所有电压值,并以此推导出对应的ocr mask(可参考3.1中的介绍)。
mmc_regulator_set_ocr用于设置host controller为某一个操作电压(vdd_bit),该接口会调用regulator framework的API,进行具体的电压切换。
mmc_regulator_set_vqmmc可根据struct mmc_ios信息,自行调用regulator framework的接口,设置vqmmc的电压。
最后,mmc_regulator_get_supply可以帮忙从dts的vmmc、vqmmc属性值中,解析出对应的regulator指针,以便后面使用。
4.2 用于判断MMC host controller所具备的能力的API
#define mmc_host_is_spi(host) ((host)->caps & MMC_CAP_SPI)static inline int mmc_card_is_removable(struct mmc_host *host)static inline int mmc_card_keep_power(struct mmc_host *host)static inline int mmc_card_wake_sdio_irq(struct mmc_host *host)static inline int mmc_host_cmd23(struct mmc_host *host)static inline int mmc_boot_partition_access(struct mmc_host *host)static inline int mmc_host_uhs(struct mmc_host *host)static inline int mmc_host_packed_wr(struct mmc_host *host)static inline int mmc_card_hs(struct mmc_card *card)static inline int mmc_card_uhs(struct mmc_card *card)static inline bool mmc_card_hs200(struct mmc_card *card)static inline bool mmc_card_ddr52(struct mmc_card *card)static inline bool mmc_card_hs400(struct mmc_card *card)static inline void mmc_retune_needed(struct mmc_host *host)static inline void mmc_retune_recheck(struct mmc_host *host)
5. MMC host驱动的编写步骤
经过上面章节的描述,相信大家对MMC controller driver有了比较深的理解,接下来驱动的编写就是一件水到渠成的事情了。这里简要描述一下驱动编写步骤,也顺便为本文做一个总结。
5.1 struct mmc_host的填充和注册
编写MMC host驱动的所有工作,都是围绕struct mmc_host结构展开的。在对应的platform driver的probe函数中,通过mmc_alloc_host分配一个mmc host后,我们需要根据controller的实际情况,填充对应的字段。
mmc host中大部分和controller能力/特性有关的字段,可以通过dts配置(然后在代码中调用mmc_of_parse自动解析并填充),举例如下:
/* arch/arm/boot/dts/exynos5420-peach-pit.dts */&mmc_1 {status = "okay";num-slots = <1>;non-removable;cap-sdio-irq;keep-power-in-suspend;clock-frequency = <400000000>;samsung,dw-mshc-ciu-div = <1>;samsung,dw-mshc-sdr-timing = <0 1>;samsung,dw-mshc-ddr-timing = <0 2>;pinctrl-names = "default";pinctrl-0 = <&sd1_clk>, <&sd1_cmd>, <&sd1_int>, <&sd1_bus1>,<&sd1_bus4>, <&sd1_bus8>, <&wifi_en>;bus-width = <4>;cap-sd-highspeed;mmc-pwrseq = <&mmc1_pwrseq>;vqmmc-supply = <&buck10_reg>;};
5.2 数据传输的实现
填充struct mmc_host变量的过程中,工作量最大的,就是对struct mmc_host_ops的实现(毫无疑问!所有MMC host的操作逻辑都封在这里呢!!)。这里简单介绍一下相关的概念。
5.2.1 Sectors(扇区)、Blocks(块)以及Segments(段)的理解
我们在3.1小节介绍struct mmc_host的时候,提到了max_seg_size、max_segs、max_req_size、max_blk_size、max_blk_count等参数。这和磁盘设备(块设备)中Sectors、Blocks、Segments等概念有关,下面简单介绍一下:
1)Sectors
Sectors是存储设备访问的基本单位。
对磁盘、NAND等块设备来说,Sector的size是固定的,例如512、2048等。
对存储类的MMC设备来说,按理说也应有固定size的sector。但因为有MMC协议的封装,host驱动以及上面的块设备驱动,不需要关注物理的size。它们需要关注的就是bus上的数据传输单位(具体可参考MMC protocol的介绍[7])。
最后,对那些非存储类的MMC设备来说,完全没有sector的概念了。
2) Blocks
Blocks是数据传输的基本单位,是VFS(虚拟文件系统)抽象出来的概念,是纯软件的概念,和硬件无关。它必须是2的整数倍、不能大于Sectors的单位、不能大于page的长度,一般为512B、2048B或者4096B。
对MMC设备来说,由于协议的封装,淡化了Sector的概念,或者说,MMC设备可以支持一定范围内的任意的Block size。Block size的范围,由两个因素决定:
a)host controller的能力,这反映在struct mmc_host结构的max_blk_size字段上。
b)卡的能力,这可以通过MMC command从卡的CSD(Card-Specific Data)寄存器中读出。
3)Segments[8]
块设备的数据传输,本质上是设备上相邻扇区与内存之间的数据传输。通常情况下,为了提升性能,数据传输通过DMA方式。
在磁盘控制器的旧时代,DMA操作都比较简单,每次传输,数据在内存中必须是连续的。现在则不同,很多SOC都支持“分散/聚合”(scatter-gather)DMA操作,这种操作模式下,数据传输可以在多个非连续的内存区域中进行。
对于每个“分散/聚合”DMA操作,块设备驱动需要向控制器发送:
a)初始扇区号和传输的总共扇区数
b)内存区域的描述链表,每个描述都包含一个地址和长度。不同的描述之间,可以在物理上连续,也可以不连续。
控制器来管理整个数据传输,例如:在读操作中,控制器从块设备相邻的扇区上读取数据,然后将数据分散存储在内存的不同区域。
这里的每个内存区域描述(物理连续的一段内存,可以是一个page,也可以是page的一部分),就称作Segment。一个Segment包含多个相邻扇区。
最后,利用“分散/聚合”的DMA操作,一次数据传输可以会涉及多个segments。
理解了Segment的概念之后,max_seg_size和max_segs两个字段就好理解了:
虽然控制器支持“分散/聚合”的DMA操作,但物理硬件总有限制,例如最大的Segment size(也即一个内存描述的最大长度),最多支持的segment个数(max_segs)等。
5.2.2 struct mmc_data中的sg
我们在3.7.4小节介绍struct mmc_data时,提到了scatterlist的概念。结合上面Segment的解释,就很好理解了:
MMC core提交给MMC host driver的数据传输请求,是一个struct scatterlist链表(也即内存区域的描述链表),也可以理解为是一个个的Segment(Segment的个数保存在sg_len变量中了)。
每个Segment是一段物理地址连续的内存区域,所有的Segments对应了MMC设备中连续的Sector(或者说Block,初始扇区号和传输的总共扇区数已经在之前的MMC command中指定了。
host driver在接收到这样的数据传输请求之后,需要调用dma_map_sg将这些Segment映射出来(获得相应的物理地址),以便交给MMC controller传输。
当然,相邻两个Segment的物理地址可能是连续(或者其它原因),map的时候可能会将两个Segment合成一个。因此可供MMC controller传输的内存片可能少于sg_len(具体要看dma_map_sg的返回值,可将结果保存在sg_count中)。
最后,如何实施传输,则要看具体的MMC controller的硬件实现(可能涉及DMA操作),后面文章再详细介绍。
6. 参考文档
[1]SoC_bubblegum96.pdf
[2]JESD84-A44.pdf
[3] DDR mode,/wiki/Double_data_rate
[4]CARDSPEED - CardReaders and MemoryCards
[5] regulator framework,regulator - 蜗窝科技
[6]MMC/SD/SDIO介绍
[7]eMMC 原理 4 :总线协议
[8]/files/Linux.Generic.Block.Layer.pdf
[9][mmc subsystem] mmc core(第四章)——host模块说明_ooonebook的博客-CSDN博客
如果觉得《Linux内核4.14版本——mmc core(3)——host模块》对你有帮助,请点赞、收藏,并留下你的观点哦!