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

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

#ifndef _SPI_H_
#define _SPI_H_

/* Controller-specific definitions: */

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

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

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

/**
 * 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 node		SPI peripheral node to use
 * @param cs		Chip select to use
 * @param max_hz	Maximum SCK rate in Hz (0 for default)
 * @param mode		Clock polarity, clock phase and other parameters
 * @return pointer to new spi_slave structure
 */
struct spi_slave *spi_setup_slave_fdt(const void *blob, int node,
		unsigned int cs, unsigned int max_hz, unsigned int mode);

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