Skip to content

Porting overview

A phone port is a small, complete description of one exact phone model, called a target. It reuses shared code only where the existing targets demonstrably behave the same.

FPLinux layers: bootstrap/ before Linux, platforms/ums9117/ and targets/<phone>/ side by side, alpine/ phone userspace on top, and common/ host and runtime tools at the side alpine/ Phone userspace and services One Alpine package recipe per component, the root-filesystem package policy and OpenRC services. platforms/ums9117/ SoC support shared by its phones Processor and interrupt integration, controller drivers, SoC Devicetree nodes and the fixed RAM-loader flow. targets/<phone>/ One exact phone Board wiring and memory, panel, keymap, bootstrap inputs, values passed to the loader, device-data declarations. selects platform and target manifests select packages bootstrap/ Before Linux starts Freestanding components with bounded callbacks for platform- and target-owned operations. common/ Target-neutral host and runtime tools Such as the RAM bundle runner and the USB keyboard client, and the contracts they share.
Source layers and what each one owns.
Directory Owns
bootstrap/ Freestanding components reused before Linux starts, with bounded callbacks for platform- and target-owned operations.
platforms/<soc>/ SoC support shared by its phones: processor and interrupt integration, controller drivers, SoC Devicetree nodes and the fixed RAM-loader flow.
targets/<phone>/ One phone: board wiring and memory, panel, keymap, bootstrap inputs, values passed to the loader and device-data declarations.
alpine/ Phone userspace: one Alpine package recipe per component, the root-filesystem package policy and OpenRC services.
common/ Target-neutral runtime entry points and host tools, such as the USB keyboard client, and the contracts they share.

C libraries shared by host tools and phone packages live in lib/fplinux/, with their headers in include/fplinux/. Their runtime requirements belong to each component, not to the package that consumes it.

The boundaries run both ways:

  • A platform never chooses a phone’s panel, keypad matrix, memory reservation or board-specific loader data.
  • A target never duplicates SoC addresses, controller support or the platform loader sequence.
  • bootstrap/ contains no SoC loader policy and no phone addresses, register setup, panel sequences, keymaps or assets.
  • common/ does not depend on a phone memory map, board register layout or bootstrap protocol. Phone programs and services are maintained as Alpine aports, even when they are target-neutral.
  • Every selected bundle and standalone archive uses the shared minimal runtime through fplinux.py; target and platform configuration supply its loading and preparation requirements.
  • Keep board-specific data in the target. Move code into a platform or another shared layer only when more than one current target uses the same behavior. SoC-specific host translation belongs to the selected platform.
  • A profile selects boot and storage policy, not peripheral features. The default profile runs from RAM; supported targets offer a microSD system-card profile. A target without microSD boot inputs offers only default. Feature profiles are not accepted.
  • Follow the Linux integration contract when adding kernel code, configuration or Devicetree inputs.
  • Name a target and its platform as described in Target and platform identity.

Keep each phone-userspace component in one conventional aport under alpine/aports/. Declare its runtime and build dependencies in APKBUILD, and use OpenRC for service ownership and supervision. Do not add rootfs overlays, duplicate recipes, target-local copies or ad-hoc installers for software that already belongs in an aport.

Select packages in platform and target manifests rather than testing target names in code. [rootfs].packages selects packages installed in the phone’s root filesystem; [bundle].packages selects optional APKs built and published under apks/, without installing them in that root filesystem. alpine.lock.toml pins the Alpine inputs. Users follow Optional APK packages to install bundle packages; Packaging covers standalone archives.

Map each consumer of shared C sources explicitly in scripts/fplinux_cli/alpine/registration.py; keep one shared implementation in lib/fplinux/ and its headers in include/fplinux/.

Rebuild an upstream component in its own fplinux- aport only when the locked Alpine package’s runtime dependencies exceed the RAM filesystem budget. Install only the runtime files its consumer loads and remove the replaced Alpine artifacts from alpine.lock.toml.

Use a hardware-specific package only when its public interface is specific to that hardware. Shared kernel and userspace interfaces belong in shared packages.

The website checklist states support for every feature on an exact phone, using the status terms. Hardware presence and FPLinux support are separate facts: a missing driver does not prove the hardware is absent. A feature is Verified only after it has been used on that phone; a successful build is not a phone test.

Source rules for every layer are in Code style, and the contribution workflow is in Contributing.