Skip to content

Bring up a new phone

This page is for the owner of a Unisoc UMS9117 (T117) phone that has no FPLinux target yet. You create a headless target, start Linux in RAM, save a read-only backup of the phone’s internal NAND, extract a board report from the stock firmware in that backup and report the phone to the project.

A new target has no display, keypad, audio or Bluetooth support. The screen stays dark, without a boot screen or backlight, and you use the phone from the PC through the USB session.

Bring-up flow from creating a target to reporting the phone, with the failure branch for each boot stage Create target target new Build build Run, then connect hold boot key when asked BootROM USB 1782:4d00 no BootROM USB Try another boot key appeared only briefly: start again FDL1 starts Custom FDL1 line no Custom FDL1 line Set the exec distance exec_distance = 0x314d Bootstrap stages BOARD INIT … LINUX failed attempts or 64MB RAM REQUIRED Report the phone another SoC variant or memory size Linux USB 0525:a4a6 error after PREPARE LINUX Check Linux USB lsusb -d 0525:a4a6; absent: report SSH session ready Linux runs Identify NAND nand identify Save NAND backup nand backup Prepare board report device-data report Report the phone new phone report form chip=unknown Report the phone with a photo of the flash chip
Bring-up steps, their ./fplinux subcommands and the failure branches.
  • Set up a Linux x86-64 PC and the source checkout as described in Build FPLinux.
  • Set up USB access as described in Run FPLinux.
  • Have a USB data cable for the phone.

Run every command from the root of the source checkout.

Choose a target name and the phone’s public brand and product names:

PC
./fplinux target new <target> --platform ums9117 --brand <brand> --product "<product>"
  • <target> names the new targets/<target> directory and is the target name for every other command. It consists of lowercase letters and digits separated by single hyphens.
  • --brand and --product are the public names described in Target and platform identity. The device name, the brand and product separated by one space, must be ASCII and at most 31 characters long.
  • --compatible <vendor>,<device> sets the board compatible string. Without it, the command forms one from the lowercase brand and product, for example hammer,horizon-lte.
  • --platform ums9117 selects the platform supported by this headless bring-up workflow. This workflow does not support SC9820E.

The command creates the target manifest, headless bootstrap, board Devicetree, kernel configuration and standalone-archive descriptions. It uses the platform’s pinned RAM loader. It lists the files it created. It refuses an existing target directory and leaves nothing behind when a name or identity field is invalid.

The new target uses * as the boot key and exec_distance = 0, both in the [adapter] table of targets/<target>/target.toml. This is a template default. Confirm the actual boot key of the new phone before connecting it. It offers only the default RAM profile, with no microSD support. Creating the target does not qualify its peripherals or add the phone to the list of supported phones.

Keep the inherited USB setup for the first headless boot. The platform requirements describe its USB ownership mode and the board inputs needed when adding peripherals.

Build the target:

PC
./fplinux build <target>

Power the phone off and disconnect USB. Start the loader before you connect the phone:

PC
./fplinux run <target>

Wait until the loader asks for the phone. Only then hold the boot key named in the target’s instructions and connect the powered-off phone, keeping that key pressed as the loader instructs. A new target starts with *; if it does not work, follow the boot-key check. Run FPLinux has the general loader rules.

Connecting a phone for bring-up: start ./fplinux run on the PC, then hold the phone's boot key and connect it powered off only after the loader asks ./fplinux run <target> powered off hold boot key connect only after the loader asks
Hold the phone's boot key and connect it powered off only after the loader asks.

Right after you connect the phone, run lsusb in a second terminal and keep the phone’s line for the report. In BootROM mode it reads ID 1782:4d00 Spreadtrum Communications Inc. If the loader does not see the phone, run lsusb while the phone is still connected with the key held and keep whatever line appears, or note that no new line appeared. A headless target with no runtime data groups boots directly; it does not stop for automatic NAND preparation.

A successful boot records these milestones in the runtime.log whose path run prints, with other output between them:

Output
BSL_REP_VER: "SPRD3\0"
BSL_REP_VER: "Custom FDL1: CHIP ID = 0x98180001\0"
<TARGET>_LINUX_BOOTSTRAP event=stage stage=1 message=NO DISPLAY
<TARGET>_LINUX_BOOTSTRAP event=stage stage=5 message=PREPARE LINUX
Secure phone connection is ready.

The first BSL_REP_VER line comes from the phone’s BootROM, the second from the RAM loader (FDL1) once it runs. Its CHIP ID identifies the SoC; the supported phones report 0x98180001. The bootstrap records use the target’s record_prefix; see Logging. NO DISPLAY confirms headless mode. Wait for the authenticated session’s final readiness message before using phone commands.

From an interactive terminal, run then opens a shell on the phone. Leaving that shell does not stop Linux. Keep the complete run output and its runtime log for the report. Close this launcher before opening another interactive launcher; explicit NAND and remote command operations can use the existing session.

Find the last milestone or error in the runtime log:

Last output Meaning What to do
fplinux run: BootROM USB was not detected The phone did not start in BootROM mode. Try another boot key.
fplinux run: BootROM USB 1782:4d00 repeatedly disconnected before it could be opened The phone appeared on USB only briefly. Start again.
BootROM BSL_REP_VER, no Custom FDL1 line, then fplinux run: RAM loader failed after 3 attempts The RAM loader did not start. Set the exec distance.
Custom FDL1, then failed attempts or event=error error=2 message=64MB RAM REQUIRED Another SoC variant or memory size. Report the phone.
PREPARE LINUX, then an error about the bridge, BootROM USB or the SSH session Linux USB did not come up. Check Linux USB.
Secure phone connection is ready. Linux runs. Identify the NAND chip.

