154 spidev：SPI“万能”驱动

一、总结

内核开放的通用版本的spi驱动

drivers/spi/spidev.c 是 SPI“万能”驱动

内核集成spidev驱动模块，开机后会自动加载此模块
支持修改多种spi通信参数

二、两个数据类型

1、spidev_data结构体

fops中的函数结构都要用到，会被赋值给file->private_data

struct spidev_data {
	// 设备号
	dev_t			devt;
	spinlock_t		spi_lock;
	struct spi_device	*spi;
	struct list_head	device_entry;
	struct mutex		buf_lock;
	unsigned		users;
	// 发送buf，接收buf，通信频率
	u8			*tx_buffer;
	u8			*rx_buffer;
	u32			speed_hz;
};

2、spi_ioc_transfer结构体

include/uapi/linux/spi/spidev.h
可用来设置spi的通信参数，但很少用，用户空间编程也会用到此结构体

struct spi_ioc_transfer {
	// spi数据发送缓存区
	__u64		tx_buf;
	// spi数据接收缓存区
	__u64		rx_buf;
	// 收发数据长度
	__u32		len;
	__u32		speed_hz;

	__u16		delay_usecs;
	__u8		bits_per_word;
	__u8		cs_change;
	__u8		tx_nbits;
	__u8		rx_nbits;
	__u16		pad;
};

三、设备树节点

1、pinctrl子节点

	pinctrl_ecspi3:ecspi3grp {
					// 此属性来记录一个引脚组
					fsl,pins = <
						MX6UL_PAD_UART2_TX_DATA__ECSPI3_SS0     0x1a090
						MX6UL_PAD_UART2_RX_DATA__ECSPI3_SCLK		0x11090
						MX6UL_PAD_UART2_CTS_B__ECSPI3_MOSI			0x11090
						MX6UL_PAD_UART2_RTS_B__ECSPI3_MISO			0x11090
					>;
	};

2、spidev子节点

&ecspi3{
	pinctrl-names = "default";
	// default表示使用pinctrl-0引脚组
	pinctrl-0 = <&pinctrl_ecspi3>;
	status = "okay";
	#address-cells = <1>;
	#size-cells = <0>; 
	// 追加一个设备节点
	// 此节点挂载在spi节点下，会被内核解析成一个spi_device设备，挂在对应的spi总线上
	spidev@0 {
		// 用来匹配对应的驱动，pdidev.c
		compatible = "spidev";
		spi-max-frequency = <20000000>;
		reg = <0>;
	};
};

四、spidev_init()函数

spidev.c

static int __init spidev_init(void)
{
	int status;
	...
	// 申请设备号，参数1主设备号为153
	// 这一步将主设备号153机器所有的次设备号都占用了
	status = register_chrdev(SPIDEV_MAJOR, "spi", &spidev_fops);
	...
	// 创建spidev设备类，新增/sys/class/spidev
	spidev_class = class_create(THIS_MODULE, "spidev");
	...
	// 向内核注册一个spi设备驱动
	status = spi_register_driver(&spidev_spi_driver);
	...
	return status;
}

spidev_fops文件操作接口

static const struct file_operations spidev_fops = {
	.owner =	THIS_MODULE,
	.write =	spidev_write,
	.read =		spidev_read,
	// 应用层 ioctl()函数底层操作接口(32位系统)
	.unlocked_ioctl = spidev_ioctl,
	// 应用层 ioctl()函数底层操作接口(64位系统)
	.compat_ioctl = spidev_compat_ioctl,
	.open =		spidev_open,
	.release =	spidev_release,
	.llseek =	no_llseek,
};

注意read和write接口只能半双工收发消息，
spi支持全双工，可使用unlocked_ioctl接口可以支持半双工，全双工（switch中的default分支）收发消息。

(1) spidev_read()函数

