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
62 /* 'pvt' structure shall contain any tcm details (attr) along with
63 linked list of allocated areas and mutex for mutually exclusive access
64 to the list. It may also contain copies of width and height to notice
65 any changes to the publicly available width and height fields. */
66 void *pvt;
67
68 /* function table */
69 s32 (*reserve_2d)(struct tcm *tcm, u16 height, u16 width, u8 align,
70 struct tcm_area *area);
71 s32 (*reserve_1d)(struct tcm *tcm, u32 slots, struct tcm_area *area);
72 s32 (*free) (struct tcm *tcm, struct tcm_area *area);
73 void (*deinit) (struct tcm *tcm);
74 };
75
76 /*=============================================================================
77 BASIC TILER CONTAINER MANAGER INTERFACE
78 =============================================================================*/
79
80 /*
81 * NOTE:
82 *
83 * Since some basic parameter checking is done outside the TCM algorithms,
84 * TCM implementation do NOT have to check the following:
85 *
86 * area pointer is NULL
87 * width and height fits within container
88 * number of pages is more than the size of the container
89 *
90 */
91
92 struct tcm *sita_init(u16 width, u16 height, struct tcm_pt *attr);
93
94
95 /**
96 * Deinitialize tiler container manager.
97 *
98 * @param tcm Pointer to container manager.
99 *
100 * @return 0 on success, non-0 error value on error. The call
101 * should free as much memory as possible and meaningful
102 * even on failure. Some error codes: -ENODEV: invalid
103 * manager.
104 */
tcm_deinit(struct tcm * tcm)105 static inline void tcm_deinit(struct tcm *tcm)
106 {
107 if (tcm)
108 tcm->deinit(tcm);
109 }
110
111 /**
112 * Reserves a 2D area in the container.
113 *
114 * @param tcm Pointer to container manager.
115 * @param height Height(in pages) of area to be reserved.
116 * @param width Width(in pages) of area to be reserved.
117 * @param align Alignment requirement for top-left corner of area. Not
118 * all values may be supported by the container manager,
119 * but it must support 0 (1), 32 and 64.
120 * 0 value is equivalent to 1.
121 * @param area Pointer to where the reserved area should be stored.
122 *
123 * @return 0 on success. Non-0 error code on failure. Also,
124 * the tcm field of the area will be set to NULL on
125 * failure. Some error codes: -ENODEV: invalid manager,
126 * -EINVAL: invalid area, -ENOMEM: not enough space for
127 * allocation.
128 */
tcm_reserve_2d(struct tcm * tcm,u16 width,u16 height,u16 align,struct tcm_area * area)129 static inline s32 tcm_reserve_2d(struct tcm *tcm, u16 width, u16 height,
130 u16 align, struct tcm_area *area)
131 {
132 /* perform rudimentary error checking */
133 s32 res = tcm == NULL ? -ENODEV :
134 (area == NULL || width == 0 || height == 0 ||
135 /* align must be a 2 power */
136 (align & (align - 1))) ? -EINVAL :
137 (height > tcm->height || width > tcm->width) ? -ENOMEM : 0;
138
139 if (!res) {
140 area->is2d = true;
141 res = tcm->reserve_2d(tcm, height, width, align, area);
142 area->tcm = res ? NULL : tcm;
143 }
144
145 return res;
146 }
147
148 /**
149 * Reserves a 1D area in the container.
150 *
151 * @param tcm Pointer to container manager.
152 * @param slots Number of (contiguous) slots to reserve.
153 * @param area Pointer to where the reserved area should be stored.
154 *
155 * @return 0 on success. Non-0 error code on failure. Also,
156 * the tcm field of the area will be set to NULL on
157 * failure. Some error codes: -ENODEV: invalid manager,
158 * -EINVAL: invalid area, -ENOMEM: not enough space for
159 * allocation.
160 */
tcm_reserve_1d(struct tcm * tcm,u32 slots,struct tcm_area * area)161 static inline s32 tcm_reserve_1d(struct tcm *tcm, u32 slots,
162 struct tcm_area *area)
163 {
164 /* perform rudimentary error checking */
165 s32 res = tcm == NULL ? -ENODEV :
166 (area == NULL || slots == 0) ? -EINVAL :
167 slots > (tcm->width * (u32) tcm->height) ? -ENOMEM : 0;
168
169 if (!res) {
170 area->is2d = false;
171 res = tcm->reserve_1d(tcm, slots, area);
172 area->tcm = res ? NULL : tcm;
173 }
174
175 return res;
176 }
177
178 /**
179 * Free a previously reserved area from the container.
180 *
181 * @param area Pointer to area reserved by a prior call to
182 * tcm_reserve_1d or tcm_reserve_2d call, whether
183 * it was successful or not. (Note: all fields of
184 * the structure must match.)
185 *
186 * @return 0 on success. Non-0 error code on failure. Also, the tcm
187 * field of the area is set to NULL on success to avoid subsequent
188 * freeing. This call will succeed even if supplying
189 * the area from a failed reserved call.
190 */
tcm_free(struct tcm_area * area)191 static inline s32 tcm_free(struct tcm_area *area)
192 {
193 s32 res = 0; /* free succeeds by default */
194
195 if (area && area->tcm) {
196 res = area->tcm->free(area->tcm, area);
197 if (res == 0)
198 area->tcm = NULL;
199 }
200
201 return res;
202 }
203
204 /*=============================================================================
205 HELPER FUNCTION FOR ANY TILER CONTAINER MANAGER
206 =============================================================================*/
207
208 /**
209 * This method slices off the topmost 2D slice from the parent area, and stores
210 * it in the 'slice' parameter. The 'parent' parameter will get modified to
211 * contain the remaining portion of the area. If the whole parent area can
212 * fit in a 2D slice, its tcm pointer is set to NULL to mark that it is no
213 * longer a valid area.
214 *
215 * @param parent Pointer to a VALID parent area that will get modified
216 * @param slice Pointer to the slice area that will get modified
217 */
tcm_slice(struct tcm_area * parent,struct tcm_area * slice)218 static inline void tcm_slice(struct tcm_area *parent, struct tcm_area *slice)
219 {
220 *slice = *parent;
221
222 /* check if we need to slice */
223 if (slice->tcm && !slice->is2d &&
224 slice->p0.y != slice->p1.y &&
225 (slice->p0.x || (slice->p1.x != slice->tcm->width - 1))) {
226 /* set end point of slice (start always remains) */
227 slice->p1.x = slice->tcm->width - 1;
228 slice->p1.y = (slice->p0.x) ? slice->p0.y : slice->p1.y - 1;
229 /* adjust remaining area */
230 parent->p0.x = 0;
231 parent->p0.y = slice->p1.y + 1;
232 } else {
233 /* mark this as the last slice */
234 parent->tcm = NULL;
235 }
236 }
237
238 /* Verify if a tcm area is logically valid */
tcm_area_is_valid(struct tcm_area * area)239 static inline bool tcm_area_is_valid(struct tcm_area *area)
240 {
241 return area && area->tcm &&
242 /* coordinate bounds */
243 area->p1.x < area->tcm->width &&
244 area->p1.y < area->tcm->height &&
245 area->p0.y <= area->p1.y &&
246 /* 1D coordinate relationship + p0.x check */
247 ((!area->is2d &&
248 area->p0.x < area->tcm->width &&
249 area->p0.x + area->p0.y * area->tcm->width <=
250 area->p1.x + area->p1.y * area->tcm->width) ||
251 /* 2D coordinate relationship */
252 (area->is2d &&
253 area->p0.x <= area->p1.x));
254 }
255
256 /* see if a coordinate is within an area */
__tcm_is_in(struct tcm_pt * p,struct tcm_area * a)257 static inline bool __tcm_is_in(struct tcm_pt *p, struct tcm_area *a)
258 {
259 u16 i;
260
261 if (a->is2d) {
262 return p->x >= a->p0.x && p->x <= a->p1.x &&
263 p->y >= a->p0.y && p->y <= a->p1.y;
264 } else {
265 i = p->x + p->y * a->tcm->width;
266 return i >= a->p0.x + a->p0.y * a->tcm->width &&
267 i <= a->p1.x + a->p1.y * a->tcm->width;
268 }
269 }
270
271 /* calculate area width */
__tcm_area_width(struct tcm_area * area)272 static inline u16 __tcm_area_width(struct tcm_area *area)
273 {
274 return area->p1.x - area->p0.x + 1;
275 }
276
277 /* calculate area height */
__tcm_area_height(struct tcm_area * area)278 static inline u16 __tcm_area_height(struct tcm_area *area)
279 {
280 return area->p1.y - area->p0.y + 1;
281 }
282
283 /* calculate number of slots in an area */
__tcm_sizeof(struct tcm_area * area)284 static inline u16 __tcm_sizeof(struct tcm_area *area)
285 {
286 return area->is2d ?
287 __tcm_area_width(area) * __tcm_area_height(area) :
288 (area->p1.x - area->p0.x + 1) + (area->p1.y - area->p0.y) *
289 area->tcm->width;
290 }
291 #define tcm_sizeof(area) __tcm_sizeof(&(area))
292 #define tcm_awidth(area) __tcm_area_width(&(area))
293 #define tcm_aheight(area) __tcm_area_height(&(area))
294 #define tcm_is_in(pt, area) __tcm_is_in(&(pt), &(area))
295
296 /* limit a 1D area to the first N pages */
tcm_1d_limit(struct tcm_area * a,u32 num_pg)297 static inline s32 tcm_1d_limit(struct tcm_area *a, u32 num_pg)
298 {
299 if (__tcm_sizeof(a) < num_pg)
300 return -ENOMEM;
301 if (!num_pg)
302 return -EINVAL;
303
304 a->p1.x = (a->p0.x + num_pg - 1) % a->tcm->width;
305 a->p1.y = a->p0.y + ((a->p0.x + num_pg - 1) / a->tcm->width);
306 return 0;
307 }
308
309 /**
310 * Iterate through 2D slices of a valid area. Behaves
311 * syntactically as a for(;;) statement.
312 *
313 * @param var Name of a local variable of type 'struct
314 * tcm_area *' that will get modified to
315 * contain each slice.
316 * @param area Pointer to the VALID parent area. This
317 * structure will not get modified
318 * throughout the loop.
319 *
320 */
321 #define tcm_for_each_slice(var, area, safe) \
322 for (safe = area, \
323 tcm_slice(&safe, &var); \
324 var.tcm; tcm_slice(&safe, &var))
325
326 #endif
327