[linux-block.git] / drivers / gpu / drm / omapdrm / tcm.h

/*
 * tcm.h
 *
 * TILER container manager specification and support functions for TI
 * TILER driver.
 *
 * Author: Lajos Molnar <molnar@ti.com>
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * * Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 *
 * * Neither the name of Texas Instruments Incorporated nor the names of
 *   its contributors may be used to endorse or promote products derived
 *   from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef TCM_H
#define TCM_H

struct tcm;

/* point */
struct tcm_pt {
	u16 x;
	u16 y;
};

/* 1d or 2d area */
struct tcm_area {
	bool is2d;		/* whether area is 1d or 2d */
	struct tcm    *tcm;	/* parent */
	struct tcm_pt  p0;
	struct tcm_pt  p1;
};

struct tcm {
	u16 width, height;	/* container dimensions */
	int lut_id;		/* Lookup table identifier */

	unsigned int y_offset;	/* offset to use for y coordinates */

	/* 'pvt' structure shall contain any tcm details (attr) along with
	linked list of allocated areas and mutex for mutually exclusive access
	to the list.  It may also contain copies of width and height to notice
	any changes to the publicly available width and height fields. */
	void *pvt;

	/* function table */
	s32 (*reserve_2d)(struct tcm *tcm, u16 height, u16 width, u8 align,
			  struct tcm_area *area);
	s32 (*reserve_1d)(struct tcm *tcm, u32 slots, struct tcm_area *area);
	s32 (*free)      (struct tcm *tcm, struct tcm_area *area);
	void (*deinit)   (struct tcm *tcm);
};

/*=============================================================================
    BASIC TILER CONTAINER MANAGER INTERFACE
=============================================================================*/

/*
 * NOTE:
 *
 * Since some basic parameter checking is done outside the TCM algorithms,
 * TCM implementation do NOT have to check the following:
 *
 *   area pointer is NULL
 *   width and height fits within container
 *   number of pages is more than the size of the container
 *
 */

struct tcm *sita_init(u16 width, u16 height, struct tcm_pt *attr);


/**
 * Deinitialize tiler container manager.
 *
 * @param tcm	Pointer to container manager.
 *
 * @return 0 on success, non-0 error value on error.  The call
 *	   should free as much memory as possible and meaningful
 *	   even on failure.  Some error codes: -ENODEV: invalid
 *	   manager.
 */
static inline void tcm_deinit(struct tcm *tcm)
{
	if (tcm)
		tcm->deinit(tcm);
}

/**
 * Reserves a 2D area in the container.
 *
 * @param tcm		Pointer to container manager.
 * @param height	Height(in pages) of area to be reserved.
 * @param width		Width(in pages) of area to be reserved.
 * @param align		Alignment requirement for top-left corner of area. Not
 *			all values may be supported by the container manager,
 *			but it must support 0 (1), 32 and 64.
 *			0 value is equivalent to 1.
 * @param area		Pointer to where the reserved area should be stored.
 *
 * @return 0 on success.  Non-0 error code on failure.  Also,
 *	   the tcm field of the area will be set to NULL on
 *	   failure.  Some error codes: -ENODEV: invalid manager,
 *	   -EINVAL: invalid area, -ENOMEM: not enough space for
 *	    allocation.
 */
static inline s32 tcm_reserve_2d(struct tcm *tcm, u16 width, u16 height,
				 u16 align, struct tcm_area *area)
{
	/* perform rudimentary error checking */
	s32 res = tcm  == NULL ? -ENODEV :
		(area == NULL || width == 0 || height == 0 ||
		 /* align must be a 2 power */
		 (align & (align - 1))) ? -EINVAL :
		(height > tcm->height || width > tcm->width) ? -ENOMEM : 0;

	if (!res) {
		area->is2d = true;
		res = tcm->reserve_2d(tcm, height, width, align, area);
		area->tcm = res ? NULL : tcm;
	}

	return res;
}

/**
 * Reserves a 1D area in the container.
 *
 * @param tcm		Pointer to container manager.
 * @param slots		Number of (contiguous) slots to reserve.
 * @param area		Pointer to where the reserved area should be stored.
 *
 * @return 0 on success.  Non-0 error code on failure.  Also,
 *	   the tcm field of the area will be set to NULL on
 *	   failure.  Some error codes: -ENODEV: invalid manager,
 *	   -EINVAL: invalid area, -ENOMEM: not enough space for
 *	    allocation.
 */