static ssize_t
spidev_read(struct file *filp, char __user *buf, size_t count, loff_t *f_pos)
{
	struct spidev_data	*spidev;
	ssize_t			status = 0;

	/* chipselect only toggles at start or end of operation */
	// 先判断用户空间想要读取的字节数
	if (count > bufsiz)
		return -EMSGSIZE;
	// 通过文件指针获取struct spidev_data，在fops->open中完成赋值
	spidev = filp->private_data;

	mutex_lock(&spidev->buf_lock);
	// 详见下
	status = spidev_sync_read(spidev, count);
	if (status > 0) {
		unsigned long	missing;

		missing = copy_to_user(buf, spidev->rx_buffer, status);
		if (missing == status)
			status = -EFAULT;
		else
			status = status - missing;
	}
	mutex_unlock(&spidev->buf_lock);

	return status;
}

spidev_sync_read()函数

spidev_sync_read(struct spidev_data *spidev, size_t len)
{
	// 此类型是传输spi消息的最基本的单元
	struct spi_transfer	t = {
			// 此buffer在fops->rx_buf中分配，4096
			.rx_buf		= spidev->rx_buffer,
			// 从fops->read可以知道是用户空间希望读取的字节数量
			.len		= len,
			// 在spi_probe中赋值，就是spi的最大通信频率
			.speed_hz	= spidev->speed_hz,
		};
	struct spi_message	m;
	// 初始化，spi核心层的函数，152讲，初始化两个链表
	spi_message_init(&m);
	spi_message_add_tail(&t, &m);
	// 数据发送，详见下
	return spidev_sync(spidev, &m);
}

spidev_sync()函数

static ssize_t
spidev_sync(struct spidev_data *spidev, struct spi_message *message)
{
	int status;
	struct spi_device *spi;

	spin_lock_irq(&spidev->spi_lock);
	spi = spidev->spi;
	spin_unlock_irq(&spidev->spi_lock);

	if (spi == NULL)
		status = -ESHUTDOWN;
	else//153有介绍，异步传输
		status = spi_async(spi, message);

	if (status == 0)
		status = message->actual_length;

	return status;
}

(2) spidev_ioctl()函数

32bit系统对应fops中的unlocked_ioctl接口，即spidev_ioctl

