EXA driver doc cleanups and additions.

hw/xfree86/doc/devel/exa-driver.txt

@@ -2,34 +2,33 @@ Adding EXA support to your X.Org video driver
 ---------------------------------------------
 EXA (for EXcellent Architecture or Ex-kaa aXeleration Architecture or
 whatever) aims to extend the life of the venerable XFree86 video drivers by
-introducing hooks that they can implement to more efficiently accelerate the X
+introducing a new set of acceleration hooks that efficiently accelerate the X
-Render extension: solid fills, blits within screen memory and to and from
+Render extension, including solid fills, blits within screen memory and to and
-system memory, and Porter-Duff compositing and transform operations.
+from system memory, and Porter-Duff compositing and transform operations.
 
-Globals
+Configuration
--------
+-------------
+A new config file option, AccelMethod, should be added to your driver, to allow
+the user to select between the EXA and XAA acceleration APIs.
+
+Some drivers implement a per-instance useEXA flag to track whether EXA is
+active or not.  It can be helpful to also conditionalize XAA support with an
+ifdef so that it can easily be turned off/removed in the future.
+
+Setting the flag and checking for AccelMethod can be done in the driver's
+Options parsing routine.
+
+Global symbols
+--------------
 XF86EXA will be defined to a nonzero value if your X server codebase supports
 the EXA API.  Use it to conditionalize your new EXA code if your driver is
 shared with a non-EXA codebases.  If present, necessary functions, structures
 and defines will be located in "exa.h".
 
-AccelMethod
+EXA library functions
------------
+---------------------
-A new config file option, AccelMethod, should be used in your driver to select
+Use the following functions to initialize your driver's EXA hooks, check the
-between the EXA and XAA acceleration APIs.  The default should be XAA for
+version, allocate memory, etc.
-6.9/7.0 drivers.
-
-Some drivers implement a per-instance useEXA flag to track whether EXA is
-active or not.  It can be helpful to also conditionalize XAA support so that
-it can easily be turned off/removed in the future.  Setting the flag and
-checking for AccelMethod can be done in the driver's Options routine (a
-friendly printf is be a nice way of letting the user know which method is in
-use).
-
-Core EXA functions
-------------------
-The following functions are provided, for use by your driver, to do
-allocation, initialization, version checking, etc.
 
   /**
    * exaGetVersion - retrieve EXA version number from server
@@ -42,13 +41,13 @@ allocation, initialization, version checking, etc.
   /**
    * exaDriverInit - tell EXA about a new EXA driver
    * @pScreen - current screen
-   * @pScreenInfo - driver structure
+   * @driverPtr - driver structure
    *
    * Tell EXA about the driver described by @pScreenInfo.
    *
    * Returns TRUE for success, FALSE for failure.
    */
-  Bool exaDriverInit(ScreenPtr pScreen, ExaDriverPtr pScreenInfo)
+  Bool exaDriverInit(ScreenPtr pScreen, ExaDriverPtr driverPtr)
 
   /**
    * exaDriverFini - teardown an EXA driver
@@ -58,7 +57,6 @@ allocation, initialization, version checking, etc.
    */
   void exaDriverFini(ScreenPtr pScreen)
 
