Generalised the SPI abstraction layer to also be able to handle interfaces
[people/xl0/gpxe.git] / src / include / gpxe / spi.h
1 #ifndef _GPXE_SPI_H
2 #define _GPXE_SPI_H
3
4 /** @file
5  *
6  * SPI interface
7  *
8  */
9
10 #include <gpxe/bitbash.h>
11
12 /**
13  * @defgroup spicmds SPI commands
14  * @{
15  */
16
17 /** Write status register */
18 #define SPI_WRSR 0x01
19
20 /** Write data to memory array */
21 #define SPI_WRITE 0x02
22
23 /** Read data from memory array */
24 #define SPI_READ 0x03
25
26 /** Reset write enable latch */
27 #define SPI_WRDI 0x04
28
29 /** Read status register */
30 #define SPI_RDSR 0x05
31
32 /** Set write enable latch */
33 #define SPI_WREN 0x06
34
35 /**
36  * @defgroup atmelcmds Atmel-specific SPI commands
37  * @{
38  */
39
40 /** Erase one sector in memory array (Not supported on all devices) */
41 #define ATMEL_SECTOR_ERASE 0x52
42
43 /** Erase all sections in memory array (Not supported on all devices) */
44 #define ATMEL_CHIP_ERASE 0x62
45
46 /** Read manufacturer and product ID (Not supported on all devices) */
47 #define ATMEL_RDID 0x15
48
49 /** @} */
50
51 /** @} */
52
53 /**
54  * @defgroup spistatus SPI status register bits (not present on all devices)
55  * @{
56  */
57
58 /** Write-protect pin enabled */
59 #define SPI_STATUS_WPEN 0x80
60
61 /** Block protection bit 2 */
62 #define SPI_STATUS_BP2 0x10
63
64 /** Block protection bit 1 */
65 #define SPI_STATUS_BP1 0x08
66
67 /** Block protection bit 0 */
68 #define SPI_STATUS_BP0 0x04
69
70 /** State of the write enable latch */
71 #define SPI_STATUS_WEN 0x02
72
73 /** Device busy flag */
74 #define SPI_STATUS_NRDY 0x01
75
76 /** @} */
77
78 struct spi_device;
79
80 /**
81  * An SPI device type
82  *
83  * This data structure represents all the characteristics belonging to
84  * a particular type of SPI device, e.g. "an Atmel 251024 serial flash",
85  * or "a Microchip 25040 serial EEPROM".
86  */
87 struct spi_device_type {
88         /** Word length, in bits */
89         unsigned int word_len;
90         /** Device size (in words) */
91         unsigned int size;
92         /** Data block size (in words)
93          *
94          * This is the block size used by the device.  It must be a
95          * power of two.  Data reads and writes must not cross a block
96          * boundary.
97          *
98          * Many devices allow reads to cross a block boundary, and
99          * restrict only writes.  For the sake of simplicity, we
100          * assume that the same restriction applies to both reads and
101          * writes.
102          */
103         unsigned int block_size;
104         /** Command length, in bits */
105         unsigned int command_len;
106         /** Address length, in bits */
107         unsigned int address_len;
108         /** Address is munged
109          *
110          * Some devices with 9-bit addresses (e.g. AT25040A EEPROM)
111          * use bit 3 of the command byte as address bit A8, rather
112          * than having a two-byte address.  If this flag is set, then
113          * commands should be munged in this way.
114          */
115         unsigned int munge_address : 1;
116         /** Read data from device
117          *
118          * @v device            SPI device
119          * @v address           Address from which to read
120          * @v data              Data buffer
121          * @v len               Length of data to read, in @b words
122          * @ret rc              Return status code
123          */
124         int ( * read ) ( struct spi_device *device, unsigned int address,
125                          void *data, unsigned int len );
126         /** Write data to device
127          *
128          * @v device            SPI device
129          * @v address           Address to which to write
130          * @v data              Data buffer
131          * @v len               Length of data to write, in @b words
132          * @ret rc              Return status code
133          */
134         int ( * write ) ( struct spi_device *device, unsigned int address,
135                           const void *data, unsigned int len );
136 };
137
138 /**
139  * @defgroup spidevs SPI device types
140  * @{
141  */
142
143 /** Atmel AT25010 serial EEPROM */
144 #define AT25010 {               \
145         .word_len = 8,          \
146         .size = 128,            \
147         .block_size = 8,        \
148         .command_len = 8,       \
149         .address_len = 8,       \
150         }
151
152 /** @} */
153
154 /**
155  * An SPI device
156  *
157  * This data structure represents a real, physical SPI device attached
158  * to an SPI controller.  It comprises the device type plus
159  * instantiation-specific information such as the slave number.
160  */
161 struct spi_device {
162         /** SPI device type */
163         struct spi_device_type *type;
164         /** SPI bus to which device is attached */
165         struct spi_bus *bus;
166         /** Slave number */
167         unsigned int slave;
168 };
169
170 /**
171  * An SPI bus
172  *
173  * 
174  */
175 struct spi_bus {
176         /** SPI interface mode
177          *
178          * This is the bitwise OR of zero or more of @c SPI_MODE_CPHA
179          * and @c SPI_MODE_CPOL.  It is also the number conventionally
180          * used to describe the SPI interface mode.  For example, SPI
181          * mode 1 is the mode in which CPOL=0 and CPHA=1, which
182          * therefore corresponds to a mode value of (0|SPI_MODE_CPHA)
183          * which, happily, equals 1.
184          */
185         unsigned int mode;
186         /**
187          * Read/write data via SPI bus
188          *
189          * @v bus               SPI bus
190          * @v device            SPI device
191          * @v command           Command
192          * @v address           Address to read/write (<0 for no address)
193          * @v data_out          TX data buffer (or NULL)
194          * @v data_in           RX data buffer (or NULL)
195          * @v len               Length of transfer (in @b words)
196          *
197          * This issues the specified command and optional address to
198          * the SPI device, then reads and/or writes data to/from the
199          * data buffers.  Note that the transfer length is measured in
200          * words, not in bytes.  Some SPI devices have 16-bit word
201          * lengths; take care with these devices not to accidentally
202          * read or write twice as much data as intended.
203          */
204         int ( * rw ) ( struct spi_bus *bus, struct spi_device *device,
205                        unsigned int command, int address,
206                        const void *data_out, void *data_in, unsigned int len );
207 };
208
209 /** Clock phase (CPHA) mode bit
210  *
211  * Phase 0 is sample on rising edge, shift data on falling edge.
212  *
213  * Phase 1 is shift data on rising edge, sample data on falling edge.
214  */
215 #define SPI_MODE_CPHA 0x01
216
217 /** Clock polarity (CPOL) mode bit
218  *
219  * This bit reflects the idle state of the clock line (SCLK).
220  */
221 #define SPI_MODE_CPOL 0x02
222
223 /** Slave select polarity mode bit
224  *
225  * This bit reflects that active state of the slave select lines.  It
226  * is not part of the normal SPI mode number (which covers only @c
227  * SPI_MODE_CPOL and @c SPI_MODE_CPHA), but is included here for
228  * convenience.
229  */
230 #define SPI_MODE_SSPOL 0x10
231
232 /** Microwire-compatible mode
233  *
234  * This is SPI mode 1 (i.e. CPOL=0, CPHA=1), and is compatible with
235  * the original Microwire protocol.
236  */
237 #define SPI_MODE_MICROWIRE 1
238
239 /** Microwire/Plus-compatible mode
240  *
241  * This is SPI mode 0 (i.e. CPOL=0, CPHA=0), and is compatible with
242  * the Microwire/Plus protocol
243  */
244 #define SPI_MODE_MICROWIRE_PLUS 0
245
246 /** Threewire-compatible mode
247  *
248  * This mode is compatible with Atmel's series of "three-wire"
249  * interfaces.
250  */
251 #define SPI_MODE_THREEWIRE ( SPI_MODE_MICROWIRE_PLUS | SPI_MODE_SSPOL )
252
253 #endif /* _GPXE_SPI_H */