dri/ BinaryCompatability

Binary compatibility

This section is about the binary compatibility within the several parts that make a DRI driver.

What does binary compatibility means?

It means that that driver binaries made on previous releases should work with newer versions.

Why is it so important?

To avoid potential havoc. For example:

  • If a user installs that latest version of XFree86 -- they don't always know they need a new kernel module too -- and end up running with the older ones.
  • A vendor has intellectual property they don't want to release. Binary only components can be released, but they will need to support many different flavors of release.
  • To support driver suite binary releases created by DRI development team.

Binary compatibility in practice.

Proper use of individual versioning components is important. The version number is comprised of three fields separated by dots ".". The first field is the major number, the second the minor number and the third is the patch level.

Generally, the service provider sets the version number, and the initial revision is 1.0.0.

The service user checks the versioning with logic like: 

if (major_number != major_expected || minor_number < minor_expected) {
        Report Incompatibility
        Return Failure
}

If the interface between service provider and service user does not change, then the patch level is the only number that needs to be incremented in order to reflect internal bug fixes and/or updates.

When interface changes are made, care should be taken to preserve the ability for the new service provider to still work with older service users. Incrementing the minor revision number will account for this type of interface change. This is the backwards compatibility the we must strive for.

In the event compatibility must be destroyed, incrementing the major version number will be required. This option is highly discouraged.

The following sections outline a list of service providers, and which components utilize these sections.

Of the Device Specific Kernel DRM Driver...

We have to maintain one direction of compatibility in order to stay in the Linux kernel release. This can be accomplished by:

  • semantic change should create a new ioctl and leave support for the old semantics in the DRM module as well
  • bumping the minor revision number to give a mechanism to know if the new semantics were available Note: Check for different versions and fail gracefully is not a viable scenario according to Linus.

Note: Even when we ignore this and break compatibility completely -- we have to use versioning properly or we don't even get warnings and disabling. We get crashes!!!

Versioning set by (service provider):

  • Kernel DRM Driver (programs/Xserver/hw/xfree86/os-support/shared/drm/kernel/<driver>.h) Versioning checked by (service user):

  • 2D Driver (xc/programs/Xserver/hw/xfree86/drivers/<driver>/<driver>_dri.c)

  • 3D Driver (xc/lib/GL/mesa/src/drv/<driver>/<driver>_screen.c)

In the SAREA...

This is not a service provider by itself, rather it's a communication mechanism used by service providers. The versioning of the service provider should reflect any changes to the SAREA. Additions to the end would typically result in a backwards compatible minor number bump. Removal of fields would result in an incompatible major number bump, and are highly discouraged.

Of the 2D Driver...

These are less likely to get out of sync as the DRM module -- but it's still possible. Again, having good revision checking can save a lot of headaches later. If the versioning isn't accounted for we get hangs and crashes with mismatches.

We need to account for older versions, but not necessarily fully support -- we could fail gracefully --, although a driver suite supporter could decide to support older versions of one module or the other -- at their options. For example, let's say a hardware vendor released a binary DDX module for a special video out mode, then it would be nice if the 3D open source component worked with that module for as many versions as the initial interface allowed. So, even though we did many updates and releases, the old closed-source binary still worked.

Versioning set by (service provider):

  • 2D Driver (programs/Xserver/hw/xfree86/drivers/<driver>/<driver>_dri.c) Versioning checked by:

  • 3D Driver (lib/GL/mesa/src/drv/<driver>/<driver>_screen.c)

Of the Device Independent DRM Library...

Unlike the individual device dependent components in the kernel, this versioning reflects the overall DRM Library API supported by the libdrm.a component. A few device extensions were added to this API, and have since been converted to use the generic drmCommand mechanism. All new extensions should exclusively use drmCommand. The older existing device extensions are still available strictly for backwards compatibility.

The 3D Driver does not check this because this module is staticly linked, and consequently is always the matching version.

Versioning set by (service provider):

  • DRM Library (programs/Xserver/hw/xfree86/os-support/<os>/drm/xf86drm.c) Versioning checked by:

  • 2D Driver (programs/Xserver/hw/xfree86/drivers/<driver>/<driver>_dri.c)

Of the DRI Server Extension...

This reflects the version of the DRI X11 protocol extension.

Versioning set by (service provider):

  • DRI Extension Module (programs/Xserver/GL/dri/dri.c) Versioning checked by:

  • 3D Driver (lib/GL/mesa/src/drv/<driver>/<driver>_screen.c)

Of the 3D Driver...

The 3D driver is used by the libGL library. Versioning does not exist for this interface, yet. However, great care should be taken to not change the interface between the libGL library and the 3D drivers.

-- JensOwen