[people/ms/u-boot.git] / include / spi.h

/*
 * Common SPI Interface: Controller-specific definitions
 *
 * (C) Copyright 2001
 * Gerald Van Baren, Custom IDEAS, vanbaren@cideas.com.
 *
 * SPDX-License-Identifier:	GPL-2.0+
 */

#ifndef _SPI_H_
#define _SPI_H_

/* SPI mode flags */
#define	SPI_CPHA	0x01			/* clock phase */
#define	SPI_CPOL	0x02			/* clock polarity */
#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	0x04			/* CS active high */
#define	SPI_LSB_FIRST	0x08			/* per-word bits-on-wire */
#define	SPI_3WIRE	0x10			/* SI/SO signals shared */
#define	SPI_LOOP	0x20			/* loopback mode */
#define	SPI_SLAVE	0x40			/* slave mode */
#define	SPI_PREAMBLE	0x80			/* Skip preamble bytes */

/* SPI transfer flags */
#define SPI_XFER_BEGIN		0x01	/* Assert CS before transfer */
#define SPI_XFER_END		0x02	/* Deassert CS after transfer */
#define SPI_XFER_MMAP		0x08	/* Memory Mapped start */
#define SPI_XFER_MMAP_END	0x10	/* Memory Mapped End */
#define SPI_XFER_ONCE		(SPI_XFER_BEGIN | SPI_XFER_END)

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

#define SPI_DEFAULT_WORDLEN 8

/**
 * struct spi_slave - Representation of a SPI slave
 *
 * Drivers are expected to extend this with controller-specific data.
 *
 * @bus:		ID of the bus that the slave is attached to.
 * @cs:			ID of the chip select connected to the slave.
 * @wordlen:		Size of SPI word in number of bits
 * @max_write_size:	If non-zero, the maximum number of bytes which can
 *			be written at once, excluding command bytes.
 * @memory_map:		Address of read-only SPI flash access.
 */
struct spi_slave {
	unsigned int bus;
	unsigned int cs;
	unsigned int wordlen;
	unsigned int max_write_size;
	void *memory_map;
};

/**
 * Initialization, must be called once on start up.
 *
 * TODO: I don't think we really need this.
 */
void spi_init(void);

/**
 * 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.
 *
 * @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.
 */
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.
 *
 * @_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.
 */
#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.
 *
 * @bus:	Bus ID of the slave chip.
 * @cs:		Chip select ID of the slave chip on the specified bus.
 */
#define spi_alloc_slave_base(bus, cs) \
	spi_do_alloc_slave(0, sizeof(struct spi_slave), bus, cs)

/**
 * 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.
 *
 * @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.
 *
 * 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);

/**
 * Free any memory associated with a SPI slave.
 *
 * @slave:	The SPI slave
 */
void spi_free_slave(struct spi_slave *slave);

/**
 * 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.
 *
 * @slave:	The SPI slave
 *
 * Returns: 0 if the bus was claimed successfully, or a negative value
 * if it wasn't.
 */
int spi_claim_bus(struct spi_slave *slave);

/**
 * 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.
 *
 * @slave:	The SPI slave
 */
void spi_release_bus(struct spi_slave *slave);

/**
 * 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);

/**
 * 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:
 * @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
 *		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  spi_xfer(struct spi_slave *slave, unsigned int bitlen, const void *dout,
		void *din, unsigned long flags);

/**
 * 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.
 */
int  spi_cs_is_valid(unsigned int bus, unsigned int cs);

/**
 * 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);

/**
 * 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);

/**
 * Set transfer speed.
 * This sets a new speed to be applied for next spi_xfer().
 * @slave:	The SPI slave
 * @hz:		The transfer speed
 */
void spi_set_speed(struct spi_slave *slave, uint hz);

/**
 * Write 8 bits, then read 8 bits.
 * @slave:	The SPI slave we're communicating with
 * @byte:	Byte to be written
 *
 * 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;

	ret = spi_xfer(slave, 16, dout, din, SPI_XFER_BEGIN | SPI_XFER_END);
	return ret < 0 ? ret : din[1];
}

/**
 * Set up a SPI slave for a particular device tree node
 *
 * This calls spi_setup_slave() with the correct bus number. Call
 * spi_free_slave() to free it later.
 *
 * @param blob:		Device tree blob
 * @param slave_node:	Slave node to use
 * @param spi_node:	SPI peripheral node to use
 * @return pointer to new spi_slave structure
 */
struct spi_slave *spi_setup_slave_fdt(const void *blob, int slave_node,
				      int spi_node);

