Commit changes missed in last commit (mis-typed path and didn't notice): Do

    a first pass of doxygen documentation of EXA. This removes the
    corresponding pieces of exa-driver.txt, which were becoming stale.
    Hopefully the documentation will stay much more up-to-date this way.
    Many thanks to jbarnes for writing exa-driver.txt which was used a lot
    in writing this documentation.

1 files changed, 43 insertions, 546 deletions

diff --git a/hw/xfree86/doc/devel/exa-driver.txt b/hw/xfree86/doc/devel/exa-driver.txt
index 804eed1b9..048307ee7 100644
--- a/hw/xfree86/doc/devel/exa-driver.txt
+++ b/hw/xfree86/doc/devel/exa-driver.txt
@@ -18,470 +18,49 @@ 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".
-
-EXA library functions
----------------------
-Use the following functions to initialize your driver's EXA hooks, check the
-version, allocate memory, etc.
-
-  /**
-   * exaGetVersion - retrieve EXA version number from server
-   *
-   * Simply returns the EXA version number, useful for checking for EXA
-   * features at runtime.
-   */
-  unsigned int exaGetVersion(void)
-
-  /**
-   * exaDriverInit - tell EXA about a new EXA driver
-   * @pScreen - current screen
-   * @driverPtr - driver structure
-   *
-   * Tell EXA about the driver described by @pScreenInfo.
-   *
-   * Returns TRUE for success, FALSE for failure.
-   */
-  Bool exaDriverInit(ScreenPtr pScreen, ExaDriverPtr driverPtr)
-
-  /**
-   * exaDriverFini - teardown an EXA driver
-   * @pScreen: current screen
-   *
-   * Tell EXA that an EXA driver associated with @pScreen is gone.
-   */
-  void exaDriverFini(ScreenPtr pScreen)
-
-  /**
-   * exaOffscreenAlloc - allocate offscreen memory
-   * @pScreen: current screen
-   * @size: size in bytes
-   * @align: alignment constraints, must be a power of two
-   * @locked: allocate the memory as locked?
-   * @save: offscreen save routine
-   * @privdata: private driver data for @save routine
-   *
-   * Allocate some offscreen memory from the device associated with @pScreen.
-   * @size and @align determine where and how large the section is, and
-   * @locked will determine whether the new memory should be freed later on or
-   * if it should be kept in card memory until freed explicitly.  @save and
-   * @privData are used to make room for the new allocation in scratch space,
-   * if necessary, and only need to be passed in if your driver doesn't
-   * support UploadToScreen and uses scratch space instead.
-   *
-   * Note that @align must be a power of two, currently.
-   *
-   * Returns NULL on failure, or a pointer to the new offscreen memory on
-   * success.
-   */
-  ExaOffscreenArea *exaOffscreenAlloc(ScreenPtr pScreen, int size, int align,
-				      Bool locked, ExaOffscreenSaveProc save,
-				      pointer privData);
-
-  /**
-   * exaOffscreenFree - free offscreen memory
-   * @pScreen: current screen
-   * @area: area to free
-   *
-   * Free some offscreen memory previously allocated with exaOffscreenAlloc,
-   * described by @area.
-   *
-   * Returns a pointer to to the freed area.
-   */
-  ExaOffscreenArea *exaOffscreenFree(ScreenPtr pScreen, ExaOffscreenArea *area)
-
-  /**
-   * exaInitCard - initialize EXA card structure
-   * @exa: card structure to initialize
-   * @sync: card needs sync?
-   * @memory_base: pointer to beginning of framebuffer memory
-   * @off_screen_base: offset to the first free byte of offscreen memory
-   * @memory_size: size of framebuffer memory
-   * @offscreen_byte_align: card alignment restriction, in bytes
-   * @offscreen_pitch: card pitch alignment restriction, in bytes
-   * @flags: flags
-   * @max_x: maximum width of screen
-   * @max_y: maximum height of screen
-   *
-   * This is just a wrapper around the initialization of the EXA driver's card
-   * structure.
-   *
-   * The flags argument specifies what features the card supports, two flags
-   * are currently defined:
-   *   %EXA_OFFSCREEN_PIXMAPS - offscreen pixmaps are supported
-   *   %EXA_OFFSCREEN_ALIGN_POT - offscreen objects must have a power of two
-   *     alignment of their pitch
-   *   %EXA_TWO_BITBLT_DIRECTIONS - device only supports blts in two
-   *     directions, +xdir,+ydir or -xdir,-ydir (identical to the XAA flag).
-   */
-  void exaInitCard(EXADriverPtr *exa, Bool sync, CARD8 *memory_base,
-		   unsigned longoff_screen_base, unsigned long memory_size,
-		   int offscreen_byte_align, int offscreen_pitch, int flags,
-		   int max_x, int max_y)
-
-  /**
-   * exaMarkSync - mark a sync point
-   * @pScreen: current screen
-   *
-   * Record a marker for later synchronization.  May be useful to drivers that
-   * need to tell EXA that they've used the accelerator.
-   */
-  void exaMarkSync(ScreenPtr pScreen)
-
-  /**
-   * exaWaitSync - wait for the last marker to complete
-   * @pScreen: current screen
-   *
-   * Wait until the device associated with @pScreen is done with the operation
-   * associated with the last exaMarkSync() call.
-   */
-  void exaWaitSync(ScreenPtr pScreen)
-
-  /**
-   * exaOffscreenInit - initialize offscreen memory
-   * @pScreen: current screen
-   *
-   * Private, core server use only (unless someone comes up with a good
-   * reason for it to be otherwise).
-   */
-  Bool exaOffscreenInit(ScreenPtr pScreen)
-
-  /**
-   * exaGetPixmapPitch - return the pitch for a pixmap
-   * @p: pixmap
-   *
-   * exaGetPixmapPitch() will calculate and return the pitch for the pixmap @p.
-   */
-  int exaGetPixmapPitch(PixmapPtr p)
-
-  /**
-   * exaGetPixmapOffset - return the offset of a pixmap
-   * @p: pixmap
-   *
-   * exaGetPixmapOffset() will calculate and return the offset in video memory
-   * of the pixmap @p.
-   */
-  unsigned int exaGetPixmapOffset(PixmapPtr p)
-
-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 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.
-
-  /**
-   * PrepareSolid - setup for solid fill
-   * @pPixmap: Pixmap destination
-   * @alu: raster operation
-   * @planemask: mask for fill
-   * @fg: foreground color
-   *
-   * Setup the card's engine for a solid fill operation into @pPixmap.
-   * @alu specifies the raster op for the fill, @planemask specifies an
-   * optional mask, and @fg specifies the foreground color for the fill.
-   *
-   * You can add additional fields to your driver record structure to store
-   * state needed by this routine, if necessary.
-   *
-   * Return TRUE for if your driver can accelerate the operation with the
-   * parameters given, or FALSE if EXA should fallback to manual rendering.
-   *
-   * Required.
-   */
-  Bool (*PrepareSolid)(PixmapPtr pPixmap, int alu, Pixel planemask,
-                       Pixel fg);
-
-  /**
-   * Solid - solid fill operation
-   * @pPixmap: Pixmap destination
-   * @x1: left coordinate
-   * @y1: top coordinate
-   * @x2: right coordinate
-   * @y2: bottom coordinate
-   *
-   * Perform the fill as specified by PrepareSolid, from x1,y1 to x2,y2 within
-   * @pPixmap.  Many devices just need the offset, pitch, start x,y, height
-   * and width to do the fill; others may require you to calculate the
-   * destination address including the offset plus the adjustment for the
-   * pitch, x and y.  Check out a few driver implementations for ideas about
-   * what might work best for your particular device.
-   *
-   * Must not fail.
-   *
-   * Required.
-   */
-  void (*Solid)(PixmapPtr pPixmap, int x1, int y1, int x2, int y2);
-
-  /**
-   * DoneSolid - finish a solid fill
-   * @pPixmap: Pixmap to finish
-   *
-   * Finish the solid fills done in the preceding Solid calls.
-   *
-   * Must not fail.
-   *
-   * Required.
-   */
-  void (*DoneSolid)(PixmapPtr pPixmap);
-
-  /**
-   * PrepareCopy - setup a copy operation
-   * @pSrcPixmap: source Pixmap
-   * @pDstPixmap: destination Pixmap
-   * @xdir: x direction for the copy
-   * @ydir: y direction for the copy
-   * @alu: raster operation
-   * @planemask: optional planemask for the copy
-   *
-   * Copy @pSrcPixmap to @pDstPixmap in the x and y direction specified,
-   * with the raster operation @alu.  @planemask specifies an optional
-   * color plane mask for the copy.  Note that pSrcPixmap isn't available in
-   * the subsequent Copy routine, so you may have to store some of its values
-   * elsewhere for later use.
-   *
-   * You can add additional fields to your driver record structure to store
-   * state needed by this routine, if necessary, for instance calculating the
-   * framebuffer offset in PrepareCopy and then using it in the subsequent
-   * Copy call.
-   *
-   * Return TRUE if your driver can accelerate the copy operation with the
-   * parameters given, or FALSE if EXA should fallback to manual rendering.
-   *
-   * Required.
-   */
-  Bool (*PrepareCopy)(PixmapPtr pSrcPixmap, PixmapPtr pDstPixmap, int xdir,
-                      int ydir, int alu, Pixel planemask);
-
-  /**
-   * Copy - perform a copy between two pixmaps
-   * @pDstPixmap: destination Pixmap
-   * @srcX: source X coordinate
-   * @srcY: source Y coordinate
-   * @dstX: destination X coordinate
-   * @dstY: destination Y coordinate
-   * @width: copy width
-   * @height: copy height
-   *
-   * Perform the copy setup by the previous PrepareCopy call, from
-   * (@srcX,@srcY) in the source pixmap to (@dstX,@dstY) in pDstPixmap using
-   * @width and @height to determine the quantity of the copy.
-   *
-   * Must not fail.
-   *
-   * Required.
-   */
-  void (*Copy)(PixmapPtr pDstPixmap, int srcX, int srcY, int dstX, int dstY,
-	       int width, int height);
-
-  /**
-   * DoneCopy - finish a copy operation
-   * @pDstPixmap: Pixmap to complete
-   *
-   * Tear down the copy operation for @pDstPixmap, if necessary.
-   *
-   * Must not fail.
-   *
-   * Required.
-   */
-  void (*DoneCopy)(PixmapPtr pDstPixmap);
-
-  /**
-   * CheckComposite - check to see if a composite operation is doable
-   * @op: composite operation
-   * @pSrcPicture: source Picture
-   * @pMaskPicture: mask Picture
-   * @pDstPicture: destination Picture
-   *
-   * Check to see if @pSrcPicture can be composited onto @pDstPicture with
-   * @pMaskPicture as a mask.
-   *
-   * Return TRUE if it should be possible to accelerate the given operation
-   * once the pixmap is migrated (so don't fail just because it looks like the
-   * pixmap is in the wrong place), or FALSE if it can't be accelerated.
-   *
-   * [Insert implementation hints here.]
-   *
-   * Optional but recommended.
-   */
-  Bool (*CheckComposite)(int op, PicturePtr pSrcPicture,
-                         PicturePtr pMaskPicture, PicturePtr pDstPicture);
-
-  /**
-   * PrepareComposite - setup a composite operation
-   * @op: composite operation
-   * @pSrcPicture: source Picture
-   * @pMaskPicture: mask Picture
-   * @pDstPicture: destination Picture
-   * @pSrc: Pixmap source
-   * @pMask: Pixmap mask
-   * @pDst: Pixmap destination
-   *
-   * Setup the Porter-Duff compositing operation, @op, with the passed in
-   * parameters.
-   *
-   * Return TRUE if the operation can be accelerated, or FALSE if the driver
-   * can't accelerate the operation (e.g. if the pixmaps are incompatible with
-   * acceleration).
-   *
-   * Optional but recommended.
-   */
-  Bool (*PrepareComposite)(int op, PicturePtr pSrcPicture,
-                           PicturePtr pMaskPicture, PicturePtr pDstPicture,
-                           PixmapPtr pSrc, PixmapPtr pMask, PixmapPtr pDst);
-
-  /**
-   * Composite - perform a composite operation
-   * @pDst: destination Pixmap
-   * @srcX: source X coordinate
-   * @srcY: source Y coordinate
-   * @maskX: X coordinate of mask
-   * @maskY: Y coordinate of mask
-   * @dstX: destination X coordinate
-   * @dstY: destination Y coordinate
-   * @width: operation width
-   * @height: operation height
-   *
-   * Perform a composite operation setup by the last PrepareComposite call.
-   *
-   * Must not fail.
-   *
-   * Optional but recommended.
-   */
-  void (*Composite)(PixmapPtr pDst, int srcX, int srcY, int maskX, int maskY,
-                    int dstX, int dstY, int width, int height);
-
-  /**
-   * DoneComposite - composite operation teardown
-   * @pDst: Pixmap in question
-   *
-   * Finish and teardown the composite operation performed by the last
-   * Composite call.
-   *
-   * Must not fail.
-   *
-   * Optional.
-   */
-  void (*DoneComposite)(PixmapPtr pDst);
-
-  /**
-   * UploadToScreen - load memory into video RAM
-   * @pDst: destination Pixmap
-   * @src: source in system memory
-   * @src_pitch: width of source
-   *
-   * Copy system memory from @src to the PixmapPtr @pDst @src_pitch
-   * bytes at a time.  UploadToScreen is used to move Pixmaps from system
-   * memory to the framebuffer, where alignment restrictions may increase the
-   * pitch.
-   *
-   * Return TRUE if the operation can be accelerated (e.g. the driver can DMA
-   * @src into the framebuffer) or FALSE if EXA should just memcpy it.
-   *
-   * Optional but recommended.
-   */
-  Bool (*UploadToScreen)(PixmapPtr pDst, char *src, int src_pitch);
-
-  /**
-   * UploadToScratch - load memory into video RAM
-   * @pSrc: source Pixmap
-   * @pDst: destination Pixmap
-   *
-   * Recommended in the absence of UploadToScreen, otherwise don't bother.
-   * Must setup space (likely reserved at driver startup time) in framebuffer
-   * memory, copy @pSrc from system memory into @pDst in framebuffer memory,
-   * and adjust pDst->devKind to the pitch of the destination and
-   * pDst->devPrivate.ptr to the pointer to the area.  The driver is
-   * responsible for syncing UploadToScratch.  Only data from the last
-   * UploadToScratch is required to be valid at any given time.
-   *
-   * Return TRUE for success, FALSE for failure.
-   *
-   * Optional, recommended only if UploadToScreen isn't available.
-   */
-  Bool (*UploadToScratch)(PixmapPtr pSrc, PixmapPtr pDst);
-
-  /**
-   * DownloadFromScreen - copy from video RAM to system memory
-   * @pSrc: source Pixmap
-   * @x: starting X coordinate in Pixmap
-   * @y: starting Y coordinate in Pixmap
-   * @w: copy width
-   * @h: copy height
-   * @dst: destination in system memory
-   * @dst_pitch: target width
-   *
-   * Just copy (x,y)->(x+w,y+h) from @pSrc to @dst using @dst_pitch
-   * width?
-   *
-   * Return TRUE for success, FALSE for failure.
-   *
-   * Optional but recommended.
-   */
-  Bool (*DownloadFromScreen)(PixmapPtr pSrc, int x, int y, int w, int h,
-                             char *dst, int dst_pitch);
-
-  /**
-   * MarkSync - return a marker for later use by WaitMarker
-   * @pScreen: current screen
-   *
-   * Return a command marker for use by WaitMarker.  This is an optional
-   * optimization that can keep WaitMarker from having to idle the whole
-   * engine.
-   *
-   * Returns an integer command id marker.
-   *
-   * Optional.
-   */
-  int (*MarkSync)(ScreenPtr screen);
-
-  /**
-   * WaitMarker - finish the last command
-   * @pScreen: current screen
-   * @marker: command marker
-   *
-   * Return after the command specified by @marker is done, or just idle
-   * the whole engine (the latter is your only option unless you implement
-   * MarkSync()).
-   *
-   * Must not fail.
-   *
-   * Required.
-   */
-  void (*WaitMarker)(ScreenPtr pScreen, int marker);
-
-  /**
-   * ScratchSave - save the scratch area, or just throw it away
-   * @pScreen: ScreenPtr for this screen
-   * @area: offscreen area pointer to save
-   *
-   * This routine is responsible for saving the scratch area for later
-   * use, but can optionally just throw it away by setting the driver's
-   * exa_scratch field to NULL.  This is the routine that should be passed to
-   * exaOffscreenAlloc so it can save the scratch area if necessary.  It might
-   * be implemented as a copy from video RAM to AGP space, for example, or
-   * just free the scratch space, track that in the driver, and then
-   * reallocate it later.
-   *
-   * Must not fail.
-   *
-   * Optional and not recommended since you should be implementing
-   * UploadToScreen instead of using scratch space!
-   */
-  void ScratchSave(ScreenPtr pScreen, ExaOffscreenArea *area);
+Loading EXA
+------------
+EXA drivers in the XFree86 DDX should use the loadable module loader to load
+the EXA core.  Careful versioning allows the EXA API to be extended without
+breaking the ABI for older versions of drivers.  Example code for loading EXA:
+
+static const char *exaSymbols[] = {
+    "exaDriverAlloc",
+    "exaDriverInit",
+    "exaDriverFini",
+    "exaOffscreenAlloc",
+    "exaOffscreenFree",
+    "exaGetPixmapOffset",
+    "exaGetPixmapPitch",
+    "exaGetPixmapSize",
+    "exaMarkSync",
+    "exaWaitSync",
+    NULL
+};
+
+	if (info->useEXA) {
+	    info->exaReq.majorversion = 2;
+	    info->exaReq.minorversion = 0;
+
+	    if (!LoadSubModule(pScrn->module, "exa", NULL, NULL, NULL,
+			       &info->exaReq, &errmaj, &errmin)) {
+		LoaderErrorMsg(NULL, "exa", errmaj, errmin);
+		return FALSE;
+	    }
+	    xf86LoaderReqSymLists(exaSymbols, NULL);
+	}
+
+EXA is then initialized using exaDriverAlloc and exaDriverInit.  See doxygen
+documentation for getting started there.
+
+Further documentation
+------------
+The EXA driver interface and public API is documented using doxygen in
+xserver/xorg/exa/.  To build the documentation, run:
+  doxygen -g
+  doxygen Doxyfile
+The resulting documentation will appear an html/index.html under the current
+directory.
 
 EXA initialization
 ------------------
@@ -490,99 +69,17 @@ 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 (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
-   * offscreenBase are used in accessing offscreen memory.  EXA will allocate
-   * memory from memoryBase + offscreenBase to memoryBase + memorySize, so be
-   * sure to set them accordingly as each device's memory map is different.
-   */
-  EXADriverPtr->card.memoryBase = ? /* base of the framebuffer */
-  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, offScreenBase may be something like:
-   *   pScrn->virtualX * pScrn->virtualY * ((pScrn->bitsPerPixel + 7) / 8)
-   * (the + 7 / 8 causes the integer division to round up instead of
-   * round down).
-   */
-
-  /*
-   * Alignment settings for pixmaps, to allow for hardware acceleration on
-   * 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 is the value that the pitch of a pixmap must be aligned
-   * to (along with ALIGN_POT).
-   */
-  EXADriverPtr->card.pixmapOffsetAlign = ?
-  EXADriverPtr->card.pixmapPitchAlign = ? /* also called stride */
-
-  /* Max screen size supported by the card? */
-  EXADriverPtr->card.maxX = ?
-  EXADriverPtr->card.maxY = ?
-
 The AccelInit routine also needs to make sure that there's enough offscreen
 memory for certain operations to function, like Xvideo, which should advertise
 a maximum size no larger than can be dealt with given the amount of offscreen
 memory available.
 
-And of course all the callbacks you implemented as described above (with
-whatever names you've chosen):
-
-  EXADriverPtr->accel.WaitMarker = WaitMarker;
-
-  /* Solid fill & copy, the bare minimum */
-  EXADriverPtr->accel.PrepareSolid = PrepareSolid;
-  EXADriverPtr->accel.Solid = Solid;
-  EXADriverPtr->accel.DoneSolid = DoneSolid;
-  EXADriverPtr->accel.PrepareCopy = PrepareCopy;
-  EXADriverPtr->accel.Copy = Copy;
-  EXADriverPtr->accel.DoneCopy = DoneCopy;
-
-  /* Composite pointers if implemented... */
-
-  /* Upload, download to/from Screen, optional */
-  EXADriverPtr->accel.UploadToScreen = UploadToScreen;
-  EXADriverPtr->accel.DownloadFromScreen = DownloadFromScreen;
-
-After setting up the above, AccelInit should call exaDriverInit and pass in
-the current Screen and the new EXADriverPtr that was just allocated and filled
-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.  E.g.
-
-  pDrv->exa_scratch = exaOffscreenAlloc(pScreen, 128 * 1024, 16, TRUE,
-					ScratchSave, pDrv);
-
-  if(pDrv->exa_scratch) {
-    pDrv->exa_scratch_next = pDrv->exa_scratch->offset;
-    pDrv->EXADriverPtr->accel.UploadToScratch = UploadToScratch;
-  }
-
 EXA and Xv
 ----------
 Video support becomes easier with EXA since AllocateFBMemory can use
 exaOffscreenAlloc directly, freeing a previous area if necessary and
 allocating a new one.  Likewise, FreeFBMemory can call exaOffscreenFree.
 
-EXA symbols
------------
-Drivers implementing EXA will also need some additional symbols from the
-X core: exaGetVersion, exaDriverInit, exaDriverFini, exaOffscreenAlloc,
-and exaOffscreenFree.  These must be added to your LoaderRefSymLists
-call at setup time.
-
 EXA teardown
 ------------
 At screen close time, EXA drivers should call exaDriverFini with their screen