1 /*
2 * DMA-able FIFO interface
3 *
4 * Copyright (C) 2012 Peter Hurley <peter@hurleysoftware.com>
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 */
16
17 #ifndef _DMA_FIFO_H_
18 #define _DMA_FIFO_H_
19
20 /**
21 * The design basis for the DMA FIFO is to provide an output side that
22 * complies with the streaming DMA API design that can be DMA'd from directly
23 * (without additional copying), coupled with an input side that maintains a
24 * logically consistent 'apparent' size (ie, bytes in + bytes avail is static
25 * for the lifetime of the FIFO).
26 *
27 * DMA output transactions originate on a cache line boundary and can be
28 * variably-sized. DMA output transactions can be retired out-of-order but
29 * the FIFO will only advance the output in the original input sequence.
30 * This means the FIFO will eventually stall if a transaction is never retired.
31 *
32 * Chunking the output side into cache line multiples means that some FIFO
33 * memory is unused. For example, if all the avail input has been pended out,
34 * then the in and out markers are re-aligned to the next cache line.
35 * The maximum possible waste is
36 * (cache line alignment - 1) * (max outstanding dma transactions)
37 * This potential waste requires additional hidden capacity within the FIFO
38 * to be able to accept input while the 'apparent' size has not been reached.
39 *
40 * Additional cache lines (ie, guard area) are used to minimize DMA
41 * fragmentation when wrapping at the end of the FIFO. Input is allowed into the
42 * guard area, but the in and out FIFO markers are wrapped when DMA is pended.
43 */
44
45 #define DMA_FIFO_GUARD 3 /* # of cache lines to reserve for the guard area */
46
47 struct dma_fifo {
48 unsigned int in;
49 unsigned int out; /* updated when dma is pended */
50 unsigned int done; /* updated upon dma completion */
51 struct {
52 unsigned corrupt:1;
53 };
54 int size; /* 'apparent' size of fifo */
55 int guard; /* ofs of guard area */
56 int capacity; /* size + reserved */
57 int avail; /* # of unused bytes in fifo */
58 unsigned int align; /* must be power of 2 */
59 int tx_limit; /* max # of bytes per dma transaction */
60 int open_limit; /* max # of outstanding allowed */
61 int open; /* # of outstanding dma transactions */
62 struct list_head pending; /* fifo markers for outstanding dma */
63 void *data;
64 };
65
66 struct dma_pending {
67 struct list_head link;
68 void *data;
69 unsigned int len;
70 unsigned int next;
71 unsigned int out;
72 };
73
dp_mark_completed(struct dma_pending * dp)74 static inline void dp_mark_completed(struct dma_pending *dp)
75 {
76 dp->data += 1;
77 }
78
dp_is_completed(struct dma_pending * dp)79 static inline bool dp_is_completed(struct dma_pending *dp)
80 {
81 return (unsigned long)dp->data & 1UL;
82 }
83
84 void dma_fifo_init(struct dma_fifo *fifo);
85 int dma_fifo_alloc(struct dma_fifo *fifo, int size, unsigned int align,
86 int tx_limit, int open_limit, gfp_t gfp_mask);
87 void dma_fifo_free(struct dma_fifo *fifo);
88 void dma_fifo_reset(struct dma_fifo *fifo);
89 int dma_fifo_in(struct dma_fifo *fifo, const void *src, int n);
90 int dma_fifo_out_pend(struct dma_fifo *fifo, struct dma_pending *pended);
91 int dma_fifo_out_complete(struct dma_fifo *fifo,
92 struct dma_pending *complete);
93
94 /* returns the # of used bytes in the fifo */
dma_fifo_level(struct dma_fifo * fifo)95 static inline int dma_fifo_level(struct dma_fifo *fifo)
96 {
97 return fifo->size - fifo->avail;
98 }
99
100 /* returns the # of bytes ready for output in the fifo */
dma_fifo_out_level(struct dma_fifo * fifo)101 static inline int dma_fifo_out_level(struct dma_fifo *fifo)
102 {
103 return fifo->in - fifo->out;
104 }
105
106 /* returns the # of unused bytes in the fifo */
dma_fifo_avail(struct dma_fifo * fifo)107 static inline int dma_fifo_avail(struct dma_fifo *fifo)
108 {
109 return fifo->avail;
110 }
111
112 /* returns true if fifo has max # of outstanding dmas */
dma_fifo_busy(struct dma_fifo * fifo)113 static inline bool dma_fifo_busy(struct dma_fifo *fifo)
114 {
115 return fifo->open == fifo->open_limit;
116 }
117
118 /* changes the max size of dma returned from dma_fifo_out_pend() */
dma_fifo_change_tx_limit(struct dma_fifo * fifo,int tx_limit)119 static inline int dma_fifo_change_tx_limit(struct dma_fifo *fifo, int tx_limit)
120 {
121 tx_limit = round_down(tx_limit, fifo->align);
122 fifo->tx_limit = max_t(int, tx_limit, fifo->align);
123 return 0;
124 }
125
126 #endif /* _DMA_FIFO_H_ */
127