Jose,
Thanks for doing this. I forgot to mention a couple of items on
monday. Here's some updates.
"Jos� Fonseca" wrote:
>
> In the following of last IRC meeting, here is a draft of a FAQ with what
> was said. Comments are welcome.
>
> Regards,
>
> Jos� Fonseca
>
> Binary compatibility
> ====================
>
> 1. What does binary compatibility means?
>
> It means that that driver binaries made on previous releases
> should work with newer versions.
>
>
> 2. 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 intelectual property they don't want to release.
> Binary only components can be released, but they will need to support many
> different flavors of release.
>
> - For sake of our driver suite binary releases.
We can clarify which binary releases:
- To support driver suite binary releases created by DRI development
team.
> 3. Binary compatibility in practice.
Proper use of individual versioning components is important. The
version number is comprised of three fields seperated 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 Incompatability
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 compatability the we
*must* strive for.
In the event compatability 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.
> 3.1 Of the DRM...
The Device Specific Kernel DRM Driver...
>
> We have to maintain one direction of compatability in order to
> stay in the Linux kernel release. This can be acomplished 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 acording to Linus.
>
> NOTE: Even when we ignore this and break compatability 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/<OS>/drm/kernel/<driver>_drv.c
Verisoning checked by (service user):
2D Driver
(programs/Xserver/hw/xfree86/drivers/<driver>/<driver>_dri.c)
3D Driver (lib/GL/mesa/src/drv/<driver>/<driver>_screen.c)
>
>
> 3.2 In the SAREA...
>
> Removing a field is generally a "no, no" as it will readily break
> backward compatability.
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 compatable minor number bump.
Removal of fields would result in an incompatible major number bump, and
are *highly* discouraged.
> 3.2 Between the DDX and the GL driver...
3.2 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)
3.3 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
compatability.
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)
3.4 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)
3.5 Of the 3D Driver
The 3D driver is used by the libGL.so library. Versioning does not
exist for this interface, yet. However, great care should be taken to
not change the interface between the libGL.so library and the 3D
drivers.
-- /\
Jens Owen / \/\ _
[EMAIL PROTECTED] / \ \ \ Steamboat Springs, Colorado
_______________________________________________
Dri-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/dri-devel
