Writing a Driver

What remains is the technical problem of developing drivers and extensions for XFree86. This still is a very dificult task, but that as well has become easier. After unpacking the XFree86 sources a detailed design document can be found at xc/programs/Xserver/hw/xfree86/doc/DESIGN This document covers the important details of the new server design and provides step by step analysis of the flow of control in the server, the mandatory interfaces that a driver needs to provide and the optional driver functions. Furthermore the data structures used in the drivers are defined and explained, handling of bus resources and the helper functions that the server provides for commonly needed tasks in a driver.

While all the details are in this design document, a quick overview of the necessary parts shall be given here.

• a ModuleData variable as described above that contains the necessary information to load and initialize the module

  
  static MODULESETUPPROTO(zzzSetup);
  
  XF86ModuleData zzzModuleData = 
  	{ &zzzVersRec, zzzSetup, NULL };
  

  a sample version info would look like this

  
  static XF86ModuleVersionInfo zzzVersRec =
  {
   "zzz",
   MODULEVENDORSTRING,
   MODINFOSTRING1,
   MODINFOSTRING2,
   XF86_VERSION_CURRENT,
   ZZZ_MAJOR_VERSION, 
   ZZZ_MINOR_VERSION, 
   ZZZ_PATCHLEVEL,
   ABI_CLASS_VIDEODRV,
   ABI_VIDEODRV_VERSION,
   MOD_CLASS_VIDEODRV,
   {0,0,0,0}
  };
  

  The MODULEVENDORSTRING would usually be i "The XFree86 Project" or the corresponding information for the vendor creating this module. The two MODINFOSTRINGs are magical values that identify allow to find the VersionInfo in a module (for example for use in a signing tool). Next comes the version of XFree86 that this module was built again and the version of the module itself. Then the ABI class and version as well as the module class. The final four integers are intended to hold the digital signature of the module.

• a Setup() function is needed to integrate the module into the XFree86 loader architecture. This function follows the ABI specification for loadable modules and makes the module functions and data available to the server.

  
  static pointer
  zzzSetup(pointer module, pointer opts, 
           int *errmaj, int *errmin)
  

  The Setup() function needs to call xf86AddDriver() in order to register the module as a driver.

• an Identify() function that prints out some identifying message is mandatory.

  
  static void
  ZZZIdentify(int flags)
  {
   xf86PrintChipsets(ZZZ_NAME, 
       "driver for ZZZ Tech chipsets",
       ZZZChipsets);
  }
  

• a Probe() function is needed that locates the hardware that this driver supports (normally some type of graphics device) and registers this driver as driver for the resource. The Probe should be as unintrusive as possible. It must not modify any settings in the hardware and should not touch any hardware except the devices that are supported by this driver.

  
  static Bool
  ZZZProbe(DriverPtr drv, int flags)
  

  for most current hardware the Probe() function can use information from the PCI data to verify if a supported card is available. A helper function xf86MatchPciInstances() is available to make matching PCI devices easier.

• a PreInit() function collects all the information that is necessary to determine the configuration of the hardware and to prepare the device for being used, without making any changes to the device at this stage. Again this function should be as unintrusive as possible.

  
  static Bool
  ZZZPreInit(ScrnInfoPtr pScrn, int flags)
  

  Information that is filled in here includes things obtained from the XF86Config file (e.g., the Monitor info, the amount of video memory, if it was given in the config file), defaults for color depth and bits per pixel (bpp), visual, gamma correction, etc.

  Additional, non-intrusive probing of hardware is done for that type of information that has not been given in the config file (e.g., exact type of chipset, amount of video memory, etc.).

  Next the video modes given in the config file are validated against the restrictions that the hardware puts on video modes.

  Finally, this function loads the submodules necessary for driving the hardware (e.g., the vgahw module for VGA compatible cards) and the framebuffer code.

• Save() and Restore() functions provide a means to save and restore the complete video state of the device. While these functions are not mandatory they are a very useful abstraction of a commonly needed task.

  
  static void
  ZZZSave(ScrnInfoPtr pScrn)
  
  static void
  ZZZRestore(ScrnInfoPtr pScrn)
  

• a ModeInit() function is used to setup a new video mode. This is again a recommended function but not part of the mandatory interfaces.

  
  static Bool
  ZZZModeInit(ScrnInfoPtr pScrn, 
              DisplayModePtr mode)
  

• a ScreenInit() function is needed to hook the driver into the server and to setup the initial video mode (using ModeInit()). This is (in the flow of control) the first function that should modify the device.

  
  static Bool
  ZZZScreenInit(int scrnIndex, 
                ScreenPtr pScreen, 
                int argc, 
                char **argv)
  

  This functions need to initialize the device independent parts of the X server as well. This includes informing setting up the visual type ( miSetVisualTypes()), initializing the framebuffer (by calling the framebuffer ScreenInit() function, e.g. cfbScreenInit()), creating the initial color map, etc.

• EnterVT() and LeaveVT() functions are needed to allow switching to and from the X server.

  
  static Bool
  ZZZEnterVT(int scrnIndex, int flags)
  
  static void
  ZZZLeaveVT(int scrnIndex, int flags)
  

• a SaveScreen() function is mandatory to blank the screen.

  
  static Bool
  ZZZSaveScreen(ScreenPtr pScreen, 
                Bool unblank)
  

• a CloseScreen() function is used to reset the device to its original state.

  
  static Bool
  ZZZCloseScreen(int scrnIndex, 
                 ScreenPtr pScreen)
  

Once these functons are implemented and hooked together, a non-accelerated driver for the device is available and can be tested. Adding accelleration to this driver (using the XFree86 Acceleration Architecture XAA) is relatively straight forward and again well documented in the XAA documentation which can be found at xc/programs/Xserver/hw/xfree86/xaa/XAA.HOWTO

Summary and Conclusion

In summary, on the one hand, the documentation of the new ddx (devive dependent X) design in XFree86 has significantly improved over the previously available material. On the other hand, the structure and layering of the server itself has become much more straight forward. Many of the previously existing SVGA-isms have been removed, many other implicit assumptions about the design of the bus and the existence of one single graphics card are gone as well.

Following the design document it is fairly straight forward to implement a multi head capable driver for almost any type of graphics device.

The DDK

The next major step forward will be the advent of a real DDK, a real driver development kit. As of this writing, this is not finished, since we need to release 4.0 before we can focus on the DDK. But the design of XFree86 4.0 is finished, the initial release will happen before this paper is going to print, and in summer 2000 a release of a full DDK is planned.

So while this paper will have to skip the description of the DDK, I should be able to talk about this during my presentation at the conference.