static long
spidev_ioctl(struct file *filp, unsigned int cmd, unsigned long arg)
{
	int			retval = 0;
	struct spidev_data	*spidev;
	struct spi_device	*spi;
	u32			tmp;
	unsigned		n_ioc;
	struct spi_ioc_transfer	*ioc;
	...
	spidev = filp->private_data;
	spin_lock_irq(&spidev->spi_lock);
	spi = spi_dev_get(spidev->spi);
	spin_unlock_irq(&spidev->spi_lock);
	...
	// 由应用层函数ioctl的参数2传递进来，具体的控制命令
	// 控制命令可以分为两类：读和写
	switch (cmd) {
	/* read requests */
	case SPI_IOC_RD_MODE://put_user：复制到用户空间，此处复制spi控制器的模式
		retval = put_user(spi->mode & SPI_MODE_MASK,
					(__u8 __user *)arg);
		break;
	case SPI_IOC_RD_MODE32:
		retval = put_user(spi->mode & SPI_MODE_MASK,
					(__u32 __user *)arg);
		break;
	case SPI_IOC_RD_LSB_FIRST:
		retval = put_user((spi->mode & SPI_LSB_FIRST) ?  1 : 0,
					(__u8 __user *)arg);
		break;
	case SPI_IOC_RD_BITS_PER_WORD:
		retval = put_user(spi->bits_per_word, (__u8 __user *)arg);
		break;
	case SPI_IOC_RD_MAX_SPEED_HZ:
		retval = put_user(spidev->speed_hz, (__u32 __user *)arg);
		break;

	/* write requests */
	case SPI_IOC_WR_MODE:
	case SPI_IOC_WR_MODE32:
		if (cmd == SPI_IOC_WR_MODE)
			retval = get_user(tmp, (u8 __user *)arg);
		else
			retval = get_user(tmp, (u32 __user *)arg);
		if (retval == 0) {
			u32	save = spi->mode;

			if (tmp & ~SPI_MODE_MASK) {
				retval = -EINVAL;
				break;
			}

			tmp |= spi->mode & ~SPI_MODE_MASK;
			// 根据写入的内容去设置mode
			spi->mode = (u16)tmp;
			// 重新设置spi设备的相关属性
			retval = spi_setup(spi);
			if (retval < 0)
				spi->mode = save;
			else
				dev_dbg(&spi->dev, "spi mode %x\n", tmp);
		}
		break;
	case SPI_IOC_WR_LSB_FIRST:
		retval = get_user(tmp, (__u8 __user *)arg);
		if (retval == 0) {
			u32	save = spi->mode;

			if (tmp)
				spi->mode |= SPI_LSB_FIRST;
			else
				spi->mode &= ~SPI_LSB_FIRST;
			retval = spi_setup(spi);
			if (retval < 0)
				spi->mode = save;
			else
				dev_dbg(&spi->dev, "%csb first\n",
						tmp ? 'l' : 'm');
		}
		break;
	case SPI_IOC_WR_BITS_PER_WORD:
		retval = get_user(tmp, (__u8 __user *)arg);
		if (retval == 0) {
			u8	save = spi->bits_per_word;

			spi->bits_per_word = tmp;
			retval = spi_setup(spi);
			if (retval < 0)
				spi->bits_per_word = save;
			else
				dev_dbg(&spi->dev, "%d bits per word\n", tmp);
		}
		break;
	case SPI_IOC_WR_MAX_SPEED_HZ:
		retval = get_user(tmp, (__u32 __user *)arg);
		if (retval == 0) {
			u32	save = spi->max_speed_hz;

			spi->max_speed_hz = tmp;
			retval = spi_setup(spi);
			if (retval >= 0)
				spidev->speed_hz = tmp;
			else
				dev_dbg(&spi->dev, "%d Hz (max)\n", tmp);
			spi->max_speed_hz = save;
		}
		break;

	default://发送特殊的数据，很少使用
		/* segmented and/or full-duplex I/O request */
		/* Check message and copy into scratch area */
		// 获取用户空间传入的struct spi_ioc_transfer
		// 参数2可能是个数组，参数3表示元素的个数
		ioc = spidev_get_ioc_message(cmd,
				(struct spi_ioc_transfer __user *)arg, &n_ioc);
		if (IS_ERR(ioc)) {
			retval = PTR_ERR(ioc);
			break;
		}
		if (!ioc)
			break;	/* n_ioc is also 0 */

		/* translate to spi_message, execute */
		// 此函数实现和spidev_read差不多，详见下
		retval = spidev_message(spidev, ioc, n_ioc);
		kfree(ioc);
		break;
	}

	mutex_unlock(&spidev->buf_lock);
	spi_dev_put(spi);
	return retval;
}

spidev_message()函数

全双工收发信息
本质上还是调用一些spi核心层的函数

static int spidev_message(struct spidev_data *spidev,
		struct spi_ioc_transfer *u_xfers, unsigned n_xfers)
{
	struct spi_message	msg;
	struct spi_transfer	*k_xfers;
	struct spi_transfer	*k_tmp;
	struct spi_ioc_transfer *u_tmp;
	unsigned		n, total, tx_total, rx_total;
	u8			*tx_buf, *rx_buf;
	int			status = -EFAULT;
	// 初始化struct spi_message
	spi_message_init(&msg);
	k_xfers = kcalloc(n_xfers, sizeof(*k_tmp), GFP_KERNEL);
	if (k_xfers == NULL)
		return -ENOMEM;

