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