Skip to content

Introduction

This page explains how to install the kernel modules for the Keyboard, Audio, Touchbar and the Ambient Light sensor with DKMS. You will need a patched kernel.

Do you need to do this?

Since many T2 distro maintainers package these modules with the kernel itself, you probabaly wouldn't need to install the modules manually. Although it can be used if you are using a kernel other than a T2 kernel provided by the maintainers here.

Are your keyboard and audio working? If no, then you'll need the BCE module.

To get started with this guide, first install the dkms package.

You may have been using an outdated kernel or your distribution may have been using kernel modules that do not match the ones listed below (check using dkms status or ls -l /usr/src). If the version of apple-bce in the output is 0.1, you have to uninstall the old modules first to avoid any compatibility issues by running:

sudo dkms uninstall -m apple-bce -v 0.1
sudo dkms uninstall -m apple-ibridge -v 0.1
sudo rm -r /usr/src/apple-bce-0.1
sudo rm -r /usr/src/apple-ibridge-0.1
sudo rm -r /var/lib/dkms/apple-bce
sudo rm -r /var/lib/dkms/apple-ibridge

Installing modules

  1. Installing the BCE (Buffer Copy Engine) module for Keyboard and Audio

    • If you are on a Debian or Ubuntu based distro, you can install it from AdityaGarg8's APT repo by running sudo apt install apple-bce

    • For other distros run sudo git clone https://github.com/kekrby/apple-bce /usr/src/apple-bce-0.2

    • Now run sudo dkms install -m apple-bce -v 0.2. If on a live ISO, use sudo dkms install -m apple-bce -v 0.2 -k x.x.x-mbp instead and change x.x.x-mbp to the kernel that you have installed, as by default dkms will try to build the module for the kernel that the live iso is using, which will most likely be older.

  2. Load the modules into the kernel

    Note

    This is only necessary if you wish to use the modules right away. If you are installing modules from a live iso the commands will fail as the modules have only been installed for the kernel you specified.

    sudo modprobe apple_bce

The Touchbar and keyboard should be working. For audio, you'll also need some config files, refer to the Audio Config guide.

Make modules load on boot

Ubuntu

Ubuntu users may skip this step as it's already set up in their distro. If the modules are still not loading on boot, then you may follow this section.

echo apple-bce | sudo tee /etc/modules-load.d/t2.conf

Make modules load on early boot

Having the apple-bce module loaded early allows the use of the keyboard for decrypting encrypted volumes (LUKS). It also is useful when boot doesn't work, and the keyboard is required for debugging. To do this, one must ensure the apple-bce module as well as its dependent modules are included in the initial ram disk. If your distro uses initramfs-tools (all debian-based distros), then /etc/initramfs-tools/modules stores a list of extra modules to be included and loaded at early boot time. Run sudo su to open a shell as root and run the following over there:

cat <<EOF >> /etc/initramfs-tools/modules
# Required modules for getting the built-in apple keyboard to work:
snd
snd_pcm
apple-bce
EOF
update-initramfs -u

Other distros use a different initramfs module loading mechanism. For example in Arch ensure that the /etc/mkinitcpio.conf file has:

MODULES="apple-bce"

And then run sudo mkinitcpio -P. See your distro-specific instructions for configuring apple-bce to added to your initramfs.

Setting up the Touch Bar

The Touch Bar can be set up by running this script in Linux using bash /path/to/script. Make sure your Linux kernel and macOS is updated before running this script.

If you are running Ubuntu, its recommended to run the following as well and rebooting :-

sudo rm /etc/modprobe.d/apple-touchbar.conf
sudo rm /etc/modules-load.d/apple-bce.conf
sudo rm /etc/modules-load.d/applespi.conf
echo apple-bce | sudo tee /etc/modules-load.d/t2.conf

After running this script, if you wish to change the default mode of the Touch Bar, run sudo touchbar and choose the mode you wish.

In case your Touch Bar is unable to change modes on pressing the fn key, you could try the following :-

  • Try adding usbhid.quirks=0x05ac:0x8302:0x80000 as a Kernel Parameter using your Bootloader.
  • Try running the following and rebooting.
echo -e "# delay loading of the touchbar driver\ninstall apple-ib-tb /bin/sleep 7; /sbin/modprobe --ignore-install apple-ib-tb" | sudo tee /etc/modprobe.d/delay-tb.conf >/dev/null
  • Boot into the macOS Recovery and then restart into Linux.
  • Unplug all the external USB keyboards and mouse and then restart into Linux, keeping them unplugged.

If you still face an issue, mention it here or on the discord.

Fixing Suspend

Copy this script to /lib/systemd/system-sleep/rmmod_tb.sh

If you are using Gentoo with OpenRC, instead copy the script to /lib64/elogind/system-sleep/rmmod_tb.sh

Now run :-

sudo chmod 755 /lib/systemd/system-sleep/rmmod_tb.sh
sudo chown root:root /lib/systemd/system-sleep/rmmod_tb.sh

Change the path to /lib64/elogind/system-sleep/rmmod_tb.sh if using OpenRC on Gentoo as mentioned previously.

It unloads the Touchbar modules as they can cause issues for suspend.