-
   /**
    * exaOffscreenAlloc - allocate offscreen memory
    * @pScreen: current screen
@@ -118,11 +116,6 @@ allocation, initialization, version checking, etc.
    *   %EXA_OFFSCREEN_PIXMAPS - offscreen pixmaps are supported
    *   %EXA_OFFSCREEN_ALIGN_POT - offscreen objects must hve a power of two
    *     alignment of their pitch
-   *
-   * This routine is just a macro, and so it can't fail (unless it causes a
-   * compile failure).
-   *
-   * [This macro appears broken in the current tree, s/Sync/needsSync/.]
    */
   void exaInitCard(EXADriverPtr *exa, Bool sync, CARD8 *memory_base,
 		   unsigned longoff_screen_base, unsigned long memory_size,
@@ -156,9 +149,6 @@ allocation, initialization, version checking, etc.
    */
   Bool exaOffscreenInit(ScreenPtr pScreen)
 
-Some helper functions are also available to make common EXA related functions
-easier.
-
   /**
    * exaGetPixmapPitch - return the pitch for a pixmap
    * @p: pixmap
@@ -176,16 +166,21 @@ easier.
    */
   unsigned int exaGetPixmapOffset(PixmapPtr p)
 
-Driver EXA routines
+EXA driver hooks
--------------------
+----------------
 EXA requires the addition of new routines to your driver's acceleration
 implementation.  The following structure defines the EXA acceleration API,
-some are required to be implemented in your driver, others are optional.
+some hooks are required to be implemented in your driver, others are optional.
+
+Each of these routines has an associated function pointer in the ExaAccelInfo
+structure.  At a minimum, your driver must allocate an ExaDriverRec struture,
+fill out the ExaCardInfoRec member structure, and define the miminum required
+functions (described below) and hook them into the ExaAccelInfo member
+structure.
 
 Note that for routines that take a source and destination pixmap, the pitches
 may be different.
 
-  typedef struct _ExaAccelInfo {
   /**
    * PrepareSolid - setup for solid fill
    * @pPixmap: Pixmap destination
@@ -340,7 +335,7 @@ may be different.
    * can't accelerate the operation (e.g. if the pixmaps are incompatible with
    * acceleration).
    *
-   * Optional.
+   * Optional but recommended.
    */
   Bool (*PrepareComposite)(int op, PicturePtr pSrcPicture,
                            PicturePtr pMaskPicture, PicturePtr pDstPicture,
@@ -362,7 +357,7 @@ may be different.
    *
    * Must not fail.
    *
-   * Optional.
+   * Optional but recommended.
    */
   void (*Composite)(PixmapPtr pDst, int srcX, int srcY, int maskX, int maskY,
                     int dstX, int dstY, int width, int height);
@@ -465,10 +460,6 @@ may be different.
    * Required.
    */
   void (*WaitMarker)(ScreenPtr pScreen, int marker);
-  } ExaAccelInfoRec, *ExaAccelInfoPtr;
-
-This is an extra, optional routine, used as a callback to the offscreen
-allocation function.
 
   /**
    * ScratchSave - save the scratch area, or just throw it away
@@ -490,24 +481,16 @@ allocation function.
    */
   void ScratchSave(ScreenPtr pScreen, ExaOffscreenArea *area);
 
-EXA driver fields
------------------
-Each driver record structure also needs a few additional fields if EXA
-support is to be used, e.g.:
-
-  #if XF86EXA
-  /* Container structure, describes card and accel. hooks */
-  ExaDriverPtr EXADriverPtr;
-  #endif
-
 EXA initialization
 ------------------
-Your driver's AccelInit routine has to initialize the EXADriverPtr if EXA
+Your driver's AccelInit routine must initialize an ExaDriverRec structure if
-support is enabled, with appropriate error handling (i.e.  NoAccel and
+EXA support is enabled, with appropriate error handling (i.e.  NoAccel and
 NoXvideo should be set to true if EXA fails to initialize for whatever
 reason).
 
-A few, card specific fields need to be initialized:
+A few, card specific fields need to be initialized (assuming your driver uses
+a variable named EXADriverPtr pointing to where your ExaDriverRec is
+allocated):
 
   /*
    * EXA uses memoryBase to access the framebuffer, while memorySize and
@@ -519,12 +502,13 @@ A few, card specific fields need to be initialized:
   EXADriverPtr->card.memorySize = ? /* end of offscreen memory */
   /* offset of offscreen memory relative to memoryBase */
   EXADriverPtr->card.offScreenBase = ?
+
   /*
    * If your offscreen memory is just after your framebuffer, which is at the
-   * start of memory, it may be something like:
+   * start of memory, offScreenBase may be something like:
-   *   pScrn->virtualX * pScrn->virtualY * ((pScrn->bitsPerPixel * + 7) / 8)
+   *   pScrn->virtualX * pScrn->virtualY * ((pScrn->bitsPerPixel + 7) / 8)
-   * should use the X value from the adjusted width based on virtualX, after
+   * (the + 7 / 8 causes the integer division to round up instead of
-   * accounting for the accelerator's pitch alignment constraints
+   * round down).
    */
 
   /*
@@ -532,13 +516,12 @@ A few, card specific fields need to be initialized:
    * them.  Not applied to all pixmaps--the visible screen is an exception,
    * and thus Prepare* acceleration hooks should test for these and fail
    * appropriately.  pixmapOffsetAlign is the value that the pixmap's offset
-   * from the beginning of the framebuffer must be aligned to.  pixmapPitchAlign
+   * from the beginning of the framebuffer must be aligned to.
-   * is the value that the pitch of a pixmap must be aligned to (along with
+   * pixmapPitchAlign is the value that the pitch of a pixmap must be aligned
-   * ALIGN_POT).
+   * to (along with ALIGN_POT).
    */
   EXADriverPtr->card.pixmapOffsetAlign = ?
-  /* also called stride */
+  EXADriverPtr->card.pixmapPitchAlign = ? /* also called stride */
-  EXADriverPtr->card.pixmapPitchAlign = ?
 
   /* Max screen size supported by the card? */
   EXADriverPtr->card.maxX = ?
@@ -575,12 +558,11 @@ out (don't forget to check for errors as that routine can fail).
 If your driver doesn't support UploadToScreen, you should allocate some
 scratch space for use by commonly used pixmaps (e.g. glyphs).  Note that it's
 much better to implement UploadToScreen than to allocate scratch space, but if
-necessary allocate about as much as you'd need for a line of text.
+necessary allocate about as much as you'd need for a line of text.  E.g.
 
   pDrv->exa_scratch = exaOffscreenAlloc(pScreen, 128 * 1024, 16, TRUE,
 					ScratchSave, pDrv);
 
-  /* Why is this required?  Shouldn't exaOffscreenAlloc take care of it? */
   if(pDrv->exa_scratch) {
     pDrv->exa_scratch_next = pDrv->exa_scratch->offset;
     pDrv->EXADriverPtr->accel.UploadToScratch = UploadToScratch;
@@ -601,7 +583,7 @@ call at setup time.
 
 EXA teardown
 ------------
-At screen close time, EXA drivers should, call exaDriverFini with their screen
+At screen close time, EXA drivers should call exaDriverFini with their screen
 pointer, free their EXADriver structure, and do any other necessary teardown.
 
 EXA misc.