| name | pmos-port-unsupported-device |
| description | Assess, port, build, temporarily boot, debug, and install postmarketOS on phones or tablets that do not have a supported device package. Use when an agent must investigate an unsupported postmarketOS device, create or audit pmaports device and kernel packages, determine deviceinfo values, build images with pmbootstrap, diagnose initramfs/rootfs/SSH failures, or plan a reversible installation without risking Android partitions. |
Port an Unsupported Device to postmarketOS
Treat an unsupported device as a porting project, not as a normal installation. Build an evidence-backed device package before proposing any flash operation.
Required references
Workflow
- Confirm support status. Search the current official pmaports tree by exact codename and aliases. If there is no matching device package, state that installation requires a port.
- Establish identity. Collect model, codename, SoC, storage type, bootloader state, slot layout, partition names and sizes, stock kernel cmdline, boot image header, DTB/DTBO arrangement, panel identifier, and available recovery method. Separate observed facts from inference.
- Preserve recovery. Require backups and a known-good stock ROM, boot image, or recovery path before any write. Never assume an unverified local image is restorable.
- Choose the kernel path. Prefer an existing generic/mainline SoC path when it supports the hardware. Use a downstream Android kernel only when necessary and record its exact source and commit.
- Create or audit packages. Use
pmbootstrap init, then inspect the generated device and kernel packages. Determine every deviceinfo value independently; do not infer rootfs sector size from boot-image page size.
- Build without touching hardware. Run checksum, package build, install/image generation, export, and artifact inspection. Verify the produced partition layout, boot image metadata, initramfs contents, DTB, modules, and firmware before connecting a phone.
- Test the smallest reversible step. Prefer a supported RAM-only boot. Obtain explicit approval immediately before booting even when it does not write storage.
- Debug from evidence. Capture
/pmOS_init.log, dmesg, block devices, blkid, mounts, network state, and service state. Change one hypothesis at a time and rebuild.
- Install incrementally. Obtain separate explicit approval immediately before each partition write. Start with the smallest required write and verify it before considering persistent kernel installation.
- Record results. Save exact commands, hashes, package revisions, logs, observed behavior, and rollback status. Redact serials, unlock tokens, and other identifiers.
Safety gates
- Never run
flash, erase, format, repartition, sideload, or bootloader-lock commands without explicit user approval for that exact action.
- Never write
boot, vendor_boot, init_boot, dtbo, vbmeta, super, persist, modem/EFS, or userdata based only on a guessed layout.
- Never relock a bootloader while non-stock images or partitions are present.
- Treat
pmbootstrap flasher boot as temporary but still hardware-affecting; confirm device support and obtain approval.
- Treat
pmbootstrap flasher flash_rootfs as destructive to the selected partition even though official help says it does not change the partition table.
- Stop when device identity, partition target, image provenance, battery state, or rollback path is uncertain.
Completion criteria
Do not call a port installed or supported merely because the kernel starts. Report milestones separately:
- image builds reproducibly;
- bootloader accepts the image;
- initramfs starts;
- rootfs is found and mounted;
switch_root completes;- a stable shell is reachable;
- storage, display, input, USB, networking, audio, modem, suspend, charging, and sensors are tested individually;
- rollback is tested or demonstrably available.
