drivers/gpu/drm/omapdrm/tcm.h

   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         unsigned int y_offset;  /* offset to use for y coordinates */
  63
  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