src/mesa/drivers/dri/common/dri_util.h

   1 /* $XFree86: xc/lib/GL/dri/dri_util.h,v 1.1 2002/02/22 21:32:52 dawes Exp $ */
   2 /**
   3  * \file dri_util.h
   4  * DRI utility functions definitions.
   5  *
   6  * This module acts as glue between GLX and the actual hardware driver.  A DRI
   7  * driver doesn't really \e have to use any of this - it's optional.  But, some
   8  * useful stuff is done here that otherwise would have to be duplicated in most
   9  * drivers.
  10  *
  11  * Basically, these utility functions take care of some of the dirty details of
  12  * screen initialization, context creation, context binding, DRM setup, etc.
  13  *
  14  * These functions are compiled into each DRI driver so libGL.so knows nothing
  15  * about them.
  16  *
  17  * \sa dri_util.c.
  18  *
  19  * \author Kevin E. Martin <kevin@precisioninsight.com>
  20  * \author Brian Paul <brian@precisioninsight.com>
  21  */
  22
  23 /*
  24  * Copyright 1998-1999 Precision Insight, Inc., Cedar Park, Texas.
  25  * All Rights Reserved.
  26  *
  27  * Permission is hereby granted, free of charge, to any person obtaining a
  28  * copy of this software and associated documentation files (the
  29  * "Software"), to deal in the Software without restriction, including
  30  * without limitation the rights to use, copy, modify, merge, publish,
  31  * distribute, sub license, and/or sell copies of the Software, and to
  32  * permit persons to whom the Software is furnished to do so, subject to
  33  * the following conditions:
  34  *
  35  * The above copyright notice and this permission notice (including the
  36  * next paragraph) shall be included in all copies or substantial portions
  37  * of the Software.
  38  *
  39  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  40  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  41  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  42  * IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
  43  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  44  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  45  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  46  */
  47
  48
  49 #ifndef _DRI_UTIL_H_
  50 #define _DRI_UTIL_H_
  51
  52 #include <GL/gl.h>
  53 #include <drm.h>
  54 #include <drm_sarea.h>
  55 #include <xf86drm.h>
  56 #include <xf86mm.h>
  57 #include "GL/internal/glcore.h"
  58 #include "GL/internal/dri_interface.h"
  59 #include "GL/internal/dri_sarea.h"
  60
  61 #define GLX_BAD_CONTEXT                    5
  62
  63 typedef struct __DRIswapInfoRec        __DRIswapInfo;
  64 typedef struct __DRIutilversionRec2    __DRIutilversion2;
  65
  66 /* Typedefs to avoid rewriting the world. */
  67 typedef struct __DRIscreenRec   __DRIscreenPrivate;
  68 typedef struct __DRIdrawableRec __DRIdrawablePrivate;
  69 typedef struct __DRIcontextRec  __DRIcontextPrivate;
  70
  71 /**
  72  * Extensions.
  73  */
  74 extern const __DRIlegacyExtension driLegacyExtension;
  75 extern const __DRIcoreExtension driCoreExtension;
  76 extern const __DRIextension driReadDrawableExtension;
  77 extern const __DRIcopySubBufferExtension driCopySubBufferExtension;
  78 extern const __DRIswapControlExtension driSwapControlExtension;
  79 extern const __DRIframeTrackingExtension driFrameTrackingExtension;
  80 extern const __DRImediaStreamCounterExtension driMediaStreamCounterExtension;
  81
  82 /**
  83  * Used by DRI_VALIDATE_DRAWABLE_INFO
  84  */
  85 #define DRI_VALIDATE_DRAWABLE_INFO_ONCE(pDrawPriv)              \
  86     do {                                                        \
  87         if (*(pDrawPriv->pStamp) != pDrawPriv->lastStamp) {     \
  88             __driUtilUpdateDrawableInfo(pDrawPriv);             \
  89         }                                                       \
  90     } while (0)
  91
  92
  93 /**
  94  * Utility macro to validate the drawable information.
  95  *
  96  * See __DRIdrawable::pStamp and __DRIdrawable::lastStamp.
  97  */
  98 #define DRI_VALIDATE_DRAWABLE_INFO(psp, pdp)                            \
  99 do {                                                                    \
 100     while (*(pdp->pStamp) != pdp->lastStamp) {                          \
 101         register unsigned int hwContext = psp->pSAREA->lock.lock &      \
 102                      ~(DRM_LOCK_HELD | DRM_LOCK_CONT);                  \
 103         DRM_UNLOCK(psp->fd, &psp->pSAREA->lock, hwContext);             \
 104                                                                         \
 105         DRM_SPINLOCK(&psp->pSAREA->drawable_lock, psp->drawLockID);     \
 106         DRI_VALIDATE_DRAWABLE_INFO_ONCE(pdp);                           \
 107         DRM_SPINUNLOCK(&psp->pSAREA->drawable_lock, psp->drawLockID);   \
 108                                                                         \
 109         DRM_LIGHT_LOCK(psp->fd, &psp->pSAREA->lock, hwContext);         \
 110     }                                                                   \
 111 } while (0)
 112
 113
 114 /**
 115  * Driver callback functions.
 116  *
 117  * Each DRI driver must have one of these structures with all the pointers set
 118  * to appropriate functions within the driver.
 119  *
 120  * When glXCreateContext() is called, for example, it'll call a helper function
 121  * dri_util.c which in turn will jump through the \a CreateContext pointer in
 122  * this structure.
 123  */
 124 struct __DriverAPIRec {
 125     const __DRIconfig **(*InitScreen) (__DRIscreen * priv);
 126
 127     /**
 128      * Screen destruction callback
 129      */
 130     void (*DestroyScreen)(__DRIscreen *driScrnPriv);
 131
 132     /**
 133      * Context creation callback
 134      */
 135     GLboolean (*CreateContext)(const __GLcontextModes *glVis,
 136                                __DRIcontext *driContextPriv,
 137                                void *sharedContextPrivate);
 138
 139     /**
 140      * Context destruction callback
 141      */
 142     void (*DestroyContext)(__DRIcontext *driContextPriv);
 143
 144     /**
 145      * Buffer (drawable) creation callback
 146      */
 147     GLboolean (*CreateBuffer)(__DRIscreen *driScrnPriv,
 148                               __DRIdrawable *driDrawPriv,
 149                               const __GLcontextModes *glVis,
 150                               GLboolean pixmapBuffer);
 151
 152     /**
 153      * Buffer (drawable) destruction callback
 154      */
 155     void (*DestroyBuffer)(__DRIdrawable *driDrawPriv);
 156
 157     /**
 158      * Buffer swapping callback
 159      */
 160     void (*SwapBuffers)(__DRIdrawable *driDrawPriv);
 161
 162     /**
 163      * Context activation callback
 164      */
 165     GLboolean (*MakeCurrent)(__DRIcontext *driContextPriv,
 166                              __DRIdrawable *driDrawPriv,
 167                              __DRIdrawable *driReadPriv);
 168
 169     /**
 170      * Context unbinding callback
 171      */
 172     GLboolean (*UnbindContext)(__DRIcontext *driContextPriv);
 173
 174     /**
 175      * Retrieves statistics about buffer swap operations.  Required if
 176      * GLX_OML_sync_control or GLX_MESA_swap_frame_usage is supported.
 177      */
 178     int (*GetSwapInfo)( __DRIdrawable *dPriv, __DRIswapInfo * sInfo );
 179
 180
 181     /**
 182      * These are required if GLX_OML_sync_control is supported.
 183      */
 184     /*@{*/
 185     int (*WaitForMSC)( __DRIdrawable *priv, int64_t target_msc,
 186                        int64_t divisor, int64_t remainder,
 187                        int64_t * msc );
 188     int (*WaitForSBC)( __DRIdrawable *priv, int64_t target_sbc,
 189                        int64_t * msc, int64_t * sbc );
 190
 191     int64_t (*SwapBuffersMSC)( __DRIdrawable *priv, int64_t target_msc,
 192                                int64_t divisor, int64_t remainder );
 193     /*@}*/
 194     void (*CopySubBuffer)(__DRIdrawable *driDrawPriv,
 195                           int x, int y, int w, int h);
 196
 197     /**
 198      * New version of GetMSC so we can pass drawable data to the low
 199      * level DRM driver (e.g. pipe info).  Required if
 200      * GLX_SGI_video_sync or GLX_OML_sync_control is supported.
 201      */
 202     int (*GetDrawableMSC) ( __DRIscreen * priv,
 203                             __DRIdrawable *drawablePrivate,
 204                             int64_t *count);
 205
 206
 207
 208     /* DRI2 Entry points */
 209     const __DRIconfig **(*InitScreen2) (__DRIscreen * priv);
 210     void (*HandleDrawableConfig)(__DRIdrawable *dPriv,
 211                                 __DRIcontext *pcp,
 212                                 __DRIDrawableConfigEvent *event);
 213
 214     void (*HandleBufferAttach)(__DRIdrawable *dPriv,
 215                                __DRIcontext *pcp,
 216                                __DRIBufferAttachEvent *ba);
 217
 218 };
 219
 220 extern const struct __DriverAPIRec driDriverAPI;
 221
 222
 223 struct __DRIswapInfoRec {
 224     /**
 225      * Number of swapBuffers operations that have been *completed*.
 226      */
 227     u_int64_t swap_count;
 228
 229     /**
 230      * Unadjusted system time of the last buffer swap.  This is the time
 231      * when the swap completed, not the time when swapBuffers was called.
 232      */
 233     int64_t   swap_ust;
 234
 235     /**
 236      * Number of swap operations that occurred after the swap deadline.  That
 237      * is if a swap happens more than swap_interval frames after the previous
 238      * swap, it has missed its deadline.  If swap_interval is 0, then the
 239      * swap deadline is 1 frame after the previous swap.
 240      */
 241     u_int64_t swap_missed_count;
 242
 243     /**
 244      * Amount of time used by the last swap that missed its deadline.  This
 245      * is calculated as (__glXGetUST() - swap_ust) / (swap_interval *
 246      * time_for_single_vrefresh)).  If the actual value of swap_interval is
 247      * 0, then 1 is used instead.  If swap_missed_count is non-zero, this
 248      * should be greater-than 1.0.
 249      */
 250     float     swap_missed_usage;
 251 };
 252
 253
 254 /**
 255  * Per-drawable private DRI driver information.
 256  */
 257 struct __DRIdrawableRec {
 258     /**
 259      * Kernel drawable handle
 260      */
 261     drm_drawable_t hHWDrawable;
 262
 263     /**
 264      * Driver's private drawable information.
 265      *
 266      * This structure is opaque.
 267      */
 268     void *driverPrivate;
 269
 270     /**
 271      * Private data from the loader.  We just hold on to it and pass
 272      * it back when calling into loader provided functions.
 273      */
 274     void *loaderPrivate;
 275
 276     /**
 277      * Reference count for number of context's currently bound to this
 278      * drawable.
 279      *
 280      * Once it reaches zero, the drawable can be destroyed.
 281      *
 282      * \note This behavior will change with GLX 1.3.
 283      */
 284     int refcount;
 285
 286     /**
 287      * Index of this drawable information in the SAREA.
 288      */
 289     unsigned int index;
 290
 291     /**
 292      * Pointer to the "drawable has changed ID" stamp in the SAREA.
 293      */
 294     unsigned int *pStamp;
 295
 296     /**
 297      * Last value of the stamp.
 298      *
 299      * If this differs from the value stored at __DRIdrawable::pStamp,
 300      * then the drawable information has been modified by the X server, and the
 301      * drawable information (below) should be retrieved from the X server.
 302      */
 303     unsigned int lastStamp;
 304
 305     /**
 306      * \name Drawable
 307      *
 308      * Drawable information used in software fallbacks.
 309      */
 310     /*@{*/
 311     int x;
 312     int y;
 313     int w;
 314     int h;
 315     int numClipRects;
 316     drm_clip_rect_t *pClipRects;
 317     /*@}*/
 318
 319     /**
 320      * \name Back and depthbuffer
 321      *
 322      * Information about the back and depthbuffer where different from above.
 323      */
 324     /*@{*/
 325     int backX;
 326     int backY;
 327     int backClipRectType;
 328     int numBackClipRects;
 329     drm_clip_rect_t *pBackClipRects;
 330     /*@}*/
 331
 332     /**
 333      * \name Vertical blank tracking information
 334      * Used for waiting on vertical blank events.
 335      */
 336     /*@{*/
 337     unsigned int vblSeq;
 338     unsigned int vblFlags;
 339     /*@}*/
 340
 341     /**
 342      * \name Monotonic MSC tracking
 343      *
 344      * Low level driver is responsible for updating msc_base and
 345      * vblSeq values so that higher level code can calculate
 346      * a new msc value or msc target for a WaitMSC call.  The new value
 347      * will be:
 348      *   msc = msc_base + get_vblank_count() - vblank_base;
 349      *
 350      * And for waiting on a value, core code will use:
 351      *   actual_target = target_msc - msc_base + vblank_base;
 352      */
 353     /*@{*/
 354     int64_t vblank_base;
 355     int64_t msc_base;
 356     /*@}*/
 357
 358     /**
 359      * Pointer to context to which this drawable is currently bound.
 360      */
 361     __DRIcontext *driContextPriv;
 362
 363     /**
 364      * Pointer to screen on which this drawable was created.
 365      */
 366     __DRIscreen *driScreenPriv;
 367
 368     /**
 369      * Controls swap interval as used by GLX_SGI_swap_control and
 370      * GLX_MESA_swap_control.
 371      */
 372     unsigned int swap_interval;
 373     struct {
 374         unsigned int tail;
 375         unsigned int drawable_id;
 376     } dri2;
 377 };
 378
 379 /**
 380  * Per-context private driver information.
 381  */
 382 struct __DRIcontextRec {
 383     /**
 384      * Kernel context handle used to access the device lock.
 385      */
 386     drm_context_t hHWContext;
 387
 388     /**
 389      * Device driver's private context data.  This structure is opaque.
 390      */
 391     void *driverPrivate;
 392
 393     /**
 394      * Pointer back to the \c __DRIcontext that contains this structure.
 395      */
 396     __DRIcontext *pctx;
 397
 398     /**
 399      * Pointer to drawable currently bound to this context for drawing.
 400      */
 401     __DRIdrawable *driDrawablePriv;
 402
 403     /**
 404      * Pointer to drawable currently bound to this context for reading.
 405      */
 406     __DRIdrawable *driReadablePriv;
 407
 408     /**
 409      * Pointer to screen on which this context was created.
 410      */
 411     __DRIscreen *driScreenPriv;
 412 };
 413
 414 /**
 415  * Per-screen private driver information.
 416  */
 417 struct __DRIscreenRec {
 418     /**
 419      * Current screen's number
 420      */
 421     int myNum;
 422
 423     /**
 424      * Callback functions into the hardware-specific DRI driver code.
 425      */
 426     struct __DriverAPIRec DriverAPI;
 427
 428     const __DRIextension **extensions;
 429     /**
 430      * DDX / 2D driver version information.
 431      */
 432     __DRIversion ddx_version;
 433
 434     /**
 435      * DRI X extension version information.
 436      */
 437     __DRIversion dri_version;
 438
 439     /**
 440      * DRM (kernel module) version information.
 441      */
 442     __DRIversion drm_version;
 443
 444     /**
 445      * ID used when the client sets the drawable lock.
 446      *
 447      * The X server uses this value to detect if the client has died while
 448      * holding the drawable lock.
 449      */
 450     int drawLockID;
 451
 452     /**
 453      * File descriptor returned when the kernel device driver is opened.
 454      *
 455      * Used to:
 456      *   - authenticate client to kernel
 457      *   - map the frame buffer, SAREA, etc.
 458      *   - close the kernel device driver
 459      */
 460     int fd;
 461
 462     /**
 463      * SAREA pointer
 464      *
 465      * Used to access:
 466      *   - the device lock
 467      *   - the device-independent per-drawable and per-context(?) information
 468      */
 469     drm_sarea_t *pSAREA;
 470
 471     /**
 472      * \name Direct frame buffer access information
 473      * Used for software fallbacks.
 474      */
 475     /*@{*/
 476     unsigned char *pFB;
 477     int fbSize;
 478     int fbOrigin;
 479     int fbStride;
 480     int fbWidth;
 481     int fbHeight;
 482     int fbBPP;
 483     /*@}*/
 484
 485     /**
 486      * \name Device-dependent private information (stored in the SAREA).
 487      *
 488      * This data is accessed by the client driver only.
 489      */
 490     /*@{*/
 491     void *pDevPriv;
 492     int devPrivSize;
 493     /*@}*/
 494
 495     /**
 496      * Dummy context to which drawables are bound when not bound to any
 497      * other context.
 498      *
 499      * A dummy hHWContext is created for this context, and is used by the GL
 500      * core when a hardware lock is required but the drawable is not currently
 501      * bound (e.g., potentially during a SwapBuffers request).  The dummy
 502      * context is created when the first "real" context is created on this
 503      * screen.
 504      */
 505     __DRIcontext dummyContextPriv;
 506
 507     /**
 508      * Device-dependent private information (not stored in the SAREA).
 509      *
 510      * This pointer is never touched by the DRI layer.
 511      */
 512     void *private;
 513
 514     /**
 515      * Pointer back to the \c __DRIscreen that contains this structure.
 516      */
 517     __DRIscreen *psc;
 518
 519     /* Extensions provided by the loader. */
 520     const __DRIgetDrawableInfoExtension *getDrawableInfo;
 521     const __DRIsystemTimeExtension *systemTime;
 522     const __DRIdamageExtension *damage;
 523
 524     struct {
 525         /* Flag to indicate that this is a DRI2 screen.  Many of the above
 526          * fields will not be valid or initializaed in that case. */
 527         int enabled;
 528         drmBO sareaBO;
 529         void *sarea;
 530         __DRIEventBuffer *buffer;
 531         __DRILock *lock;
 532         __DRIloaderExtension *loader;
 533     } dri2;
 534
 535     /* The lock actually in use, old sarea or DRI2 */
 536     drmLock *lock;
 537 };
 538
 539 struct __DRIconfigRec {
 540     __GLcontextModes modes;
 541 };
 542
 543 /**
 544  * Used to store a version which includes a major range instead of a single
 545  * major version number.
 546  */
 547 struct __DRIutilversionRec2 {
 548     int    major_min;    /** min allowed Major version number. */
 549     int    major_max;    /** max allowed Major version number. */
 550     int    minor;        /**< Minor version number. */
 551     int    patch;        /**< Patch-level. */
 552 };
 553
 554
 555 extern void
 556 __driUtilMessage(const char *f, ...);
 557
 558
 559 extern void
 560 __driUtilUpdateDrawableInfo(__DRIdrawable *pdp);
 561
 562 extern int
 563 __driParseEvents(__DRIcontext *psp, __DRIdrawable *pdp);
 564
 565 extern float
 566 driCalculateSwapUsage( __DRIdrawable *dPriv,
 567                        int64_t last_swap_ust, int64_t current_ust );
 568
 569 #endif /* _DRI_UTIL_H_ */