static inline s32 tcm_reserve_1d(struct tcm *tcm, u32 slots,
				 struct tcm_area *area)
{
	/* perform rudimentary error checking */
	s32 res = tcm  == NULL ? -ENODEV :
		(area == NULL || slots == 0) ? -EINVAL :
		slots > (tcm->width * (u32) tcm->height) ? -ENOMEM : 0;

	if (!res) {
		area->is2d = false;
		res = tcm->reserve_1d(tcm, slots, area);
		area->tcm = res ? NULL : tcm;
	}

	return res;
}

/**
 * Free a previously reserved area from the container.
 *
 * @param area	Pointer to area reserved by a prior call to
 *		tcm_reserve_1d or tcm_reserve_2d call, whether
 *		it was successful or not. (Note: all fields of
 *		the structure must match.)
 *
 * @return 0 on success.  Non-0 error code on failure.  Also, the tcm
 *	   field of the area is set to NULL on success to avoid subsequent
 *	   freeing.  This call will succeed even if supplying
 *	   the area from a failed reserved call.
 */
static inline s32 tcm_free(struct tcm_area *area)
{
	s32 res = 0; /* free succeeds by default */

	if (area && area->tcm) {
		res = area->tcm->free(area->tcm, area);
		if (res == 0)
			area->tcm = NULL;
	}

	return res;
}

/*=============================================================================
    HELPER FUNCTION FOR ANY TILER CONTAINER MANAGER
=============================================================================*/

/**
 * This method slices off the topmost 2D slice from the parent area, and stores
 * it in the 'slice' parameter.  The 'parent' parameter will get modified to
 * contain the remaining portion of the area.  If the whole parent area can
 * fit in a 2D slice, its tcm pointer is set to NULL to mark that it is no
 * longer a valid area.
 *
 * @param parent	Pointer to a VALID parent area that will get modified
 * @param slice		Pointer to the slice area that will get modified
 */
static inline void tcm_slice(struct tcm_area *parent, struct tcm_area *slice)
{
	*slice = *parent;

	/* check if we need to slice */
	if (slice->tcm && !slice->is2d &&
		slice->p0.y != slice->p1.y &&
		(slice->p0.x || (slice->p1.x != slice->tcm->width - 1))) {
		/* set end point of slice (start always remains) */
		slice->p1.x = slice->tcm->width - 1;
		slice->p1.y = (slice->p0.x) ? slice->p0.y : slice->p1.y - 1;
		/* adjust remaining area */
		parent->p0.x = 0;
		parent->p0.y = slice->p1.y + 1;
	} else {
		/* mark this as the last slice */
		parent->tcm = NULL;
	}
}

/* Verify if a tcm area is logically valid */
static inline bool tcm_area_is_valid(struct tcm_area *area)
{
	return area && area->tcm &&
		/* coordinate bounds */
		area->p1.x < area->tcm->width &&
		area->p1.y < area->tcm->height &&
		area->p0.y <= area->p1.y &&
		/* 1D coordinate relationship + p0.x check */
		((!area->is2d &&
		  area->p0.x < area->tcm->width &&
		  area->p0.x + area->p0.y * area->tcm->width <=
		  area->p1.x + area->p1.y * area->tcm->width) ||
		 /* 2D coordinate relationship */
		 (area->is2d &&
		  area->p0.x <= area->p1.x));
}

/* see if a coordinate is within an area */
static inline bool __tcm_is_in(struct tcm_pt *p, struct tcm_area *a)
{
	u16 i;

	if (a->is2d) {
		return p->x >= a->p0.x && p->x <= a->p1.x &&
		       p->y >= a->p0.y && p->y <= a->p1.y;
	} else {
		i = p->x + p->y * a->tcm->width;
		return i >= a->p0.x + a->p0.y * a->tcm->width &&
		       i <= a->p1.x + a->p1.y * a->tcm->width;
	}
}

/* calculate area width */
static inline u16 __tcm_area_width(struct tcm_area *area)
{
	return area->p1.x - area->p0.x + 1;
}

/* calculate area height */
static inline u16 __tcm_area_height(struct tcm_area *area)
{
	return area->p1.y - area->p0.y + 1;
}

