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