If no BSL_REP_VER line appears after you connect the phone, the phone did not start in BootROM mode, and the loader stops after 300 seconds. When the phone appears on USB only briefly, the loader stops with the “repeatedly disconnected” message.

Disconnect the phone, power it off and start again with run, holding the key before and while you connect USB. If * never works, the phone uses another BootROM key: try another key in the same sequence. When a key works, replace * with it in boot_instructions in the [adapter] table of targets/<target>/target.toml and build again.

If the loader reports that the USB device is not readable and writable, fix USB access as described in Run FPLinux.

When the BootROM BSL_REP_VER line appears but the Custom FDL1 line never does, the attempt fails. run asks you to disconnect, power off and reconnect the phone after each failed attempt and stops after the third one.

If FDL1 does not start with the new target’s exec_distance = 0, set this in the [adapter] table of targets/<target>/target.toml:

targets/<target>/target.toml
exec_distance = 0x314d

Build and run the target again. The runtime log then lists the extra operation:

Output
Operations: exec-distance setup, RAM FDL1 load, RAM payload load.

No value other than 0 and 0x314d is known to start FDL1.

FDL1 sets up the 64 MB of LPDDR2 memory used by the supported phones, and FPLinux requires 64 MB of RAM. On a phone with another SoC variant or memory, the attempts fail after the Custom FDL1 line, or the bootstrap stops with:

Output
<TARGET>_LINUX_BOOTSTRAP event=error error=2 message=64MB RAM REQUIRED

FPLinux does not start on such a phone. Report it with the complete run output and photos of the markings on its SoC and flash chip.

After PREPARE LINUX, the phone leaves BootROM USB 1782:4d00 and Linux starts its USB device 0525:a4a6. When the boot stops before Secure phone connection is ready., run ends with an error such as:

Output
fplinux run: bridge did not acknowledge the Linux transition before the deadline
fplinux run: BootROM USB did not disconnect before the deadline
fplinux ssh: the exact USB-NCM SSH session did not become ready before the deadline

Check whether Linux USB is present:

PC
lsusb -d 0525:a4a6

If the device is listed, follow the troubleshooting for a Linux USB device without a console in Run FPLinux. If it is not, report the phone with the complete run output.

While the phone session runs, use a second terminal on the PC, or leave the phone shell, and run:

PC
./fplinux nand identify <target>

For a phone with a DS35M1GA chip the report reads:

Output
id_bytes=e521
chip=DS35M1GA
page_main_bytes=2048
oob_bytes=64
pages_per_block=64
block_count=1024
raw_bytes=138412032
geometry_source=table
feature_a0=0x38
feature_b0=0x10
feature_c0=0x00

geometry_source=table means that the reader recognised the chip from its list of known chips. Raw reads on supported phones are established for FM25LG01B, DS35M1GA, F35UQA001G and GD5F1GM7RExxG. Identification of another chip does not establish its raw read path. The NAND reference describes every field.

  • chip=unknown: the reader does not know the chip. The report shows zero sizes and geometry_source=unknown, but still the chip’s id_bytes and feature values. A backup is not possible. Report the phone with the complete nand identify output and a photo of the markings on the flash chip.
  • A recognised chip: continue with the backup and include the complete identification output in the report. For a chip outside the group above, state that its reader entry has not been checked on a supported phone.
PC
./fplinux nand backup <target> nand.bin

The command reads the complete NAND through the running session, which takes several minutes, and reports progress and the backup path:

Output
Reading NAND: 100.0% (132.0/132.0 MiB) · … MiB/s
Backup saved: /path/to/nand.bin

nand.bin holds every page’s main and OOB bytes. nand.bin.json is the geometry receipt. Both files are readable only by you.

If the transfer stops, for example because USB was disconnected or you pressed Ctrl+C, the command fails and publishes nothing; an earlier backup at the same path and its receipt stay unchanged. Run nand backup again. If the phone no longer runs the session, start again from a powered-off phone with run.

When you are done, end the session safely before returning to the stock firmware.

The board report lists the keypad, panel, pin and other board values found in the stock firmware in your backup. Prepare it from the saved backup; the phone does not need to be connected, and no target build is required:

PC
./fplinux device-data report <target> --from-dump nand.bin

The command reads nand.bin with its receipt nand.bin.json, prepares the host extraction tool from local inputs in the pinned build environment without a target bundle, and prints the location of diagnostics/device-data/<target>/report-*/board-report.json inside the working data directory. A new target without declared NAND geometry needs the receipt; the command does not infer geometry from file length. Prepare missing dependencies with ./fplinux setup <target>. The report is independent of runtime data groups and supplies no pin-map or keymap files to later boots.

Board data from the stock firmware describes what the report contains and which decisions it leaves to a person. Device data describes device-data preparation in general.

Open a new phone report in the project’s issue tracker. The form asks for:

  • the phone’s brand, product name and any model code printed on it or under its battery;
  • the boot key that worked;
  • the lsusb line;
  • the complete run output, including any error;
  • the complete nand identify output, if Linux started;
  • the contents of the geometry receipt nand.bin.json;
  • the board-report.json file;
  • photos of the markings on the SoC and on the flash chip.

Do not attach the NAND backup or any stock firmware image.

Display, keypad, audio and Bluetooth support are completed by hand from the backup and board report. The existing targets under targets/ provide board examples, and UMS9117 platform lists what a target supplies.

The NAND command and receipt reference defines the report fields, file publication and reachable failures.