/* calculate number of slots in an area */
static inline u16 __tcm_sizeof(struct tcm_area *area)
{
	return area->is2d ?
		__tcm_area_width(area) * __tcm_area_height(area) :
		(area->p1.x - area->p0.x + 1) + (area->p1.y - area->p0.y) *
							area->tcm->width;
}
#define tcm_sizeof(area) __tcm_sizeof(&(area))
#define tcm_awidth(area) __tcm_area_width(&(area))
#define tcm_aheight(area) __tcm_area_height(&(area))
#define tcm_is_in(pt, area) __tcm_is_in(&(pt), &(area))

/* limit a 1D area to the first N pages */
static inline s32 tcm_1d_limit(struct tcm_area *a, u32 num_pg)
{
	if (__tcm_sizeof(a) < num_pg)
		return -ENOMEM;
	if (!num_pg)
		return -EINVAL;

	a->p1.x = (a->p0.x + num_pg - 1) % a->tcm->width;
	a->p1.y = a->p0.y + ((a->p0.x + num_pg - 1) / a->tcm->width);
	return 0;
}

/**
 * Iterate through 2D slices of a valid area. Behaves
 * syntactically as a for(;;) statement.
 *
 * @param var		Name of a local variable of type 'struct
 *			tcm_area *' that will get modified to
 *			contain each slice.
 * @param area		Pointer to the VALID parent area. This
 *			structure will not get modified
 *			throughout the loop.
 *
 */
#define tcm_for_each_slice(var, area, safe) \
	for (safe = area, \
	     tcm_slice(&safe, &var); \
	     var.tcm; tcm_slice(&safe, &var))

