==========================================
Pin control — TLMM and the PMIC GPIOs
==========================================

The pin multiplexer and the GPIO wiring, from the device tree, the overlays, and
the XBL config. This is the "which pin does what" map a replacement bootloader
needs before it can drive a UART, a bus, or a reset line. Everything here is
static: TLMM node and base pin groups from ``artifacts/boot_a/board.dts``, the
board GPIO assignments from the ``dtbo_a`` overlays, and the pin-config keys from
``uefiplat.cfg`` in ``_READONLY/lun1/xbl_a.bin``.

There are **six** pin controllers on the device: the SoC TLMM plus five PMIC
GPIO blocks.

The SoC TLMM
============

``pinctrl@f100000``, ``compatible = "qcom,lagoon-pinctrl"`` — the Top-Level Mode
Multiplexer.

:Register window: **0xF100000** size **0x300000** (3 MiB — the three TLMM tiles).
   XBL's MMAP names it ``"TLMM" 0x0F000000 size 0x1000000`` as a single window,
   with the per-tile sub-ranges (``TLMM_SOUTH`` 0x0F100000, ``TLMM_WEST``
   0x0F500000, ``TLMM_EAST`` 0x0F900000, each 0x300000) commented out — XBL maps
   the whole block flat.
:GPIO / IRQ controller: ``gpio-controller`` (``#gpio-cells = 2``) +
   ``interrupt-controller`` (``#interrupt-cells = 2``). Nine summary SPIs
   ``0xD0``–``0xD8`` (208–216) aggregate the per-tile GPIO interrupts.
:Line count: the tree names pin groups up to ``gpio94`` and routes wakeup lines
   up to ``gpio155`` (below), i.e. the lagoon TLMM's full ``gpio0``–``gpio15x``
   range; the exact ``ngpios`` is not a property in this tree.
:Wakeup: ``wakeup-parent`` = the **PDC** (``phandle 0x27``) — GPIO wake events are
   routed to the always-on PDC so the AP can be woken from deep sleep
   (:doc:`/soc/aop`).

SoC-function pin groups (base DTB)
----------------------------------

The base tree muxes the on-die controllers onto their pads. These are the groups
a bootloader reprograms to bring a bus up:

.. list-table::
   :header-rows: 1
   :widths: 22 26 52

   * - Function
     - Pins
     - What it is
   * - ``qup00``
     - gpio0–3
     - QUP0-0 (I2C/SPI/UART), :doc:`/boot/qup-buses`
   * - ``qup01``
     - gpio61–64
     - QUP0-1
   * - ``qup02``
     - gpio45,46,56,57
     - QUP0-2
   * - ``qup10``
     - gpio13–16
     - QUP1-0
   * - ``qup11``
     - gpio27,28
     - QUP1-1
   * - ``qup12``
     - gpio19,20
     - QUP1-2
   * - ``qup13_f2``
     - gpio25,26
     - QUP1-3 — the **debug/console UART** (``serial0`` = ``qup_uart@98c000``)
   * - ``qup14``
     - gpio4,5
     - QUP1-4
   * - ``CCI_I2C``
     - gpio2,3 / gpio39,40 / gpio41,42 / gpio43,44
     - the four camera-control I2C (CCI) buses
   * - ``CAM_MCLK0``–``4``
     - gpio29,30,31,32,33
     - camera master clocks
   * - ``MDP_VSYNC``
     - gpio23
     - display TE / vsync
   * - ``qdss_cti``
     - gpio87
     - QDSS cross-trigger (debug)

The ``CCI_I2C`` / ``CAM_MCLK`` groups exist because the SM6350 reference design is
a camera SoC; on this e-reader they are unused (:doc:`absent-hardware`). The one
group a bootloader really cares about is ``qup13_f2`` on **gpio25/26**, the
console UART.

PDC wakeup routing
------------------

The TLMM ``irqdomain-map`` pins 87 GPIOs to individual PDC interrupt lines, so
each can wake the SoC from a low-power island. The full ``gpio → PDC-line`` map
(from the tree)::

   g3→126  g4→151  g7→58   g8→113  g9→66   g11→106 g12→59  g13→112
   g16→73  g17→74  g18→75  g19→76  g21→130 g22→96  g23→146 g24→114
   g25→83  g27→84  g28→85  g34→147 g35→92  g36→93  g37→94  g38→68
   g48→100 g50→57  g51→81  g52→80  g53→69  g54→71  g55→70  g57→152
   g58→115 g59→116 g60→117 g61→118 g62→119 g64→121 g66→127 g67→128
   g69→60  g73→78  g78→135 g82→138 g83→140 g84→141 g85→98  g87→88
   g88→107 g89→109 g90→110 g91→111 g92→149 g93→101 g94→61  g95→65
   g96→95  g97→72  g98→145 g99→150 g100→108 g104→129 g107→131 g110→132
   g112→133 g114→134 g116→136 g118→137 g122→97 g123→99 g124→148 g125→82
   g128→144 g129→86 g131→87 g133→142 g134→143 g136→102 g137→91 g138→77
   g139→79 g140→90 g142→103 g144→105 g147→104 g153→120 g155→67

The console (``g25``), the touch/pen IRQs, the hall sensor, the fingerprint IRQ
and the keyboard wake line (below) are all in this set, so all of them can wake
the device.

Board GPIO wiring (overlays)
============================

The production peripheral wiring is added by the ``dtbo`` overlays (each pin is
muxed to plain ``gpio`` and driven/read by a driver). Pin numbers are the second
cell of each ``<&tlmm N flags>`` reference; ``AL`` marks ``flags = 1``
(active-low):

.. list-table::
   :header-rows: 1
   :widths: 30 14 56

   * - Signal
     - GPIO
     - Peripheral
   * - Capacitive-touch IRQ
     - gpio22
     - touch controller (``pt_tp@24``), on QUP
   * - Capacitive-touch reset
     - gpio21
     - "
   * - Touch VDD / VCC enable
     - gpio88 / gpio89
     - "
   * - Pen (EMR) IRQ
     - gpio52
     - Wacom digitiser (``wacom@09``)
   * - Pen reset
     - gpio54
     - "
   * - Pen VDD / VCC enable
     - gpio10 / gpio49
     - "
   * - Hall-sensor IRQ
     - gpio99
     - cover/lid magnet (``onyx_hall``) — wake source
   * - Fingerprint IRQ
     - gpio17
     - fingerprint sensor (SPI)
   * - Fingerprint reset
     - gpio18
     - "
   * - Fingerprint SPI-CS
     - gpio16
     - "
   * - Front-light EN (×2)
     - gpio11 / gpio73
     - two ``lm3630a`` backlight drivers (warm + cold LEDs)
   * - Keyboard ID / ID2
     - gpio140 / gpio155
     - pogo-pin keyboard detect (``onyx-keyboard``)
   * - Keyboard VCC-ctrl
     - gpio139
     - "
   * - Keyboard wake
     - gpio60
     - "
   * - SD card-detect
     - gpio94 ``AL``
     - microSD socket (:doc:`storage`, SDCC2)
   * - EPD-FPGA SPI-CS
     - gpio57
     - e-ink controller FPGA (``lfcpnx@0``)
   * - EPD-FPGA 12 V core EN
     - gpio58
     - "
   * - EPD-FPGA 30 V EN
     - gpio97
     - "
   * - EPD-FPGA reset
     - gpio122 ``AL``
     - "
   * - EPD-FPGA standby
     - gpio96 ``AL``
     - "
   * - EPD-FPGA program enable / init / done
     - gpio38 ``AL`` / gpio9 ``AL`` / gpio8
     - FPGA bitstream load handshake

The EPD-FPGA lines are the front-end of the e-ink pipeline
(:doc:`/display/panel`): the SoC gates the panel's 12 V / 30 V rails, holds
the FPGA in reset/standby, and loads its bitstream over SPI before any waveform
is driven.

PMIC GPIO controllers
=====================

Each PMIC exposes a ``qcom,spmi-gpio`` block (an ``ngpios`` = window÷0x100):

.. list-table::
   :header-rows: 1
   :widths: 22 12 14 14 38

   * - PMIC (USID)
     - Node
     - Window
     - GPIOs
     - Notes
   * - PM6350 (0)
     - ``pinctrl@c000``
     - 0xC000/0x900
     - 9
     - master PMIC (:doc:`/soc/pmic`)
   * - PM7250B (2)
     - ``pinctrl@c000``
     - 0xC000/0xC00
     - 12
     - charger / Type-C PMIC
   * - PM6150L (4)
     - ``pinctrl@c000``
     - 0xC000/0xC00
     - 12
     - "L" companion PMIC
   * - PMK8350 (6)
     - ``pinctrl@b000``
     - 0xB000/0x400
     - 4
     - measurement PMIC (RTC/ADC)
   * - PM8008 (8)
     - ``pinctrl@c000``
     - 0xC000/0x200
     - 2
     - **I²C** camera PMIC (``qcom,i2c-pmic``) — vestigial, see :doc:`absent-hardware`

The PMK8350 block is at SPMI base ``0xB000`` (the others at ``0xC000``); PM8008 is
an I²C-attached PMIC (``qcom,i2c-pmic``), not SPMI, and part of the unused camera
subsystem.

XBL / boot-time pin config
==========================

``uefiplat.cfg`` carries the pin configs XBL applies before Linux:

- ``EnableSDHCSwitch = 0x1``; ``Sdc1GpioConfigOn = 0x1E92`` /
  ``Sdc2GpioConfigOn = 0x1E92`` (active drive/pull) and ``…Off = 0xA00`` (parked)
  — the SDCC pad configs (:doc:`storage`).
- XBL and ABL both log to the console SE on ``qup13_f2`` (above)
  (:doc:`/boot/qup-buses`, :doc:`/boot/below-uefi`).

Static end
==========

The pin *routing* (function per pad, wakeup mapping, board GPIO assignments) is
fully recovered from the tree, overlays and XBL config — nothing here needs a
device. What a *register dump* would add is only the live per-pad electrical
state (the TLMM ``drive-strength`` / ``bias`` / output-value registers at
``0xF100000 + tile``), which the tree specifies per pinctrl state but which the
boot chain reprograms as drivers claim pins; that is a runtime value, not a
static datum, and is XPU-open (TLMM is ``NS_DEVICE``) so it is the one part that
could be confirmed on a live device.

Provenance
==========

:Source: ``artifacts/boot_a/board.dts`` (``pinctrl@f100000`` node, base pin
   groups, ``irqdomain-map``, the five ``qcom,spmi-gpio`` nodes),
   ``artifacts/dtbo_a/overlay_0.dts`` (board GPIO assignments),
   ``_READONLY/lun1/xbl_a.bin`` (``uefiplat.cfg`` TLMM/SDCC keys).
:Method: DTB + overlay node reading; ``irqdomain-map`` decoded (5-cell
   ``gpio,0,pdc,line,0`` tuples); PMIC ``ngpios`` from window size. No code
   executed.
:Cross-refs: :doc:`/boot/qup-buses` (QUP SE ↔ pin detail), :doc:`storage`
   (SDCC/UFS pins), :doc:`/display/panel` (EPD-FPGA lines),
   :doc:`/soc/pmic` (PMIC USIDs), :doc:`/soc/aop` (PDC wakeup),
   :doc:`absent-hardware` (camera CCI/MCLK, PM8008).