spi.h 23.6 KB
Newer Older
1
/* SPDX-License-Identifier: GPL-2.0+ */
wdenk's avatar
wdenk committed
2
/*
3
4
 * Common SPI Interface: Controller-specific definitions
 *
wdenk's avatar
wdenk committed
5
6
7
8
9
10
11
 * (C) Copyright 2001
 * Gerald Van Baren, Custom IDEAS, vanbaren@cideas.com.
 */

#ifndef _SPI_H_
#define _SPI_H_

12
#include <common.h>
13
#include <linux/bitops.h>
14

Guennadi Liakhovetski's avatar
Guennadi Liakhovetski committed
15
/* SPI mode flags */
16
17
#define SPI_CPHA	BIT(0)	/* clock phase (1 = SPI_CLOCK_PHASE_SECOND) */
#define SPI_CPOL	BIT(1)	/* clock polarity (1 = SPI_POLARITY_HIGH) */
Jagan Teki's avatar
Jagan Teki committed
18
19
20
21
22
23
24
25
26
27
#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	BIT(2)			/* CS active high */
#define SPI_LSB_FIRST	BIT(3)			/* per-word bits-on-wire */
#define SPI_3WIRE	BIT(4)			/* SI/SO signals shared */
#define SPI_LOOP	BIT(5)			/* loopback mode */
#define SPI_SLAVE	BIT(6)			/* slave mode */
#define SPI_PREAMBLE	BIT(7)			/* Skip preamble bytes */
Jagan Teki's avatar
Jagan Teki committed
28
#define SPI_TX_BYTE	BIT(8)			/* transmit with 1 wire byte */
Jagan Teki's avatar
Jagan Teki committed
29
30
#define SPI_TX_DUAL	BIT(9)			/* transmit with 2 wires */
#define SPI_TX_QUAD	BIT(10)			/* transmit with 4 wires */
Jagan Teki's avatar
Jagan Teki committed
31
#define SPI_RX_SLOW	BIT(11)			/* receive with 1 wire slow */
Jagan Teki's avatar
Jagan Teki committed
32
33
#define SPI_RX_DUAL	BIT(12)			/* receive with 2 wires */
#define SPI_RX_QUAD	BIT(13)			/* receive with 4 wires */
34
35
#define SPI_TX_OCTAL	BIT(14)			/* transmit with 8 wires */
#define SPI_RX_OCTAL	BIT(15)			/* receive with 8 wires */
36

37
/* Header byte that marks the start of the message */
38
#define SPI_PREAMBLE_END_BYTE	0xec
39

Jagan Teki's avatar
Jagan Teki committed
40
#define SPI_DEFAULT_WORDLEN	8
41

42
43
44
45
46
47
48
49
50
51
52
53
/**
 * struct dm_spi_bus - SPI bus info
 *
 * This contains information about a SPI bus. To obtain this structure, use
 * dev_get_uclass_priv(bus) where bus is the SPI bus udevice.
 *
 * @max_hz:	Maximum speed that the bus can tolerate.
 * @speed:	Current bus speed. This is 0 until the bus is first claimed.
 * @mode:	Current bus mode. This is 0 until the bus is first claimed.
 *
 * TODO(sjg@chromium.org): Remove this and use max_hz from struct spi_slave.
 */
Simon Glass's avatar
Simon Glass committed
54
55
struct dm_spi_bus {
	uint max_hz;
56
57
	uint speed;
	uint mode;
Simon Glass's avatar
Simon Glass committed
58
59
};

60
/**
61
 * struct dm_spi_plat - platform data for all SPI slaves
62
63
 *
 * This describes a SPI slave, a child device of the SPI bus. To obtain this
64
65
 * struct from a spi_slave, use dev_get_parent_plat(dev) or
 * dev_get_parent_plat(slave->dev).
66
 *
Sean Anderson's avatar
Sean Anderson committed
67
 * This data is immutable. Each time the device is probed, @max_hz and @mode
68
69
70
71
72
73
 * will be copied to struct spi_slave.
 *
 * @cs:		Chip select number (0..n-1)
 * @max_hz:	Maximum bus speed that this slave can tolerate
 * @mode:	SPI mode to use for this device (see SPI mode flags)
 */
