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.
Before you start
Section titled “Before you start”- 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.
Create a headless target
Section titled “Create a headless target”Choose a target name and the phone’s public brand and product names:
./fplinux target new <target> --platform ums9117 --brand <brand> --product "<product>"<target>names the newtargets/<target>directory and is the target name for every other command. It consists of lowercase letters and digits separated by single hyphens.--brandand--productare 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 examplehammer,horizon-lte.--platform ums9117selects 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.
Boot without a screen
Section titled “Boot without a screen”Build the target:
./fplinux build <target>Power the phone off and disconnect USB. Start the loader before you connect the phone:
./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.
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:
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 LINUXSecure 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.
Where the boot stopped
Section titled “Where the boot stopped”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. |
The loader does not see the phone
Section titled “The loader does not see the phone”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.
FDL1 does not start
Section titled “FDL1 does not start”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:
exec_distance = 0x314dBuild and run the target again. The runtime log then lists the extra operation:
Operations: exec-distance setup, RAM FDL1 load, RAM payload load.No value other than 0 and 0x314d is known to start FDL1.
Loading stops after FDL1 starts
Section titled “Loading stops after FDL1 starts”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:
<TARGET>_LINUX_BOOTSTRAP event=error error=2 message=64MB RAM REQUIREDFPLinux 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.
Linux USB does not appear
Section titled “Linux USB does not appear”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:
fplinux run: bridge did not acknowledge the Linux transition before the deadlinefplinux run: BootROM USB did not disconnect before the deadlinefplinux ssh: the exact USB-NCM SSH session did not become ready before the deadlineCheck whether Linux USB is present:
lsusb -d 0525:a4a6If 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.
Identify the NAND chip
Section titled “Identify the NAND chip”While the phone session runs, use a second terminal on the PC, or leave the phone shell, and run:
./fplinux nand identify <target>For a phone with a DS35M1GA chip the report reads:
id_bytes=e521chip=DS35M1GApage_main_bytes=2048oob_bytes=64pages_per_block=64block_count=1024raw_bytes=138412032geometry_source=tablefeature_a0=0x38feature_b0=0x10feature_c0=0x00geometry_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 andgeometry_source=unknown, but still the chip’sid_bytesand feature values. A backup is not possible. Report the phone with the completenand identifyoutput 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.
Save a NAND backup
Section titled “Save a NAND backup”./fplinux nand backup <target> nand.binThe command reads the complete NAND through the running session, which takes several minutes, and reports progress and the backup path:
Reading NAND: 100.0% (132.0/132.0 MiB) · … MiB/sBackup saved: /path/to/nand.binnand.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.
Prepare the board report
Section titled “Prepare the board report”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:
./fplinux device-data report <target> --from-dump nand.binThe 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.
Report the phone
Section titled “Report the phone”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
lsusbline; - the complete
runoutput, including any error; - the complete
nand identifyoutput, if Linux started; - the contents of the geometry receipt
nand.bin.json; - the
board-report.jsonfile; - photos of the markings on the SoC and on the flash chip.
Do not attach the NAND backup or any stock firmware image.
After the report
Section titled “After the report”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.
NAND backup reference
Section titled “NAND backup reference”The NAND command and receipt reference defines the report fields, file publication and reachable failures.