[deliverable/linux.git] / drivers / staging / fwserial / dma_fifo.h

/*
 * DMA-able FIFO interface
 *
 * Copyright (C) 2012 Peter Hurley <peter@hurleysoftware.com>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef _DMA_FIFO_H_
#define _DMA_FIFO_H_

/**
 * The design basis for the DMA FIFO is to provide an output side that
 * complies with the streaming DMA API design that can be DMA'd from directly
 * (without additional copying), coupled with an input side that maintains a
 * logically consistent 'apparent' size (ie, bytes in + bytes avail is static
 * for the lifetime of the FIFO).
 *
 * DMA output transactions originate on a cache line boundary and can be
 * variably-sized. DMA output transactions can be retired out-of-order but
 * the FIFO will only advance the output in the original input sequence.
 * This means the FIFO will eventually stall if a transaction is never retired.
 *
 * Chunking the output side into cache line multiples means that some FIFO
 * memory is unused. For example, if all the avail input has been pended out,
 * then the in and out markers are re-aligned to the next cache line.
 * The maximum possible waste is
 *     (cache line alignment - 1) * (max outstanding dma transactions)
 * This potential waste requires additional hidden capacity within the FIFO
 * to be able to accept input while the 'apparent' size has not been reached.
 *
 * Additional cache lines (ie, guard area) are used to minimize DMA
 * fragmentation when wrapping at the end of the FIFO. Input is allowed into the
 * guard area, but the in and out FIFO markers are wrapped when DMA is pended.
 */

#define DMA_FIFO_GUARD 3   /* # of cache lines to reserve for the guard area */

struct dma_fifo {
	unsigned	 in;
	unsigned	 out;		/* updated when dma is pended         */
	unsigned	 done;		/* updated upon dma completion        */
	struct {
		unsigned corrupt:1;
	};
	int		 size;		/* 'apparent' size of fifo	      */
	int		 guard;		/* ofs of guard area		      */
	int		 capacity;	/* size + reserved                    */
	int		 avail;		/* # of unused bytes in fifo          */
	unsigned	 align;		/* must be power of 2                 */
	int		 tx_limit;	/* max # of bytes per dma transaction */
	int		 open_limit;	/* max # of outstanding allowed       */
	int		 open;		/* # of outstanding dma transactions  */
	struct list_head pending;	/* fifo markers for outstanding dma   */
	void		 *data;
};

struct dma_pending {
	struct list_head link;
	void		 *data;
	unsigned	 len;
	unsigned         next;
	unsigned         out;
};

static inline void dp_mark_completed(struct dma_pending *dp)
{
	dp->data += 1;
}

static inline bool dp_is_completed(struct dma_pending *dp)
{
	return (unsigned long)dp->data & 1UL;
}

extern void dma_fifo_init(struct dma_fifo *fifo);
extern int dma_fifo_alloc(struct dma_fifo *fifo, int size, unsigned align,
			  int tx_limit, int open_limit, gfp_t gfp_mask);
extern void dma_fifo_free(struct dma_fifo *fifo);
extern void dma_fifo_reset(struct dma_fifo *fifo);
extern int dma_fifo_in(struct dma_fifo *fifo, const void *src, int n);
extern int dma_fifo_out_pend(struct dma_fifo *fifo, struct dma_pending *pended);
extern int dma_fifo_out_complete(struct dma_fifo *fifo,
				 struct dma_pending *complete);

/* returns the # of used bytes in the fifo */
static inline int dma_fifo_level(struct dma_fifo *fifo)
{
	return fifo->size - fifo->avail;
}

/* returns the # of bytes ready for output in the fifo */
static inline int dma_fifo_out_level(struct dma_fifo *fifo)
{
	return fifo->in - fifo->out;
}

/* returns the # of unused bytes in the fifo */
static inline int dma_fifo_avail(struct dma_fifo *fifo)
{
	return fifo->avail;
}

/* returns true if fifo has max # of outstanding dmas */
static inline bool dma_fifo_busy(struct dma_fifo *fifo)
{
	return fifo->open == fifo->open_limit;
}

/* changes the max size of dma returned from dma_fifo_out_pend() */
static inline int dma_fifo_change_tx_limit(struct dma_fifo *fifo, int tx_limit)
{
	tx_limit = round_down(tx_limit, fifo->align);
	fifo->tx_limit = max_t(int, tx_limit, fifo->align);
	return 0;
}

