Linux下SPI总线驱动有通用接口，一般的SPI设备驱动使用这个驱动接口实现设备驱动。分析驱动最好是先了解核心代码，然后从具体设备分析入手，然后从下至上，了解整个框架，再从上到下分析，理解透彻。
以下分析内核根目录均以"src"代替。内核代码，版本2.6.37.2。
SPI的核心代码即
"src/drivers/spi/spi.c"——SPI 初始化和核心代码
"src/drivers/spi/spi_gpio.c"——IO模拟SPI接口代码
头文件：
"src/include/linux/spi/spi.h"
"src/include/linux/spi/spi_gpio.h"
"src/include/linux/spi/spi_bitbang.h"
首先，先看核心代码。
一步步来，先分析代码，然后看了具体驱动再回过头来看这个核心代码。
spi.c
--------------------------------------------------------------------------------
/* 这个函数是驱动模块卸载时使用 */
32static void spidev_release(struct device *dev)
33{
/* 标准设备结构体转换成SPI设备结构体
* 调用container_of函数获取dev设备所在的SPI设备结构体指针
*/
34 struct spi_device *spi = to_spi_device(dev);
35
36 /* spi masters may cleanup for released devices */
/* 清空SPI主机申请的内存 */
37 if (spi->master->cleanup)
38 spi->master->cleanup(spi);
39
/* 减调用次数 */
40 spi_master_put(spi->master);
/* 释放SPI设备节点内存 */
41 kfree(spi);
42}
43
/* 打印模块别名 */
44static ssize_t
45modalias_show(struct device *dev, struct device_attribute *a, char *buf)
46{
47 const struct spi_device *spi = to_spi_device(dev);
48
49 return sprintf(buf, "%s\n", spi->modalias);
50}
51
/* 设置SPI总线属性——名称/显示 */
52static struct device_attribute spi_dev_attrs[] = {
53 __ATTR_RO(modalias),
54 __ATTR_NULL,
55};
56
/* 获取设备ID */
57/* modalias support makes "modprobe $MODALIAS" new-style hotplug work,
58 * and the sysfs version makes coldplug work too.
59 */
60
61static const struct spi_device_id *spi_match_id(const struct spi_device_id *id,
62 const struct spi_device *sdev)
63{
/* 判断设备中名称与模块别名相同，则返回该设备ID */
64 while (id->name[0]) {
65 if (!strcmp(sdev->modalias, id->name))
66 return id;
67 id++;
68 }
69 return NULL;
70}
71
/* 返回设备ID */
72const struct spi_device_id *spi_get_device_id(const struct spi_device *sdev)
73{
74 const struct spi_driver *sdrv = to_spi_driver(sdev->dev.driver);
75
76 return spi_match_id(sdrv->id_table, sdev);
77}
78EXPORT_SYMBOL_GPL(spi_get_device_id);
接上一个继续看spi.c。
-------------------------------
匹配设备 /* 名词解释of: OpenFirmware
* 调用层次spi_match_device-->of_driver_match_device-->of_match_device-->
* of_match_node
* 用于驱动程序检查platform_device是否在其支持列表里
*/
80static int spi_match_device(struct device *dev, struct device_driver *drv)
81{
82 const struct spi_device *spi = to_spi_device(dev);
83 const struct spi_driver *sdrv = to_spi_driver(drv);
84
85 /* Attempt an OF style match */
/* 不匹配返回0；匹配返回非0，指向struct of_device_id类型的指针
* dev:需要查找的设备; drv:驱动程序结构体
*/
86 if (of_driver_match_device(dev, drv))
87 return 1;
88
/* 在驱动查找设备ID，找到返回真，否则假 */
89 if (sdrv->id_table)
90 return !!spi_match_id(sdrv->id_table, spi);
91
/* 比较设备别名和驱动名称，匹配返回真 */
92 return strcmp(spi->modalias, drv->name) == 0;
93}
94
-------------------------------
uevent /* struct kobj_uevent_env 是内核用户空间的一个环境参数
* uevent是sysfs向用户空间发出的消息，这里实际上添加的是一串字符串消息。
* 关于uevent参考:http://blog.csdn.net/walkingman321/archive/2010/10/01/5917737.aspx
*/
95static int spi_uevent(struct device *dev, struct kobj_uevent_env *env)
96{
97 const struct spi_device *spi = to_spi_device(dev);
98
99 add_uevent_var(env, "MODALIAS=%s%s", SPI_MODULE_PREFIX, spi->modalias);
100 return 0;
101}
-------------------------------
电源管理 /* 配置了电源管理
* 现在不清楚suspend和resume函数哪里实现，等找到了再说
*/
103#ifdef CONFIG_PM
104
/* 挂起
*/
105static int spi_suspend(struct device *dev, pm_message_t message)
106{
107 int value = 0;
108 struct spi_driver *drv = to_spi_driver(dev->driver);
109
110 /* suspend will stop irqs and dma; no more i/o */
/* 挂起将定制终端和DMA，没有输入输出 */
111 if (drv) {
/* 驱动实现了挂起操作函数 */
112 if (drv->suspend)
113 value = drv->suspend(to_spi_device(dev), message);
114 else
115 dev_dbg(dev, "... can't suspend\n");
116 }
117 return value;
118}
119
/* 恢复
*/
120static int spi_resume(struct device *dev)
121{
122 int value = 0;
123 struct spi_driver *drv = to_spi_driver(dev->driver);
124
125 /* resume may restart the i/o queue */
/* 重新开始输入输出队列 */
126 if (drv) {
127 if (drv->resume)
128 value = drv->resume(to_spi_device(dev));
129 else
130 dev_dbg(dev, "... can't resume\n");
131 }
132 return value;
133}
134
135#else /* 没有电源管理 */
136#define spi_suspend NULL
137#define spi_resume NULL
138#endif
-------------------------------
总线 /* 总线 参考:http://hi.baidu.com/xingzuzi/blog/item/d12c03f473b3c2a0a50f5260.html
*/
140struct bus_type spi_bus_type = {
141 .name = "spi",
142 .dev_attrs = spi_dev_attrs,
143 .match = spi_match_device,
144 .uevent = spi_uevent,
145 .suspend = spi_suspend,
146 .resume = spi_resume,
147};
148EXPORT_SYMBOL_GPL(spi_bus_type);
-------------------------------
驱动注册、删除 /* 驱动注册
*/
151static int spi_drv_probe(struct device *dev)
152{
153 const struct spi_driver *sdrv = to_spi_driver(dev->driver);
154
155 return sdrv->probe(to_spi_device(dev));
156}
157
/* 驱动删除
*/
158static int spi_drv_remove(struct device *dev)
159{
160 const struct spi_driver *sdrv = to_spi_driver(dev->driver);
161
162 return sdrv->remove(to_spi_device(dev));
163}
164
/* 关闭
*/
165static void spi_drv_shutdown(struct device *dev)
166{
167 const struct spi_driver *sdrv = to_spi_driver(dev->driver);
168
169 sdrv->shutdown(to_spi_device(dev));
170}
-------------------------------
注册SPI总线驱动 /* 注册SPI驱动
*/
172/**
173 * spi_register_driver - register a SPI driver
174 * @sdrv: the driver to register
175 * Context: can sleep
176 */
177int spi_register_driver(struct spi_driver *sdrv)
178{
/* 初始化总线结构体 */
179 sdrv->driver.bus = &spi_bus_type;
/* 初始化驱动相关函数 */
180 if (sdrv->probe)
181 sdrv->driver.probe = spi_drv_probe;
182 if (sdrv->remove)
183 sdrv->driver.remove = spi_drv_remove;
184 if (sdrv->shutdown)
185 sdrv->driver.shutdown = spi_drv_shutdown;
/* 驱动注册
* 添加驱动到总线
* sysfs、uevent等创建、初始化
*/
186 return driver_register(&sdrv->driver);
187}
188EXPORT_SYMBOL_GPL(spi_register_driver);
接下去看spi.c
特殊的板级相关设备添加方法 /* 神奇的分割线 */
190/*-------------------------------------------------------------------------*/
191
192/* SPI devices should normally not be created by SPI device drivers; that
193 * would make them board-specific. Similarly with SPI master drivers.
194 * Device registration normally goes into like arch/.../mach.../board-YYY.c
195 * with other readonly (flashable) information about mainboard devices.
196 */
197
/* 板级相关信息链表 */
198struct boardinfo {
199 struct list_head list;
200 struct spi_board_info board_info;
201};
202
203static LIST_HEAD(board_list);
204static LIST_HEAD(spi_master_list);
206/*
207 * Used to protect add/del opertion for board_info list and
208 * spi_master list, and their matching process
209 */
/* 链表操作锁 */
210static DEFINE_MUTEX(board_lock);
211
212/**
213 * spi_alloc_device - Allocate a new SPI device
214 * @master: Controller to which device is connected
215 * Context: can sleep
216 *
217 * Allows a driver to allocate and initialize a spi_device without
218 * registering it immediately. This allows a driver to directly
219 * fill the spi_device with device parameters before calling
220 * spi_add_device() on it.
221 *
222 * Caller is responsible to call spi_add_device() on the returned
223 * spi_device structure to add it to the SPI master. If the caller
224 * needs to discard the spi_device without adding it, then it should
225 * call spi_dev_put() on it.
226 *
227 * Returns a pointer to the new device, or NULL.
228 */
/* 为申请SPI设备结构体空间而不注册设备，必须调用spi_add_device，如要丢弃这个设备
* 则必须调用spi_dev_put
*/
229struct spi_device *spi_alloc_device(struct spi_master *master)
230{
231 struct spi_device *spi;
232 struct device *dev = master->dev.parent;
233
/* 增加设备引用次数，相反操作spi_master_put */
234 if (!spi_master_get(master))
235 return NULL;
236
/* 申请内核空间内存 */
237 spi = kzalloc(sizeof *spi, GFP_KERNEL);
238 if (!spi) {
239 dev_err(dev, "cannot alloc spi_device\n");
240 spi_master_put(master);
241 return NULL;
242 }
243
/* SPI主机控制结构体 */
244 spi->master = master;
/* 设备 */
245 spi->dev.parent = dev;
/* 总线 */
246 spi->dev.bus = &spi_bus_type;
/* 删除方法 */
247 spi->dev.release = spidev_release;
/* 设备初始化
* 初始化kobject，dma池链表，设备互斥锁，自旋锁，设备对象的电源相关部分
* src/drivers/base/core.c
*/
248 device_initialize(&spi->dev);
/* 返回spi设备结构体指针 */
249 return spi;
250}
251EXPORT_SYMBOL_GPL(spi_alloc_device);
252
253/**
254 * spi_add_device - Add spi_device allocated with spi_alloc_device
255 * @spi: spi_device to register
256 *
257 * Companion function to spi_alloc_device. Devices allocated with
258 * spi_alloc_device can be added onto the spi bus with this function.
259 *
260 * Returns 0 on success; negative errno on failure
261 */
/* 与spi_alloc_device配合使用，将设备结构体添加到SPI总线 */
262int spi_add_device(struct spi_device *spi)
263{
264 static DEFINE_MUTEX(spi_add_lock);
265 struct device *dev = spi->master->dev.parent;
266 struct device *d;
267 int status;
268
269 /* Chipselects are numbered 0..max; validate. */
/* 设备片选编号比SPI主控制器的片选大，出错 */
270 if (spi->chip_select >= spi->master->num_chipselect) {
271 dev_err(dev, "cs%d >= max %d\n",
272 spi->chip_select,
273 spi->master->num_chipselect);
274 return -EINVAL;
275 }
276
277 /* Set the bus ID string */
/* 设置设备名称，调用kobject的设置设备名称参数方法 */
278 dev_set_name(&spi->dev, "%s.%u", dev_name(&spi->master->dev),
279 spi->chip_select);
280
281
282 /* We need to make sure there's no other device with this
283 * chipselect **BEFORE** we call setup(), else we'll trash
284 * its configuration. Lock against concurrent add() calls.
285 */
/* 互斥锁，保证设置时，没有其他设备用这个片选，防止并发添加add() */
286 mutex_lock(&spi_add_lock);
287
/* 按照名称字符查找设备结构体，设备名称由dev_name查找kobject返回
* 能够找到说明设备已经在用
*/
288 d = bus_find_device_by_name(&spi_bus_type, NULL, dev_name(&spi->dev));
289 if (d != NULL) {
290 dev_err(dev, "chipselect %d already in use\n",
291 spi->chip_select);
292 put_device(d);
293 status = -EBUSY;
294 goto done;
295 }
296
297 /* Drivers may modify this initial i/o setup, but will
298 * normally rely on the device being setup. Devices
299 * using SPI_CS_HIGH can't coexist well otherwise...
300 */
/*
/* 设置SPI模式和时钟频率
* 驱动可以初始化IO，当设备被设置的时候
* 取消片选没有用
* 详细见后面驱动核心方法spi_setup解析
*/
301 status = spi_setup(spi);
302 if (status < 0) {
303 dev_err(dev, "can't setup %s, status %d\n",
304 dev_name(&spi->dev), status);
305 goto done;
306 }
307
308 /* Device may be bound to an active driver when this returns */
/* 将设备添加到驱动层次结构，添加到kobject层次结构，添加到其他子系统 */
309 status = device_add(&spi->dev);
310 if (status < 0)
311 dev_err(dev, "can't add %s, status %d\n",
312 dev_name(&spi->dev), status);
313 else
314 dev_dbg(dev, "registered child %s\n", dev_name(&spi->dev));
315
316done:
317 mutex_unlock(&spi_add_lock);
318 return status;
319}
320EXPORT_SYMBOL_GPL(spi_add_device);
321
322/**
323 * spi_new_device - instantiate one new SPI device
324 * @master: Controller to which device is connected
325 * @chip: Describes the SPI device
326 * Context: can sleep
327 *
328 * On typical mainboards, this is purely internal; and it's not needed
329 * after board init creates the hard-wired devices. Some development
330 * platforms may not be able to use spi_register_board_info though, and
331 * this is exported so that for example a USB or parport based adapter
332 * driver could add devices (which it would learn about out-of-band).
333 *
334 * Returns the new device, or NULL.
335 */
/* 有些开发平台可能不能通过spi_register_board_info添加设备
* 这个用来让一些比如基于USB适配的驱动添加设备
*/
336struct spi_device *spi_new_device(struct spi_master *master,
337 struct spi_board_info *chip)
338{
339 struct spi_device *proxy;
340 int status;
341
342 /* NOTE: caller did any chip->bus_num checks necessary.
343 *
344 * Also, unless we change the return value convention to use
345 * error-or-pointer (not NULL-or-pointer), troubleshootability
346 * suggests syslogged diagnostics are best here (ugh).
347 */
348
/* 分配设备结构体内存空间，并初始化 */
349 proxy = spi_alloc_device(master);
350 if (!proxy)
351 return NULL;
352
353 WARN_ON(strlen(chip->modalias) >= sizeof(proxy->modalias));
354
355 proxy->chip_select = chip->chip_select;
356 proxy->max_speed_hz = chip->max_speed_hz;
357 proxy->mode = chip->mode;
358 proxy->irq = chip->irq;
359 strlcpy(proxy->modalias, chip->modalias, sizeof(proxy->modalias));
360 proxy->dev.platform_data = (void *) chip->platform_data;
361 proxy->controller_data = chip->controller_data;
362 proxy->controller_state = NULL;
363
/* 添加设备 */
364 status = spi_add_device(proxy);
365 if (status < 0) {
366 spi_dev_put(proxy);
367 return NULL;
368 }
369
370 return proxy;
371}
372EXPORT_SYMBOL_GPL(spi_new_device);
373
/* 使用主控制类和板级信息匹配则添加一个新设备 */
374static void spi_match_master_to_boardinfo(struct spi_master *master,
375 struct spi_board_info *bi)
376{
377 struct spi_device *dev;
378
379 if (master->bus_num != bi->bus_num)
380 return;
381
382 dev = spi_new_device(master, bi);
383 if (!dev)
384 dev_err(master->dev.parent, "can't create new device for %s\n",
385 bi->modalias);
386}
387
388/**
389 * spi_register_board_info - register SPI devices for a given board
390 * @info: array of chip descriptors
391 * @n: how many descriptors are provided
392 * Context: can sleep
393 *
394 * Board-specific early init code calls this (probably during arch_initcall)
395 * with segments of the SPI device table. Any device nodes are created later,
396 * after the relevant parent SPI controller (bus_num) is defined. We keep
397 * this table of devices forever, so that reloading a controller driver will
398 * not make Linux forget about these hard-wired devices.
399 *
400 * Other code can also call this, e.g. a particular add-on board might provide
401 * SPI devices through its expansion connector, so code initializing that board
402 * would naturally declare its SPI devices.
403 *
404 * The board info passed can safely be __initdata ... but be careful of
405 * any embedded pointers (platform_data, etc), they're copied as-is.
406 */
/* 使用一系列板级描述信息初始化设备 */
407int __init
408spi_register_board_info(struct spi_board_info const *info, unsigned n)
409{
410 struct boardinfo *bi;
411 int i;
412
413 bi = kzalloc(n * sizeof(*bi), GFP_KERNEL);
414 if (!bi)
415 return -ENOMEM;
416
417 for (i = 0; i < n; i++, bi++, info++) {
418 struct spi_master *master;
419
420 memcpy(&bi->board_info, info, sizeof(*info));
421 mutex_lock(&board_lock);
/* 添加到板级描述符链表 */
422 list_add_tail(&bi->list, &board_list);
/* 将主机控制类链表所有的节点匹配板级信息的设备初始化 */
423 list_for_each_entry(master, &spi_master_list, list)
424 spi_match_master_to_boardinfo(master, &bi->board_info);
425 mutex_unlock(&board_lock);
426 }
427
428 return 0;
429}
430
431/*-------------------------------------------------------------------------*/
接下来继续看SPI主机注册、删除方法。
---------------------------------------------
主机设备删除、添加方法 /* 又见神奇的分割线 */
431/*-------------------------------------------------------------------------*/
432
/* SPI主机驱动删除方法
* 这里是由设备驱动找到主机控制结构体，并释放内存
*/
433static void spi_master_release(struct device *dev)
434{
435 struct spi_master *master;
436
437 master = container_of(dev, struct spi_master, dev);
438 kfree(master);
439}
440
/* SPI主机设备类 */
441static struct class spi_master_class = {
442 .name = "spi_master",
443 .owner = THIS_MODULE,
444 .dev_release = spi_master_release,
445};
446
447
448/**
449 * spi_alloc_master - allocate SPI master controller
450 * @dev: the controller, possibly using the platform_bus
451 * @size: how much zeroed driver-private data to allocate; the pointer to this
452 * memory is in the driver_data field of the returned device,
453 * accessible with spi_master_get_devdata().
454 * Context: can sleep
455 *
456 * This call is used only by SPI master controller drivers, which are the
457 * only ones directly touching chip registers. It's how they allocate
458 * an spi_master structure, prior to calling spi_register_master().
459 *
460 * This must be called from context that can sleep. It returns the SPI
461 * master structure on success, else NULL.
462 *
463 * The caller is responsible for assigning the bus number and initializing
464 * the master's methods before calling spi_register_master(); and (after errors
465 * adding the device) calling spi_master_put() to prevent a memory leak.
466 */
/* 只用在直接操作芯片寄存器的SPI主机控制器驱动
*/
467struct spi_master *spi_alloc_master(struct device *dev, unsigned size)
468{
469 struct spi_master *master;
470
471 if (!dev)
472 return NULL;
473
/* 多申请size用于存放设备私有数据 */
474 master = kzalloc(size + sizeof *master, GFP_KERNEL);
475 if (!master)
476 return NULL;
477
/* 初始化设备，kobject、电源相关方法... */
478 device_initialize(&master->dev);
/* 设备类 */
479 master->dev.class = &spi_master_class;
/* 增加引用次数，并返回设备结构体 */
480 master->dev.parent = get_device(dev);
/* 设置设备私有数据 */
481 spi_master_set_devdata(master, &master[1]);
482
483 return master;
484}
485EXPORT_SYMBOL_GPL(spi_alloc_master);
486
487/**
488 * spi_register_master - register SPI master controller
489 * @master: initialized master, originally from spi_alloc_master()
490 * Context: can sleep
491 *
492 * SPI master controllers connect to their drivers using some non-SPI bus,
493 * such as the platform bus. The final stage of probe() in that code
494 * includes calling spi_register_master() to hook up to this SPI bus glue.
495 *
496 * SPI controllers use board specific (often SOC specific) bus numbers,
497 * and board-specific addressing for SPI devices combines those numbers
498 * with chip select numbers. Since SPI does not directly support dynamic
499 * device identification, boards need configuration tables telling which
500 * chip is at which address.
501 *
502 * This must be called from context that can sleep. It returns zero on
503 * success, else a negative error code (dropping the master's refcount).
504 * After a successful return, the caller is responsible for calling
505 * spi_unregister_master().
506 */
507int spi_register_master(struct spi_master *master)
508{
509 static atomic_t dyn_bus_id = ATOMIC_INIT((1<<15) - 1);
510 struct device *dev = master->dev.parent;
511 struct boardinfo *bi;
512 int status = -ENODEV;
513 int dynamic = 0;
514
515 if (!dev)
516 return -ENODEV;
517
518 /* even if it's just one always-selected device, there must
519 * be at least one chipselect
520 */
/* 至少要有一个片选 */
521 if (master->num_chipselect == 0)
522 return -EINVAL;
523
524 /* convention: dynamically assigned bus IDs count down from the max */
/* 总线号从最大开始减 */
525 if (master->bus_num < 0) {
526 /* FIXME switch to an IDR based scheme, something like
527 * I2C now uses, so we can't run out of "dynamic" IDs
528 */
529 master->bus_num = atomic_dec_return(&dyn_bus_id);
530 dynamic = 1;
531 }
532
533 spin_lock_init(&master->bus_lock_spinlock);
534 mutex_init(&master->bus_lock_mutex);
/* 指示SPI总线是否被锁 */
535 master->bus_lock_flag = 0;
536
537 /* register the device, then userspace will see it.
538 * registration fails if the bus ID is in use.
539 */
/* 注册设备，用户空间就可以看到了
* 失败，当总线ID正在使用
* 下面的设备添加与上一篇文章一样
*/
540 dev_set_name(&master->dev, "spi%u", master->bus_num);
541 status = device_add(&master->dev);
542 if (status < 0)
543 goto done;
544 dev_dbg(dev, "registered master %s%s\n", dev_name(&master->dev),
545 dynamic ? " (dynamic)" : "");
546
547 mutex_lock(&board_lock);
/* 添加主机设备链表 */
548 list_add_tail(&master->list, &spi_master_list);
/* 在主机链表中查找匹配板设备信息的添加设备 */
549 list_for_each_entry(bi, &board_list, list)
550 spi_match_master_to_boardinfo(master, &bi->board_info);
551 mutex_unlock(&board_lock);
552
553 status = 0;
554
555 /* Register devices from the device tree */
/* OF注册SPI设备
* 为主节点的子节点中含有reg属性的子节点注册一个SPI设备
*/
556 of_register_spi_devices(master);
557done:
558 return status;
559}
560EXPORT_SYMBOL_GPL(spi_register_master);
561
562
/* 删除设备驱动 */
563static int __unregister(struct device *dev, void *null)
564{
/* 内联函数，调用device_unregister
* 从系统中删除设备相关的电源方法、sysfs……释放内存、删除文件等
* 减引用次数
*/
565 spi_unregister_device(to_spi_device(dev));
566 return 0;
567}
568
569/**
570 * spi_unregister_master - unregister SPI master controller
571 * @master: the master being unregistered
572 * Context: can sleep
573 *
574 * This call is used only by SPI master controller drivers, which are the
575 * only ones directly touching chip registers.
576 *
577 * This must be called from context that can sleep.
578 */
/* 仅用在SPI主机控制驱动删除 */
579void spi_unregister_master(struct spi_master *master)
580{
581 int dummy;
582
583 mutex_lock(&board_lock);
/* 删除设备链表 */
584 list_del(&master->list);
585 mutex_unlock(&board_lock);
586
/* 删除所有子设备 */
587 dummy = device_for_each_child(&master->dev, NULL, __unregister);
/* 删除设备 */
588 device_unregister(&master->dev);
589}
590EXPORT_SYMBOL_GPL(spi_unregister_master);
591
592static int __spi_master_match(struct device *dev, void *data)
593{
594 struct spi_master *m;
595 u16 *bus_num = data;
596
/* 比较设备的总线数，一样返回TRUE */
597 m = container_of(dev, struct spi_master, dev);
598 return m->bus_num == *bus_num;
599}
600
601/**
602 * spi_busnum_to_master - look up master associated with bus_num
603 * @bus_num: the master's bus number
604 * Context: can sleep
605 *
606 * This call may be used with devices that are registered after
607 * arch init time. It returns a refcounted pointer to the relevant
608 * spi_master (which the caller must release), or NULL if there is
609 * no such master registered.
610 */
611struct spi_master *spi_busnum_to_master(u16 bus_num)
612{
613 struct device *dev;
614 struct spi_master *master = NULL;
615
/* 在主机设备类中查找与bus_num匹配的设备
* 找到则返回主机设备结构体指针
*/
616 dev = class_find_device(&spi_master_class, NULL, &bus_num,
617 __spi_master_match);
618 if (dev)
619 master = container_of(dev, struct spi_master, dev);
620 /* reference got in class_find_device */
621 return master;
622}
623EXPORT_SYMBOL_GPL(spi_busnum_to_master);
---------------------------------------------
接下来，看SPI的核心方法。
---------------------------------------------
SPI主机驱动的核心方法
-------------------------------------------------
SPI主机协议驱动核心方法 /* 神奇的分割线 */
626/*-------------------------------------------------------------------------*/
627
628/* Core methods for SPI master protocol drivers. Some of the
629 * other core methods are currently defined as inline functions.
630 */
631
632/**
633 * spi_setup - setup SPI mode and clock rate
634 * @spi: the device whose settings are being modified
635 * Context: can sleep, and no requests are queued to the device
636 *
637 * SPI protocol drivers may need to update the transfer mode if the
638 * device doesn't work with its default. They may likewise need
639 * to update clock rates or word sizes from initial values. This function
640 * changes those settings, and must be called from a context that can sleep.
641 * Except for SPI_CS_HIGH, which takes effect immediately, the changes take
642 * effect the next time the device is selected and data is transferred to
643 * or from it. When this function returns, the spi device is deselected.
644 *
645 * Note that this call will fail if the protocol driver specifies an option
646 * that the underlying controller or its driver does not support. For
647 * example, not all hardware supports wire transfers using nine bit words,
648 * LSB-first wire encoding, or active-high chipselects.
649 */
650int spi_setup(struct spi_device *spi)
651{
652 unsigned bad_bits;
653 int status;
654
655 /* help drivers fail *cleanly* when they need options
656 * that aren't supported with their current master
657 */
/* 显示驱动不支持的模式 */
658 bad_bits = spi->mode & ~spi->master->mode_bits;
659 if (bad_bits) {
660 dev_err(&spi->dev, "setup: unsupported mode bits %x\n",
661 bad_bits);
662 return -EINVAL;
663 }
664
/* 设置传输位数 */
665 if (!spi->bits_per_word)
666 spi->bits_per_word = 8;
667
/* 调用主机驱动的设置方法设置驱动 */
668 status = spi->master->setup(spi);
669
670 dev_dbg(&spi->dev, "setup mode %d, %s%s%s%s"
671 "%u bits/w, %u Hz max --> %d\n",
672 (int) (spi->mode & (SPI_CPOL | SPI_CPHA)),
673 (spi->mode & SPI_CS_HIGH) ? "cs_high, " : "",
674 (spi->mode & SPI_LSB_FIRST) ? "lsb, " : "",
675 (spi->mode & SPI_3WIRE) ? "3wire, " : "",
676 (spi->mode & SPI_LOOP) ? "loopback, " : "",
677 spi->bits_per_word, spi->max_speed_hz,
678 status);
679
680 return status;
681}
682EXPORT_SYMBOL_GPL(spi_setup);
683
684static int __spi_async(struct spi_device *spi, struct spi_message *message)
685{
686 struct spi_master *master = spi->master;
687
688 /* Half-duplex links include original MicroWire, and ones with
689 * only one data pin like SPI_3WIRE (switches direction) or where
690 * either MOSI or MISO is missing. They can also be caused by
691 * software limitations.
692 */
/* 半双工模式 或者 3线SPI */
693 if ((master->flags & SPI_MASTER_HALF_DUPLEX)
694 || (spi->mode & SPI_3WIRE)) {
/* struct spi_transfer 读写缓存 */
695 struct spi_transfer *xfer;
696 unsigned flags = master->flags;
697
/* 遍历message->transfers链表判断缓存 */
698 list_for_each_entry(xfer, &message->transfers, transfer_list) {
/* 半双工 */
699 if (xfer->rx_buf && xfer->tx_buf)
700 return -EINVAL;
/* 当前模式没有发送，而有发送缓存 */
701 if ((flags & SPI_MASTER_NO_TX) && xfer->tx_buf)
702 return -EINVAL;
/* 当前模式没有接收，而有接收缓存 */
703 if ((flags & SPI_MASTER_NO_RX) && xfer->rx_buf)
704 return -EINVAL;
705 }
706 }
707
/* 该消息使用的设备为SPI */
708 message->spi = spi;
/* 消息正在处理 */
709 message->status = -EINPROGRESS;
/* 调用主机驱动的传输方法 */
710 return master->transfer(spi, message);
711}
712
713/**
714 * spi_async - asynchronous SPI transfer
715 * @spi: device with which data will be exchanged
716 * @message: describes the data transfers, including completion callback
717 * Context: any (irqs may be blocked, etc)
718 *
719 * This call may be used in_irq and other contexts which can't sleep,
720 * as well as from task contexts which can sleep.
721 *
722 * The completion callback is invoked in a context which can't sleep.
723 * Before that invocation, the value of message->status is undefined.
724 * When the callback is issued, message->status holds either zero (to
725 * indicate complete success) or a negative error code. After that
726 * callback returns, the driver which issued the transfer request may
727 * deallocate the associated memory; it's no longer in use by any SPI
728 * core or controller driver code.
729 *
730 * Note that although all messages to a spi_device are handled in
731 * FIFO order, messages may go to different devices in other orders.
732 * Some device might be higher priority, or have various "hard" access
733 * time requirements, for example.
734 *
735 * On detection of any fault during the transfer, processing of
736 * the entire message is aborted, and the device is deselected.
737 * Until returning from the associated message completion callback,
738 * no other spi_message queued to that device will be processed.
739 * (This rule applies equally to all the synchronous transfer calls,
740 * which are wrappers around this core asynchronous primitive.)
741 */
742int spi_async(struct spi_device *spi, struct spi_message *message)
743{
744 struct spi_master *master = spi->master;
745 int ret;
746 unsigned long flags;
747
/* 禁止终端，同时请求持有自旋锁 */
748 spin_lock_irqsave(&master->bus_lock_spinlock, flags);
749
750 if (master->bus_lock_flag)
751 ret = -EBUSY;
752 else
/* 异步传输消息 */
753 ret = __spi_async(spi, message);
754
/* 恢复终端，解锁自旋锁 */
755 spin_unlock_irqrestore(&master->bus_lock_spinlock, flags);
756
757 return ret;
758}
759EXPORT_SYMBOL_GPL(spi_async);
760
761/**
762 * spi_async_locked - version of spi_async with exclusive bus usage
763 * @spi: device with which data will be exchanged
764 * @message: describes the data transfers, including completion callback
765 * Context: any (irqs may be blocked, etc)
766 *
767 * This call may be used in_irq and other contexts which can't sleep,
768 * as well as from task contexts which can sleep.
769 *
770 * The completion callback is invoked in a context which can't sleep.
771 * Before that invocation, the value of message->status is undefined.
772 * When the callback is issued, message->status holds either zero (to
773 * indicate complete success) or a negative error code. After that
774 * callback returns, the driver which issued the transfer request may
775 * deallocate the associated memory; it's no longer in use by any SPI
776 * core or controller driver code.
777 *
778 * Note that although all messages to a spi_device are handled in
779 * FIFO order, messages may go to different devices in other orders.
780 * Some device might be higher priority, or have various "hard" access
781 * time requirements, for example.
782 *
783 * On detection of any fault during the transfer, processing of
784 * the entire message is aborted, and the device is deselected.
785 * Until returning from the associated message completion callback,
786 * no other spi_message queued to that device will be processed.
787 * (This rule applies equally to all the synchronous transfer calls,
788 * which are wrappers around this core asynchronous primitive.)
789 */
/* 另一个版本的spi_async，不包括使用总线 */
790int spi_async_locked(struct spi_device *spi, struct spi_message *message)
791{
792 struct spi_master *master = spi->master;
793 int ret;
794 unsigned long flags;
795
796 spin_lock_irqsave(&master->bus_lock_spinlock, flags);
797
798 ret = __spi_async(spi, message);
799
800 spin_unlock_irqrestore(&master->bus_lock_spinlock, flags);
801
802 return ret;
803
804}
805EXPORT_SYMBOL_GPL(spi_async_locked);
806
807
808/*-------------------------------------------------------------------------*/
-------------------------------------------------
SPI主机协议驱动核心方法2 808/*-------------------------------------------------------------------------*/
809
810/* Utility methods for SPI master protocol drivers, layered on
811 * top of the core. Some other utility methods are defined as
812 * inline functions.
813 */
814
/* 发送信号给一个线程完成等待，唤醒线程 */
815static void spi_complete(void *arg)
816{
817 complete(arg);
818}
819
/* 驱动同步发送信息
* bus_locked如果为1，则不使用锁，0则是使用锁
*/
820static int __spi_sync(struct spi_device *spi, struct spi_message *message,
821 int bus_locked)
822{
/* 在堆栈中定义并初始化一个完成状态变量 */
823 DECLARE_COMPLETION_ONSTACK(done);
824 int status;
825 struct spi_master *master = spi->master;
826
827 message->complete = spi_complete;
828 message->context = &done;
829
830 if (!bus_locked)
831 mutex_lock(&master->bus_lock_mutex);
832
/* 使用不加锁的异步发送消息方法 */
833 status = spi_async_locked(spi, message);
834
835 if (!bus_locked)
836 mutex_unlock(&master->bus_lock_mutex);
837
838 if (status == 0) {
/* 等待任务结束 */
839 wait_for_completion(&done);
840 status = message->status;
841 }
842 message->context = NULL;
843 return status;
844}
845
846/**
847 * spi_sync - blocking/synchronous SPI data transfers
848 * @spi: device with which data will be exchanged
849 * @message: describes the data transfers
850 * Context: can sleep
851 *
852 * This call may only be used from a context that may sleep. The sleep
853 * is non-interruptible, and has no timeout. Low-overhead controller
854 * drivers may DMA directly into and out of the message buffers.
855 *
856 * Note that the SPI device's chip select is active during the message,
857 * and then is normally disabled between messages. Drivers for some
858 * frequently-used devices may want to minimize costs of selecting a chip,
859 * by leaving it selected in anticipation that the next message will go
860 * to the same chip. (That may increase power usage.)
861 *
862 * Also, the caller is guaranteeing that the memory associated with the
863 * message will not be freed before this call returns.
864 *
865 * It returns zero on success, else a negative error code.
866 */
/* 同步、阻塞方式传输 */
867int spi_sync(struct spi_device *spi, struct spi_message *message)
868{
869 return __spi_sync(spi, message, 0);
870}
871EXPORT_SYMBOL_GPL(spi_sync);
872
873/**
874 * spi_sync_locked - version of spi_sync with exclusive bus usage
875 * @spi: device with which data will be exchanged
876 * @message: describes the data transfers
877 * Context: can sleep
878 *
879 * This call may only be used from a context that may sleep. The sleep
880 * is non-interruptible, and has no timeout. Low-overhead controller
881 * drivers may DMA directly into and out of the message buffers.
882 *
883 * This call should be used by drivers that require exclusive access to the
884 * SPI bus. It has to be preceeded by a spi_bus_lock call. The SPI bus must
885 * be released by a spi_bus_unlock call when the exclusive access is over.
886 *
887 * It returns zero on success, else a negative error code.
888 */
/* 同步、阻塞方式传输，不是用总线锁 */
889int spi_sync_locked(struct spi_device *spi, struct spi_message *message)
890{
891 return __spi_sync(spi, message, 1);
892}
893EXPORT_SYMBOL_GPL(spi_sync_locked);
-------------------------------------------------
总线加解锁 /* 用于上述无使用锁得方法 */
895/**
896 * spi_bus_lock - obtain a lock for exclusive SPI bus usage
897 * @master: SPI bus master that should be locked for exclusive bus access
898 * Context: can sleep
899 *
900 * This call may only be used from a context that may sleep. The sleep
901 * is non-interruptible, and has no timeout.
902 *
903 * This call should be used by drivers that require exclusive access to the
904 * SPI bus. The SPI bus must be released by a spi_bus_unlock call when the
905 * exclusive access is over. Data transfer must be done by spi_sync_locked
906 * and spi_async_locked calls when the SPI bus lock is held.
907 *
908 * It returns zero on success, else a negative error code.
909 */
/* 用于不使用总线锁的一些方法来加锁 */
910int spi_bus_lock(struct spi_master *master)
911{
912 unsigned long flags;
913
914 mutex_lock(&master->bus_lock_mutex);
915
916 spin_lock_irqsave(&master->bus_lock_spinlock, flags);
917 master->bus_lock_flag = 1;
918 spin_unlock_irqrestore(&master->bus_lock_spinlock, flags);
919
920 /* mutex remains locked until spi_bus_unlock is called */
921
922 return 0;
923}
924EXPORT_SYMBOL_GPL(spi_bus_lock);
925
926/**
927 * spi_bus_unlock - release the lock for exclusive SPI bus usage
928 * @master: SPI bus master that was locked for exclusive bus access
929 * Context: can sleep
930 *
931 * This call may only be used from a context that may sleep. The sleep
932 * is non-interruptible, and has no timeout.
933 *
934 * This call releases an SPI bus lock previously obtained by an spi_bus_lock
935 * call.
936 *
937 * It returns zero on success, else a negative error code.
938 */
/* 用于不使用总线锁的一些方法来解锁 */
939int spi_bus_unlock(struct spi_master *master)
940{
941 master->bus_lock_flag = 0;
942
943 mutex_unlock(&master->bus_lock_mutex);
944
945 return 0;
946}
947EXPORT_SYMBOL_GPL(spi_bus_unlock);
-------------------------------------------------
半双工式的传输，先写后读 /* SPI缓存大小 */
949/* portable code must never pass more than 32 bytes */
950#define SPI_BUFSIZ max(32,SMP_CACHE_BYTES)
951
/* 缓存指针 */
952static u8 *buf;
953
954/**
955 * spi_write_then_read - SPI synchronous write followed by read
956 * @spi: device with which data will be exchanged
957 * @txbuf: data to be written (need not be dma-safe)
958 * @n_tx: size of txbuf, in bytes
959 * @rxbuf: buffer into which data will be read (need not be dma-safe)
960 * @n_rx: size of rxbuf, in bytes
961 * Context: can sleep
962 *
963 * This performs a half duplex MicroWire style transaction with the
964 * device, sending txbuf and then reading rxbuf. The return value
965 * is zero for success, else a negative errno status code.
966 * This call may only be used from a context that may sleep.
967 *
968 * Parameters to this routine are always copied using a small buffer;
969 * portable code should never use this for more than 32 bytes.
970 * Performance-sensitive or bulk transfer code should instead use
971 * spi_{async,sync}() calls with dma-safe buffers.
972 */
/* 半双工式的传输，先写后读
*/
973int spi_write_then_read(struct spi_device *spi,
974 const u8 *txbuf, unsigned n_tx,
975 u8 *rxbuf, unsigned n_rx)
976{
/* 定义、初始化缓存互斥锁 */
977 static DEFINE_MUTEX(lock);
978
979 int status;
980 struct spi_message message;
981 struct spi_transfer x[2];
982 u8 *local_buf;
983
984 /* Use preallocated DMA-safe buffer. We can't avoid copying here,
985 * (as a pure convenience thing), but we can keep heap costs
986 * out of the hot path ...
987 */
/* 要发送和接收数据总量不能超过缓存大小 */
988 if ((n_tx + n_rx) > SPI_BUFSIZ)
989 return -EINVAL;
990
/* 初始化message->transfer缓存链表 */
991 spi_message_init(&message);
992 memset(x, 0, sizeof x);
/* 需要发送，将x[0]加入消息链表尾 */
993 if (n_tx) {
994 x[0].len = n_tx;
995 spi_message_add_tail(&x[0], &message);
996 }
/* 需要接收，将x[1]加入消息链表尾 */
997 if (n_rx) {
998 x[1].len = n_rx;
999 spi_message_add_tail(&x[1], &message);
1000 }
1001
1002 /* ... unless someone else is using the pre-allocated buffer */
/* 有在用，则重新申请一块内存，第一次锁操作必返回1
* 这里有个地方，buf没有申请内存空间，如何使用？
*/
1003 if (!mutex_trylock(&lock)) {
1004 local_buf = kmalloc(SPI_BUFSIZ, GFP_KERNEL);
1005 if (!local_buf)
1006 return -ENOMEM;
1007 } else
1008 local_buf = buf;
1009
1010 memcpy(local_buf, txbuf, n_tx);
1011 x[0].tx_buf = local_buf;
1012 x[1].rx_buf = local_buf + n_tx;
1013
1014 /* do the i/o */
/* IO操作，传输消息 */
1015 status = spi_sync(spi, &message);
/* 成功，拷贝接收数据 */
1016 if (status == 0)
1017 memcpy(rxbuf, x[1].rx_buf, n_rx);
1018
/* 释放缓存空间，解锁 */
1019 if (x[0].tx_buf == buf)
1020 mutex_unlock(&lock);
1021 else
1022 kfree(local_buf);
1023
1024 return status;
1025}
1026EXPORT_SYMBOL_GPL(spi_write_then_read);
1027
1028/*-------------------------------------------------------------------------*/
-------------------------------------------------
SPI初始化 /* SPI初始化
* 初始化缓存
* 注册总线驱动
* 注册主机驱动类
*/
1030static int __init spi_init(void)
1031{
1032 int status;
1033
/* 初始化缓存 */
1034 buf = kmalloc(SPI_BUFSIZ, GFP_KERNEL);
1035 if (!buf) {
1036 status = -ENOMEM;
1037 goto err0;
1038 }
1039
/* 注册总线驱动 */
1040 status = bus_register(&spi_bus_type);
1041 if (status < 0)
1042 goto err1;
1043
/* 注册主机驱动类 */
1044 status = class_register(&spi_master_class);
1045 if (status < 0)
1046 goto err2;
1047 return 0;
1048
1049err2:
1050 bus_unregister(&spi_bus_type);
1051err1:
1052 kfree(buf);
1053 buf = NULL;
1054err0:
1055 return status;
1056}
1057
1058/* board_info is normally registered in arch_initcall(),
1059 * but even essential drivers wait till later
1060 *
1061 * REVISIT only boardinfo really needs static linking. the rest (device and
1062 * driver registration) _could_ be dynamically linked (modular) ... costs
1063 * include needing to have boardinfo data structures be much more public.
1064 */
/* 定义初始化函数，不能再模块中调用，需要静态链接 */
1065postcore_initcall(spi_init);
-------------------------------------------------
结束。初步了解了代码…
-------------------------------------------------
本篇文章来源于 Linux公社网站() 原文链接：
