# Trying to write keyboard SPI drivers for MacBook Pro (15-inch, 2017) MacBookPro14,3



## soongrazer (Oct 12, 2020)

I have a MacBook Pro (15-inch, 2017) and I want to run FreeBSD on it natively. But the built-in keyboard, trackpad and Touch Bar do not work. External keyboards and mice attached via USB work. 

So I want to write a driver for the keyboard first; I will write the drivers for the rest afterwards. Linux kernel 5.3 has drivers for newer keyboards and trackpads but not for the Touch Bar.
kernel/git/torvalds/linux.git - Linux kernel source tree

I am reading Part II. Device Drivers from FreeBSD Architecture Handbook. I have listed the hardware with `ioreg` command from macOS.

The result of `ioreg -flir -n SPI1` is attached.

I want to know if *writing a driver for the hardware without documentation could damage the hardware*, as I am using my work computer. Also please suggest me what I should read further to write FreeBSD drivers.


----------



## ralphbsz (Oct 12, 2020)

Ask yourself this question: What persistent state does a keyboard have which would survive power cycling? For example, if it were a disk drive, you could overwrite data with a defective driver (been there, done that).

So the likely chances are: firmware downloads, and persistent configuration changes. Mac's famously have PRAM (parameter RAM), which holds persistent configuration information, and when it gets scrozzled, the machine won't boot. So look at the documentation for that kind of thing. Just as an example: Maybe the keyboard can be remapped? If you remap all keys to be the letter X, then the machine will boot, but you'll never enter a password again (unless your password was XXXX). The end ...


----------



## soongrazer (Oct 31, 2020)

I got more information about the hardware. I have attached the output of `acpidump -dt`.

At line number 7592 is the SPI keyboard and trackpad.

```
Name (_HID, EisaId ("APP000D"))  // _HID: Hardware ID
```

I am taking reference from the corresponding Linux driver in Linux source tree. In Linux driver source, it matched using ACPI Based Device Enumeration. The table in the source is like this.

```
static struct spi_driver applespi_driver = {
    .driver        = {
        .name            = "applespi",
        .acpi_match_table    = applespi_acpi_match,
        .pm            = &applespi_pm_ops,
    },
    .probe        = applespi_probe,
    .remove        = applespi_remove,
    .shutdown    = applespi_shutdown,
};

module_spi_driver(applespi_driver)
```

I don't know what the equivalent in FreeBSD is. I have tried Character Devices and PCI Devices examples and I can't find how to match that ID.

I would like to know how to match the device by HID, *APP000D* in FreeBSD. Please help. Thanks in advance.


----------



## mark_j (Nov 3, 2020)

Doesn't the FreeBSD kernel expose this via /dev/spigen0?
What's all the stuff in spibus in /sys/dev?
Anyway, you'll probably have more luck if you join freebsd-hackers mailing list.


----------



## George (Nov 3, 2020)

soongrazer said:


> I want to know if *writing a driver for the hardware without documentation could damage the hardware*, as I am using my work computer.



Loading a driver into the kernel with `kldload` can cause a kernel panic. This can harm your mounted file systems. So don't use your work computer.

The resources are scarce. There is an outdated book on writing drivers (Device Drivers for the interpred). E.g. it doesn't cover libusb for usb devices.
There is the architecture handbook, but it provides only an overview. Then there are man files in section 9, e.g. DRIVER_MODULE(). Finally, there is the source code of linux and freebsd (e.g. in github). Look at keyboard drivers and try to understand some of the code.. That's where everything starts...


----------



## soongrazer (Nov 4, 2020)

Elazar said:


> Loading a driver into the kernel with `kldload` can cause a kernel panic. This can harm your mounted file systems. So don't use your work computer.
> 
> The resources are scarce. There is an outdated book on writing drivers (Device Drivers for the interpred). E.g. it doesn't cover libusb for usb devices.
> There is the architecture handbook, but it provides only an overview. Then there are man files in section 9, e.g. DRIVER_MODULE(). Finally, there is the source code of linux and freebsd (e.g. in github). Look at keyboard drivers and try to understand some of the code.. That's where everything starts...


Thanks for your explanation. I will try. 

Currently I do my work on macOS. I installed FreeBSD on a partition in the same SSD where macOS is installed. When in FreeBSD, it only mount its partitions / and swap. macOS partition is untouched I think. If kernel panic can also damage other partitions, then I will just backup.


----------



## msplsh (Nov 4, 2020)

Have you poked around with this yet

spi(8)


----------



## soongrazer (Nov 4, 2020)

mark_j said:


> Doesn't the FreeBSD kernel expose this via /dev/spigen0?
> What's all the stuff in spibus in /sys/dev?
> Anyway, you'll probably have more luck if you join freebsd-hackers mailing list.


I do not see /dev/spigen0.
I will reply back with what I found in /sys/dev.
And I will join the mailing list. Thanks.


----------



## soongrazer (Nov 4, 2020)

msplsh said:


> Have you poked around with this yet
> 
> spi(8)


I see the spi(8) command. I cannot use that since there is no SPI devices listed in /dev.


----------



## mark_j (Nov 4, 2020)

soongrazer said:


> I do not see /dev/spigen0.
> I will reply back with what I found in /sys/dev.
> And I will join the mailing list. Thanks.


I've only able to see spigen devices on ARM7/64, but it may give you hints to integration to the kernel for amd64.

See /usr/src/sys/dev/arm64/conf/GENERIC

Edit: As I recall, the SPI implementation by FreeBSD is very rudimentary, so back to your original concern about harming the laptop, I think the only issue would be interrupts (or lack thereof in FreeBSD) and therefore being forced to use polling, which will inevitably eat into battery life. How much I don't know, I can't speculate the figure, just a 'gut feel' given that polling inevitably uses more cpu.


----------



## msplsh (Nov 4, 2020)

Well, you'll have to get SPI working before you can get the keyboard working, I think, based on the IOReg output.


----------



## unrelentingtech (Nov 3, 2021)

I am developing the MacBook SPI input driver, it mostly works already but there's quite a lot of work still required to finish it.

https://reviews.freebsd.org/D29249 is a patch for SPI itself working, only tested on Broadwell (2015) so far, it would be pretty helpful to check operation on a Kaby Lake machine. The "Test Plan" in phabricator lists all the things required just to observe some interesting packets.. well, it's not a very detailed description, but maybe you can figure it out


----------