74
struct dm_spi_slave_plat {
75
76
77
78
79
	unsigned int cs;
	uint max_hz;
	uint mode;
};

Simon Glass's avatar
Simon Glass committed
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
/**
 * enum spi_clock_phase - indicates  the clock phase to use for SPI (CPHA)
 *
 * @SPI_CLOCK_PHASE_FIRST: Data sampled on the first phase
 * @SPI_CLOCK_PHASE_SECOND: Data sampled on the second phase
 */
enum spi_clock_phase {
	SPI_CLOCK_PHASE_FIRST,
	SPI_CLOCK_PHASE_SECOND,
};

/**
 * enum spi_wire_mode - indicates the number of wires used for SPI
 *
 * @SPI_4_WIRE_MODE: Normal bidirectional mode with MOSI and MISO
 * @SPI_3_WIRE_MODE: Unidirectional version with a single data line SISO
 */
enum spi_wire_mode {
	SPI_4_WIRE_MODE,
	SPI_3_WIRE_MODE,
};

/**
 * enum spi_polarity - indicates the polarity of the SPI bus (CPOL)
 *
 * @SPI_POLARITY_LOW: Clock is low in idle state
 * @SPI_POLARITY_HIGH: Clock is high in idle state
 */
enum spi_polarity {
	SPI_POLARITY_LOW,
	SPI_POLARITY_HIGH,
};

113
/**
114
 * struct spi_slave - Representation of a SPI slave
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
115
 *
Simon Glass's avatar
Simon Glass committed
116
 * For driver model this is the per-child data used by the SPI bus. It can
117
 * be accessed using dev_get_parent_priv() on the slave device. The SPI uclass
118
 * sets up per_child_auto to sizeof(struct spi_slave), and the
119
120
121
 * driver should not override it. Two platform data fields (max_hz and mode)
 * are copied into this structure to provide an initial value. This allows
 * them to be changed, since we should never change platform data in drivers.
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
122
 *
Simon Glass's avatar
Simon Glass committed
123
124
125
126
127
128
129
 * If not using driver model, drivers are expected to extend this with
 * controller-specific data.
 *
 * @dev:		SPI slave device
 * @max_hz:		Maximum speed for this slave
 * @bus:		ID of the bus that the slave is attached to. For
 *			driver model this is the sequence number of the SPI
Simon Glass's avatar
Simon Glass committed
130
 *			bus (dev_seq(bus)) so does not need to be stored
131
 * @cs:			ID of the chip select connected to the slave.
132
 * @mode:		SPI mode to use for this slave (see SPI mode flags)
133
 * @wordlen:		Size of SPI word in number of bits
134
135
 * @max_read_size:	If non-zero, the maximum number of bytes which can
 *			be read at once.
136
 * @max_write_size:	If non-zero, the maximum number of bytes which can
137
 *			be written at once.
138
 * @memory_map:		Address of read-only SPI flash access.
139
 * @flags:		Indication of SPI flags.
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
140
141
 */
struct spi_slave {
142
#if CONFIG_IS_ENABLED(DM_SPI)
Simon Glass's avatar
Simon Glass committed
143
144
145
	struct udevice *dev;	/* struct spi_slave is dev->parentdata */
	uint max_hz;
#else
146
147
	unsigned int bus;
	unsigned int cs;
148
#endif
149
	uint mode;
150
	unsigned int wordlen;
151
	unsigned int max_read_size;
152
	unsigned int max_write_size;
153
	void *memory_map;
154

155
	u8 flags;
Jagan Teki's avatar
Jagan Teki committed
156
157
#define SPI_XFER_BEGIN		BIT(0)	/* Assert CS before transfer */
#define SPI_XFER_END		BIT(1)	/* Deassert CS after transfer */
158
#define SPI_XFER_ONCE		(SPI_XFER_BEGIN | SPI_XFER_END)
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
159
};
wdenk's avatar
wdenk committed
160

