hw/xfree86/doc/exa-driver.txt

   1 Adding EXA support to your X.Org video driver
   2 ---------------------------------------------
   3 EXA (for EXcellent Architecture or Ex-kaa aXeleration Architecture or
   4 whatever) aims to extend the life of the venerable XFree86 video drivers by
   5 introducing a new set of acceleration hooks that efficiently accelerate the X
   6 Render extension, including solid fills, blits within screen memory and to and
   7 from system memory, and Porter-Duff compositing and transform operations.
   8
   9 Configuration
  10 -------------
  11 Some drivers implement a per-instance useEXA flag to track whether EXA is
  12 active or not.
  13
  14 Setting the flag can be done in the driver's Options parsing routine.
  15
  16 Loading EXA
  17 ------------
  18 EXA drivers in the XFree86 DDX should use the loadable module loader to load
  19 the EXA core.  Careful versioning allows the EXA API to be extended without
  20 breaking the ABI for older versions of drivers.  Example code for loading EXA:
  21
  22 static const char *exaSymbols[] = {
  23     "exaDriverAlloc",
  24     "exaDriverInit",
  25     "exaDriverFini",
  26     "exaOffscreenAlloc",
  27     "exaOffscreenFree",
  28     "exaGetPixmapOffset",
  29     "exaGetPixmapPitch",
  30     "exaGetPixmapSize",
  31     "exaMarkSync",
  32     "exaWaitSync",
  33     NULL
  34 };
  35
  36         if (info->useEXA) {
  37             info->exaReq.majorversion = 2;
  38             info->exaReq.minorversion = 0;
  39
  40             if (!LoadSubModule(pScrn->module, "exa", NULL, NULL, NULL,
  41                                &info->exaReq, &errmaj, &errmin)) {
  42                 LoaderErrorMsg(NULL, "exa", errmaj, errmin);
  43                 return FALSE;
  44             }
  45             xf86LoaderReqSymLists(exaSymbols, NULL);
  46         }
  47
  48 EXA is then initialized using exaDriverAlloc and exaDriverInit.  See doxygen
  49 documentation for getting started there.
  50
  51 Further documentation
  52 ------------
  53 The EXA driver interface and public API is documented using doxygen in
  54 xserver/xorg/exa/.  To build the documentation, run:
  55   doxygen -g
  56   doxygen Doxyfile
  57 The resulting documentation will appear an html/index.html under the current
  58 directory.
  59
  60 EXA initialization
  61 ------------------
  62 Your driver's AccelInit routine must initialize an ExaDriverRec structure if
  63 EXA support is enabled, with appropriate error handling (i.e.  NoAccel and
  64 NoXvideo should be set to true if EXA fails to initialize for whatever
  65 reason).
  66
  67 The AccelInit routine also needs to make sure that there's enough offscreen
  68 memory for certain operations to function, like Xvideo, which should advertise
  69 a maximum size no larger than can be dealt with given the amount of offscreen
  70 memory available.
  71
  72 EXA and Xv
  73 ----------
  74 Video support becomes easier with EXA since AllocateFBMemory can use
  75 exaOffscreenAlloc directly, freeing a previous area if necessary and
  76 allocating a new one.  Likewise, FreeFBMemory can call exaOffscreenFree.
  77
  78 EXA teardown
  79 ------------
  80 At screen close time, EXA drivers should call exaDriverFini with their screen
  81 pointer, free their EXADriver structure, and do any other necessary teardown.
  82
  83 EXA misc.
  84 ---------
  85 In many drivers, DGA support will need to be changed to be aware of the new
  86 EXA support.
  87
  88 Send updates and corrections to Jesse Barnes <jbarnes@virtuousgeek.org> or
  89 just check them in if you have permission.