LCOV - code coverage report
Current view: top level - include/linux/spi - spi.h (source / functions) Hit Total Coverage
Test: coverage.info Lines: 4 4 100.0 %
Date: 2017-01-25 Functions: 0 0 -

          Line data    Source code
       1             : /*
       2             :  * Copyright (C) 2005 David Brownell
       3             :  *
       4             :  * This program is free software; you can redistribute it and/or modify
       5             :  * it under the terms of the GNU General Public License as published by
       6             :  * the Free Software Foundation; either version 2 of the License, or
       7             :  * (at your option) any later version.
       8             :  *
       9             :  * This program is distributed in the hope that it will be useful,
      10             :  * but WITHOUT ANY WARRANTY; without even the implied warranty of
      11             :  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      12             :  * GNU General Public License for more details.
      13             :  *
      14             :  * You should have received a copy of the GNU General Public License
      15             :  * along with this program; if not, write to the Free Software
      16             :  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
      17             :  */
      18             : 
      19             : #ifndef __LINUX_SPI_H
      20             : #define __LINUX_SPI_H
      21             : 
      22             : #include <linux/device.h>
      23             : #include <linux/mod_devicetable.h>
      24             : 
      25             : /*
      26             :  * INTERFACES between SPI master-side drivers and SPI infrastructure.
      27             :  * (There's no SPI slave support for Linux yet...)
      28             :  */
      29             : extern struct bus_type spi_bus_type;
      30           2 : 
      31             : /**
      32             :  * struct spi_device - Master side proxy for an SPI slave device
      33             :  * @dev: Driver model representation of the device.
      34             :  * @master: SPI controller used with the device.
      35             :  * @max_speed_hz: Maximum clock rate to be used with this chip
      36             :  *      (on this board); may be changed by the device's driver.
      37             :  *      The spi_transfer.speed_hz can override this for each transfer.
      38             :  * @chip_select: Chipselect, distinguishing chips handled by @master.
      39             :  * @mode: The spi mode defines how data is clocked out and in.
      40             :  *      This may be changed by the device's driver.
      41             :  *      The "active low" default for chipselect mode can be overridden
      42             :  *      (by specifying SPI_CS_HIGH) as can the "MSB first" default for
      43             :  *      each word in a transfer (by specifying SPI_LSB_FIRST).
      44             :  * @bits_per_word: Data transfers involve one or more words; word sizes
      45             :  *      like eight or 12 bits are common.  In-memory wordsizes are
      46             :  *      powers of two bytes (e.g. 20 bit samples use 32 bits).
      47             :  *      This may be changed by the device's driver, or left at the
      48             :  *      default (0) indicating protocol words are eight bit bytes.
      49             :  *      The spi_transfer.bits_per_word can override this for each transfer.
      50             :  * @irq: Negative, or the number passed to request_irq() to receive
      51             :  *      interrupts from this device.
      52             :  * @controller_state: Controller's runtime state
      53             :  * @controller_data: Board-specific definitions for controller, such as
      54             :  *      FIFO initialization parameters; from board_info.controller_data
      55             :  * @modalias: Name of the driver to use with this device, or an alias
      56             :  *      for that name.  This appears in the sysfs "modalias" attribute
      57             :  *      for driver coldplugging, and in uevents used for hotplugging
      58             :  *
      59             :  * A @spi_device is used to interchange data between an SPI slave
      60             :  * (usually a discrete chip) and CPU memory.
      61             :  *
      62             :  * In @dev, the platform_data is used to hold information about this
      63             :  * device that's meaningful to the device's protocol driver, but not
      64             :  * to its controller.  One example might be an identifier for a chip
      65             :  * variant with slightly different functionality; another might be
      66             :  * information about how this particular board wires the chip's pins.
      67             :  */
      68             : struct spi_device {
      69             :         struct device           dev;
      70             :         struct spi_master       *master;
      71             :         u32                     max_speed_hz;
      72             :         u8                      chip_select;
      73             :         u8                      mode;
      74             : #define SPI_CPHA        0x01                    /* clock phase */
      75             : #define SPI_CPOL        0x02                    /* clock polarity */
      76             : #define SPI_MODE_0      (0|0)                   /* (original MicroWire) */
      77             : #define SPI_MODE_1      (0|SPI_CPHA)
      78             : #define SPI_MODE_2      (SPI_CPOL|0)
      79             : #define SPI_MODE_3      (SPI_CPOL|SPI_CPHA)
      80             : #define SPI_CS_HIGH     0x04                    /* chipselect active high? */
      81             : #define SPI_LSB_FIRST   0x08                    /* per-word bits-on-wire */
      82             : #define SPI_3WIRE       0x10                    /* SI/SO signals shared */
      83             : #define SPI_LOOP        0x20                    /* loopback mode */
      84             : #define SPI_NO_CS       0x40                    /* 1 dev/bus, no chipselect */
      85             : #define SPI_READY       0x80                    /* slave pulls low to pause */
      86             :         u8                      bits_per_word;
      87             :         int                     irq;
      88             :         void                    *controller_state;
      89             :         void                    *controller_data;
      90             :         char                    modalias[SPI_NAME_SIZE];
      91             : 
      92             :         /*
      93             :          * likely need more hooks for more protocol options affecting how
      94             :          * the controller talks to each chip, like:
      95             :          *  - memory packing (12 bit samples into low bits, others zeroed)
      96             :          *  - priority
      97             :          *  - drop chipselect after each word
      98             :          *  - chipselect delays
      99             :          *  - ...
     100             :          */
     101             : };
     102             : 
     103             : static inline struct spi_device *to_spi_device(struct device *dev)
     104             : {
     105             :         return dev ? container_of(dev, struct spi_device, dev) : NULL;
     106             : }
     107             : 
     108             : /* most drivers won't need to care about device refcounting */
     109             : static inline struct spi_device *spi_dev_get(struct spi_device *spi)
     110             : {
     111             :         return (spi && get_device(&spi->dev)) ? spi : NULL;
     112             : }
     113             : 
     114             : static inline void spi_dev_put(struct spi_device *spi)
     115             : {
     116             :         if (spi)
     117             :                 put_device(&spi->dev);
     118             : }
     119             : 
     120             : /* ctldata is for the bus_master driver's runtime state */
     121             : static inline void *spi_get_ctldata(struct spi_device *spi)
     122             : {
     123             :         return spi->controller_state;
     124             : }
     125             : 
     126             : static inline void spi_set_ctldata(struct spi_device *spi, void *state)
     127             : {
     128             :         spi->controller_state = state;
     129             : }
     130             : 
     131             : /* device driver data */
     132             : 
     133             : static inline void spi_set_drvdata(struct spi_device *spi, void *data)
     134             : {
     135             :         dev_set_drvdata(&spi->dev, data);
     136             : }
     137             : 
     138             : static inline void *spi_get_drvdata(struct spi_device *spi)
     139             : {
     140             :         return dev_get_drvdata(&spi->dev);
     141             : }
     142           1 : 
     143             : struct spi_message;
     144             : 
     145             : 
     146             : 
     147             : /**
     148             :  * struct spi_driver - Host side "protocol" driver
     149             :  * @id_table: List of SPI devices supported by this driver
     150             :  * @probe: Binds this driver to the spi device.  Drivers can verify
     151             :  *      that the device is actually present, and may need to configure
     152             :  *      characteristics (such as bits_per_word) which weren't needed for
     153             :  *      the initial configuration done during system setup.
     154             :  * @remove: Unbinds this driver from the spi device
     155             :  * @shutdown: Standard shutdown callback used during system state
     156             :  *      transitions such as powerdown/halt and kexec
     157             :  * @suspend: Standard suspend callback used during system state transitions
     158             :  * @resume: Standard resume callback used during system state transitions
     159             :  * @driver: SPI device drivers should initialize the name and owner
     160             :  *      field of this structure.
     161             :  *
     162             :  * This represents the kind of device driver that uses SPI messages to
     163             :  * interact with the hardware at the other end of a SPI link.  It's called
     164             :  * a "protocol" driver because it works through messages rather than talking
     165             :  * directly to SPI hardware (which is what the underlying SPI controller
     166             :  * driver does to pass those messages).  These protocols are defined in the
     167             :  * specification for the device(s) supported by the driver.
     168             :  *
     169             :  * As a rule, those device protocols represent the lowest level interface
     170             :  * supported by a driver, and it will support upper level interfaces too.
     171             :  * Examples of such upper levels include frameworks like MTD, networking,
     172             :  * MMC, RTC, filesystem character device nodes, and hardware monitoring.
     173             :  */
     174             : struct spi_driver {
     175             :         const struct spi_device_id *id_table;
     176             :         int                     (*probe)(struct spi_device *spi);
     177             :         int                     (*remove)(struct spi_device *spi);
     178             :         void                    (*shutdown)(struct spi_device *spi);
     179             :         int                     (*suspend)(struct spi_device *spi, pm_message_t mesg);
     180             :         int                     (*resume)(struct spi_device *spi);
     181             :         struct device_driver    driver;
     182             : };
     183             : 
     184             : static inline struct spi_driver *to_spi_driver(struct device_driver *drv)
     185             : {
     186             :         return drv ? container_of(drv, struct spi_driver, driver) : NULL;
     187             : }
     188             : 
     189             : extern int spi_register_driver(struct spi_driver *sdrv);
     190             : 
     191             : /**
     192             :  * spi_unregister_driver - reverse effect of spi_register_driver
     193             :  * @sdrv: the driver to unregister
     194             :  * Context: can sleep
     195             :  */
     196             : static inline void spi_unregister_driver(struct spi_driver *sdrv)
     197             : {
     198             :         if (sdrv)
     199             :                 driver_unregister(&sdrv->driver);
     200             : }
     201           1 : 
     202             : 
     203             : /**
     204             :  * struct spi_master - interface to SPI master controller
     205             :  * @dev: device interface to this driver
     206             :  * @bus_num: board-specific (and often SOC-specific) identifier for a
     207             :  *      given SPI controller.
     208             :  * @num_chipselect: chipselects are used to distinguish individual
     209             :  *      SPI slaves, and are numbered from zero to num_chipselects.
     210             :  *      each slave has a chipselect signal, but it's common that not
     211             :  *      every chipselect is connected to a slave.
     212             :  * @dma_alignment: SPI controller constraint on DMA buffers alignment.
     213             :  * @mode_bits: flags understood by this controller driver
     214             :  * @flags: other constraints relevant to this driver
     215             :  * @setup: updates the device mode and clocking records used by a
     216             :  *      device's SPI controller; protocol code may call this.  This
     217             :  *      must fail if an unrecognized or unsupported mode is requested.
     218             :  *      It's always safe to call this unless transfers are pending on
     219             :  *      the device whose settings are being modified.
     220             :  * @transfer: adds a message to the controller's transfer queue.
     221             :  * @cleanup: frees controller-specific state
     222             :  *
     223             :  * Each SPI master controller can communicate with one or more @spi_device
     224             :  * children.  These make a small bus, sharing MOSI, MISO and SCK signals
     225             :  * but not chip select signals.  Each device may be configured to use a
     226             :  * different clock rate, since those shared signals are ignored unless
     227             :  * the chip is selected.
     228             :  *
     229             :  * The driver for an SPI controller manages access to those devices through
     230             :  * a queue of spi_message transactions, copying data between CPU memory and
     231             :  * an SPI slave device.  For each such message it queues, it calls the
     232             :  * message's completion function when the transaction completes.
     233             :  */
     234             : struct spi_master {
     235             :         struct device   dev;
     236             : 
     237             :         /* other than negative (== assign one dynamically), bus_num is fully
     238             :          * board-specific.  usually that simplifies to being SOC-specific.
     239             :          * example:  one SOC has three SPI controllers, numbered 0..2,
     240             :          * and one board's schematics might show it using SPI-2.  software
     241             :          * would normally use bus_num=2 for that controller.
     242             :          */
     243             :         s16                     bus_num;
     244             : 
     245             :         /* chipselects will be integral to many controllers; some others
     246             :          * might use board-specific GPIOs.
     247             :          */
     248             :         u16                     num_chipselect;
     249             : 
     250             :         /* some SPI controllers pose alignment requirements on DMAable
     251             :          * buffers; let protocol drivers know about these requirements.
     252             :          */
     253             :         u16                     dma_alignment;
     254             : 
     255             :         /* spi_device.mode flags understood by this controller driver */
     256             :         u16                     mode_bits;
     257             : 
     258             :         /* other constraints relevant to this driver */
     259             :         u16                     flags;
     260             : #define SPI_MASTER_HALF_DUPLEX  BIT(0)          /* can't do full duplex */
     261             : #define SPI_MASTER_NO_RX        BIT(1)          /* can't do buffer read */
     262             : #define SPI_MASTER_NO_TX        BIT(2)          /* can't do buffer write */
     263             : 
     264             :         /* Setup mode and clock, etc (spi driver may call many times).
     265             :          *
     266             :          * IMPORTANT:  this may be called when transfers to another
     267             :          * device are active.  DO NOT UPDATE SHARED REGISTERS in ways
     268             :          * which could break those transfers.
     269             :          */
     270             :         int                     (*setup)(struct spi_device *spi);
     271             : 
     272             :         /* bidirectional bulk transfers
     273             :          *
     274             :          * + The transfer() method may not sleep; its main role is
     275             :          *   just to add the message to the queue.
     276             :          * + For now there's no remove-from-queue operation, or
     277             :          *   any other request management
     278             :          * + To a given spi_device, message queueing is pure fifo
     279             :          *
     280             :          * + The master's main job is to process its message queue,
     281             :          *   selecting a chip then transferring data
     282             :          * + If there are multiple spi_device children, the i/o queue
     283             :          *   arbitration algorithm is unspecified (round robin, fifo,
     284             :          *   priority, reservations, preemption, etc)
     285             :          *
     286             :          * + Chipselect stays active during the entire message
     287             :          *   (unless modified by spi_transfer.cs_change != 0).
     288             :          * + The message transfers use clock and SPI mode parameters
     289             :          *   previously established by setup() for this device
     290             :          */
     291             :         int                     (*transfer)(struct spi_device *spi,
     292             :                                                 struct spi_message *mesg);
     293             : 
     294             :         /* called on release() to free memory provided by spi_master */
     295             :         void                    (*cleanup)(struct spi_device *spi);
     296             : };
     297             : 
     298             : static inline void *spi_master_get_devdata(struct spi_master *master)
     299             : {
     300             :         return dev_get_drvdata(&master->dev);
     301             : }
     302             : 
     303             : static inline void spi_master_set_devdata(struct spi_master *master, void *data)
     304             : {
     305             :         dev_set_drvdata(&master->dev, data);
     306             : }
     307             : 
     308             : static inline struct spi_master *spi_master_get(struct spi_master *master)
     309             : {
     310             :         if (!master || !get_device(&master->dev))
     311             :                 return NULL;
     312             :         return master;
     313             : }
     314             : 
     315             : static inline void spi_master_put(struct spi_master *master)
     316             : {
     317             :         if (master)
     318             :                 put_device(&master->dev);
     319             : }
     320             : 
     321             : 
     322             : /* the spi driver core manages memory for the spi_master classdev */
     323             : extern struct spi_master *
     324             : spi_alloc_master(struct device *host, unsigned size);
     325             : 
     326             : extern int spi_register_master(struct spi_master *master);
     327             : extern void spi_unregister_master(struct spi_master *master);
     328             : 
     329             : extern struct spi_master *spi_busnum_to_master(u16 busnum);
     330             : 
     331             : /*---------------------------------------------------------------------------*/
     332             : 
     333             : /*
     334             :  * I/O INTERFACE between SPI controller and protocol drivers
     335             :  *
     336             :  * Protocol drivers use a queue of spi_messages, each transferring data
     337             :  * between the controller and memory buffers.
     338             :  *
     339             :  * The spi_messages themselves consist of a series of read+write transfer
     340             :  * segments.  Those segments always read the same number of bits as they
     341             :  * write; but one or the other is easily ignored by passing a null buffer
     342             :  * pointer.  (This is unlike most types of I/O API, because SPI hardware
     343             :  * is full duplex.)
     344             :  *
     345             :  * NOTE:  Allocation of spi_transfer and spi_message memory is entirely
     346             :  * up to the protocol driver, which guarantees the integrity of both (as
     347             :  * well as the data buffers) for as long as the message is queued.
     348             :  */
     349             : 
     350             : /**
     351             :  * struct spi_transfer - a read/write buffer pair
     352             :  * @tx_buf: data to be written (dma-safe memory), or NULL
     353             :  * @rx_buf: data to be read (dma-safe memory), or NULL
     354             :  * @tx_dma: DMA address of tx_buf, if @spi_message.is_dma_mapped
     355             :  * @rx_dma: DMA address of rx_buf, if @spi_message.is_dma_mapped
     356             :  * @len: size of rx and tx buffers (in bytes)
     357             :  * @speed_hz: Select a speed other than the device default for this
     358             :  *      transfer. If 0 the default (from @spi_device) is used.
     359             :  * @bits_per_word: select a bits_per_word other than the device default
     360             :  *      for this transfer. If 0 the default (from @spi_device) is used.
     361             :  * @cs_change: affects chipselect after this transfer completes
     362             :  * @delay_usecs: microseconds to delay after this transfer before
     363             :  *      (optionally) changing the chipselect status, then starting
     364             :  *      the next transfer or completing this @spi_message.
     365             :  * @transfer_list: transfers are sequenced through @spi_message.transfers
     366             :  *
     367             :  * SPI transfers always write the same number of bytes as they read.
     368             :  * Protocol drivers should always provide @rx_buf and/or @tx_buf.
     369             :  * In some cases, they may also want to provide DMA addresses for
     370             :  * the data being transferred; that may reduce overhead, when the
     371             :  * underlying driver uses dma.
     372             :  *
     373             :  * If the transmit buffer is null, zeroes will be shifted out
     374             :  * while filling @rx_buf.  If the receive buffer is null, the data
     375             :  * shifted in will be discarded.  Only "len" bytes shift out (or in).
     376             :  * It's an error to try to shift out a partial word.  (For example, by
     377             :  * shifting out three bytes with word size of sixteen or twenty bits;
     378             :  * the former uses two bytes per word, the latter uses four bytes.)
     379             :  *
     380             :  * In-memory data values are always in native CPU byte order, translated
     381             :  * from the wire byte order (big-endian except with SPI_LSB_FIRST).  So
     382             :  * for example when bits_per_word is sixteen, buffers are 2N bytes long
     383             :  * (@len = 2N) and hold N sixteen bit words in CPU byte order.
     384             :  *
     385             :  * When the word size of the SPI transfer is not a power-of-two multiple
     386             :  * of eight bits, those in-memory words include extra bits.  In-memory
     387             :  * words are always seen by protocol drivers as right-justified, so the
     388             :  * undefined (rx) or unused (tx) bits are always the most significant bits.
     389             :  *
     390             :  * All SPI transfers start with the relevant chipselect active.  Normally
     391             :  * it stays selected until after the last transfer in a message.  Drivers
     392             :  * can affect the chipselect signal using cs_change.
     393             :  *
     394             :  * (i) If the transfer isn't the last one in the message, this flag is
     395             :  * used to make the chipselect briefly go inactive in the middle of the
     396             :  * message.  Toggling chipselect in this way may be needed to terminate
     397             :  * a chip command, letting a single spi_message perform all of group of
     398             :  * chip transactions together.
     399             :  *
     400             :  * (ii) When the transfer is the last one in the message, the chip may
     401             :  * stay selected until the next transfer.  On multi-device SPI busses
     402             :  * with nothing blocking messages going to other devices, this is just
     403             :  * a performance hint; starting a message to another device deselects
     404             :  * this one.  But in other cases, this can be used to ensure correctness.
     405             :  * Some devices need protocol transactions to be built from a series of
     406             :  * spi_message submissions, where the content of one message is determined
     407             :  * by the results of previous messages and where the whole transaction
     408             :  * ends when the chipselect goes intactive.
     409             :  *
     410             :  * The code that submits an spi_message (and its spi_transfers)
     411             :  * to the lower layers is responsible for managing its memory.
     412             :  * Zero-initialize every field you don't set up explicitly, to
     413             :  * insulate against future API updates.  After you submit a message
     414             :  * and its transfers, ignore them until its completion callback.
     415             :  */
     416             : struct spi_transfer {
     417             :         /* it's ok if tx_buf == rx_buf (right?)
     418             :          * for MicroWire, one buffer must be null
     419             :          * buffers must work with dma_*map_single() calls, unless
     420             :          *   spi_message.is_dma_mapped reports a pre-existing mapping
     421             :          */
     422             :         const void      *tx_buf;
     423             :         void            *rx_buf;
     424             :         unsigned        len;
     425             : 
     426             :         dma_addr_t      tx_dma;
     427             :         dma_addr_t      rx_dma;
     428             : 
     429             :         unsigned        cs_change:1;
     430             :         u8              bits_per_word;
     431             :         u16             delay_usecs;
     432             :         u32             speed_hz;
     433             : 
     434             :         struct list_head transfer_list;
     435             : };
     436           1 : 
     437             : /**
     438             :  * struct spi_message - one multi-segment SPI transaction
     439             :  * @transfers: list of transfer segments in this transaction
     440             :  * @spi: SPI device to which the transaction is queued
     441             :  * @is_dma_mapped: if true, the caller provided both dma and cpu virtual
     442             :  *      addresses for each transfer buffer
     443             :  * @complete: called to report transaction completions
     444             :  * @context: the argument to complete() when it's called
     445             :  * @actual_length: the total number of bytes that were transferred in all
     446             :  *      successful segments
     447             :  * @status: zero for success, else negative errno
     448             :  * @queue: for use by whichever driver currently owns the message
     449             :  * @state: for use by whichever driver currently owns the message
     450             :  *
     451             :  * A @spi_message is used to execute an atomic sequence of data transfers,
     452             :  * each represented by a struct spi_transfer.  The sequence is "atomic"
     453             :  * in the sense that no other spi_message may use that SPI bus until that
     454             :  * sequence completes.  On some systems, many such sequences can execute as
     455             :  * as single programmed DMA transfer.  On all systems, these messages are
     456             :  * queued, and might complete after transactions to other devices.  Messages
     457             :  * sent to a given spi_device are alway executed in FIFO order.
     458             :  *
     459             :  * The code that submits an spi_message (and its spi_transfers)
     460             :  * to the lower layers is responsible for managing its memory.
     461             :  * Zero-initialize every field you don't set up explicitly, to
     462             :  * insulate against future API updates.  After you submit a message
     463             :  * and its transfers, ignore them until its completion callback.
     464             :  */
     465             : struct spi_message {
     466             :         struct list_head        transfers;
     467             : 
     468             :         struct spi_device       *spi;
     469             : 
     470             :         unsigned                is_dma_mapped:1;
     471             : 
     472             :         /* REVISIT:  we might want a flag affecting the behavior of the
     473             :          * last transfer ... allowing things like "read 16 bit length L"
     474             :          * immediately followed by "read L bytes".  Basically imposing
     475             :          * a specific message scheduling algorithm.
     476             :          *
     477             :          * Some controller drivers (message-at-a-time queue processing)
     478             :          * could provide that as their default scheduling algorithm.  But
     479             :          * others (with multi-message pipelines) could need a flag to
     480             :          * tell them about such special cases.
     481             :          */
     482             : 
     483             :         /* completion is reported through a callback */
     484             :         void                    (*complete)(void *context);
     485             :         void                    *context;
     486             :         unsigned                actual_length;
     487             :         int                     status;
     488             : 
     489             :         /* for optional use by whatever driver currently owns the
     490             :          * spi_message ...  between calls to spi_async and then later
     491             :          * complete(), that's the spi_master controller driver.
     492             :          */
     493             :         struct list_head        queue;
     494             :         void                    *state;
     495             : };
     496             : 
     497             : static inline void spi_message_init(struct spi_message *m)
     498             : {
     499             :         memset(m, 0, sizeof *m);
     500             :         INIT_LIST_HEAD(&m->transfers);
     501             : }
     502             : 
     503             : static inline void
     504             : spi_message_add_tail(struct spi_transfer *t, struct spi_message *m)
     505             : {
     506             :         list_add_tail(&t->transfer_list, &m->transfers);
     507             : }
     508             : 
     509             : static inline void
     510             : spi_transfer_del(struct spi_transfer *t)
     511             : {
     512             :         list_del(&t->transfer_list);
     513             : }
     514             : 
     515             : /* It's fine to embed message and transaction structures in other data
     516             :  * structures so long as you don't free them while they're in use.
     517             :  */
     518             : 
     519             : static inline struct spi_message *spi_message_alloc(unsigned ntrans, gfp_t flags)
     520             : {
     521             :         struct spi_message *m;
     522             : 
     523             :         m = kzalloc(sizeof(struct spi_message)
     524             :                         + ntrans * sizeof(struct spi_transfer),
     525             :                         flags);
     526             :         if (m) {
     527             :                 int i;
     528             :                 struct spi_transfer *t = (struct spi_transfer *)(m + 1);
     529             : 
     530             :                 INIT_LIST_HEAD(&m->transfers);
     531             :                 for (i = 0; i < ntrans; i++, t++)
     532             :                         spi_message_add_tail(t, m);
     533             :         }
     534             :         return m;
     535             : }
     536             : 
     537             : static inline void spi_message_free(struct spi_message *m)
     538             : {
     539             :         kfree(m);
     540             : }
     541             : 
     542             : extern int spi_setup(struct spi_device *spi);
     543             : extern int spi_async(struct spi_device *spi, struct spi_message *message);
     544             : 
     545             : /*---------------------------------------------------------------------------*/
     546             : 
     547             : /* All these synchronous SPI transfer routines are utilities layered
     548             :  * over the core async transfer primitive.  Here, "synchronous" means
     549             :  * they will sleep uninterruptibly until the async transfer completes.
     550             :  */
     551             : 
     552             : extern int spi_sync(struct spi_device *spi, struct spi_message *message);
     553             : 
     554             : /**
     555             :  * spi_write - SPI synchronous write
     556             :  * @spi: device to which data will be written
     557             :  * @buf: data buffer
     558             :  * @len: data buffer size
     559             :  * Context: can sleep
     560             :  *
     561             :  * This writes the buffer and returns zero or a negative error code.
     562             :  * Callable only from contexts that can sleep.
     563             :  */
     564             : static inline int
     565             : spi_write(struct spi_device *spi, const u8 *buf, size_t len)
     566             : {
     567             :         struct spi_transfer     t = {
     568             :                         .tx_buf         = buf,
     569             :                         .len            = len,
     570             :                 };
     571             :         struct spi_message      m;
     572             : 
     573             :         spi_message_init(&m);
     574             :         spi_message_add_tail(&t, &m);
     575             :         return spi_sync(spi, &m);
     576             : }
     577             : 
     578             : /**
     579             :  * spi_read - SPI synchronous read
     580             :  * @spi: device from which data will be read
     581             :  * @buf: data buffer
     582             :  * @len: data buffer size
     583             :  * Context: can sleep
     584             :  *
     585             :  * This reads the buffer and returns zero or a negative error code.
     586             :  * Callable only from contexts that can sleep.
     587             :  */
     588             : static inline int
     589             : spi_read(struct spi_device *spi, u8 *buf, size_t len)
     590             : {
     591             :         struct spi_transfer     t = {
     592             :                         .rx_buf         = buf,
     593             :                         .len            = len,
     594             :                 };
     595             :         struct spi_message      m;
     596             : 
     597             :         spi_message_init(&m);
     598             :         spi_message_add_tail(&t, &m);
     599             :         return spi_sync(spi, &m);
     600             : }
     601             : 
     602             : /* this copies txbuf and rxbuf data; for small transfers only! */
     603             : extern int spi_write_then_read(struct spi_device *spi,
     604             :                 const u8 *txbuf, unsigned n_tx,
     605             :                 u8 *rxbuf, unsigned n_rx);
     606             : 
     607             : /**
     608             :  * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read
     609             :  * @spi: device with which data will be exchanged
     610             :  * @cmd: command to be written before data is read back
     611             :  * Context: can sleep
     612             :  *
     613             :  * This returns the (unsigned) eight bit number returned by the
     614             :  * device, or else a negative error code.  Callable only from
     615             :  * contexts that can sleep.
     616             :  */
     617             : static inline ssize_t spi_w8r8(struct spi_device *spi, u8 cmd)
     618             : {
     619             :         ssize_t                 status;
     620             :         u8                      result;
     621             : 
     622             :         status = spi_write_then_read(spi, &cmd, 1, &result, 1);
     623             : 
     624             :         /* return negative errno or unsigned value */
     625             :         return (status < 0) ? status : result;
     626             : }
     627             : 
     628             : /**
     629             :  * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read
     630             :  * @spi: device with which data will be exchanged
     631             :  * @cmd: command to be written before data is read back
     632             :  * Context: can sleep
     633             :  *
     634             :  * This returns the (unsigned) sixteen bit number returned by the
     635             :  * device, or else a negative error code.  Callable only from
     636             :  * contexts that can sleep.
     637             :  *
     638             :  * The number is returned in wire-order, which is at least sometimes
     639             :  * big-endian.
     640             :  */
     641             : static inline ssize_t spi_w8r16(struct spi_device *spi, u8 cmd)
     642             : {
     643             :         ssize_t                 status;
     644             :         u16                     result;
     645             : 
     646             :         status = spi_write_then_read(spi, &cmd, 1, (u8 *) &result, 2);
     647             : 
     648             :         /* return negative errno or unsigned value */
     649             :         return (status < 0) ? status : result;
     650             : }
     651             : 
     652             : /*---------------------------------------------------------------------------*/
     653             : 
     654             : /*
     655             :  * INTERFACE between board init code and SPI infrastructure.
     656             :  *
     657             :  * No SPI driver ever sees these SPI device table segments, but
     658             :  * it's how the SPI core (or adapters that get hotplugged) grows
     659             :  * the driver model tree.
     660             :  *
     661             :  * As a rule, SPI devices can't be probed.  Instead, board init code
     662             :  * provides a table listing the devices which are present, with enough
     663             :  * information to bind and set up the device's driver.  There's basic
     664             :  * support for nonstatic configurations too; enough to handle adding
     665             :  * parport adapters, or microcontrollers acting as USB-to-SPI bridges.
     666             :  */
     667             : 
     668             : /**
     669             :  * struct spi_board_info - board-specific template for a SPI device
     670             :  * @modalias: Initializes spi_device.modalias; identifies the driver.
     671             :  * @platform_data: Initializes spi_device.platform_data; the particular
     672             :  *      data stored there is driver-specific.
     673             :  * @controller_data: Initializes spi_device.controller_data; some
     674             :  *      controllers need hints about hardware setup, e.g. for DMA.
     675             :  * @irq: Initializes spi_device.irq; depends on how the board is wired.
     676             :  * @max_speed_hz: Initializes spi_device.max_speed_hz; based on limits
     677             :  *      from the chip datasheet and board-specific signal quality issues.
     678             :  * @bus_num: Identifies which spi_master parents the spi_device; unused
     679             :  *      by spi_new_device(), and otherwise depends on board wiring.
     680             :  * @chip_select: Initializes spi_device.chip_select; depends on how
     681             :  *      the board is wired.
     682             :  * @mode: Initializes spi_device.mode; based on the chip datasheet, board
     683             :  *      wiring (some devices support both 3WIRE and standard modes), and
     684             :  *      possibly presence of an inverter in the chipselect path.
     685             :  *
     686             :  * When adding new SPI devices to the device tree, these structures serve
     687             :  * as a partial device template.  They hold information which can't always
     688             :  * be determined by drivers.  Information that probe() can establish (such
     689             :  * as the default transfer wordsize) is not included here.
     690             :  *
     691             :  * These structures are used in two places.  Their primary role is to
     692             :  * be stored in tables of board-specific device descriptors, which are
     693             :  * declared early in board initialization and then used (much later) to
     694             :  * populate a controller's device tree after the that controller's driver
     695             :  * initializes.  A secondary (and atypical) role is as a parameter to
     696             :  * spi_new_device() call, which happens after those controller drivers
     697             :  * are active in some dynamic board configuration models.
     698             :  */
     699             : struct spi_board_info {
     700             :         /* the device name and module name are coupled, like platform_bus;
     701             :          * "modalias" is normally the driver name.
     702             :          *
     703             :          * platform_data goes to spi_device.dev.platform_data,
     704             :          * controller_data goes to spi_device.controller_data,
     705             :          * irq is copied too
     706             :          */
     707             :         char            modalias[SPI_NAME_SIZE];
     708             :         const void      *platform_data;
     709             :         void            *controller_data;
     710             :         int             irq;
     711             : 
     712             :         /* slower signaling on noisy or low voltage boards */
     713             :         u32             max_speed_hz;
     714             : 
     715             : 
     716             :         /* bus_num is board specific and matches the bus_num of some
     717             :          * spi_master that will probably be registered later.
     718             :          *
     719             :          * chip_select reflects how this chip is wired to that master;
     720             :          * it's less than num_chipselect.
     721             :          */
     722             :         u16             bus_num;
     723             :         u16             chip_select;
     724             : 
     725             :         /* mode becomes spi_device.mode, and is essential for chips
     726             :          * where the default of SPI_CS_HIGH = 0 is wrong.
     727             :          */
     728             :         u8              mode;
     729             : 
     730             :         /* ... may need additional spi_device chip config data here.
     731             :          * avoid stuff protocol drivers can set; but include stuff
     732             :          * needed to behave without being bound to a driver:
     733             :          *  - quirks like clock rate mattering when not selected
     734             :          */
     735             : };
     736             : 
     737             : #ifdef  CONFIG_SPI
     738             : extern int
     739             : spi_register_board_info(struct spi_board_info const *info, unsigned n);
     740             : #else
     741             : /* board init code may ignore whether SPI is configured or not */
     742             : static inline int
     743             : spi_register_board_info(struct spi_board_info const *info, unsigned n)
     744             :         { return 0; }
     745             : #endif
     746             : 
     747             : 
     748             : /* If you're hotplugging an adapter with devices (parport, usb, etc)
     749             :  * use spi_new_device() to describe each device.  You can also call
     750             :  * spi_unregister_device() to start making that device vanish, but
     751             :  * normally that would be handled by spi_unregister_master().
     752             :  *
     753             :  * You can also use spi_alloc_device() and spi_add_device() to use a two
     754             :  * stage registration sequence for each spi_device.  This gives the caller
     755             :  * some more control over the spi_device structure before it is registered,
     756             :  * but requires that caller to initialize fields that would otherwise
     757             :  * be defined using the board info.
     758             :  */
     759             : extern struct spi_device *
     760             : spi_alloc_device(struct spi_master *master);
     761             : 
     762             : extern int
     763             : spi_add_device(struct spi_device *spi);
     764             : 
     765             : extern struct spi_device *
     766             : spi_new_device(struct spi_master *, struct spi_board_info *);
     767             : 
     768             : static inline void
     769             : spi_unregister_device(struct spi_device *spi)
     770             : {
     771             :         if (spi)
     772             :                 device_unregister(&spi->dev);
     773             : }
     774             : 
     775             : extern const struct spi_device_id *
     776             : spi_get_device_id(const struct spi_device *sdev);
     777             : 
     778             : #endif /* __LINUX_SPI_H */

Generated by: LCOV version 1.10