161
162
163
164
165
166
/**
 * spi_do_alloc_slave - Allocate a new SPI slave (internal)
 *
 * Allocate and zero all fields in the spi slave, and set the bus/chip
 * select. Use the helper macro spi_alloc_slave() to call this.
 *
167
168
169
170
 * @offset:	Offset of struct spi_slave within slave structure.
 * @size:	Size of slave structure.
 * @bus:	Bus ID of the slave chip.
 * @cs:		Chip select ID of the slave chip on the specified bus.
171
172
173
174
175
176
177
178
179
180
 */
void *spi_do_alloc_slave(int offset, int size, unsigned int bus,
			 unsigned int cs);

/**
 * spi_alloc_slave - Allocate a new SPI slave
 *
 * Allocate and zero all fields in the spi slave, and set the bus/chip
 * select.
 *
181
182
183
184
 * @_struct:	Name of structure to allocate (e.g. struct tegra_spi).
 *		This structure must contain a member 'struct spi_slave *slave'.
 * @bus:	Bus ID of the slave chip.
 * @cs:		Chip select ID of the slave chip on the specified bus.
185
186
187
188
189
190
191
192
193
194
195
 */
#define spi_alloc_slave(_struct, bus, cs) \
	spi_do_alloc_slave(offsetof(_struct, slave), \
			    sizeof(_struct), bus, cs)

/**
 * spi_alloc_slave_base - Allocate a new SPI slave with no private data
 *
 * Allocate and zero all fields in the spi slave, and set the bus/chip
 * select.
 *
196
197
 * @bus:	Bus ID of the slave chip.
 * @cs:		Chip select ID of the slave chip on the specified bus.
198
199
200
201
 */
#define spi_alloc_slave_base(bus, cs) \
	spi_do_alloc_slave(0, sizeof(struct spi_slave), bus, cs)

202
/**
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
203
204
205
206
207
208
209
 * Set up communications parameters for a SPI slave.
 *
 * This must be called once for each slave. Note that this function
 * usually doesn't touch any actual hardware, it only initializes the
 * contents of spi_slave so that the hardware can be easily
 * initialized later.
 *
210
211
212
213
 * @bus:	Bus ID of the slave chip.
 * @cs:		Chip select ID of the slave chip on the specified bus.
 * @max_hz:	Maximum SCK rate in Hz.
 * @mode:	Clock polarity, clock phase and other parameters.
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
214
215
216
217
218
219
220
 *
 * Returns: A spi_slave reference that can be used in subsequent SPI
 * calls, or NULL if one or more of the parameters are not supported.
 */
struct spi_slave *spi_setup_slave(unsigned int bus, unsigned int cs,
		unsigned int max_hz, unsigned int mode);

221
/**
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
222
223
 * Free any memory associated with a SPI slave.
 *
224
 * @slave:	The SPI slave
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
225
226
227
 */
void spi_free_slave(struct spi_slave *slave);

228
/**
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
229
230
231
232
233
234
235
236
 * Claim the bus and prepare it for communication with a given slave.
 *
 * This must be called before doing any transfers with a SPI slave. It
 * will enable and initialize any SPI hardware as necessary, and make
 * sure that the SCK line is in the correct idle state. It is not
 * allowed to claim the same bus for several slaves without releasing
 * the bus in between.
 *
237
 * @slave:	The SPI slave
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
238
239
240
241
242
243
 *
 * Returns: 0 if the bus was claimed successfully, or a negative value
 * if it wasn't.
 */
int spi_claim_bus(struct spi_slave *slave);

244
/**
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
245
246
247
248
249
250
 * Release the SPI bus
 *
 * This must be called once for every call to spi_claim_bus() after
 * all transfers have finished. It may disable any SPI hardware as
 * appropriate.
 *
251
 * @slave:	The SPI slave
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
252
253
 */
void spi_release_bus(struct spi_slave *slave);
wdenk's avatar
wdenk committed
254

