drivers/staging/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         /* '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