Files
UniXNU Docs 1446f449b6 docs(porting): cover the macOS path
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.
2026-11-10 19:26:10 +08:00

7.6 KiB
Raw Permalink Blame History

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

  1. Define the target's controller windows, bus mode/rate, GPIOs, interrupt and SMMU stream from its DTS and clock/pin definitions. TouchBoard.h is a board data-layout reference.
  2. Implement power/reset ownership and verify engine firmware, pins and clocks.
  3. Set DMA addressing and cache maintenance for the target SMMU context.
  4. Read the chip ID, then load its firmware and check the returned geometry.
  5. Decode complete frames and map coordinates to the display's orientation.
  6. 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.