1/*
2 * polling/bitbanging SPI master controller driver utilities
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU General Public License for more details.
13 */
14
15#include <linux/spinlock.h>
16#include <linux/workqueue.h>
17#include <linux/interrupt.h>
18#include <linux/module.h>
19#include <linux/delay.h>
20#include <linux/errno.h>
21#include <linux/platform_device.h>
22#include <linux/slab.h>
23
24#include <linux/spi/spi.h>
25#include <linux/spi/spi_bitbang.h>
26
27
28/*----------------------------------------------------------------------*/
29
30/*
31 * FIRST PART (OPTIONAL):  word-at-a-time spi_transfer support.
32 * Use this for GPIO or shift-register level hardware APIs.
33 *
34 * spi_bitbang_cs is in spi_device->controller_state, which is unavailable
35 * to glue code.  These bitbang setup() and cleanup() routines are always
36 * used, though maybe they're called from controller-aware code.
37 *
38 * chipselect() and friends may use spi_device->controller_data and
39 * controller registers as appropriate.
40 *
41 *
42 * NOTE:  SPI controller pins can often be used as GPIO pins instead,
43 * which means you could use a bitbang driver either to get hardware
44 * working quickly, or testing for differences that aren't speed related.
45 */
46
47struct spi_bitbang_cs {
48	unsigned	nsecs;	/* (clock cycle time)/2 */
49	u32		(*txrx_word)(struct spi_device *spi, unsigned nsecs,
50					u32 word, u8 bits);
51	unsigned	(*txrx_bufs)(struct spi_device *,
52					u32 (*txrx_word)(
53						struct spi_device *spi,
54						unsigned nsecs,
55						u32 word, u8 bits),
56					unsigned, struct spi_transfer *);
57};
58
59static unsigned bitbang_txrx_8(
60	struct spi_device	*spi,
61	u32			(*txrx_word)(struct spi_device *spi,
62					unsigned nsecs,
63					u32 word, u8 bits),
64	unsigned		ns,
65	struct spi_transfer	*t
66) {
67	unsigned		bits = t->bits_per_word;
68	unsigned		count = t->len;
69	const u8		*tx = t->tx_buf;
70	u8			*rx = t->rx_buf;
71
72	while (likely(count > 0)) {
73		u8		word = 0;
74
75		if (tx)
76			word = *tx++;
77		word = txrx_word(spi, ns, word, bits);
78		if (rx)
79			*rx++ = word;
80		count -= 1;
81	}
82	return t->len - count;
83}
84
85static unsigned bitbang_txrx_16(
86	struct spi_device	*spi,
87	u32			(*txrx_word)(struct spi_device *spi,
88					unsigned nsecs,
89					u32 word, u8 bits),
90	unsigned		ns,
91	struct spi_transfer	*t
92) {
93	unsigned		bits = t->bits_per_word;
94	unsigned		count = t->len;
95	const u16		*tx = t->tx_buf;
96	u16			*rx = t->rx_buf;
97
98	while (likely(count > 1)) {
99		u16		word = 0;
100
101		if (tx)
102			word = *tx++;
103		word = txrx_word(spi, ns, word, bits);
104		if (rx)
105			*rx++ = word;
106		count -= 2;
107	}
108	return t->len - count;
109}
110
111static unsigned bitbang_txrx_32(
112	struct spi_device	*spi,
113	u32			(*txrx_word)(struct spi_device *spi,
114					unsigned nsecs,
115					u32 word, u8 bits),
116	unsigned		ns,
117	struct spi_transfer	*t
118) {
119	unsigned		bits = t->bits_per_word;
120	unsigned		count = t->len;
121	const u32		*tx = t->tx_buf;
122	u32			*rx = t->rx_buf;
123
124	while (likely(count > 3)) {
125		u32		word = 0;
126
127		if (tx)
128			word = *tx++;
129		word = txrx_word(spi, ns, word, bits);
130		if (rx)
131			*rx++ = word;
132		count -= 4;
133	}
134	return t->len - count;
135}
136
137int spi_bitbang_setup_transfer(struct spi_device *spi, struct spi_transfer *t)
138{
139	struct spi_bitbang_cs	*cs = spi->controller_state;
140	u8			bits_per_word;
141	u32			hz;
142
143	if (t) {
144		bits_per_word = t->bits_per_word;
145		hz = t->speed_hz;
146	} else {
147		bits_per_word = 0;
148		hz = 0;
149	}
150
151	/* spi_transfer level calls that work per-word */
152	if (!bits_per_word)
153		bits_per_word = spi->bits_per_word;
154	if (bits_per_word <= 8)
155		cs->txrx_bufs = bitbang_txrx_8;
156	else if (bits_per_word <= 16)
157		cs->txrx_bufs = bitbang_txrx_16;
158	else if (bits_per_word <= 32)
159		cs->txrx_bufs = bitbang_txrx_32;
160	else
161		return -EINVAL;
162
163	/* nsecs = (clock period)/2 */
164	if (!hz)
165		hz = spi->max_speed_hz;
166	if (hz) {
167		cs->nsecs = (1000000000/2) / hz;
168		if (cs->nsecs > (MAX_UDELAY_MS * 1000 * 1000))
169			return -EINVAL;
170	}
171
172	return 0;
173}
174EXPORT_SYMBOL_GPL(spi_bitbang_setup_transfer);
175
176/**
177 * spi_bitbang_setup - default setup for per-word I/O loops
178 */
179int spi_bitbang_setup(struct spi_device *spi)
180{
181	struct spi_bitbang_cs	*cs = spi->controller_state;
182	struct spi_bitbang	*bitbang;
183	unsigned long		flags;
184
185	bitbang = spi_master_get_devdata(spi->master);
186
187	if (!cs) {
188		cs = kzalloc(sizeof(*cs), GFP_KERNEL);
189		if (!cs)
190			return -ENOMEM;
191		spi->controller_state = cs;
192	}
193
194	/* per-word shift register access, in hardware or bitbanging */
195	cs->txrx_word = bitbang->txrx_word[spi->mode & (SPI_CPOL|SPI_CPHA)];
196	if (!cs->txrx_word)
197		return -EINVAL;
198
199	if (bitbang->setup_transfer) {
200		int retval = bitbang->setup_transfer(spi, NULL);
201		if (retval < 0)
202			return retval;
203	}
204
205	dev_dbg(&spi->dev, "%s, %u nsec/bit\n", __func__, 2 * cs->nsecs);
206
207	/* NOTE we _need_ to call chipselect() early, ideally with adapter
208	 * setup, unless the hardware defaults cooperate to avoid confusion
209	 * between normal (active low) and inverted chipselects.
210	 */
211
212	/* deselect chip (low or high) */
213	spin_lock_irqsave(&bitbang->lock, flags);
214	if (!bitbang->busy) {
215		bitbang->chipselect(spi, BITBANG_CS_INACTIVE);
216		ndelay(cs->nsecs);
217	}
218	spin_unlock_irqrestore(&bitbang->lock, flags);
219
220	return 0;
221}
222EXPORT_SYMBOL_GPL(spi_bitbang_setup);
223
224/**
225 * spi_bitbang_cleanup - default cleanup for per-word I/O loops
226 */
227void spi_bitbang_cleanup(struct spi_device *spi)
228{
229	kfree(spi->controller_state);
230}
231EXPORT_SYMBOL_GPL(spi_bitbang_cleanup);
232
233static int spi_bitbang_bufs(struct spi_device *spi, struct spi_transfer *t)
234{
235	struct spi_bitbang_cs	*cs = spi->controller_state;
236	unsigned		nsecs = cs->nsecs;
237
238	return cs->txrx_bufs(spi, cs->txrx_word, nsecs, t);
239}
240
241/*----------------------------------------------------------------------*/
242
243/*
244 * SECOND PART ... simple transfer queue runner.
245 *
246 * This costs a task context per controller, running the queue by
247 * performing each transfer in sequence.  Smarter hardware can queue
248 * several DMA transfers at once, and process several controller queues
249 * in parallel; this driver doesn't match such hardware very well.
250 *
251 * Drivers can provide word-at-a-time i/o primitives, or provide
252 * transfer-at-a-time ones to leverage dma or fifo hardware.
253 */
254
255static int spi_bitbang_prepare_hardware(struct spi_master *spi)
256{
257	struct spi_bitbang	*bitbang;
258	unsigned long		flags;
259
260	bitbang = spi_master_get_devdata(spi);
261
262	spin_lock_irqsave(&bitbang->lock, flags);
263	bitbang->busy = 1;
264	spin_unlock_irqrestore(&bitbang->lock, flags);
265
266	return 0;
267}
268
269static int spi_bitbang_transfer_one(struct spi_master *master,
270				    struct spi_message *m)
271{
272	struct spi_bitbang	*bitbang;
273	unsigned		nsecs;
274	struct spi_transfer	*t = NULL;
275	unsigned		cs_change;
276	int			status;
277	int			do_setup = -1;
278	struct spi_device	*spi = m->spi;
279
280	bitbang = spi_master_get_devdata(master);
281
282	/* FIXME this is made-up ... the correct value is known to
283	 * word-at-a-time bitbang code, and presumably chipselect()
284	 * should enforce these requirements too?
285	 */
286	nsecs = 100;
287
288	cs_change = 1;
289	status = 0;
290
291	list_for_each_entry(t, &m->transfers, transfer_list) {
292
293		/* override speed or wordsize? */
294		if (t->speed_hz || t->bits_per_word)
295			do_setup = 1;
296
297		/* init (-1) or override (1) transfer params */
298		if (do_setup != 0) {
299			if (bitbang->setup_transfer) {
300				status = bitbang->setup_transfer(spi, t);
301				if (status < 0)
302					break;
303			}
304			if (do_setup == -1)
305				do_setup = 0;
306		}
307
308		/* set up default clock polarity, and activate chip;
309		 * this implicitly updates clock and spi modes as
310		 * previously recorded for this device via setup().
311		 * (and also deselects any other chip that might be
312		 * selected ...)
313		 */
314		if (cs_change) {
315			bitbang->chipselect(spi, BITBANG_CS_ACTIVE);
316			ndelay(nsecs);
317		}
318		cs_change = t->cs_change;
319		if (!t->tx_buf && !t->rx_buf && t->len) {
320			status = -EINVAL;
321			break;
322		}
323
324		/* transfer data.  the lower level code handles any
325		 * new dma mappings it needs. our caller always gave
326		 * us dma-safe buffers.
327		 */
328		if (t->len) {
329			/* REVISIT dma API still needs a designated
330			 * DMA_ADDR_INVALID; ~0 might be better.
331			 */
332			if (!m->is_dma_mapped)
333				t->rx_dma = t->tx_dma = 0;
334			status = bitbang->txrx_bufs(spi, t);
335		}
336		if (status > 0)
337			m->actual_length += status;
338		if (status != t->len) {
339			/* always report some kind of error */
340			if (status >= 0)
341				status = -EREMOTEIO;
342			break;
343		}
344		status = 0;
345
346		/* protocol tweaks before next transfer */
347		if (t->delay_usecs)
348			udelay(t->delay_usecs);
349
350		if (cs_change &&
351		    !list_is_last(&t->transfer_list, &m->transfers)) {
352			/* sometimes a short mid-message deselect of the chip
353			 * may be needed to terminate a mode or command
354			 */
355			ndelay(nsecs);
356			bitbang->chipselect(spi, BITBANG_CS_INACTIVE);
357			ndelay(nsecs);
358		}
359	}
360
361	m->status = status;
362
363	/* normally deactivate chipselect ... unless no error and
364	 * cs_change has hinted that the next message will probably
365	 * be for this chip too.
366	 */
367	if (!(status == 0 && cs_change)) {
368		ndelay(nsecs);
369		bitbang->chipselect(spi, BITBANG_CS_INACTIVE);
370		ndelay(nsecs);
371	}
372
373	spi_finalize_current_message(master);
374
375	return status;
376}
377
378static int spi_bitbang_unprepare_hardware(struct spi_master *spi)
379{
380	struct spi_bitbang	*bitbang;
381	unsigned long		flags;
382
383	bitbang = spi_master_get_devdata(spi);
384
385	spin_lock_irqsave(&bitbang->lock, flags);
386	bitbang->busy = 0;
387	spin_unlock_irqrestore(&bitbang->lock, flags);
388
389	return 0;
390}
391
392/*----------------------------------------------------------------------*/
393
394/**
395 * spi_bitbang_start - start up a polled/bitbanging SPI master driver
396 * @bitbang: driver handle
397 *
398 * Caller should have zero-initialized all parts of the structure, and then
399 * provided callbacks for chip selection and I/O loops.  If the master has
400 * a transfer method, its final step should call spi_bitbang_transfer; or,
401 * that's the default if the transfer routine is not initialized.  It should
402 * also set up the bus number and number of chipselects.
403 *
404 * For i/o loops, provide callbacks either per-word (for bitbanging, or for
405 * hardware that basically exposes a shift register) or per-spi_transfer
406 * (which takes better advantage of hardware like fifos or DMA engines).
407 *
408 * Drivers using per-word I/O loops should use (or call) spi_bitbang_setup,
409 * spi_bitbang_cleanup and spi_bitbang_setup_transfer to handle those spi
410 * master methods.  Those methods are the defaults if the bitbang->txrx_bufs
411 * routine isn't initialized.
412 *
413 * This routine registers the spi_master, which will process requests in a
414 * dedicated task, keeping IRQs unblocked most of the time.  To stop
415 * processing those requests, call spi_bitbang_stop().
416 *
417 * On success, this routine will take a reference to master. The caller is
418 * responsible for calling spi_bitbang_stop() to decrement the reference and
419 * spi_master_put() as counterpart of spi_alloc_master() to prevent a memory
420 * leak.
421 */
422int spi_bitbang_start(struct spi_bitbang *bitbang)
423{
424	struct spi_master *master = bitbang->master;
425	int ret;
426
427	if (!master || !bitbang->chipselect)
428		return -EINVAL;
429
430	spin_lock_init(&bitbang->lock);
431
432	if (!master->mode_bits)
433		master->mode_bits = SPI_CPOL | SPI_CPHA | bitbang->flags;
434
435	if (master->transfer || master->transfer_one_message)
436		return -EINVAL;
437
438	master->prepare_transfer_hardware = spi_bitbang_prepare_hardware;
439	master->unprepare_transfer_hardware = spi_bitbang_unprepare_hardware;
440	master->transfer_one_message = spi_bitbang_transfer_one;
441
442	if (!bitbang->txrx_bufs) {
443		bitbang->use_dma = 0;
444		bitbang->txrx_bufs = spi_bitbang_bufs;
445		if (!master->setup) {
446			if (!bitbang->setup_transfer)
447				bitbang->setup_transfer =
448					 spi_bitbang_setup_transfer;
449			master->setup = spi_bitbang_setup;
450			master->cleanup = spi_bitbang_cleanup;
451		}
452	}
453
454	/* driver may get busy before register() returns, especially
455	 * if someone registered boardinfo for devices
456	 */
457	ret = spi_register_master(spi_master_get(master));
458	if (ret)
459		spi_master_put(master);
460
461	return 0;
462}
463EXPORT_SYMBOL_GPL(spi_bitbang_start);
464
465/**
466 * spi_bitbang_stop - stops the task providing spi communication
467 */
468void spi_bitbang_stop(struct spi_bitbang *bitbang)
469{
470	spi_unregister_master(bitbang->master);
471}
472EXPORT_SYMBOL_GPL(spi_bitbang_stop);
473
474MODULE_LICENSE("GPL");
475
476