#endif
Commit	Line	Data
71e8831f AG	1	/*
	2	* tcm.h
	3	*
	4	* TILER container manager specification and support functions for TI
	5	* TILER driver.
	6	*
	7	* Author: Lajos Molnar <molnar@ti.com>
	8	*
	9	* All rights reserved.
	10	*
	11	* Redistribution and use in source and binary forms, with or without
	12	* modification, are permitted provided that the following conditions
	13	* are met:
	14	*
	15	* * Redistributions of source code must retain the above copyright
	16	* notice, this list of conditions and the following disclaimer.
	17	*
	18	* * Redistributions in binary form must reproduce the above copyright
	19	* notice, this list of conditions and the following disclaimer in the
	20	* documentation and/or other materials provided with the distribution.
	21	*
	22	* * Neither the name of Texas Instruments Incorporated nor the names of
	23	* its contributors may be used to endorse or promote products derived
	24	* from this software without specific prior written permission.
	25	*
	26	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
	27	* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
	28	* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
	29	* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
	30	* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
	31	* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
	32	* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
	33	* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
	34	* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
	35	* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
	36	* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	37	*/
	38
	39	#ifndef TCM_H
	40	#define TCM_H
	41
	42	struct tcm;
	43
	44	/* point */
	45	struct tcm_pt {
	46	u16 x;
	47	u16 y;
	48	};
	49
	50	/* 1d or 2d area */
	51	struct tcm_area {
	52	bool is2d; /* whether area is 1d or 2d */
	53	struct tcm tcm; / parent */
	54	struct tcm_pt p0;
	55	struct tcm_pt p1;
	56	};
	57
	58	struct tcm {
	59	u16 width, height; /* container dimensions */
	60	int lut_id; /* Lookup table identifier */
	61
238083ad AG	62	unsigned int y_offset; /* offset to use for y coordinates */
238083ad AG	63
71e8831f AG	64	/* 'pvt' structure shall contain any tcm details (attr) along with
	65	linked list of allocated areas and mutex for mutually exclusive access
	66	to the list. It may also contain copies of width and height to notice
	67	any changes to the publicly available width and height fields. */
	68	void *pvt;
	69
	70	/* function table */
	71	s32 (reserve_2d)(struct tcm tcm, u16 height, u16 width, u8 align,
	72	struct tcm_area *area);
	73	s32 (reserve_1d)(struct tcm tcm, u32 slots, struct tcm_area *area);
	74	s32 (free) (struct tcm tcm, struct tcm_area *area);
	75	void (deinit) (struct tcm tcm);
	76	};
	77
	78	/*=============================================================================
	79	BASIC TILER CONTAINER MANAGER INTERFACE
	80	=============================================================================*/
	81
	82	/*
	83	* NOTE:
	84	*
	85	* Since some basic parameter checking is done outside the TCM algorithms,
	86	* TCM implementation do NOT have to check the following:
	87	*
	88	* area pointer is NULL
	89	* width and height fits within container
	90	* number of pages is more than the size of the container
	91	*
	92	*/
	93
	94	struct tcm sita_init(u16 width, u16 height, struct tcm_pt attr);
	95
	96
	97	/**
	98	* Deinitialize tiler container manager.
	99	*
	100	* @param tcm Pointer to container manager.
	101	*
	102	* @return 0 on success, non-0 error value on error. The call
	103	* should free as much memory as possible and meaningful
	104	* even on failure. Some error codes: -ENODEV: invalid
	105	* manager.
	106	*/
	107	static inline void tcm_deinit(struct tcm *tcm)
	108	{
	109	if (tcm)
	110	tcm->deinit(tcm);
	111	}
	112
	113	/**
	114	* Reserves a 2D area in the container.
	115	*
	116	* @param tcm Pointer to container manager.
	117	* @param height Height(in pages) of area to be reserved.
	118	* @param width Width(in pages) of area to be reserved.
	119	* @param align Alignment requirement for top-left corner of area. Not
	120	* all values may be supported by the container manager,
	121	* but it must support 0 (1), 32 and 64.
	122	* 0 value is equivalent to 1.
	123	* @param area Pointer to where the reserved area should be stored.
	124	*
	125	* @return 0 on success. Non-0 error code on failure. Also,
	126	* the tcm field of the area will be set to NULL on
	127	* failure. Some error codes: -ENODEV: invalid manager,
128	* -EINVAL: invalid area, -ENOMEM: not enough space for
129	* allocation.
130	*/
131	static inline s32 tcm_reserve_2d(struct tcm *tcm, u16 width, u16 height,
132	u16 align, struct tcm_area *area)
133	{
134	/* perform rudimentary error checking */
135	s32 res = tcm == NULL ? -ENODEV :
136	(area == NULL \|\| width == 0 \|\| height == 0 \|\|
137	/* align must be a 2 power */
138	(align & (align - 1))) ? -EINVAL :
139	(height > tcm->height \|\| width > tcm->width) ? -ENOMEM : 0;
140
141	if (!res) {
142	area->is2d = true;
143	res = tcm->reserve_2d(tcm, height, width, align, area);
144	area->tcm = res ? NULL : tcm;
145	}
146
147	return res;
148	}
149
150	/**
151	* Reserves a 1D area in the container.
152	*
153	* @param tcm Pointer to container manager.
154	* @param slots Number of (contiguous) slots to reserve.
155	* @param area Pointer to where the reserved area should be stored.
156	*
157	* @return 0 on success. Non-0 error code on failure. Also,
158	* the tcm field of the area will be set to NULL on
159	* failure. Some error codes: -ENODEV: invalid manager,
160	* -EINVAL: invalid area, -ENOMEM: not enough space for
161	* allocation.
162	*/
163	static inline s32 tcm_reserve_1d(struct tcm *tcm, u32 slots,
164	struct tcm_area *area)
165	{
166	/* perform rudimentary error checking */
167	s32 res = tcm == NULL ? -ENODEV :
168	(area == NULL \|\| slots == 0) ? -EINVAL :
169	slots > (tcm->width * (u32) tcm->height) ? -ENOMEM : 0;
170
171	if (!res) {
172	area->is2d = false;
173	res = tcm->reserve_1d(tcm, slots, area);
174	area->tcm = res ? NULL : tcm;
175	}
176
177	return res;
178	}
179
180	/**
181	* Free a previously reserved area from the container.
182	*
183	* @param area Pointer to area reserved by a prior call to
184	* tcm_reserve_1d or tcm_reserve_2d call, whether
185	* it was successful or not. (Note: all fields of
186	* the structure must match.)
187	*
188	* @return 0 on success. Non-0 error code on failure. Also, the tcm
189	* field of the area is set to NULL on success to avoid subsequent
190	* freeing. This call will succeed even if supplying
191	* the area from a failed reserved call.
192	*/
193	static inline s32 tcm_free(struct tcm_area *area)
194	{
195	s32 res = 0; /* free succeeds by default */
196
197	if (area && area->tcm) {
198	res = area->tcm->free(area->tcm, area);
199	if (res == 0)
200	area->tcm = NULL;
201	}
202
203	return res;
204	}
205
206	/*=============================================================================
207	HELPER FUNCTION FOR ANY TILER CONTAINER MANAGER
208	=============================================================================*/
209
210	/**
211	* This method slices off the topmost 2D slice from the parent area, and stores
212	* it in the 'slice' parameter. The 'parent' parameter will get modified to
213	* contain the remaining portion of the area. If the whole parent area can
214	* fit in a 2D slice, its tcm pointer is set to NULL to mark that it is no
215	* longer a valid area.
216	*
217	* @param parent Pointer to a VALID parent area that will get modified
218	* @param slice Pointer to the slice area that will get modified
219	*/
220	static inline void tcm_slice(struct tcm_area parent, struct tcm_area slice)
221	{
222	slice = parent;
223
224	/* check if we need to slice */
225	if (slice->tcm && !slice->is2d &&
226	slice->p0.y != slice->p1.y &&
227	(slice->p0.x \|\| (slice->p1.x != slice->tcm->width - 1))) {
228	/* set end point of slice (start always remains) */
229	slice->p1.x = slice->tcm->width - 1;
230	slice->p1.y = (slice->p0.x) ? slice->p0.y : slice->p1.y - 1;
231	/* adjust remaining area */
232	parent->p0.x = 0;
233	parent->p0.y = slice->p1.y + 1;
234	} else {
235	/* mark this as the last slice */
236	parent->tcm = NULL;
237	}
238	}
239
240	/* Verify if a tcm area is logically valid */
241	static inline bool tcm_area_is_valid(struct tcm_area *area)
242	{
243	return area && area->tcm &&
244	/* coordinate bounds */
245	area->p1.x < area->tcm->width &&
246	area->p1.y < area->tcm->height &&
247	area->p0.y <= area->p1.y &&
248	/* 1D coordinate relationship + p0.x check */
249	((!area->is2d &&
250	area->p0.x < area->tcm->width &&
251	area->p0.x + area->p0.y * area->tcm->width <=
252	area->p1.x + area->p1.y * area->tcm->width) \|\|
253	/* 2D coordinate relationship */
254	(area->is2d &&
255	area->p0.x <= area->p1.x));
256	}
257
258	/* see if a coordinate is within an area */
259	static inline bool __tcm_is_in(struct tcm_pt p, struct tcm_area a)
260	{
261	u16 i;
262
263	if (a->is2d) {
264	return p->x >= a->p0.x && p->x <= a->p1.x &&
265	p->y >= a->p0.y && p->y <= a->p1.y;
266	} else {
267	i = p->x + p->y * a->tcm->width;
268	return i >= a->p0.x + a->p0.y * a->tcm->width &&
269	i <= a->p1.x + a->p1.y * a->tcm->width;
270	}
271	}
272
273	/* calculate area width */
274	static inline u16 __tcm_area_width(struct tcm_area *area)
275	{
276	return area->p1.x - area->p0.x + 1;
277	}
278
279	/* calculate area height */
280	static inline u16 __tcm_area_height(struct tcm_area *area)
281	{
282	return area->p1.y - area->p0.y + 1;
283	}
284
285	/* calculate number of slots in an area */
286	static inline u16 __tcm_sizeof(struct tcm_area *area)
287	{
288	return area->is2d ?
289	__tcm_area_width(area) * __tcm_area_height(area) :
290	(area->p1.x - area->p0.x + 1) + (area->p1.y - area->p0.y) *
291	area->tcm->width;
292	}
293	#define tcm_sizeof(area) __tcm_sizeof(&(area))
294	#define tcm_awidth(area) __tcm_area_width(&(area))
295	#define tcm_aheight(area) __tcm_area_height(&(area))
296	#define tcm_is_in(pt, area) __tcm_is_in(&(pt), &(area))
297
298	/* limit a 1D area to the first N pages */
299	static inline s32 tcm_1d_limit(struct tcm_area *a, u32 num_pg)
300	{
301	if (__tcm_sizeof(a) < num_pg)
302	return -ENOMEM;
303	if (!num_pg)
304	return -EINVAL;
305
306	a->p1.x = (a->p0.x + num_pg - 1) % a->tcm->width;
307	a->p1.y = a->p0.y + ((a->p0.x + num_pg - 1) / a->tcm->width);
308	return 0;
309	}
310
311	/**
312	* Iterate through 2D slices of a valid area. Behaves
313	* syntactically as a for(;;) statement.
314	*
315	* @param var Name of a local variable of type 'struct
316	* tcm_area *' that will get modified to
317	* contain each slice.
318	* @param area Pointer to the VALID parent area. This
319	* structure will not get modified
320	* throughout the loop.
321	*
322	*/
323	#define tcm_for_each_slice(var, area, safe) \
324	for (safe = area, \
325	tcm_slice(&safe, &var); \
326	var.tcm; tcm_slice(&safe, &var))
327
328	#endif