spi.h

pxa3xx ssp driver for linux

 /*
  * Copyright (C) 2005 David Brownell
  *
  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  */
 
 #ifndef __LINUX_SPI_H
  #define __LINUX_SPI_H
  
  /*
   * INTERFACES between SPI master-side drivers and SPI infrastructure.
   * (There's no SPI slave support for Linux yet...)
   */
  extern struct bus_type spi_bus_type;
  
 28 /**
 29  * struct spi_device - Master side proxy for an SPI slave device
 30  * @dev: Driver model representation of the device.
 31  * @master: SPI controller used with the device.
 32  * @max_speed_hz: Maximum clock rate to be used with this chip
 33  *      (on this board); may be changed by the device's driver.
 34  *      The spi_transfer.speed_hz can override this for each transfer.
 35  * @chip-select: Chipselect, distinguishing chips handled by "master".
 36  * @mode: The spi mode defines how data is clocked out and in.
 37  *      This may be changed by the device's driver.
 38  *      The "active low" default for chipselect mode can be overridden,
 39  *      as can the "MSB first" default for each word in a transfer.
 40  * @bits_per_word: Data transfers involve one or more words; word sizes
 41  *      like eight or 12 bits are common.  In-memory wordsizes are
 42  *      powers of two bytes (e.g. 20 bit samples use 32 bits).
 43  *      This may be changed by the device's driver, or left at the
 44  *      default (0) indicating protocol words are eight bit bytes.
 45  *      The spi_transfer.bits_per_word can override this for each transfer.
 46  * @irq: Negative, or the number passed to request_irq() to receive
 47  *      interrupts from this device.
 48  * @controller_state: Controller's runtime state
 49  * @controller_data: Board-specific definitions for controller, such as
 50  *      FIFO initialization parameters; from board_info.controller_data
 51  *
 52  * An spi_device is used to interchange data between an SPI slave
 53  * (usually a discrete chip) and CPU memory.
 54  *
 55  * In "dev", the platform_data is used to hold information about this
 56  * device that's meaningful to the device's protocol driver, but not
 57  * to its controller.  One example might be an identifier for a chip
 58  * variant with slightly different functionality.
 59  */
  struct spi_device {
          struct device           dev;
          struct spi_master       *master;
          u32                     max_speed_hz;
          u8                      chip_select;
          u8                      mode;
  #define SPI_CPHA        0x01                    /* clock phase */
  #define SPI_CPOL        0x02                    /* clock polarity */
  #define SPI_MODE_0      (0|0)                   /* (original MicroWire) */
  #define SPI_MODE_1      (0|SPI_CPHA)
  #define SPI_MODE_2      (SPI_CPOL|0)
  #define SPI_MODE_3      (SPI_CPOL|SPI_CPHA)
  #define SPI_CS_HIGH     0x04                    /* chipselect active high? */
  #define SPI_LSB_FIRST   0x08                    /* per-word bits-on-wire */
          u8                      bits_per_word;
          int                     irq;
          void                    *controller_state;
          void                    *controller_data;
          const char              *modalias;
  
          // likely need more hooks for more protocol options affecting how
          // the controller talks to each chip, like:
          //  - memory packing (12 bit samples into low bits, others zeroed)
          //  - priority
          //  - drop chipselect after each word
          //  - chipselect delays
          //  - ...
  };
  
  static inline struct spi_device *to_spi_device(struct device *dev)
  {
          return dev ? container_of(dev, struct spi_device, dev) : NULL;
  }
  
  /* most drivers won't need to care about device refcounting */
  static inline struct spi_device *spi_dev_get(struct spi_device *spi)
  {
          return (spi && get_device(&spi->dev)) ? spi : NULL;
  }
  
 static inline void spi_dev_put(struct spi_device *spi)
 {
         if (spi)
                 put_device(&spi->dev);
 }
 
 /* ctldata is for the bus_master driver's runtime state */
 static inline void *spi_get_ctldata(struct spi_device *spi)
 {
         return spi->controller_state;
 }
 
 static inline void spi_set_ctldata(struct spi_device *spi, void *state)
 {
         spi->controller_state = state;
 }
 
 
 struct spi_message;
 
 
 
 struct spi_driver {
         int                     (*probe)(struct spi_device *spi);
         int                     (*remove)(struct spi_device *spi);
         void                    (*shutdown)(struct spi_device *spi);
         int                     (*suspend)(struct spi_device *spi, pm_message_t mesg);
         int                     (*resume)(struct spi_device *spi);
         struct device_driver    driver;
 };
 
 static inline struct spi_driver *to_spi_driver(struct device_driver *drv)
 {
         return drv ? container_of(drv, struct spi_driver, driver) : NULL;
 }
 
 extern int spi_register_driver(struct spi_driver *sdrv);
 
 static inline void spi_unregister_driver(struct spi_driver *sdrv)
 {
         if (!sdrv)
                 return;
         driver_unregister(&sdrv->driver);
 }
 
 
 
 /**
148  * struct spi_master - interface to SPI master controller
149  * @cdev: class interface to this driver
150  * @bus_num: board-specific (and often SOC-specific) identifier for a
151  *      given SPI controller.
152  * @num_chipselect: chipselects are used to distinguish individual
153  *      SPI slaves, and are numbered from zero to num_chipselects.
154  *      each slave has a chipselect signal, but it's common that not
155  *      every chipselect is connected to a slave.
156  * @setup: updates the device mode and clocking records used by a
157  *      device's SPI controller; protocol code may call this.
158  * @transfer: adds a message to the controller's transfer queue.
159  * @cleanup: frees controller-specific state
160  *
161  * Each SPI master controller can communicate with one or more spi_device
162  * children.  These make a small bus, sharing MOSI, MISO and SCK signals
163  * but not chip select signals.  Each device may be configured to use a
164  * different clock rate, since those shared signals are ignored unless
165  * the chip is selected.
166  *
167  * The driver for an SPI controller manages access to those devices through
168  * a queue of spi_message transactions, copyin data between CPU memory and
169  * an SPI slave device).  For each such message it queues, it calls the
170  * message's completion function when the transaction completes.
171  */
 struct spi_master {
         struct class_device     cdev;
 
         /* other than negative (== assign one dynamically), bus_num is fully
          * board-specific.  usually that simplifies to being SOC-specific.
          * example:  one SOC has three SPI controllers, numbered 0..2,
          * and one board's schematics might show it using SPI-2.  software
          * would normally use bus_num=2 for that controller.
          */
         s16                     bus_num;
 
         /* chipselects will be integral to many controllers; some others
184          * might use board-specific GPIOs.
185          */
         u16                     num_chipselect;
 
         /* setup mode and clock, etc (spi driver may call many times) */
         int                     (*setup)(struct spi_device *spi);
 
191         /* bidirectional bulk transfers
192          *
193          * + The transfer() method may not sleep; its main role is
194          *   just to add the message to the queue.
195          * + For now there's no remove-from-queue operation, or
196          *   any other request management
197          * + To a given spi_device, message queueing is pure fifo
198          *
199          * + The master's main job is to process its message queue,
200          *   selecting a chip then transferring data
201          * + If there are multiple spi_device children, the i/o queue
202          *   arbitration algorithm is unspecified (round robin, fifo,
203          *   priority, reservations, preemption, etc)
204          *
205          * + Chipselect stays active during the entire message
206          *   (unless modified by spi_transfer.cs_change != 0).
207          * + The message transfers use clock and SPI mode parameters
208          *   previously established by setup() for this device
209          */
         int                     (*transfer)(struct spi_device *spi,
                                                 struct spi_message *mesg);
 
         /* called on release() to free memory provided by spi_master */
         void                    (*cleanup)(const struct spi_device *spi);
 };
 
 static inline void *spi_master_get_devdata(struct spi_master *master)
 {
         return class_get_devdata(&master->cdev);
 }
 
 static inline void spi_master_set_devdata(struct spi_master *master, void *data)
 {
         class_set_devdata(&master->cdev, data);
 }
 
 static inline struct spi_master *spi_master_get(struct spi_master *master)
 {
         if (!master || !class_device_get(&master->cdev))
                 return NULL;
         return master;
 }
 
 static inline void spi_master_put(struct spi_master *master)
 {
         if (master)
                 class_device_put(&master->cdev);
 }
 
 
 /* the spi driver core manages memory for the spi_master classdev */
 extern struct spi_master *
 spi_alloc_master(struct device *host, unsigned size);
 
 extern int spi_register_master(struct spi_master *master);
 extern void spi_unregister_master(struct spi_master *master);
 
 extern struct spi_master *spi_busnum_to_master(u16 busnum);
 
