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 }10011002 /* ... 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 } else1008 local_buf = buf;10091010 memcpy(local_buf, txbuf, n_tx);1011 x[0].tx_buf = local_buf;1012 x[1].rx_buf = local_buf + n_tx;10131014 /* 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 else1022 kfree(local_buf);10231024 return status;1025}1026EXPORT_SYMBOL_GPL(spi_write_then_read);10271028/*-------------------------------------------------------------------------*/
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;10481049err2:1050 bus_unregister(&spi_bus_type);1051err1:1052 kfree(buf);1053 buf = NULL;1054err0:1055 return status;1056}10571058/* board_info is normally registered in arch_initcall(),1059 * but even essential drivers wait till later1060 *1061 * REVISIT only boardinfo really needs static linking. the rest (device and1062 * driver registration) _could_ be dynamically linked (modular) ... costs1063 * include needing to have boardinfo data structures be much more public.1064 */ /* 定义初始化函数，不能再模块中调用，需要静态链接 */1065postcore_initcall(spi_init);