	tx_buf = spidev->tx_buffer;
	rx_buf = spidev->rx_buffer;
	total = 0;
	tx_total = 0;
	rx_total = 0;
	for (n = n_xfers, k_tmp = k_xfers, u_tmp = u_xfers;
			n;
			n--, k_tmp++, u_tmp++) {
		k_tmp->len = u_tmp->len;

		total += k_tmp->len;
		
		if (total > INT_MAX || k_tmp->len > INT_MAX) {
			status = -EMSGSIZE;
			goto done;
		}

		if (u_tmp->rx_buf) {
			/* this transfer needs space in RX bounce buffer */
			rx_total += k_tmp->len;
			if (rx_total > bufsiz) {
				status = -EMSGSIZE;
				goto done;
			}
			k_tmp->rx_buf = rx_buf;
			rx_buf += k_tmp->len;
		}
		if (u_tmp->tx_buf) {
			/* this transfer needs space in TX bounce buffer */
			tx_total += k_tmp->len;
			if (tx_total > bufsiz) {
				status = -EMSGSIZE;
				goto done;
			}
			k_tmp->tx_buf = tx_buf;
			// 全双工之收，读取用户空间的数据
			if (copy_from_user(tx_buf, (const u8 __user *)
						(uintptr_t) u_tmp->tx_buf,
					u_tmp->len))
				goto done;
			tx_buf += k_tmp->len;
		}

		k_tmp->cs_change = !!u_tmp->cs_change;
		k_tmp->tx_nbits = u_tmp->tx_nbits;
		k_tmp->rx_nbits = u_tmp->rx_nbits;
		k_tmp->bits_per_word = u_tmp->bits_per_word;
		k_tmp->delay_usecs = u_tmp->delay_usecs;
		k_tmp->speed_hz = u_tmp->speed_hz;
		if (!k_tmp->speed_hz)
			k_tmp->speed_hz = spidev->speed_hz;
#ifdef VERBOSE
		dev_dbg(&spidev->spi->dev,
			"  xfer len %u %s%s%s%dbits %u usec %uHz\n",
			u_tmp->len,
			u_tmp->rx_buf ? "rx " : "",
			u_tmp->tx_buf ? "tx " : "",
			u_tmp->cs_change ? "cs " : "",
			u_tmp->bits_per_word ? : spidev->spi->bits_per_word,
			u_tmp->delay_usecs,
			u_tmp->speed_hz ? : spidev->spi->max_speed_hz);
#endif
		spi_message_add_tail(k_tmp, &msg);
	}
	// 同步发送
	status = spidev_sync(spidev, &msg);
	if (status < 0)
		goto done;

	/* copy any rx data out of bounce buffer */
	rx_buf = spidev->rx_buffer;
	for (n = n_xfers, u_tmp = u_xfers; n; n--, u_tmp++) {
		if (u_tmp->rx_buf) {
			// 全双工之发，发回用户空间的数据
			if (copy_to_user((u8 __user *)
					(uintptr_t) u_tmp->rx_buf, rx_buf,
					u_tmp->len)) {
				status = -EFAULT;
				goto done;
			}
			rx_buf += u_tmp->len;
		}
	}
	status = total;

done:
	kfree(k_xfers);
	return status;
}

应用层对应的ioctl()函数

应用层函数，用来控制文件
#include <sys/ioctl.h>

int ioctl(int fd,int request,...)

• 参数：（两个固定参数，加上可变参数）
  fd：要控制的文件描述符
  request：控制命令

• 返回值：
  成功：0
  失败：-1

SPI_MODE_MASK宏

#define SPI_MODE_MASK (SPI_CPHA|SPI_CPOL|SPI_CS_HIGH|SPI_LSB_FIRST|SPI_3WIRE|SPI_LOOP|SPI_NO_CS|SPI_READY)  

spidev_get_ioc_message()函数

drivers/spi/spidev.c

static struct spi_ioc_transfer *
spidev_get_ioc_message(unsigned int cmd, struct spi_ioc_transfer __user *u_ioc,
		unsigned *n_ioc)
{
	u32	tmp;
	// 帕努单命令的合法性
	/* Check type, command number and direction */
	if (_IOC_TYPE(cmd) != SPI_IOC_MAGIC
			|| _IOC_NR(cmd) != _IOC_NR(SPI_IOC_MESSAGE(0))
			|| _IOC_DIR(cmd) != _IOC_WRITE)
		return ERR_PTR(-ENOTTY);
	// 此处约定cmd表示struct spi_ioc_transfer数组总的大小
	tmp = _IOC_SIZE(cmd);
	if ((tmp % sizeof(struct spi_ioc_transfer)) != 0)
		return ERR_PTR(-EINVAL);
	// struct spi_ioc_transfer数组元素个数
	*n_ioc = tmp / sizeof(struct spi_ioc_transfer);
	if (*n_ioc == 0)
		return NULL;

	/* copy into scratch area */
	// 申请内存，复制结构体，返回回去
	return memdup_user(u_ioc, tmp);
}

