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