255
256
257
258
259
260
261
262
263
264
265
266
/**
 * Set the word length for SPI transactions
 *
 * Set the word length (number of bits per word) for SPI transactions.
 *
 * @slave:	The SPI slave
 * @wordlen:	The number of bits in a word
 *
 * Returns: 0 on success, -1 on failure.
 */
int spi_set_wordlen(struct spi_slave *slave, unsigned int wordlen);

267
/**
268
 * SPI transfer (optional if mem_ops is used)
wdenk's avatar
wdenk committed
269
270
271
272
273
274
275
276
277
278
279
 *
 * This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks
 * "bitlen" bits in the SPI MISO port.  That's just the way SPI works.
 *
 * The source of the outgoing bits is the "dout" parameter and the
 * destination of the input bits is the "din" parameter.  Note that "dout"
 * and "din" can point to the same memory location, in which case the
 * input data overwrites the output data (since both are buffered by
 * temporary variables, this is OK).
 *
 * spi_xfer() interface:
280
281
282
 * @slave:	The SPI slave which will be sending/receiving the data.
 * @bitlen:	How many bits to write and read.
 * @dout:	Pointer to a string of bits to send out.  The bits are
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
283
 *		held in a byte array and are sent MSB first.
284
285
 * @din:	Pointer to a string of bits that will be filled in.
 * @flags:	A bitwise combination of SPI_XFER_* flags.
wdenk's avatar
wdenk committed
286
 *
287
 * Returns: 0 on success, not 0 on failure
wdenk's avatar
wdenk committed
288
 */
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
289
290
291
int  spi_xfer(struct spi_slave *slave, unsigned int bitlen, const void *dout,
		void *din, unsigned long flags);

Jagan Teki's avatar
Jagan Teki committed
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
/**
 * spi_write_then_read - SPI synchronous write followed by read
 *
 * This performs a half duplex transaction in which the first transaction
 * is to send the opcode and if the length of buf is non-zero then it start
 * the second transaction as tx or rx based on the need from respective slave.
 *
 * @slave:	The SPI slave device with which opcode/data will be exchanged
 * @opcode:	opcode used for specific transfer
 * @n_opcode:	size of opcode, in bytes
 * @txbuf:	buffer into which data to be written
 * @rxbuf:	buffer into which data will be read
 * @n_buf:	size of buf (whether it's [tx|rx]buf), in bytes
 *
 * Returns: 0 on success, not 0 on failure
 */
int spi_write_then_read(struct spi_slave *slave, const u8 *opcode,
			size_t n_opcode, const u8 *txbuf, u8 *rxbuf,
			size_t n_buf);

312
313
314
/* Copy memory mapped data */
void spi_flash_copy_mmap(void *data, void *offset, size_t len);

315
/**
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
316
317
318
319
320
321
322
 * Determine if a SPI chipselect is valid.
 * This function is provided by the board if the low-level SPI driver
 * needs it to determine if a given chipselect is actually valid.
 *
 * Returns: 1 if bus:cs identifies a valid chip on this board, 0
 * otherwise.
 */
Simon Glass's avatar
Simon Glass committed
323
int spi_cs_is_valid(unsigned int bus, unsigned int cs);
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
324

325
326
327
328
329
/*
 * These names are used in several drivers and these declarations will be
 * removed soon as part of the SPI DM migration. Drop them if driver model is
 * enabled for SPI.
 */
330
#if !CONFIG_IS_ENABLED(DM_SPI)
331
/**
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
332
333
334
335
336
337
338
339
 * Activate a SPI chipselect.
 * This function is provided by the board code when using a driver
 * that can't control its chipselects automatically (e.g.
 * common/soft_spi.c). When called, it should activate the chip select
 * to the device identified by "slave".
 */
void spi_cs_activate(struct spi_slave *slave);

340
/**
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
341
342
343
344
345
346
347
 * Deactivate a SPI chipselect.
 * This function is provided by the board code when using a driver
 * that can't control its chipselects automatically (e.g.
 * common/soft_spi.c). When called, it should deactivate the chip
 * select to the device identified by "slave".
 */
