The display page carries the backlight service's properties, requests, boot arguments and verification as its last section, and the separate brightness page is gone.
11 KiB
Display and brightness
Start after platform and memory. Collect the firmware GOP base, size, dimensions, stride, pixel format and reserved-memory range. Identify the panel, display controller, backlight controller and their power owners.
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 |
|---|---|---|
| OS display interface | NativeLegacyDisplay.cpp, OriginalMobileFramebufferABI.h | Provider methods, request layouts and selected MobileFramebuffer ABI |
| Frame ownership | NativeGOPWire.h, NativeGOPPresenter.cpp | NGPPresent, NGPSwap, NGPComplete: buffer bounds and swap retirement |
| Brightness implementation | AppleARMBacklight.cpp, GeniI2c.h | OS properties and geni_i2c_start_write/read, event and timeout handling |
| Timing reference | DisplayTimingProbe.cpp | Target controller counters and refresh measurement |
1. Establish firmware scanout
Build the integrated UEFI firmware. Confirm that its menu displays correctly. Compare GOP geometry and framebuffer bounds with the firmware memory map and board DTS. Preserve the active scanout allocation through kernel handoff.
Expected result: a stable firmware image with correct colors and dimensions. Resolve this before enabling the XNU presentation backend.
2. Adapt the XNU display backend
Read GopFramebuffer and its NativeLegacyDisplay.cpp,
NativeGOPPresenter.cpp and NativeGOPWire.h. It consumes PE_current_console
and integrates with the selected MobileFramebuffer and IOSurface ABI.
In the reference board package,
inspect LegacyDisplayProbe.cpp and DisplayTimingProbe.cpp. The device's
scripts/build-gop-legacy-display.py qualifies ABI methods against a prelinked
candidate before producing the late display archive. Supply the matching
candidate and audit inputs listed in build inputs.
- Select GopFramebuffer and the display archive recipe, preserving its dependencies.
- Enable the recipe's kernel configuration and initialization caller. The reference uses
CONFIG_XNU_NATIVE_LEGACY_DISPLAY=yand itsoffline-legacy-*arguments. - Check pixel layout, row stride, allocation size and cache handling in CPU presentation. Confirm that a known frame reaches the display.
- Check swap completion and IOSurface lifetime before enabling GPU presentation.
- Adapt timing reads to the target display controller. The reference probe,
dpu=1, samples the SM8550 DPU and dual-DSI counters throughDisplayTimingProbe.cpp. Set refresh policy from the observed panel mode. The reference requests 120 Hz withvsync=120.
For the NativeGOPWire.h path, query mode/geometry first and validate each
present buffer's size and stride. In GPU handoff, track the pending frame by
NGPSwap.sequence and return NGPComplete with that sequence after copying.
Retain the source frame and IOSurface until the swap completes, and complete
the corresponding error path on timeout or failure.
Expected result: XNU publishes the display, presents frames and completes swaps. Record requested refresh and measured frame timing separately.
The 24A446 adapter supplies the default surface through the original IOSurfaceRoot
factory and validates its backing memory and geometry before transferring ownership
to the display family. The family's create_default_fb_surface() slot returns void;
its residual return register is not an object pointer.
Read the display pipes
Before changing what the display fetches, read how firmware left it.
The reference DisplayTimingProbe.cpp exposes these stages:
| Argument | Reads |
|---|---|
dpu=2 |
VIG 0 and 1 source, size, format and fetch settings; CTL 0 state; the tear check of both interfaces; the display streams in the apps SMMU |
dpu=3 |
Also rewrites each pipe's current address and times the CTL flush latch |
In this reference, both VIG pipes fetch one 32-bit physical address, the right pipe from its own source x, and a flush latches within 5.4 ms without a start because the panel refreshes by itself. The display context bank starts with translation off.
Direct scanout (dpu-scanout=2) is experimental and off by default: it
gives the display bank a stage 1 window (ShengUfs) and points the pipes at the
compositor's surfaces. Any failure falls back to the GPU copy.
The window's TCR2 sets the sign extension field (SEP, bits 17:15) to 7, as
arm-smmu does for AArch64 contexts; with SEP 0 an address with bit 31 set faults
at level 0. The compositor submits a swap when its command buffer is scheduled,
not when the GPU finished it, so the display driver flips only after the GPU
wrote everything handed to it before the swap arrived (the Adreno driver exports
the newest and the completed fence). Without that wait the pipes scan a surface
the GPU is still writing and the panel flickers. The boot log row
[direct scanout] shows flips, mapped surfaces, latch times and the time the
flips waited for the GPU. The framebuffer must be 8-bit BGRA.
3. Identify the brightness transport
Select the target's I2C, DSI-command or PWM transport and its brightness encoding.
AppleARMBacklight.cpp provides an OS-service example for KTZ8866 controllers;
GeniI2c.h defines the GENI transfer state machine used by that example.
Before reuse, record the target's controller count, register encoding, brightness range, I2C engine, slave address, pins, clocks, interrupts and power sequence. For a DSI-command or PWM backlight, implement that transport and its level encoding behind the OS-facing brightness service.
4. Adapt and enable brightness
- Update the board's engine mappings, clock votes and interrupt routing. The reference GENI path adopts firmware-loaded engine code and timing; verify that handoff or implement the target's initialization sequence.
- Implement the target controller's level encoding, write and readback. Match the number of controllers and update order to the panel's wiring.
- For the GENI example, call
geni_i2c_prepare, start a read/write, feed interrupt status togeni_i2c_eventand callgeni_i2c_timeoutwhen its deadline expires. Complete or cancel the transfer before starting the next one. Keep service requests on the work loop and inspect failures before enabling fades. - Publish the properties and accept the requests of the selected OS, as the brightness interface lists them.
- Build the service and its registration wrapper. The reference display recipe does
both;
backlight=1enables its probe.
From the resolved target tree, locate these integration points:
rg -n 'kSeA|kSeB|kSpi|kMaxLevel|backlight-control|FadePeriod|brightness-nits' kits/*/AppleARMBacklight.cpp
rg -n 'backlight|GeniI2c' scripts/build-gop-legacy-display.py
Use the equivalent kit path for the new board. Rebuild the kernel, payload and boot image through Building.
Expected result: minimum, middle and maximum settings produce corresponding
readback and visible levels; fades complete; timeout counters remain stable.
The reference native_backlight_stats records publication, requests, readback,
interrupts and failures. Verify UI brightness changes as a separate step from
raw controller writes.
5. Brightness interface
What the OS expects from the backlight service. The values are those of the sheng
service in AppleARMBacklight.cpp.
Service identity
AppleARMPlatform already defines AppleARMBacklight, so the board class has
its own name and its getMetaClass answers the AppleARMBacklight metaclass.
CoreBrightness takes the service for the built-in display's backlight through
that answer, and the sandbox applies the profile of that class.
Published properties
| Property | Read by | Content |
|---|---|---|
backlight-control |
CoreBrightness | true |
IODisplayParameters.brightness |
iPadOS 17 | min, max, value as levels |
IODisplayParameters.BrightnessMilliNits |
iPadOS 27 | min, max, value in millinits |
backlight-marketing-table |
iPadOS 27 | Signed 16.16 nits at equally spaced slider positions. Display creation fails without it |
LmaxProduct |
iPadOS 27 | 4 bytes of 16.16 nits. At zero every slider position means the maximum |
LmidProduct, LminProduct |
iPadOS 27 | Numbers in nits |
backlight-calibration-parameters |
iPadOS 27 | lMinProduct, lMidProduct, lMaxProduct, lMinPanel, lMidPanel, lMaxPanel as 16.16 nits |
Accepted requests
| Property | Effect |
|---|---|
brightness-nits |
Signed 16.16 nits. Zero or less turns the LEDs off; other values map proportionally to a level of at least 1 |
brightness, FadePeriod |
A level and a fade in 16.16 seconds, at most 5 s, stepped every 16 ms |
Other keys succeed with no effect. Requests reach the work loop through a timer, so the caller never waits for a transfer.
Virtual platform on iPadOS 27
A board that sets the ADT property vmm-present makes MobileGestalt answer
IsVirtualDevice. CoreBrightness then selects a control that drops every
brightness request. scripts/appsync/BacklightMode.m gives backboardd the
mode of a physical device. It loads through the
AppSync adapter.
Boot arguments
| Argument | Effect |
|---|---|
backlight=1 |
Starts the service |
backlight-control=0 |
Leaves out backlight-control and the metaclass answer |
log-display=1 |
Adds the L rows to the boot log |
Verification
- The system log shows
[UniXNU backlight] physical brightness control selected. - The
Lrow showsst=4, andxerrstays 0. - Moving the slider raises
reqand changeslvland the panel. - Sleep turns the backlight off and wake restores it.
Next step
Record display and brightness results separately, then continue with touch and buttons.