Skip to content

UMS9117 platform

Source:platforms/ums9117

The ums9117 platform supports phones built on the Unisoc UMS9117, also known by its reference name T117: an ARMv7-A SoC with one Cortex-A7 CPU. Its Devicetree compatible is sprd,ums9117. The phone catalog lists each target’s platform.

What the UMS9117 platform provides and what each phone target supplies UMS9117 platform provides shared implementations for UMS9117 targets CPU, interrupts and timers USB device Display (DRM/KMS) Matrix keypad Audio Bluetooth and FM radio microSD Camera capture Image rotation and JPEG Power-management chip Read-only NAND reader RAM-loader flow Each target supplies for one exact phone Board memory Panel profile and wiring Keypad wiring and keymap Bootstrap inputs Enabled Devicetree nodes Board USB setup Loader values in [adapter] Device-data groups
What the platform shares and what each target adds for its phone.

The table describes the shared integration and target requirements. Use the feature overview for implementation and verification status, and the phone checklist for exact-model support.

Capability What a target supplies or must know
CPU, interrupts and timers Uses the shared interrupt and timer nodes.
CPU clock Manual selection between 768 MHz and 1 GHz keeps the voltage set before Linux starts. The target states whether switching works.
USB device Board USB setup. USB host mode is not supported.
AP DMAengine 32 memory-copy channels and the fixed image-rotation request. Enabled clients depend on the target.
Display (DRM/KMS) Panel profile, transport, initialization and backlight brightness range. The kernel diagnostic console uses the same display.
Matrix keypad Matrix wiring and keys on external-interrupt (EIC) lines. The phone key codes are shared.
Audio Headphones, speaker and microphones; the phone’s audio tuning comes from its device data. The target states its microphone limits.
Bluetooth Firmware prepared from the phone’s own internal storage.
FM radio Needs the phone’s prepared radio data; the required groups are target-specific.
microSD Enables the slot.
Camera capture (V4L2 NV16) Camera sensor and wiring.
Image rotation and JPEG No board data; the userspace tools are shared.
Native image presentation Native-size NV16 or RGB565 through DRM/KMS; consult the exact phone’s display status.
Power-management chip Charger status, battery telemetry, RTC, keypad light and power-off are shared. The vibrator is enabled per target.
Internal NAND reader Read-only raw page stream for a NAND backup; no filesystem, writes or erase.
GPIO and I2C Used for the cameras; general peripheral use has not been checked.
  • Board memory, the panel profile and wiring, the keypad map and the bootstrap inputs.
  • The SoC Devicetree nodes its board can use; enable nothing else.
  • Board USB setup.
  • The values the loader needs, in the [adapter] table of its target.toml: the boot instructions, the exec distance and, for a phone with a boot screen, the loader display settings.
  • The device-data groups that must come from the exact phone.

Display targets select one target-owned panel description through [display].panel in target.toml. It defines the native size, transport, panel ID, initialization sequence and transfer settings used by the loader, bootstrap and Linux display. The selected SPI or LCM transport must agree with the board pin configuration. Set boot_font to "6x8" for a 128×160 display or "7x14" for a 240×320 or 320×240 display in the same [display] table; it selects the bootstrap and Linux console font. GUI applications use the fonts selected by the shared UI profile.

Use targets/nokia-ta1618/ as an example of a display target with both RAM and microSD boot inputs. Keep the new phone’s panel, keypad, board wiring and device-data declarations in its own target.

The platform’s loader/assets.lock.toml pins the common RAM loader in [fdl1]. Target-owned early initialization supplies the board setup needed before Linux; the panel description supplies the display and pad settings. Linux reads its keypad map from the target’s Devicetree. Normal boot needs no external pin-map or keymap archive and no maps extracted from the phone.

A target loads headless when it has none of the loader display settings (spi_mode, backlight_channels and backlight_level in [adapter]) and no panel selected in [display]. The loader leaves the panel and backlight untouched and reports boot progress only to the PC. The headless template provides no display or keypad initialization and declares no runtime data groups, so its first run boots directly to SSH.

./fplinux target new creates such a target; see Bring up a new phone.

The headless target retains the boot stage’s USB state through CONFIG_USB_MUSB_UMS9117_INHERITED and fplinux,ums9117-musb-inherited. A target that initializes USB in Linux uses CONFIG_USB_MUSB_UMS9117_COLD and sprd,ums9117-musb. The build requires a matching built-in ownership mode for every enabled USB node.

The standard image uses the Weston/Wayland phone interface. Weston owns display and input; applications use Wayland input and client surfaces. A port must verify the compositor and native application output separately from its earlier direct-display results.

Terminal is an application in that session. Its terminal font and input controls are separate from the Linux text console; Bash needs /dev/ptmx with a mounted devpts filesystem. Its terminal type is xterm-256color. Verify the keypad, keyboard layouts, shell output, Home/Tasks transitions and closing running jobs through the graphical application.

Kernel fbcon remains the Linux text console. Its font and virtual terminal are separate from Terminal’s GUI font and client surface. The Weston session disables keyboard VT-switching shortcuts.

Linux inputs follow the shared integration contract.

Use ./fplinux device-data report <target> --from-dump nand.bin to extract a board report from the stock firmware in the phone’s saved NAND backup. It builds the required host extraction tool without a target bundle or phone connection and writes the report under diagnostics/device-data/<target>/report-*/ inside the working data directory. The report is separate from prepared runtime firmware and audio data; see Device data. It lists:

  • the keypad matrix with the phone key codes, the boot key and, when exactly one standard phone key is missing from the matrix, that key as the candidate for external-interrupt line 9 (eic9_candidate);
  • every panel in the firmware’s LCD list: its 16-bit ID, the controller name when the firmware gives it, size, SPI or LCM interface, SPI clock or DBI timing, and the initialization commands and delays when they can be decoded;
  • the pin settings of the display control, display data and audio pads;
  • the white LED backlight level and the fuel-gauge current calibration;
  • the NAND chip configurations listed by the firmware.

A value that cannot be found is listed as unresolved. Report extraction stops when the partition table, the signed application image, the pin map or the keymap is missing, or when the copies of the partition table disagree. Extracted maps are temporary report inputs, not runtime files or build inputs.

A person still has to decide which panel is fitted, the keypad light current, whether a vibration motor is fitted and whether the radio works with the prepared firmware. Keys on other external-interrupt lines, the line-9 candidate and the decoded panel commands must be confirmed on the phone.

The AP DMA controller offers 32 channels through the standard Linux DMAengine DMA_MEMCPY interface for kernel clients. It accepts any byte alignment, queued transfers, pause and resume, and synchronous termination; large transfers are split transparently. Residue is reported per completed segment, not as a live byte count.

A configuration error aborts the active and queued transfers with DMA_ERROR and DMA_TRANS_ABORTED; release and request the channel again before reusing it. If the controller cannot be stopped, termination returns an error and the client must keep its DMA buffers until a cold boot.

Image rotation uses its fixed peripheral request through this controller. Generic peripheral requests, cyclic transfers, caller-supplied hardware linked lists and a userspace memory-copy interface are not provided.

  • USB works only in device mode.
  • UART, general SPI, the watchdog, system reset and Linux reboot are not supported.
  • CPU frequency selection does not change the voltage.
  • General use of GPIO and I2C beyond the cameras has not been checked.