Linux下SPI驱动分析(5)

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);

-------------------------------------------------

结束。初步了解了代码…

-------------------------------------------------