/**
 * spi_base_setup_slave_fdt() - helper function to set up a SPI slace
 *
 * This decodes SPI properties from the slave node to determine the
 * chip select and SPI parameters.
 *
 * @blob:	Device tree blob
 * @busnum:	Bus number to use
 * @node:	Device tree node for the SPI bus
 */
struct spi_slave *spi_base_setup_slave_fdt(const void *blob, int busnum,
					   int node);

#endif	/* _SPI_H_ */
Commit	Line	Data
77f85581	1	/*
469146c0 JT	2	* Common SPI Interface: Controller-specific definitions
469146c0 JT	3	*
77f85581 WD	4	* (C) Copyright 2001
	5	* Gerald Van Baren, Custom IDEAS, vanbaren@cideas.com.
	6	*
1a459660	7	* SPDX-License-Identifier: GPL-2.0+
77f85581 WD	8	*/
	9
	10	#ifndef _SPI_H_
	11	#define _SPI_H_
	12
38254f45 GL	13	/* SPI mode flags */
	14	#define SPI_CPHA 0x01 /* clock phase */
	15	#define SPI_CPOL 0x02 /* clock polarity */
	16	#define SPI_MODE_0 (0\|0) /* (original MicroWire) */
	17	#define SPI_MODE_1 (0\|SPI_CPHA)
	18	#define SPI_MODE_2 (SPI_CPOL\|0)
	19	#define SPI_MODE_3 (SPI_CPOL\|SPI_CPHA)
d255bb0e	20	#define SPI_CS_HIGH 0x04 /* CS active high */
38254f45 GL	21	#define SPI_LSB_FIRST 0x08 /* per-word bits-on-wire */
	22	#define SPI_3WIRE 0x10 /* SI/SO signals shared */
	23	#define SPI_LOOP 0x20 /* loopback mode */
bb786b84 RS	24	#define SPI_SLAVE 0x40 /* slave mode */
bb786b84 RS	25	#define SPI_PREAMBLE 0x80 /* Skip preamble bytes */
38254f45	26
d255bb0e	27	/* SPI transfer flags */
ce22b922 JT	28	#define SPI_XFER_BEGIN 0x01 /* Assert CS before transfer */
	29	#define SPI_XFER_END 0x02 /* Deassert CS after transfer */
	30	#define SPI_XFER_MMAP 0x08 /* Memory Mapped start */
	31	#define SPI_XFER_MMAP_END 0x10 /* Memory Mapped End */
4700219d	32	#define SPI_XFER_ONCE (SPI_XFER_BEGIN \| SPI_XFER_END)
77f85581	33
bb786b84	34	/* Header byte that marks the start of the message */
ce22b922	35	#define SPI_PREAMBLE_END_BYTE 0xec
bb786b84	36
5753d09b NK	37	#define SPI_DEFAULT_WORDLEN 8
5753d09b NK	38
1b1bd9a7	39	/**
ce22b922	40	* struct spi_slave - Representation of a SPI slave
d255bb0e HS	41	*
	42	* Drivers are expected to extend this with controller-specific data.
	43	*
ce22b922 JT	44	* @bus: ID of the bus that the slave is attached to.
ce22b922 JT	45	* @cs: ID of the chip select connected to the slave.
5753d09b	46	* @wordlen: Size of SPI word in number of bits
ce22b922 JT	47	* @max_write_size: If non-zero, the maximum number of bytes which can
	48	* be written at once, excluding command bytes.
	49	* @memory_map: Address of read-only SPI flash access.
d255bb0e HS	50	*/
d255bb0e HS	51	struct spi_slave {
1b1bd9a7 JT	52	unsigned int bus;
1b1bd9a7 JT	53	unsigned int cs;
5753d09b	54	unsigned int wordlen;
0c456cee	55	unsigned int max_write_size;
004f15b6	56	void *memory_map;
d255bb0e	57	};
77f85581	58
1b1bd9a7	59	/**
77f85581	60	* Initialization, must be called once on start up.
d255bb0e HS	61	*
d255bb0e HS	62	* TODO: I don't think we really need this.
77f85581 WD	63	*/
	64	void spi_init(void);
	65