(3) spidev_open()函数

为tx_buffer、rx_buffer分配4096字节内存

static int spidev_open(struct inode *inode, struct file *filp)
{
	struct spidev_data	*spidev;
	int			status = -ENXIO;

	mutex_lock(&device_list_lock);
	// 之前在spidev_probe中将spidev加入到device_list中保存
	list_for_each_entry(spidev, &device_list, device_entry) {
		// 通过设备号来匹配
		if (spidev->devt == inode->i_rdev) {
			status = 0;
			break;
		}
	}

	if (status) {
		pr_debug("spidev: nothing for minor %d\n", iminor(inode));
		goto err_find_dev;
	}

	if (!spidev->tx_buffer) {
		// 为空则分配内存，参数1为4096
		spidev->tx_buffer = kmalloc(bufsiz, GFP_KERNEL);
		if (!spidev->tx_buffer) {
			dev_dbg(&spidev->spi->dev, "open/ENOMEM\n");
			status = -ENOMEM;
			goto err_find_dev;
		}
	}

	if (!spidev->rx_buffer) {
		// 为空则分配内存，参数1为4096
		spidev->rx_buffer = kmalloc(bufsiz, GFP_KERNEL);
		if (!spidev->rx_buffer) {
			dev_dbg(&spidev->spi->dev, "open/ENOMEM\n");
			status = -ENOMEM;
			goto err_alloc_rx_buf;
		}
	}

	spidev->users++;
	// spidev 记录在文件指针里面
	filp->private_data = spidev;
	// 让当前文件不支持lseek函数
	nonseekable_open(inode, filp);

	mutex_unlock(&device_list_lock);
	return 0;

err_alloc_rx_buf:
	kfree(spidev->tx_buffer);
	spidev->tx_buffer = NULL;
err_find_dev:
	mutex_unlock(&device_list_lock);
	return status;
}

五、spidev_probe()函数

• 主要内容
  创建字符设备
  次设备号按位图分配
  设备文件名后缀数字的含义
  spi控制器编号
  spi设备片选信号编号

static int spidev_probe(struct spi_device *spi)
{
	struct spidev_data	*spidev;
	int			status;
	unsigned long		minor;
	...
	/* Allocate driver data */
	spidev = kzalloc(sizeof(*spidev), GFP_KERNEL);
	if (!spidev)
		return -ENOMEM;

	/* Initialize the driver data */
	spidev->spi = spi;
	spin_lock_init(&spidev->spi_lock);
	mutex_init(&spidev->buf_lock);

	INIT_LIST_HEAD(&spidev->device_entry);

	/* If we can allocate a minor number, hook up this device.
	 * Reusing minors is fine so long as udev or mdev is working.
	 */
	mutex_lock(&device_list_lock);
	// 分配一个次设备号，从256个次设备号中提取1个
	minor = find_first_zero_bit(minors, N_SPI_MINORS);
	if (minor < N_SPI_MINORS) {
		struct device *dev;
		// 此成员记录设备号
		spidev->devt = MKDEV(SPIDEV_MAJOR, minor);
		// 参数4表示spi控制器的编号，参数5表示spi设备使用哪个片选信号
		dev = device_create(spidev_class, &spi->dev, spidev->devt,
				    spidev, "spidev%d.%d",
				    spi->master->bus_num, spi->chip_select);
		status = PTR_ERR_OR_ZERO(dev);
	} else {
		dev_dbg(&spi->dev, "no minor number available!\n");
		status = -ENODEV;
	}
	if (status == 0) {
		set_bit(minor, minors);
		// 链接
		list_add(&spidev->device_entry, &device_list);
	}
	mutex_unlock(&device_list_lock);

	spidev->speed_hz = spi->max_speed_hz;

	if (status == 0)
		spi_set_drvdata(spi, spidev);
	else
		kfree(spidev);

	return status;
}