void spi_cs_deactivate(struct spi_slave *slave);
348
#endif
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
349

350
/**
Thomas Chou's avatar
Thomas Chou committed
351
352
 * Set transfer speed.
 * This sets a new speed to be applied for next spi_xfer().
353
354
 * @slave:	The SPI slave
 * @hz:		The transfer speed
Thomas Chou's avatar
Thomas Chou committed
355
356
357
 */
void spi_set_speed(struct spi_slave *slave, uint hz);

358
/**
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
359
 * Write 8 bits, then read 8 bits.
360
361
 * @slave:	The SPI slave we're communicating with
 * @byte:	Byte to be written
Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
362
363
364
365
366
367
368
369
370
371
372
373
374
 *
 * Returns: The value that was read, or a negative value on error.
 *
 * TODO: This function probably shouldn't be inlined.
 */
static inline int spi_w8r8(struct spi_slave *slave, unsigned char byte)
{
	unsigned char dout[2];
	unsigned char din[2];
	int ret;

	dout[0] = byte;
	dout[1] = 0;
Guennadi Liakhovetski's avatar
Guennadi Liakhovetski committed
375

Haavard Skinnemoen's avatar
Haavard Skinnemoen committed
376
377
378
	ret = spi_xfer(slave, 16, dout, din, SPI_XFER_BEGIN | SPI_XFER_END);
	return ret < 0 ? ret : din[1];
}
wdenk's avatar
wdenk committed
379

Simon Glass's avatar
Simon Glass committed
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
/**
 * struct spi_cs_info - Information about a bus chip select
 *
 * @dev:	Connected device, or NULL if none
 */
struct spi_cs_info {
	struct udevice *dev;
};

/**
 * struct struct dm_spi_ops - Driver model SPI operations
 *
 * The uclass interface is implemented by all SPI devices which use
 * driver model.
 */
struct dm_spi_ops {
	/**
	 * Claim the bus and prepare it for communication.
	 *
	 * The device provided is the slave device. It's parent controller
	 * will be used to provide the communication.
	 *
	 * This must be called before doing any transfers with a SPI slave. It
	 * will enable and initialize any SPI hardware as necessary, and make
	 * sure that the SCK line is in the correct idle state. It is not
	 * allowed to claim the same bus for several slaves without releasing
	 * the bus in between.
	 *
408
	 * @dev:	The SPI slave
Simon Glass's avatar
Simon Glass committed
409
410
411
412
	 *
	 * Returns: 0 if the bus was claimed successfully, or a negative value
	 * if it wasn't.
	 */
413
	int (*claim_bus)(struct udevice *dev);
Simon Glass's avatar
Simon Glass committed
414
415
416
417
418
419
420
421

	/**
	 * Release the SPI bus
	 *
	 * This must be called once for every call to spi_claim_bus() after
	 * all transfers have finished. It may disable any SPI hardware as
	 * appropriate.
	 *
422
	 * @dev:	The SPI slave
Simon Glass's avatar
Simon Glass committed
423
	 */
424
	int (*release_bus)(struct udevice *dev);
Simon Glass's avatar
Simon Glass committed
425
426
427
428
429
430
431
432
433
434
435

	/**
	 * Set the word length for SPI transactions
	 *
	 * Set the word length (number of bits per word) for SPI transactions.
	 *
	 * @bus:	The SPI slave
	 * @wordlen:	The number of bits in a word
	 *
	 * Returns: 0 on success, -ve on failure.
	 */
436
	int (*set_wordlen)(struct udevice *dev, unsigned int wordlen);
Simon Glass's avatar
Simon Glass committed
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463

