2021-10-15 mitch
All of the drivers for this project use the GPIO controller in the SoC for I/O.
The actual wiring of the phone is a microcosm of board design in general, and the abstraction used by modern Linux between board design and the kernel is the Device Tree (DT).  Spec here: https://www.devicetree.org/
In general, the DT defines how the components on the board are wired together, and, in my tiny use case, that mostly translates into which GPIO pins each component (dialer, hook, led) is using.
Rather than hardcode the GPIO pin numbers into the drivers, or pass them in as params, I'm trying to do this the "right" way and define them in DT overlays.

The .dts files in the driver directories are compiled into .dtbo (overlays) by the dtc tool (see Makefiles).  These can then be copied into /boot/overlays and referenced in /boot/config.txt.

The syntax of these .dts files isn't obvious, and the official specifications don't seem to mention labels, which are a crucial part of this use-case.  I found this article to be the most thorough and helpful: https://www.codeleading.com/article/28961607485/

This article is more specifically helpful: https://www.raspberrypi.com/documentation/computers/configuration.html#device-trees-overlays-and-parameters
in that it discusses the RPi use-case and some RPi (or Broadcom?) specific tools (dtmerge, dtdiff) for testing overlays, but it's light on actual syntax.

Ultimately, the purpose of these overlays is to give us a name to pass as the second argument to gpiod_get so that we can read from or write to GPIO pins in our driver.

Ex (from dialer.c): data_in = gpiod_get(&pdev->dev, "din", GPIOD_IN);

The "din" here corresponds to din-gpios in the DT overlay:

dialer {
    pinctrl-name = "default";
    pinctrl-0    = <&dialer_gpio>;
    compatible   = "phone,dialer";
    din-gpios    = <&gpio 0x11 0>;
    };

The value is a triple of: ref to gpio node (in the main DT), the actual GPIO pin number (in hex here, but decimal literals are also allowed), any GPIO flags (none, here).