ba6c3ce9 SG	66	/**
	67	* spi_do_alloc_slave - Allocate a new SPI slave (internal)
	68	*
	69	* Allocate and zero all fields in the spi slave, and set the bus/chip
	70	* select. Use the helper macro spi_alloc_slave() to call this.
	71	*
1b1bd9a7 JT	72	* @offset: Offset of struct spi_slave within slave structure.
	73	* @size: Size of slave structure.
	74	* @bus: Bus ID of the slave chip.
	75	* @cs: Chip select ID of the slave chip on the specified bus.
ba6c3ce9 SG	76	*/
	77	void *spi_do_alloc_slave(int offset, int size, unsigned int bus,
	78	unsigned int cs);
	79
	80	/**
	81	* spi_alloc_slave - Allocate a new SPI slave
	82	*
	83	* Allocate and zero all fields in the spi slave, and set the bus/chip
	84	* select.
	85	*
1b1bd9a7 JT	86	* @_struct: Name of structure to allocate (e.g. struct tegra_spi).
	87	* This structure must contain a member 'struct spi_slave *slave'.
	88	* @bus: Bus ID of the slave chip.
	89	* @cs: Chip select ID of the slave chip on the specified bus.
ba6c3ce9 SG	90	*/
	91	#define spi_alloc_slave(_struct, bus, cs) \
	92	spi_do_alloc_slave(offsetof(_struct, slave), \
	93	sizeof(_struct), bus, cs)
	94
	95	/**
	96	* spi_alloc_slave_base - Allocate a new SPI slave with no private data
	97	*
	98	* Allocate and zero all fields in the spi slave, and set the bus/chip
	99	* select.
	100	*
1b1bd9a7 JT	101	* @bus: Bus ID of the slave chip.
1b1bd9a7 JT	102	* @cs: Chip select ID of the slave chip on the specified bus.
ba6c3ce9 SG	103	*/
	104	#define spi_alloc_slave_base(bus, cs) \
	105	spi_do_alloc_slave(0, sizeof(struct spi_slave), bus, cs)
	106
1b1bd9a7	107	/**
d255bb0e HS	108	* Set up communications parameters for a SPI slave.
	109	*
	110	* This must be called once for each slave. Note that this function
	111	* usually doesn't touch any actual hardware, it only initializes the
	112	* contents of spi_slave so that the hardware can be easily
	113	* initialized later.
	114	*
1b1bd9a7 JT	115	* @bus: Bus ID of the slave chip.
	116	* @cs: Chip select ID of the slave chip on the specified bus.
	117	* @max_hz: Maximum SCK rate in Hz.
	118	* @mode: Clock polarity, clock phase and other parameters.
d255bb0e HS	119	*
	120	* Returns: A spi_slave reference that can be used in subsequent SPI
	121	* calls, or NULL if one or more of the parameters are not supported.
	122	*/
	123	struct spi_slave *spi_setup_slave(unsigned int bus, unsigned int cs,
	124	unsigned int max_hz, unsigned int mode);
	125
1b1bd9a7	126	/**
d255bb0e HS	127	* Free any memory associated with a SPI slave.
d255bb0e HS	128	*
1b1bd9a7	129	* @slave: The SPI slave
d255bb0e HS	130	*/
	131	void spi_free_slave(struct spi_slave *slave);
	132
1b1bd9a7	133	/**
d255bb0e HS	134	* Claim the bus and prepare it for communication with a given slave.
	135	*
	136	* This must be called before doing any transfers with a SPI slave. It
	137	* will enable and initialize any SPI hardware as necessary, and make
	138	* sure that the SCK line is in the correct idle state. It is not
	139	* allowed to claim the same bus for several slaves without releasing
	140	* the bus in between.
	141	*
1b1bd9a7	142	* @slave: The SPI slave
d255bb0e HS	143	*
	144	* Returns: 0 if the bus was claimed successfully, or a negative value
	145	* if it wasn't.
	146	*/
	147	int spi_claim_bus(struct spi_slave *slave);
	148
1b1bd9a7	149	/**
d255bb0e HS	150	* Release the SPI bus
	151	*
	152	* This must be called once for every call to spi_claim_bus() after
	153	* all transfers have finished. It may disable any SPI hardware as
	154	* appropriate.
	155	*
1b1bd9a7	156	* @slave: The SPI slave
d255bb0e HS	157	*/
d255bb0e HS	158	void spi_release_bus(struct spi_slave *slave);
77f85581	159
5753d09b NK	160	/**
	161	* Set the word length for SPI transactions
	162	*
	163	* Set the word length (number of bits per word) for SPI transactions.
	164	*
	165	* @slave: The SPI slave
	166	* @wordlen: The number of bits in a word
	167	*
	168	* Returns: 0 on success, -1 on failure.
	169	*/
	170	int spi_set_wordlen(struct spi_slave *slave, unsigned int wordlen);
	171
