Graphics Blocklisting

This document is a work in progress based on https://wiki.mozilla.org/Blocklisting/Graphics. Please contact Anthony Hughes if you have any questions or feedback.

What is Blocklisting?

In simple terms, blocklisting turns off Firefox's ability to use certain features provided by the graphics chipset driver in a computer or mobile device. Often times we will blocklist a driver because it causes serious security, stability, or usability issues. We must always weigh the pros and cons of blocklisting since it can have a negative performance side effect for some users.

Types

Firefox references a built-in and a downloadable blocklist. The graphics team will decide which blocklist to update based on urgency of the issue at hand. The built-in blocklist is easier to manage from an engineering standpoint but takes longer to deploy since it requires a Firefox version update. The downloadable blocklist is faster to deploy but can be more difficult to manage from an engineering standpoint.

Gotchas

There are some things that one should be aware of when modifying or interpreting the blocklist for graphics.

Until version 41 (bug 1162299) any features in the blocklist would be interpreted as "all features" by the versions that do not know about those features. For example, FEATURE_STAGEFRIGHT was added in Gecko version 17. If FEATURE_STAGEFRIGHT was added to the downloadable blocklist, all versions prior to version 17 would automatically block all features that otherwise match that blocklist entry.
Until version 41 (bug 1162530) all blocklist entries applied to all Gecko versions. We introduced the graphics blocklist entry versioning, which let us specify the minimum and maximum version that any particular blocklist entry applies to. Note that the versions include nightly/aurora/beta suffixes, so if you wanted a blocklist entry to apply to all versions after version 42, for example, you would specify minVersion as 43.0a1.
Downloadable blocklists are usually only downloaded once a day, and cached in the profile directory (as blocklist.xml.) Modifying that file is often the best way to do local testing of changes, before proceeding with the staging of the modified blocklist file.
Even with the local blocklist file, note that we don't necessarily check against it every run, so your testing should involve multiple runs.

Requesting a Block

Before you request a blocklist update, make sure your issue meets one or more of the following criteria:

If a device/driver is thought to be causing Firefox to crash at startup
If a device/driver is thought to be causing Firefox to crash multiple times a day (even if recoverable)
If a device/driver is thought to be crashing itself in an extreme number of instances
If a device/driver is thought to be causing a severe negative impact on performance
If a device/driver is thought to be causing a visual glitch in Firefox (eg. artifacts, checkerboarding, screen tearing, etc)

Use one of the following templates to file your blocklist update request:

Once the request is received the following process will be followed:

	Downloadable	Built-in
1	The request will be discussed among Firefox release drivers, graphics developers, and other stakeholders.
2	The blocklist entry will be drafted once stakeholders agree to the terms, type, and validity of the request.
3	The blocklist entry will be pushed to the staging server	A test version of Firefox will be created with the updated blocklist
4	QA will verify the blocklist on the staging server	QA will verify the blocklist in the test version of Firefox
5	The blocklist update will be pushed to production	The new Firefox version will be released
6	QA may verify the blocklist on the production server	QA may verify the blocklist in the new Firefox version
7	The Blocked Graphics Drivers wiki page will be updated once the blocklist update is live.

By-passing a Blocklist

Warning: Use at your own risk -- there usually are good reasons why features get blocked.

If you would like to forcibly enable a graphics feature that is blocked on your system, follow these instructions.

To force-enable WebGL, go to about:config and set webgl.force-enabled=true.
To force-enable WebGL anti-aliasing, go to about:config and set webgl.msaa-force=true.
To force-enable Layers Acceleration, go to about:config and set layers.acceleration.force-enabled=true.
On Windows Vista and Windows 7, to force-enable Direct2D Content Acceleration, go to about:config and set gfx.direct2d.force-enabled=true.
On Android, to force-enable StageFright software decoding, go to about:config and set stagefright.force-enabled=true.

On Windows, you can also spoof your graphics system information to help debug driver blacklisting issues (see bug 604771):

Create spoofed-firefox.bat in the installation folder (e.g. C:\Program Files (x86)\Mozilla Firefox)
Set the new values of spoofed variables ending with a command to launch Firefox:
SET MOZ_GFX_SPOOF_WINDOWS_VERSION=60001
SET MOZ_GFX_SPOOF_VENDOR_ID=0x8086
SET MOZ_GFX_SPOOF_DEVICE_ID=0x0046
SET MOZ_GFX_SPOOF_DRIVER_VERSION=8.15.10.2302
"C:\Program Files (x86)\Mozilla Firefox\firefox.exe" -p -no-remote
Double-click spoofed-firefox.bat and create a profile if required
Click the Firefox button, then select Help, finally Troubleshooting Information and check the Graphics section.

If force-enabling a feature doesn't work, that probably means that your hardware doesn't support it. For example, layers acceleration currently requires support for 4Kx4K textures, which rules out some graphics cards, like the Intel G31/G33.

Questions

Are vendors consulted in the process of blocklisting and if so, do we have a process defined with them?