#endif /* _DMA_FIFO_H_ */
Commit	Line	Data
e5711071 PH	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	* You should have received a copy of the GNU General Public License
	17	* along with this program; if not, write to the Free Software Foundation,
	18	* Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
	19	*/
	20
	21	#ifndef _DMA_FIFO_H_
	22	#define _DMA_FIFO_H_
	23
	24	/**
	25	* The design basis for the DMA FIFO is to provide an output side that
	26	* complies with the streaming DMA API design that can be DMA'd from directly
	27	* (without additional copying), coupled with an input side that maintains a
	28	* logically consistent 'apparent' size (ie, bytes in + bytes avail is static
	29	* for the lifetime of the FIFO).
	30	*
	31	* DMA output transactions originate on a cache line boundary and can be
	32	* variably-sized. DMA output transactions can be retired out-of-order but
	33	* the FIFO will only advance the output in the original input sequence.
	34	* This means the FIFO will eventually stall if a transaction is never retired.
	35	*
	36	* Chunking the output side into cache line multiples means that some FIFO
	37	* memory is unused. For example, if all the avail input has been pended out,
	38	* then the in and out markers are re-aligned to the next cache line.
	39	* The maximum possible waste is
	40	* (cache line alignment - 1) * (max outstanding dma transactions)
	41	* This potential waste requires additional hidden capacity within the FIFO
	42	* to be able to accept input while the 'apparent' size has not been reached.
	43	*
	44	* Additional cache lines (ie, guard area) are used to minimize DMA
	45	* fragmentation when wrapping at the end of the FIFO. Input is allowed into the
	46	* guard area, but the in and out FIFO markers are wrapped when DMA is pended.
	47	*/
	48
	49	#define DMA_FIFO_GUARD 3 /* # of cache lines to reserve for the guard area */
	50
	51	struct dma_fifo {
	52	unsigned in;
	53	unsigned out; /* updated when dma is pended */
	54	unsigned done; /* updated upon dma completion */
	55	struct {
	56	unsigned corrupt:1;
	57	};
	58	int size; /* 'apparent' size of fifo */
	59	int guard; /* ofs of guard area */
	60	int capacity; /* size + reserved */
	61	int avail; /* # of unused bytes in fifo */
	62	unsigned align; /* must be power of 2 */
	63	int tx_limit; /* max # of bytes per dma transaction */
	64	int open_limit; /* max # of outstanding allowed */
65	int open; /* # of outstanding dma transactions */
66	struct list_head pending; /* fifo markers for outstanding dma */
67	void *data;
68	};
69
70	struct dma_pending {
71	struct list_head link;
72	void *data;
73	unsigned len;
74	unsigned next;
75	unsigned out;
76	};
77
78	static inline void dp_mark_completed(struct dma_pending *dp)
79	{
80	dp->data += 1;
81	}
82
83	static inline bool dp_is_completed(struct dma_pending *dp)
84	{
85	return (unsigned long)dp->data & 1UL;
86	}
87
88	extern void dma_fifo_init(struct dma_fifo *fifo);
89	extern int dma_fifo_alloc(struct dma_fifo *fifo, int size, unsigned align,
90	int tx_limit, int open_limit, gfp_t gfp_mask);
91	extern void dma_fifo_free(struct dma_fifo *fifo);
92	extern void dma_fifo_reset(struct dma_fifo *fifo);
93	extern int dma_fifo_in(struct dma_fifo fifo, const void src, int n);
94	extern int dma_fifo_out_pend(struct dma_fifo fifo, struct dma_pending pended);
95	extern int dma_fifo_out_complete(struct dma_fifo *fifo,
96	struct dma_pending *complete);
97
98	/* returns the # of used bytes in the fifo */
99	static inline int dma_fifo_level(struct dma_fifo *fifo)
100	{
101	return fifo->size - fifo->avail;
102	}
103
104	/* returns the # of bytes ready for output in the fifo */
105	static inline int dma_fifo_out_level(struct dma_fifo *fifo)
106	{
107	return fifo->in - fifo->out;
108	}
109
110	/* returns the # of unused bytes in the fifo */
111	static inline int dma_fifo_avail(struct dma_fifo *fifo)
112	{
113	return fifo->avail;
114	}
115
116	/* returns true if fifo has max # of outstanding dmas */
117	static inline bool dma_fifo_busy(struct dma_fifo *fifo)
118	{
119	return fifo->open == fifo->open_limit;
120	}
121
122	/* changes the max size of dma returned from dma_fifo_out_pend() */
123	static inline int dma_fifo_change_tx_limit(struct dma_fifo *fifo, int tx_limit)
124	{
125	tx_limit = round_down(tx_limit, fifo->align);
126	fifo->tx_limit = max_t(int, tx_limit, fifo->align);
127	return 0;
128	}
129
130	#endif /* _DMA_FIFO_H_ */