>Psychtoolbox>PsychDocumentation

PsychtoolboxKernelDriver - A low level support driver for Apple OS-X

The PsychtoolboxKernelDriver (PKD) is a MacOS-X kernel extension (a
kext). It currently should somewhat work with AMD/ATI Radeon graphics cards
of the X1000 series, as well as the HD2000 series up to the AMD RX 400 “Polaris”
graphics cards. Some recent Polaris gpu’s and all Vega gpu’s and later models
are unsupported at the moment.

On NVidia cards, only beamposition queries for high precision timestamping
are supported. Intel graphics chips are mostly not supported.

The driver needs to be manually installed by a user with administrator
privileges and provides a few special services to PTB-3, ie., PTB’s
functionality is extended/enhanced if it detects such a driver at startup
time:

* Beamposition queries (See help BeampositionQueries)) allow for
especially robust and accurate stimulus onset timestamping. They are
no longer supported by OS-X 10.9 and later and were not supported at all
on Intel based Macintosh computers with AMD/ATI or Intel graphics.
The driver restores this functionality for NVidia and AMD/ATI gpu’s.
Support for Intel gpu’s is disabled by default, as it can lead to system
crashes due to some unfixable incompatibility of Intel graphics hardware
which is completely out of our control.

* Multihead display sync: The driver allows to synchronize the display
refresh cycles of the displays connected to a multihead graphics card
to allow for high quality tear-free binocular and stereo stimulation of
subjects. This is only supported on AMD/ATI graphics cards.

* Use of 10 bit per color component framebuffers: The driver enabled two
extra bits of color output precision per color channel on your card,
allowing for 1 billion shades of different colors instead of the 16.8
million colors available without the driver. This was only supported on
AMD/ATI graphics cards and is no longer supported since Psychtoolbox 3.0.14,
as Apple sabotaged our ability to provide this functionality on OSX 10.11
and later.

* The driver implements workarounds to fix some problems caused by
graphics driver and operating system bugs when the graphics card is used
with high color/luminance precision display devices like the CRS Bits+ or
Bits# boxes, or the VPixx Inc. DataPixx and ViewPixx devices, and similar
equipment. This is only supported on AMD/ATI graphics hardware and may not
work anymore on latest AMD gpu’s or macOS versions – unknown.

The driver only works with one single graphics card at a time. On a
single-gpu system it will just work. On a MacBookPro hybrid-graphics
system with an integrated intel gpu and a discrete NVidia or AMD gpu, it
will automatically switch to use the proper gpu. On a multi-gpu system
with multiple discrete gpu’s, e.g., MacPro with multiple graphics cards
installed, it will use the default gpu zero by default. You can ask it use a
different gpu by calling the command PsychTweak(‘UseGPUIndex’, gpuidx);
to select gpu ‘gpuidx’ - numbering starts at zero. Then call clear
Screen, so Screen() actually picks up the new setting. Simultaneous use
of multiple gpu’s is not supported at this time.

As this driver accesses the hardware at a very low level, bypassing the
whole operating system, its graphics subsystem and drivers, there is
some potential for things to go wrong. Although our testing over 10 years
didn’t show any such problems, it could happen on some future OSX systems.
That is why this driver is considered a permanently experimental feature.

How to install (one time setup) - on OSX 10.11 “El Capitan” and later only

Install the PsychtoolboxKernelDriver64Bit.kext.zip, as exemplified here.

You must type this into the terminal:

cd /Library/Extensions/
sudo unzip /PathToPsychtoolbox/Psychtoolbox/PsychHardware/PsychtoolboxKernelDriver64Bit.kext.zip

“PathToPsychtoolbox” must be replaced with the path to the Psychtoolbox folder, e.g., if your
Psychtoolbox is installed under /Users/kleinerm/Psychtoolbox, then the above command would
look like this:

sudo unzip /Users/kleinerm/Psychtoolbox/PsychHardware/PsychtoolboxKernelDriver64Bit.kext.zip

This will automatically load the driver after a few seconds, and also after
each system restart.

If the driver fails to load, then please report it to the Psychtoolbox forum.
If it fails to load due to invalid cryptographic signatures you can disable
“System integrity protection” (SIP) as a temporary measure. The Internet will
tell you how to do that. This would make the kernel driver load, but reduce
resistance of your system against potential hacker/virus/trojan horses attacks
and other security threats.

If you are a user of OSX 10.13 “High Sierra” or later, the iToys company put up
some additional obstacles on top of all the awfulness of macOS. Read these
instructions if you get the error message “System policy prevents loading the kernel extension.”
from “kextload”, or it fails for some other reason:

https://developer.apple.com/library/content/technotes/tn2459/_index.html

If you are using macOS 10.14 “Mojave”, the driver may not load at all unless
you disable SIP. Apple put additional obstacles in our way, because Apple!

If you use some of the latest and most overprized Apple computers with some
models of “AMD Radeon Pro” 500 series RX gpu’s and Psychtoolbox doesn’t recognize
your graphics card, you may need to install this updated driver instead:

/PathToPsychtoolbox/Psychtoolbox/PsychHardware/PsychtoolboxKernelDriverUpTodDate_Unsigned.kext.zip

This driver is not yet cryptographically signed or attestated by us, so macOS may
throw extra obstacles into your way, e.g., not loading the driver automatically at
system boot, requiring you to do it manually with a kextload or kexttool command
from a terminal window. Disable SIP and other than that, good luck!

Another limitation on Apples latest “masterpieces” is that auto-detection of screen
to video output mappings may not work reliably on multi-display setups. Read how
to work around this in “help DisplayOutputMappings”.

How to upgrade with a more recent version, bundled with a new version of Psychtoolbox

You can unload and delete the driver before a driver upgrade via:

sudo kextunload /Library/Extensions/PsychtoolboxKernelDriver.kext
sudo rm -R /Library/Extensions/PsychtoolboxKernelDriver.kext

On older setups, the driver may reside in /System/Library/Extensions/, so
delete it from there if above does not work:

sudo kextunload /System/Library/Extensions/PsychtoolboxKernelDriver.kext
sudo rm -R /System/Library/Extensions/PsychtoolboxKernelDriver.kext

Then you can follow the instructions for installation above.

If everything went well, Psychtoolbox will report availability (and its
use) of the driver the first time the Screen() mex file gets loaded and
used. If it doesn’t happen immediately, type “clear Screen” to force a
reload of Screen.