The porting flow covers the macos-27.3-26C5035r profile from profile selection to the porting record: the macOS profile page lists the profile contents, host inputs, board.toml override, Data seed, build commands, driver adaptations and boot checkpoints, and the steps, arm64e, packaging, records, bring-up, building, requirements and reference pages point to it. The iPadOS instructions are unchanged. Porting pages link porting pages for driver topics: Develop a driver and Brightness interface are porting pages, and component names in porting pages are plain text. English and Chinese pages.
7.6 KiB
Touch, button and keyboard adaptation
Complete display geometry and interrupt/DMA setup. Record touch-controller model, firmware, matrix geometry, physical orientation, bus wiring, reset/IRQ pins and the OS HID ABI.
Use driver build integration to connect initialization, archive recipes and the OS ABI, then run this page's hardware checks.
Sources and interfaces
These links identify reviewed source revisions. Match interfaces to the selected SoC, component and OS versions. The linked device sources provide board integration examples.
| Implementation | Source | What to read and implement |
|---|---|---|
| Bus and sensor | GeniSpi.h, NvtProtocol.h | nvt_bus, chip identification, firmware download and frame reads |
| Contact processing | NvtTouchCore.c | Matrix processing and contact tracking for the supported sensor |
| Board integration | TouchBoard.h, TouchProbe.cpp | Power/reset, transport callbacks, interrupt handling and coordinates |
| Keyboard cover | Wn8030.h, KeyboardProbe.cpp, KeyboardCover.cpp | Controller image load, frame codec, attach and hall gating, one HID device for keyboard and touchpad |
| OS reports | NativeHidInput.cpp, ButtonProbe.cpp | IOHIDDevice, report descriptors, coherent contact snapshots and button events |
1. Select the transport and sensor protocol
Read QcomGeniSpi,
ShengNovatekTouch and
ShengHidInput. Their responsibilities are:
For a different sensor, implement its identification, firmware and report
protocol. For a different bus controller, implement the transfer/delay callbacks
used by nvt_bus when reusing the Novatek protocol.
Implement nvt_bus.xfer as one full-duplex transfer with chip select held
throughout. Supply caller-owned buffers and the delay callback from NvtProtocol.h.
Call nvt_identify, nvt_fw_parse, nvt_download_firmware and nvt_read_frame
in that order, checking each return code. On download failure, preserve stage,
CRC and SRAM-readback diagnostics before retrying. Publish decoded coordinates,
IDs and contact count as one coherent frame for the HID consumer.
2. Adapt the board path
- Define the target's controller windows, bus mode/rate, GPIOs, interrupt and
SMMU stream from its DTS and clock/pin definitions.
TouchBoard.his a board data-layout reference. - Implement power/reset ownership and verify engine firmware, pins and clocks.
- Set DMA addressing and cache maintenance for the target SMMU context.
- Read the chip ID, then load its firmware and check the returned geometry.
- Decode complete frames and map coordinates to the display's orientation.
- Check stable contact IDs, simultaneous contacts, edge behavior and release.
The Novatek processing core uses a 40 × 60 matrix. Verify geometry and bounds
when adapting its firmware or processing core. Firmware extraction is owned by
the device's scripts/gen-touch-firmware.py and proprietary-file inventory.
The reference probe arguments touch=1, 2, 3 and 4 select resource inspection, clocks/pins,
controller identification, then firmware/scanning. Use those stages only after
adapting the hardware values consumed by that stage.
Expected result: coherent contact frames in display coordinates, including
lift events. The HID layer consumes native_touch_* through a sequence counter;
preserve snapshot consistency when replacing the producer.
3. Publish HID reports
Qualify IOHIDFamily methods and object layouts against the selected kernelcache. The reference archive recipe uses a prelinked candidate and ABI records; see build inputs. Adapt the report descriptor, logical coordinate ranges and contact limits to the sensor.
Select the sensor, transport and HID components in the complete component list.
The reference display recipe links the sensor and bus objects; its HID recipe binds
the OS interface. touch-hid=1 enables its touch publication path.
From the assembled target tree, inspect their integration:
rg -n 'TouchProbe|GeniSpi|NvtProtocol|NvtTouchCore|NvtFirmware' scripts/build-gop-legacy-display.py
rg -n 'native_touch_|ReportDescriptor' drivers/ShengHidInput/NativeHidInput.cpp
Expected result: the OS receives correct down, move and up reports for each contact, and UI gestures follow the panel orientation.
4. Adapt physical buttons
Use ButtonProbe.cpp in the source map as a reference for
interrupt sampling and HID button events.
Map the target's GPIO or PMIC inputs, polarity, ownership, interrupt routing and
acknowledgement. Access only the PMIC peripherals owned by the selected execution
environment. Adapt BootResetCore.h helpers where the SPMI controller differs.
Connect press/release state to the HID consumer report. The reference uses report 2 bits
for Power, Volume Increment and Volume Decrement and enables this with
buttons=1.
Expected result: every press and release produces the expected report, including held and simultaneous buttons, with bounded interrupt activity.
5. Adapt a keyboard cover
A cover whose controller sits on I2C reaches the system as one IOHIDDevice.
iPadOS's SmartCoverServiceFilter makes the touchpad gestures when one service
has all of these:
- Keyboard (1/6), Touch Pad (0x0d/5) and Finger (0x0d/0x22) usage pairs. Only Application and Physical collections count, so each finger is a Physical collection.
- A transport that does not contain
test. - X and Y physical extents in centimetres (unit 0x11). The event driver turns
only that unit into
SurfaceDimensions.
Keyboard Power (keyboard page, usage 0x66) as an input and a feature element
sets KeyboardEnabled; report 0 when the cover is folded or closed so the
system shows the on-screen keyboard.
Check the touchpad Y direction against the HID convention and send a touching contact with Touch Valid 0 as lifted: the filter aborts backboardd when such a palm is the last child of a frame.
The sheng reference loads the WN8030 RAM image through its boot ROM, reads one
68-byte frame per interrupt and gates input with the hall sensors.
keyboard=1 enables it.
Expected result: typing, Caps Lock, pointer and scroll gestures work; folding or closing the cover disables input; detaching removes the device.
Next step
Rebuild through Building, record touch, buttons and keyboard separately, then continue with GPU adaptation.
For the arm64e public-source build path and its current linking/runtime limits, see public-source driver builds. Historical iOS 17 device results do not qualify this path.