include/spi.h

   1 /*
   2  * (C) Copyright 2001
   3  * Gerald Van Baren, Custom IDEAS, vanbaren@cideas.com.
   4  *
   5  * See file CREDITS for list of people who contributed to this
   6  * project.
   7  *
   8  * This program is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License as
  10  * published by the Free Software Foundation; either version 2 of
  11  * the License, or (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  21  * MA 02111-1307 USA
  22  */
  23
  24 #ifndef _SPI_H_
  25 #define _SPI_H_
  26
  27 /* Controller-specific definitions: */
  28
  29 /* CONFIG_HARD_SPI triggers SPI bus initialization in PowerPC */
  30 #ifdef CONFIG_MPC8XXX_SPI
  31 # ifndef CONFIG_HARD_SPI
  32 #  define CONFIG_HARD_SPI
  33 # endif
  34 #endif
  35
  36 /* SPI mode flags */
  37 #define SPI_CPHA        0x01                    /* clock phase */
  38 #define SPI_CPOL        0x02                    /* clock polarity */
  39 #define SPI_MODE_0      (0|0)                   /* (original MicroWire) */
  40 #define SPI_MODE_1      (0|SPI_CPHA)
  41 #define SPI_MODE_2      (SPI_CPOL|0)
  42 #define SPI_MODE_3      (SPI_CPOL|SPI_CPHA)
  43 #define SPI_CS_HIGH     0x04                    /* CS active high */
  44 #define SPI_LSB_FIRST   0x08                    /* per-word bits-on-wire */
  45 #define SPI_3WIRE       0x10                    /* SI/SO signals shared */
  46 #define SPI_LOOP        0x20                    /* loopback mode */
  47
  48 /* SPI transfer flags */
  49 #define SPI_XFER_BEGIN  0x01                    /* Assert CS before transfer */
  50 #define SPI_XFER_END    0x02                    /* Deassert CS after transfer */
  51
  52 /*-----------------------------------------------------------------------
  53  * Representation of a SPI slave, i.e. what we're communicating with.
  54  *
  55  * Drivers are expected to extend this with controller-specific data.
  56  *
  57  *   bus:       ID of the bus that the slave is attached to.
  58  *   cs:        ID of the chip select connected to the slave.
  59  */
  60 struct spi_slave {
  61         unsigned int    bus;
  62         unsigned int    cs;
  63 };
  64
  65 /*-----------------------------------------------------------------------
  66  * Initialization, must be called once on start up.
  67  *
  68  * TODO: I don't think we really need this.
  69  */
  70 void spi_init(void);
  71
  72 /*-----------------------------------------------------------------------
  73  * Set up communications parameters for a SPI slave.
  74  *
  75  * This must be called once for each slave. Note that this function
  76  * usually doesn't touch any actual hardware, it only initializes the
  77  * contents of spi_slave so that the hardware can be easily
  78  * initialized later.
  79  *
  80  *   bus:     Bus ID of the slave chip.
  81  *   cs:      Chip select ID of the slave chip on the specified bus.
  82  *   max_hz:  Maximum SCK rate in Hz.
  83  *   mode:    Clock polarity, clock phase and other parameters.
  84  *
  85  * Returns: A spi_slave reference that can be used in subsequent SPI
  86  * calls, or NULL if one or more of the parameters are not supported.
  87  */
  88 struct spi_slave *spi_setup_slave(unsigned int bus, unsigned int cs,
  89                 unsigned int max_hz, unsigned int mode);
  90
  91 /*-----------------------------------------------------------------------
  92  * Free any memory associated with a SPI slave.
  93  *
  94  *   slave:     The SPI slave
  95  */
  96 void spi_free_slave(struct spi_slave *slave);
  97
  98 /*-----------------------------------------------------------------------
  99  * Claim the bus and prepare it for communication with a given slave.
 100  *
 101  * This must be called before doing any transfers with a SPI slave. It
 102  * will enable and initialize any SPI hardware as necessary, and make
 103  * sure that the SCK line is in the correct idle state. It is not
 104  * allowed to claim the same bus for several slaves without releasing
 105  * the bus in between.
 106  *
 107  *   slave:     The SPI slave
 108  *
 109  * Returns: 0 if the bus was claimed successfully, or a negative value
 110  * if it wasn't.
 111  */
 112 int spi_claim_bus(struct spi_slave *slave);
 113
 114 /*-----------------------------------------------------------------------
 115  * Release the SPI bus
 116  *
 117  * This must be called once for every call to spi_claim_bus() after
 118  * all transfers have finished. It may disable any SPI hardware as
 119  * appropriate.
 120  *
 121  *   slave:     The SPI slave
 122  */
 123 void spi_release_bus(struct spi_slave *slave);
 124
 125 /*-----------------------------------------------------------------------
 126  * SPI transfer
 127  *
 128  * This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks
 129  * "bitlen" bits in the SPI MISO port.  That's just the way SPI works.
 130  *
 131  * The source of the outgoing bits is the "dout" parameter and the
 132  * destination of the input bits is the "din" parameter.  Note that "dout"
 133  * and "din" can point to the same memory location, in which case the
 134  * input data overwrites the output data (since both are buffered by
 135  * temporary variables, this is OK).
 136  *
 137  * spi_xfer() interface:
 138  *   slave:     The SPI slave which will be sending/receiving the data.
 139  *   bitlen:    How many bits to write and read.
 140  *   dout:      Pointer to a string of bits to send out.  The bits are
 141  *              held in a byte array and are sent MSB first.
 142  *   din:       Pointer to a string of bits that will be filled in.
 143  *   flags:     A bitwise combination of SPI_XFER_* flags.
 144  *
 145  *   Returns: 0 on success, not 0 on failure
 146  */
 147 int  spi_xfer(struct spi_slave *slave, unsigned int bitlen, const void *dout,
 148                 void *din, unsigned long flags);
 149
 150 /*-----------------------------------------------------------------------
 151  * Determine if a SPI chipselect is valid.
 152  * This function is provided by the board if the low-level SPI driver
 153  * needs it to determine if a given chipselect is actually valid.
 154  *
 155  * Returns: 1 if bus:cs identifies a valid chip on this board, 0
 156  * otherwise.
 157  */
 158 int  spi_cs_is_valid(unsigned int bus, unsigned int cs);
 159
 160 /*-----------------------------------------------------------------------
 161  * Activate a SPI chipselect.
 162  * This function is provided by the board code when using a driver
 163  * that can't control its chipselects automatically (e.g.
 164  * common/soft_spi.c). When called, it should activate the chip select
 165  * to the device identified by "slave".
 166  */
 167 void spi_cs_activate(struct spi_slave *slave);
 168
 169 /*-----------------------------------------------------------------------
 170  * Deactivate a SPI chipselect.
 171  * This function is provided by the board code when using a driver
 172  * that can't control its chipselects automatically (e.g.
 173  * common/soft_spi.c). When called, it should deactivate the chip
 174  * select to the device identified by "slave".
 175  */
 176 void spi_cs_deactivate(struct spi_slave *slave);
 177
 178 /*-----------------------------------------------------------------------
 179  * Set transfer speed.
 180  * This sets a new speed to be applied for next spi_xfer().
 181  *   slave:     The SPI slave
 182  *   hz:        The transfer speed
 183  */
 184 void spi_set_speed(struct spi_slave *slave, uint hz);
 185
 186 /*-----------------------------------------------------------------------
 187  * Write 8 bits, then read 8 bits.
 188  *   slave:     The SPI slave we're communicating with
 189  *   byte:      Byte to be written
 190  *
 191  * Returns: The value that was read, or a negative value on error.
 192  *
 193  * TODO: This function probably shouldn't be inlined.
 194  */
 195 static inline int spi_w8r8(struct spi_slave *slave, unsigned char byte)
 196 {
 197         unsigned char dout[2];
 198         unsigned char din[2];
 199         int ret;
 200
 201         dout[0] = byte;
 202         dout[1] = 0;
 203
 204         ret = spi_xfer(slave, 16, dout, din, SPI_XFER_BEGIN | SPI_XFER_END);
 205         return ret < 0 ? ret : din[1];
 206 }
 207
 208 #endif  /* _SPI_H_ */