	/**
	 * SPI transfer
	 *
	 * This writes "bitlen" bits out the SPI MOSI port and simultaneously
	 * clocks "bitlen" bits in the SPI MISO port.  That's just the way SPI
	 * works.
	 *
	 * The source of the outgoing bits is the "dout" parameter and the
	 * destination of the input bits is the "din" parameter.  Note that
	 * "dout" and "din" can point to the same memory location, in which
	 * case the input data overwrites the output data (since both are
	 * buffered by temporary variables, this is OK).
	 *
	 * spi_xfer() interface:
	 * @dev:	The slave device to communicate with
	 * @bitlen:	How many bits to write and read.
	 * @dout:	Pointer to a string of bits to send out.  The bits are
	 *		held in a byte array and are sent MSB first.
	 * @din:	Pointer to a string of bits that will be filled in.
	 * @flags:	A bitwise combination of SPI_XFER_* flags.
	 *
	 * Returns: 0 on success, not -1 on failure
	 */
	int (*xfer)(struct udevice *dev, unsigned int bitlen, const void *dout,
		    void *din, unsigned long flags);

464
465
466
467
468
469
470
471
472
	/**
	 * Optimized handlers for SPI memory-like operations.
	 *
	 * Optimized/dedicated operations for interactions with SPI memory. This
	 * field is optional and should only be implemented if the controller
	 * has native support for memory like operations.
	 */
	const struct spi_controller_mem_ops *mem_ops;

Simon Glass's avatar
Simon Glass committed
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
	/**
	 * Set transfer speed.
	 * This sets a new speed to be applied for next spi_xfer().
	 * @bus:	The SPI bus
	 * @hz:		The transfer speed
	 * @return 0 if OK, -ve on error
	 */
	int (*set_speed)(struct udevice *bus, uint hz);

	/**
	 * Set the SPI mode/flags
	 *
	 * It is unclear if we want to set speed and mode together instead
	 * of separately.
	 *
	 * @bus:	The SPI bus
	 * @mode:	Requested SPI mode (SPI_... flags)
	 * @return 0 if OK, -ve on error
	 */
	int (*set_mode)(struct udevice *bus, uint mode);

	/**
	 * Get information on a chip select
	 *
	 * This is only called when the SPI uclass does not know about a
	 * chip select, i.e. it has no attached device. It gives the driver
	 * a chance to allow activity on that chip select even so.
	 *
	 * @bus:	The SPI bus
	 * @cs:		The chip select (0..n-1)
	 * @info:	Returns information about the chip select, if valid.
	 *		On entry info->dev is NULL
505
	 * @return 0 if OK (and @info is set up), -EINVAL if the chip select
Simon Glass's avatar
Simon Glass committed
506
507
508
	 *	   is invalid, other -ve value on error
	 */
	int (*cs_info)(struct udevice *bus, uint cs, struct spi_cs_info *info);
509
510
511
512
513
514
515
516
517
518
519
520
521

	/**
	 * get_mmap() - Get memory-mapped SPI
	 *
	 * @dev:	The SPI flash slave device
	 * @map_basep:	Returns base memory address for mapped SPI
	 * @map_sizep:	Returns size of mapped SPI
	 * @offsetp:	Returns start offset of SPI flash where the map works
	 *	correctly (offsets before this are not visible)
	 * @return 0 if OK, -EFAULT if memory mapping is not available
	 */
	int (*get_mmap)(struct udevice *dev, ulong *map_basep,
			uint *map_sizep, uint *offsetp);
Simon Glass's avatar
Simon Glass committed
522
523
};

524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
struct dm_spi_emul_ops {
	/**
	 * SPI transfer
	 *
	 * This writes "bitlen" bits out the SPI MOSI port and simultaneously
	 * clocks "bitlen" bits in the SPI MISO port.  That's just the way SPI
	 * works. Here the device is a slave.
	 *
	 * The source of the outgoing bits is the "dout" parameter and the
	 * destination of the input bits is the "din" parameter.  Note that
	 * "dout" and "din" can point to the same memory location, in which
	 * case the input data overwrites the output data (since both are
	 * buffered by temporary variables, this is OK).
	 *
	 * spi_xfer() interface:
	 * @slave:	The SPI slave which will be sending/receiving the data.
	 * @bitlen:	How many bits to write and read.
	 * @dout:	Pointer to a string of bits sent to the device. The
	 *		bits are held in a byte array and are sent MSB first.
	 * @din:	Pointer to a string of bits that will be sent back to
	 *		the master.
	 * @flags:	A bitwise combination of SPI_XFER_* flags.
	 *
	 * Returns: 0 on success, not -1 on failure
	 */
	int (*xfer)(struct udevice *slave, unsigned int bitlen,
		    const void *dout, void *din, unsigned long flags);
};