1b1bd9a7	172	/**
77f85581 WD	173	* SPI transfer
	174	*
	175	* This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks
	176	* "bitlen" bits in the SPI MISO port. That's just the way SPI works.
	177	*
	178	* The source of the outgoing bits is the "dout" parameter and the
	179	* destination of the input bits is the "din" parameter. Note that "dout"
	180	* and "din" can point to the same memory location, in which case the
	181	* input data overwrites the output data (since both are buffered by
	182	* temporary variables, this is OK).
	183	*
77f85581	184	* spi_xfer() interface:
1b1bd9a7 JT	185	* @slave: The SPI slave which will be sending/receiving the data.
	186	* @bitlen: How many bits to write and read.
	187	* @dout: Pointer to a string of bits to send out. The bits are
d255bb0e	188	* held in a byte array and are sent MSB first.
1b1bd9a7 JT	189	* @din: Pointer to a string of bits that will be filled in.
1b1bd9a7 JT	190	* @flags: A bitwise combination of SPI_XFER_* flags.
77f85581	191	*
1b1bd9a7	192	* Returns: 0 on success, not 0 on failure
77f85581	193	*/
d255bb0e HS	194	int spi_xfer(struct spi_slave slave, unsigned int bitlen, const void dout,
	195	void *din, unsigned long flags);
	196
1b1bd9a7	197	/**
d255bb0e HS	198	* Determine if a SPI chipselect is valid.
	199	* This function is provided by the board if the low-level SPI driver
	200	* needs it to determine if a given chipselect is actually valid.
	201	*
	202	* Returns: 1 if bus:cs identifies a valid chip on this board, 0
	203	* otherwise.
	204	*/
	205	int spi_cs_is_valid(unsigned int bus, unsigned int cs);
	206
1b1bd9a7	207	/**
d255bb0e HS	208	* Activate a SPI chipselect.
	209	* This function is provided by the board code when using a driver
	210	* that can't control its chipselects automatically (e.g.
	211	* common/soft_spi.c). When called, it should activate the chip select
	212	* to the device identified by "slave".
	213	*/
	214	void spi_cs_activate(struct spi_slave *slave);
	215
1b1bd9a7	216	/**
d255bb0e HS	217	* Deactivate a SPI chipselect.
	218	* This function is provided by the board code when using a driver
	219	* that can't control its chipselects automatically (e.g.
	220	* common/soft_spi.c). When called, it should deactivate the chip
	221	* select to the device identified by "slave".
	222	*/
	223	void spi_cs_deactivate(struct spi_slave *slave);
	224
1b1bd9a7	225	/**
fa1423e7 TC	226	* Set transfer speed.
fa1423e7 TC	227	* This sets a new speed to be applied for next spi_xfer().
1b1bd9a7 JT	228	* @slave: The SPI slave
1b1bd9a7 JT	229	* @hz: The transfer speed
fa1423e7 TC	230	*/
	231	void spi_set_speed(struct spi_slave *slave, uint hz);
	232
1b1bd9a7	233	/**
d255bb0e	234	* Write 8 bits, then read 8 bits.
1b1bd9a7 JT	235	* @slave: The SPI slave we're communicating with
1b1bd9a7 JT	236	* @byte: Byte to be written
d255bb0e HS	237	*
	238	* Returns: The value that was read, or a negative value on error.
	239	*
	240	* TODO: This function probably shouldn't be inlined.
	241	*/
	242	static inline int spi_w8r8(struct spi_slave *slave, unsigned char byte)
	243	{
	244	unsigned char dout[2];
	245	unsigned char din[2];
	246	int ret;
	247
	248	dout[0] = byte;
	249	dout[1] = 0;
38254f45	250
d255bb0e HS	251	ret = spi_xfer(slave, 16, dout, din, SPI_XFER_BEGIN \| SPI_XFER_END);
	252	return ret < 0 ? ret : din[1];
	253	}
77f85581	254
f3424c55 HT	255	/**
	256	* Set up a SPI slave for a particular device tree node
	257	*
	258	* This calls spi_setup_slave() with the correct bus number. Call
	259	* spi_free_slave() to free it later.
	260	*
469146c0	261	* @param blob: Device tree blob
0efc0249 SG	262	* @param slave_node: Slave node to use
0efc0249 SG	263	* @param spi_node: SPI peripheral node to use
f3424c55 HT	264	* @return pointer to new spi_slave structure
f3424c55 HT	265	*/
0efc0249 SG	266	struct spi_slave spi_setup_slave_fdt(const void blob, int slave_node,
	267	int spi_node);
	268
	269	/**
	270	* spi_base_setup_slave_fdt() - helper function to set up a SPI slace
	271	*
	272	* This decodes SPI properties from the slave node to determine the
	273	* chip select and SPI parameters.
	274	*
	275	* @blob: Device tree blob
	276	* @busnum: Bus number to use
	277	* @node: Device tree node for the SPI bus
	278	*/
	279	struct spi_slave spi_base_setup_slave_fdt(const void blob, int busnum,
	280	int node);
f3424c55	281
77f85581	282	#endif /* _SPI_H_ */