250 /*---------------------------------------------------------------------------*/
251 
252 /*
253  * I/O INTERFACE between SPI controller and protocol drivers
254  *
255  * Protocol drivers use a queue of spi_messages, each transferring data
256  * between the controller and memory buffers.
257  *
258  * The spi_messages themselves consist of a series of read+write transfer
259  * segments.  Those segments always read the same number of bits as they
260  * write; but one or the other is easily ignored by passing a null buffer
261  * pointer.  (This is unlike most types of I/O API, because SPI hardware
262  * is full duplex.)
263  *
264  * NOTE:  Allocation of spi_transfer and spi_message memory is entirely
265  * up to the protocol driver, which guarantees the integrity of both (as
266  * well as the data buffers) for as long as the message is queued.
267  */
268 
269 /**
270  * struct spi_transfer - a read/write buffer pair
271  * @tx_buf: data to be written (dma-safe memory), or NULL
272  * @rx_buf: data to be read (dma-safe memory), or NULL
273  * @tx_dma: DMA address of tx_buf, if spi_message.is_dma_mapped
274  * @rx_dma: DMA address of rx_buf, if spi_message.is_dma_mapped
275  * @len: size of rx and tx buffers (in bytes)
276  * @speed_hz: Select a speed other then the device default for this
277  *      transfer. If 0 the default (from spi_device) is used.
278  * @bits_per_word: select a bits_per_word other then the device default
279  *      for this transfer. If 0 the default (from spi_device) is used.
280  * @cs_change: affects chipselect after this transfer completes
281  * @delay_usecs: microseconds to delay after this transfer before
282  *      (optionally) changing the chipselect status, then starting
283  *      the next transfer or completing this spi_message.
284  * @transfer_list: transfers are sequenced through spi_message.transfers
285  *
286  * SPI transfers always write the same number of bytes as they read.
287  * Protocol drivers should always provide rx_buf and/or tx_buf.
288  * In some cases, they may also want to provide DMA addresses for
289  * the data being transferred; that may reduce overhead, when the
290  * underlying driver uses dma.
291  *
292  * If the transmit buffer is null, undefined data will be shifted out
293  * while filling rx_buf.  If the receive buffer is null, the data
294  * shifted in will be discarded.  Only "len" bytes shift out (or in).
295  * It's an error to try to shift out a partial word.  (For example, by
296  * shifting out three bytes with word size of sixteen or twenty bits;
297  * the former uses two bytes per word, the latter uses four bytes.)
298  *
299  * All SPI transfers start with the relevant chipselect active.  Normally
300  * it stays selected until after the last transfer in a message.  Drivers
301  * can affect the chipselect signal using cs_change:
302  *
303  * (i) If the transfer isn't the last one in the message, this flag is
304  * used to make the chipselect briefly go inactive in the middle of the
305  * message.  Toggling chipselect in this way may be needed to terminate
306  * a chip command, letting a single spi_message perform all of group of
307  * chip transactions together.
308  *
309  * (ii) When the transfer is the last one in the message, the chip may
310  * stay selected until the next transfer.  This is purely a performance
311  * hint; the controller driver may need to select a different device
312  * for the next message.
313  *
314  * The code that submits an spi_message (and its spi_transfers)
315  * to the lower layers is responsible for managing its memory.
316  * Zero-initialize every field you don't set up explicitly, to
317  * insulate against future API updates.  After you submit a message
318  * and its transfers, ignore them until its completion callback.
319  */
 struct spi_transfer {
         /* it's ok if tx_buf == rx_buf (right?)
322          * for MicroWire, one buffer must be null
323          * buffers must work with dma_*map_single() calls, unless
324          *   spi_message.is_dma_mapped reports a pre-existing mapping
325          */
         const void      *tx_buf;
         void            *rx_buf;
         unsigned        len;
 
         dma_addr_t      tx_dma;
         dma_addr_t      rx_dma;
 
         unsigned        cs_change:1;
         u8              bits_per_word;
         u16             delay_usecs;
         u32             speed_hz;
 
         struct list_head transfer_list;
 };