Simon Glass's avatar
Simon Glass committed
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
/**
 * spi_find_bus_and_cs() - Find bus and slave devices by number
 *
 * Given a bus number and chip select, this finds the corresponding bus
 * device and slave device. Neither device is activated by this function,
 * although they may have been activated previously.
 *
 * @busnum:	SPI bus number
 * @cs:		Chip select to look for
 * @busp:	Returns bus device
 * @devp:	Return slave device
 * @return 0 if found, -ENODEV on error
 */
int spi_find_bus_and_cs(int busnum, int cs, struct udevice **busp,
			struct udevice **devp);

/**
 * spi_get_bus_and_cs() - Find and activate bus and slave devices by number
 *
 * Given a bus number and chip select, this finds the corresponding bus
 * device and slave device.
 *
 * If no such slave exists, and drv_name is not NULL, then a new slave device
576
 * is automatically bound on this chip select with requested speed and mode.
Simon Glass's avatar
Simon Glass committed
577
 *
578
 * Ths new slave device is probed ready for use with the speed and mode
579
 * from plat when available or the requested values.
Simon Glass's avatar
Simon Glass committed
580
581
582
 *
 * @busnum:	SPI bus number
 * @cs:		Chip select to look for
583
584
 * @speed:	SPI speed to use for this slave when not available in plat
 * @mode:	SPI mode to use for this slave when not available in plat
Simon Glass's avatar
Simon Glass committed
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
 * @drv_name:	Name of driver to attach to this chip select
 * @dev_name:	Name of the new device thus created
 * @busp:	Returns bus device
 * @devp:	Return slave device
 * @return 0 if found, -ve on error
 */
int spi_get_bus_and_cs(int busnum, int cs, int speed, int mode,
			const char *drv_name, const char *dev_name,
			struct udevice **busp, struct spi_slave **devp);

/**
 * spi_chip_select() - Get the chip select for a slave
 *
 * @return the chip select this slave is attached to
 */
int spi_chip_select(struct udevice *slave);

602
603
604
605
606
607
/**
 * spi_find_chip_select() - Find the slave attached to chip select
 *
 * @bus:	SPI bus to search
 * @cs:		Chip select to look for
 * @devp:	Returns the slave device if found
608
609
 * @return 0 if found, -EINVAL if cs is invalid, -ENODEV if no device attached,
 *	   other -ve value on error
610
611
612
 */
int spi_find_chip_select(struct udevice *bus, int cs, struct udevice **devp);

Simon Glass's avatar
Simon Glass committed
613
/**
614
 * spi_slave_of_to_plat() - decode standard SPI platform data
Simon Glass's avatar
Simon Glass committed
615
 *
616
 * This decodes the speed and mode for a slave from a device tree node
Simon Glass's avatar
Simon Glass committed
617
618
619
 *
 * @blob:	Device tree blob
 * @node:	Node offset to read from
620
 * @plat:	Place to put the decoded information
Simon Glass's avatar
Simon Glass committed
621
 */
622
int spi_slave_of_to_plat(struct udevice *dev, struct dm_spi_slave_plat *plat);
Simon Glass's avatar
Simon Glass committed
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638

/**
 * spi_cs_info() - Check information on a chip select
 *
 * This checks a particular chip select on a bus to see if it has a device
 * attached, or is even valid.
 *
 * @bus:	The SPI bus
 * @cs:		The chip select (0..n-1)
 * @info:	Returns information about the chip select, if valid
 * @return 0 if OK (and @info is set up), -ENODEV if the chip select
 *	   is invalid, other -ve value on error
 */
