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 | ||
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 | */ | |
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 | */ | |
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 | */ | |
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 | */ | |
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 | */ | |
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 */ | |
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 */ | |
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 */ | |
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 */ | |
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 */ | |
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 */ | |
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 |