6. Optional Driver Functions

The functions outlined here can be called from the XFree86 common layer, but their presence is optional.

6.1. Mode Validation

When a mode validation helper supplied by the XFree86-common layer is being used, it can be useful to provide a function to check for hw specific mode constraints:

ModeStatus ChipValidMode(int index, DisplayModePtr mode,
          Bool verbose, int flags)

Check the passed mode for hw-specific constraints, and return the appropriate status value.

This function may also modify the effective timings and clock of the passed mode. These have been stored in the mode's Crtc* and SynthClock elements, and have already been adjusted for interlacing, doublescanning, multiscanning and clock multipliers and dividers. The function should not modify any other mode field, unless it wants to modify the mode timings reported to the user by xf86PrintModes().

The function is called once for every mode in the XF86Config Monitor section assigned to the screen, with flags set to MODECHECK_INITIAL. It is subsequently called for every mode in the XF86Config Display subsection assigned to the screen, with flags set to MODECHECK_FINAL. In the second case, the mode will have successfully passed all other tests. In addition, the ScrnInfoRec's virtualX, virtualY and displayWidth fields will have been set as if the mode to be validated were to be the last mode accepted.

In effect, calls with MODECHECK_INITIAL are intended for checks that do not depend on any mode other than the one being validated, while calls with MODECHECK_FINAL are intended for checks that may involve more than one mode.

6.2. Free screen data

When a screen is deleted prior to the completion of the ScreenInit phase the ChipFreeScreen() function is called when defined.

void ChipFreeScreen(int scrnindex, int flags)

Free any driver-allocated data that may have been allocated up to and including an unsuccessful ChipScreenInit() call. This would predominantly be data allocated by ChipPreInit() that persists across server generations. It would include the driverPrivate, and any ``privates'' entries that modules may have allocated.