int spi_cs_info(struct udevice *bus, uint cs, struct spi_cs_info *info);

struct sandbox_state;
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653

/**
 * sandbox_spi_get_emul() - get an emulator for a SPI slave
 *
 * This provides a way to attach an emulated SPI device to a particular SPI
 * slave, so that xfer() operations on the slave will be handled by the
 * emulator. If a emulator already exists on that chip select it is returned.
 * Otherwise one is created.
 *
 * @state:	Sandbox state
 * @bus:	SPI bus requesting the emulator
 * @slave:	SPI slave device requesting the emulator
 * @emuip:	Returns pointer to emulator
 * @return 0 if OK, -ve on error
 */
Simon Glass's avatar
Simon Glass committed
654
655
656
657
int sandbox_spi_get_emul(struct sandbox_state *state,
			 struct udevice *bus, struct udevice *slave,
			 struct udevice **emulp);

Peng Fan's avatar
Peng Fan committed
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
/**
 * Claim the bus and prepare it for communication with a given slave.
 *
 * This must be called before doing any transfers with a SPI slave. It
 * will enable and initialize any SPI hardware as necessary, and make
 * sure that the SCK line is in the correct idle state. It is not
 * allowed to claim the same bus for several slaves without releasing
 * the bus in between.
 *
 * @dev:	The SPI slave device
 *
 * Returns: 0 if the bus was claimed successfully, or a negative value
 * if it wasn't.
 */
int dm_spi_claim_bus(struct udevice *dev);

/**
 * Release the SPI bus
 *
 * This must be called once for every call to dm_spi_claim_bus() after
 * all transfers have finished. It may disable any SPI hardware as
 * appropriate.
 *
 * @slave:	The SPI slave device
 */
void dm_spi_release_bus(struct udevice *dev);

/**
 * SPI transfer
 *
 * This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks
 * "bitlen" bits in the SPI MISO port.  That's just the way SPI works.
 *
 * The source of the outgoing bits is the "dout" parameter and the
 * destination of the input bits is the "din" parameter.  Note that "dout"
 * and "din" can point to the same memory location, in which case the
 * input data overwrites the output data (since both are buffered by
 * temporary variables, this is OK).
 *
 * dm_spi_xfer() interface:
 * @dev:	The SPI slave device which will be sending/receiving the data.
 * @bitlen:	How many bits to write and read.
 * @dout:	Pointer to a string of bits to send out.  The bits are
 *		held in a byte array and are sent MSB first.
 * @din:	Pointer to a string of bits that will be filled in.
 * @flags:	A bitwise combination of SPI_XFER_* flags.
 *
 * Returns: 0 on success, not 0 on failure
 */
int dm_spi_xfer(struct udevice *dev, unsigned int bitlen,
		const void *dout, void *din, unsigned long flags);

710
711
712
713
714
715
716
717
718
719
720
721
722
723
/**
 * spi_get_mmap() - Get memory-mapped SPI
 *
 * @dev:	SPI slave device to check
 * @map_basep:	Returns base memory address for mapped SPI
 * @map_sizep:	Returns size of mapped SPI
 * @offsetp:	Returns start offset of SPI flash where the map works
 *	correctly (offsets before this are not visible)
 * @return 0 if OK, -ENOSYS if no operation, -EFAULT if memory mapping is not
 *	available
 */
int dm_spi_get_mmap(struct udevice *dev, ulong *map_basep, uint *map_sizep,
		    uint *offsetp);

724
/* Access the operations for a SPI device */
Simon Glass's avatar
Simon Glass committed
725
#define spi_get_ops(dev)	((struct dm_spi_ops *)(dev)->driver->ops)
726
#define spi_emul_get_ops(dev)	((struct dm_spi_emul_ops *)(dev)->driver->ops)
Simon Glass's avatar
Simon Glass committed
727

wdenk's avatar
wdenk committed
728
#endif	/* _SPI_H_ */