Documentation/networking/caif/spi_porting.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ================
   4 CAIF SPI porting
   5 ================
   6
   7 CAIF SPI basics
   8 ===============
   9
  10 Running CAIF over SPI needs some extra setup, owing to the nature of SPI.
  11 Two extra GPIOs have been added in order to negotiate the transfers
  12 between the master and the slave. The minimum requirement for running
  13 CAIF over SPI is a SPI slave chip and two GPIOs (more details below).
  14 Please note that running as a slave implies that you need to keep up
  15 with the master clock. An overrun or underrun event is fatal.
  16
  17 CAIF SPI framework
  18 ==================
  19
  20 To make porting as easy as possible, the CAIF SPI has been divided in
  21 two parts. The first part (called the interface part) deals with all
  22 generic functionality such as length framing, SPI frame negotiation
  23 and SPI frame delivery and transmission. The other part is the CAIF
  24 SPI slave device part, which is the module that you have to write if
  25 you want to run SPI CAIF on a new hardware. This part takes care of
  26 the physical hardware, both with regard to SPI and to GPIOs.
  27
  28 - Implementing a CAIF SPI device:
  29
  30         - Functionality provided by the CAIF SPI slave device:
  31
  32         In order to implement a SPI device you will, as a minimum,
  33         need to implement the following
  34         functions:
  35
  36         ::
  37
  38             int (*init_xfer) (struct cfspi_xfer * xfer, struct cfspi_dev *dev):
  39
  40         This function is called by the CAIF SPI interface to give
  41         you a chance to set up your hardware to be ready to receive
  42         a stream of data from the master. The xfer structure contains
  43         both physical and logical addresses, as well as the total length
  44         of the transfer in both directions.The dev parameter can be used
  45         to map to different CAIF SPI slave devices.
  46
  47         ::
  48
  49             void (*sig_xfer) (bool xfer, struct cfspi_dev *dev):
  50
  51         This function is called by the CAIF SPI interface when the output
  52         (SPI_INT) GPIO needs to change state. The boolean value of the xfer
  53         variable indicates whether the GPIO should be asserted (HIGH) or
  54         deasserted (LOW). The dev parameter can be used to map to different CAIF
  55         SPI slave devices.
  56
  57         - Functionality provided by the CAIF SPI interface:
  58
  59         ::
  60
  61             void (*ss_cb) (bool assert, struct cfspi_ifc *ifc);
  62
  63         This function is called by the CAIF SPI slave device in order to
  64         signal a change of state of the input GPIO (SS) to the interface.
  65         Only active edges are mandatory to be reported.
  66         This function can be called from IRQ context (recommended in order
  67         not to introduce latency). The ifc parameter should be the pointer
  68         returned from the platform probe function in the SPI device structure.
  69
  70         ::
  71
  72             void (*xfer_done_cb) (struct cfspi_ifc *ifc);
  73
  74         This function is called by the CAIF SPI slave device in order to
  75         report that a transfer is completed. This function should only be
  76         called once both the transmission and the reception are completed.
  77         This function can be called from IRQ context (recommended in order
  78         not to introduce latency). The ifc parameter should be the pointer
  79         returned from the platform probe function in the SPI device structure.
  80
  81         - Connecting the bits and pieces:
  82
  83                 - Filling in the SPI slave device structure:
  84
  85                   Connect the necessary callback functions.
  86
  87                   Indicate clock speed (used to calculate toggle delays).
  88
  89                   Chose a suitable name (helps debugging if you use several CAIF
  90                   SPI slave devices).
  91
  92                   Assign your private data (can be used to map to your
  93                   structure).
  94
  95                 - Filling in the SPI slave platform device structure:
  96
  97                   Add name of driver to connect to ("cfspi_sspi").
  98
  99                   Assign the SPI slave device structure as platform data.
 100
 101 Padding
 102 =======
 103
 104 In order to optimize throughput, a number of SPI padding options are provided.
 105 Padding can be enabled independently for uplink and downlink transfers.
 106 Padding can be enabled for the head, the tail and for the total frame size.
 107 The padding needs to be correctly configured on both sides of the link.
 108 The padding can be changed via module parameters in cfspi_sspi.c or via
 109 the sysfs directory of the cfspi_sspi driver (before device registration).
 110
 111 - CAIF SPI device template::
 112
 113     /*
 114     *   Copyright (C) ST-Ericsson AB 2010
 115     *   Author: Daniel Martensson / Daniel.Martensson@stericsson.com
 116     *   License terms: GNU General Public License (GPL), version 2.
 117     *
 118     */
 119
 120     #include <linux/init.h>
 121     #include <linux/module.h>
 122     #include <linux/device.h>
 123     #include <linux/wait.h>
 124     #include <linux/interrupt.h>
 125     #include <linux/dma-mapping.h>
 126     #include <net/caif/caif_spi.h>
 127
 128     MODULE_LICENSE("GPL");
 129
 130     struct sspi_struct {
 131             struct cfspi_dev sdev;
 132             struct cfspi_xfer *xfer;
 133     };
 134
 135     static struct sspi_struct slave;
 136     static struct platform_device slave_device;
 137
 138     static irqreturn_t sspi_irq(int irq, void *arg)
 139     {
 140             /* You only need to trigger on an edge to the active state of the
 141             * SS signal. Once a edge is detected, the ss_cb() function should be
 142             * called with the parameter assert set to true. It is OK
 143             * (and even advised) to call the ss_cb() function in IRQ context in
 144             * order not to add any delay. */
 145
 146             return IRQ_HANDLED;
 147     }
 148
 149     static void sspi_complete(void *context)
 150     {
 151             /* Normally the DMA or the SPI framework will call you back
 152             * in something similar to this. The only thing you need to
 153             * do is to call the xfer_done_cb() function, providing the pointer
 154             * to the CAIF SPI interface. It is OK to call this function
 155             * from IRQ context. */
 156     }
 157
 158     static int sspi_init_xfer(struct cfspi_xfer *xfer, struct cfspi_dev *dev)
 159     {
 160             /* Store transfer info. For a normal implementation you should
 161             * set up your DMA here and make sure that you are ready to
 162             * receive the data from the master SPI. */
 163
 164             struct sspi_struct *sspi = (struct sspi_struct *)dev->priv;
 165
 166             sspi->xfer = xfer;
 167
 168             return 0;
 169     }
 170
 171     void sspi_sig_xfer(bool xfer, struct cfspi_dev *dev)
 172     {
 173             /* If xfer is true then you should assert the SPI_INT to indicate to
 174             * the master that you are ready to receive the data from the master
 175             * SPI. If xfer is false then you should de-assert SPI_INT to indicate
 176             * that the transfer is done.
 177             */
 178
 179             struct sspi_struct *sspi = (struct sspi_struct *)dev->priv;
 180     }
 181
 182     static void sspi_release(struct device *dev)
 183     {
 184             /*
 185             * Here you should release your SPI device resources.
 186             */
 187     }
 188
 189     static int __init sspi_init(void)
 190     {
 191             /* Here you should initialize your SPI device by providing the
 192             * necessary functions, clock speed, name and private data. Once
 193             * done, you can register your device with the
 194             * platform_device_register() function. This function will return
 195             * with the CAIF SPI interface initialized. This is probably also
 196             * the place where you should set up your GPIOs, interrupts and SPI
 197             * resources. */
 198
 199             int res = 0;
 200
 201             /* Initialize slave device. */
 202             slave.sdev.init_xfer = sspi_init_xfer;
 203             slave.sdev.sig_xfer = sspi_sig_xfer;
 204             slave.sdev.clk_mhz = 13;
 205             slave.sdev.priv = &slave;
 206             slave.sdev.name = "spi_sspi";
 207             slave_device.dev.release = sspi_release;
 208
 209             /* Initialize platform device. */
 210             slave_device.name = "cfspi_sspi";
 211             slave_device.dev.platform_data = &slave.sdev;
 212
 213             /* Register platform device. */
 214             res = platform_device_register(&slave_device);
 215             if (res) {
 216                     printk(KERN_WARNING "sspi_init: failed to register dev.\n");
 217                     return -ENODEV;
 218             }
 219
 220             return res;
 221     }
 222
 223     static void __exit sspi_exit(void)
 224     {
 225             platform_device_del(&slave_device);
 226     }
 227
 228     module_init(sspi_init);
 229     module_exit(sspi_exit);