Optional Driver Functions

XFree86 X server ``New Design'' (DRAFT) : Optional Driver Functions
Previous: Control Flow in the Server and Mandatory Driver Functions
Next: Recommended driver functions

## 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.

XFree86 X server ``New Design'' (DRAFT) : Optional Driver Functions
Previous: Control Flow in the Server and Mandatory Driver Functions
Next: Recommended driver functions