spi.h

pxa3xx ssp driver for linux

341 /**
342  * struct spi_message - one multi-segment SPI transaction
343  * @transfers: list of transfer segments in this transaction
344  * @spi: SPI device to which the transaction is queued
345  * @is_dma_mapped: if true, the caller provided both dma and cpu virtual
346  *      addresses for each transfer buffer
347  * @complete: called to report transaction completions
348  * @context: the argument to complete() when it's called
349  * @actual_length: the total number of bytes that were transferred in all
350  *      successful segments
351  * @status: zero for success, else negative errno
352  * @queue: for use by whichever driver currently owns the message
353  * @state: for use by whichever driver currently owns the message
354  *
355  * An spi_message is used to execute an atomic sequence of data transfers,
356  * each represented by a struct spi_transfer.  The sequence is "atomic"
357  * in the sense that no other spi_message may use that SPI bus until that
358  * sequence completes.  On some systems, many such sequences can execute as
359  * as single programmed DMA transfer.  On all systems, these messages are
360  * queued, and might complete after transactions to other devices.  Messages
361  * sent to a given spi_device are alway executed in FIFO order.
362  *
363  * The code that submits an spi_message (and its spi_transfers)
364  * to the lower layers is responsible for managing its memory.
365  * Zero-initialize every field you don't set up explicitly, to
366  * insulate against future API updates.  After you submit a message
367  * and its transfers, ignore them until its completion callback.
368  */
 struct spi_message {
         struct list_head        transfers;
 
         struct spi_device       *spi;
 
         unsigned                is_dma_mapped:1;
 
         /* REVISIT:  we might want a flag affecting the behavior of the
377          * last transfer ... allowing things like "read 16 bit length L"
378          * immediately followed by "read L bytes".  Basically imposing
379          * a specific message scheduling algorithm.
380          *
381          * Some controller drivers (message-at-a-time queue processing)
382          * could provide that as their default scheduling algorithm.  But
383          * others (with multi-message pipelines) could need a flag to
384          * tell them about such special cases.
385          */
 
         /* completion is reported through a callback */
         void                    (*complete)(void *context);
         void                    *context;
         unsigned                actual_length;
         int                     status;
 
         /* for optional use by whatever driver currently owns the
394          * spi_message ...  between calls to spi_async and then later
395          * complete(), that's the spi_master controller driver.
396          */
         struct list_head        queue;
         void                    *state;
 };
 
 static inline void spi_message_init(struct spi_message *m)
 {
         memset(m, 0, sizeof *m);
         INIT_LIST_HEAD(&m->transfers);
 }
 
 static inline void
 spi_message_add_tail(struct spi_transfer *t, struct spi_message *m)
 {
         list_add_tail(&t->transfer_list, &m->transfers);
 }
 
 static inline void
 spi_transfer_del(struct spi_transfer *t)
 {
         list_del(&t->transfer_list);
 }
 
 /* It's fine to embed message and transaction structures in other data
420  * structures so long as you don't free them while they're in use.
421  */
 
 static inline struct spi_message *spi_message_alloc(unsigned ntrans, gfp_t flags)
 {
         struct spi_message *m;
 
         m = kzalloc(sizeof(struct spi_message)
                         + ntrans * sizeof(struct spi_transfer),
                         flags);
         if (m) {
                 int i;
                 struct spi_transfer *t = (struct spi_transfer *)(m + 1);
 
                 INIT_LIST_HEAD(&m->transfers);
                 for (i = 0; i < ntrans; i++, t++)
                         spi_message_add_tail(t, m);
         }
         return m;
 }
 
 static inline void spi_message_free(struct spi_message *m)
 {
         kfree(m);
 }
 
 /**
447  * spi_setup -- setup SPI mode and clock rate
448  * @spi: the device whose settings are being modified
449  *
450  * SPI protocol drivers may need to update the transfer mode if the
451  * device doesn't work with the mode 0 default.  They may likewise need
452  * to update clock rates or word sizes from initial values.  This function
453  * changes those settings, and must be called from a context that can sleep.
454  * The changes take effect the next time the device is selected and data
455  * is transferred to or from it.
456  */
 static inline int
 spi_setup(struct spi_device *spi)
 {
         return spi->master->setup(spi);
 }
 
 
 /**
465  * spi_async -- asynchronous SPI transfer
466  * @spi: device with which data will be exchanged
467  * @message: describes the data transfers, including completion callback
468  *
469  * This call may be used in_irq and other contexts which can't sleep,
470  * as well as from task contexts which can sleep.
471  *
472  * The completion callback is invoked in a context which can't sleep.
473  * Before that invocation, the value of message->status is undefined.
474  * When the callback is issued, message->status holds either zero (to
475  * indicate complete success) or a negative error code.  After that
476  * callback returns, the driver which issued the transfer request may
477  * deallocate the associated memory; it's no longer in use by any SPI
478  * core or controller driver code.
479  *
480  * Note that although all messages to a spi_device are handled in
481  * FIFO order, messages may go to different devices in other orders.
482  * Some device might be higher priority, or have various "hard" access
483  * time requirements, for example.
484  *
485  * On detection of any fault during the transfer, processing of
486  * the entire message is aborted, and the device is deselected.
487  * Until returning from the associated message completion callback,
488  * no other spi_message queued to that device will be processed.
489  * (This rule applies equally to all the synchronous transfer calls,
490  * which are wrappers around this core asynchronous primitive.)
491  */
 static inline int
 spi_async(struct spi_device *spi, struct spi_message *message)
 {
         message->spi = spi;
         return spi->master->transfer(spi, message);
 }
 
 /*---------------------------------------------------------------------------*/
 
 /* All these synchronous SPI transfer routines are utilities layered
502  * over the core async transfer primitive.  Here, "synchronous" means
503  * they will sleep uninterruptibly until the async transfer completes.
504  */
 
 extern int spi_sync(struct spi_device *spi, struct spi_message *message);
 
 /**
509  * spi_write - SPI synchronous write
510  * @spi: device to which data will be written
511  * @buf: data buffer
512  * @len: data buffer size
513  *
514  * This writes the buffer and returns zero or a negative error code.
515  * Callable only from contexts that can sleep.
516  */
517 static inline int
 spi_write(struct spi_device *spi, const u8 *buf, size_t len)
 {
         struct spi_transfer     t = {
                         .tx_buf         = buf,
                         .len            = len,
                 };
         struct spi_message      m;
 
         spi_message_init(&m);
         spi_message_add_tail(&t, &m);
         return spi_sync(spi, &m);
 }
 
 /**
532  * spi_read - SPI synchronous read
533  * @spi: device from which data will be read
534  * @buf: data buffer
535  * @len: data buffer size
536  *
537  * This writes the buffer and returns zero or a negative error code.
538  * Callable only from contexts that can sleep.
539  */
 static inline int
 spi_read(struct spi_device *spi, u8 *buf, size_t len)
 {
         struct spi_transfer     t = {
                         .rx_buf         = buf,
                         .len            = len,
                 };
         struct spi_message      m;
 
         spi_message_init(&m);
         spi_message_add_tail(&t, &m);
         return spi_sync(spi, &m);
 }
 
 /* this copies txbuf and rxbuf data; for small transfers only! */
 extern int spi_write_then_read(struct spi_device *spi,
                 const u8 *txbuf, unsigned n_tx,
                 u8 *rxbuf, unsigned n_rx);
 
 /**
560  * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read
561  * @spi: device with which data will be exchanged
562  * @cmd: command to be written before data is read back
563  *
564  * This returns the (unsigned) eight bit number returned by the
565  * device, or else a negative error code.  Callable only from
566  * contexts that can sleep.
567  */
 static inline ssize_t spi_w8r8(struct spi_device *spi, u8 cmd)
 {
         ssize_t                 status;
         u8                      result;
 
         status = spi_write_then_read(spi, &cmd, 1, &result, 1);
 
         /* return negative errno or unsigned value */
         return (status < 0) ? status : result;
 }
 
 /**
580  * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read
581  * @spi: device with which data will be exchanged
582  * @cmd: command to be written before data is read back
583  *
584  * This returns the (unsigned) sixteen bit number returned by the
585  * device, or else a negative error code.  Callable only from
586  * contexts that can sleep.
587  *
588  * The number is returned in wire-order, which is at least sometimes
589  * big-endian.
590  */
 static inline ssize_t spi_w8r16(struct spi_device *spi, u8 cmd)
 {
         ssize_t                 status;
         u16                     result;
 
         status = spi_write_then_read(spi, &cmd, 1, (u8 *) &result, 2);
 
         /* return negative errno or unsigned value */
         return (status < 0) ? status : result;
 }
 
 /*---------------------------------------------------------------------------*/
 
 /*
605  * INTERFACE between board init code and SPI infrastructure.
606  *
607  * No SPI driver ever sees these SPI device table segments, but
608  * it's how the SPI core (or adapters that get hotplugged) grows
609  * the driver model tree.
610  *
611  * As a rule, SPI devices can't be probed.  Instead, board init code
612  * provides a table listing the devices which are present, with enough
613  * information to bind and set up the device's driver.  There's basic
614  * support for nonstatic configurations too; enough to handle adding
615  * parport adapters, or microcontrollers acting as USB-to-SPI bridges.
616  */
 
 /* board-specific information about each SPI device */
 struct spi_board_info {
         /* the device name and module name are coupled, like platform_bus;
621          * "modalias" is normally the driver name.
622          *
623          * platform_data goes to spi_device.dev.platform_data,
624          * controller_data goes to spi_device.controller_data,
625          * irq is copied too
626          */
         char            modalias[KOBJ_NAME_LEN];
         const void      *platform_data;
         void            *controller_data;
         int             irq;
 
         /* slower signaling on noisy or low voltage boards */
         u32             max_speed_hz;
 
 
         /* bus_num is board specific and matches the bus_num of some
637          * spi_master that will probably be registered later.
638          *
639          * chip_select reflects how this chip is wired to that master;
640          * it's less than num_chipselect.
641          */
         u16             bus_num;
         u16             chip_select;
 
         /* ... may need additional spi_device chip config data here.
646          * avoid stuff protocol drivers can set; but include stuff
647          * needed to behave without being bound to a driver:
648          *  - chipselect polarity
649          *  - quirks like clock rate mattering when not selected
650          */
 };
 
 #ifdef  CONFIG_SPI
 extern int
 spi_register_board_info(struct spi_board_info const *info, unsigned n);
 #else
 /* board init code may ignore whether SPI is configured or not */
 static inline int
 spi_register_board_info(struct spi_board_info const *info, unsigned n)
         { return 0; }
 #endif
 
 
 /* If you're hotplugging an adapter with devices (parport, usb, etc)
665  * use spi_new_device() to describe each device.  You can also call
666  * spi_unregister_device() to start making that device vanish, but
667  * normally that would be handled by spi_unregister_master().
668  */
 extern struct spi_device *
 spi_new_device(struct spi_master *, struct spi_board_info *);
 
 static inline void
 spi_unregister_device(struct spi_device *spi)
 {
         if (spi)
                 device_unregister(&spi->dev);
 }
 
 #endif /* __LINUX_SPI_H */