Debugging
Debug builds
Section titled “Debug builds”release is the default build type. A debug build adds kernel diagnostics and the fplinux-debug-tools package, which supplies perf 7.1.0 and Alpine’s strace 6.19. Applications and hardware support follow the selected target.
| Kernel facility | release |
debug |
|---|---|---|
Symbol names (kallsyms) |
Included | Included |
| Kernel log buffer | 64 KiB | 128 KiB on UMS9117; 256 KiB on SC9820E |
| ftrace, function/function-graph tracing, kprobe/uprobe events, syscall tracing and DMATEST | Disabled | Enabled in the kernel configuration |
UMS9117 debug builds also enable module loading, /dev/mem and the irqsoff tracer. SC9820E builds keep those facilities disabled. FPLinux ships no loadable modules.
Build and load a debug image with --build-type debug, and pass the same option to every later command for that session:
./fplinux build nokia-ta1618 --build-type debug./fplinux run nokia-ta1618 --build-type debugA debug image that boots does not show that a feature works on the phone.
Read command logs
Section titled “Read command logs”build, check, test and format keep tool output in stage logs. On failure, they print where the log is stored. Use logs to find and read it:
./fplinux logs list --status failed./fplinux logs show latest --command build --failed./fplinux logs follow latest --command buildlogs listshows recorded runs, newest first, with their command, target, profile, status, start time and duration.logs showprints the last 40 lines of each stage of one run.--failedlimits it to failed stages,--stage NAMEto one stage, and--tail Nchanges the number of lines.logs show --summarylists stage IDs, status and exit codes without printing their output.--max-bytes Nlimits log content across selected stages and reports truncation;logs list --limit Nlimits the number of recent runs.logs followkeeps printing new output until that run finishes. Ctrl+C stops only the reader.
Filters such as --command, --target, --profile and --status work with all three. A run’s status describes the command’s result, not the phone’s health. Run ./fplinux logs show --help for all options.
Commands that use the shared working-data lock wait by default. Add --lock-timeout SECONDS, such as ./fplinux console nokia-ta1618 --lock-timeout 0, to limit that wait; zero returns immediately if the lock is busy. Timeout reports the recorded owner and exits with status 75 without stopping the holder or contacting the phone.
Messages from the kernel, loader and phone programs follow the logging contract.
Profile a program
Section titled “Profile a program”Open a root shell on the debug image:
./fplinux console xiaomi-qin-1s-plus --build-type debugUse explicit software events for CPU accounting. These commands measure a bounded hashing workload; replace the command after -- with the program you need to investigate:
perf stat -e task-clock,context-switches,cpu-migrations,page-faults -- sh -c 'dd if=/dev/zero bs=64K count=512 | sha256sum'perf record -e cpu-clock -F 99 -o /tmp/perf.data -- sh -c 'dd if=/dev/zero bs=64K count=2048 | sha256sum'perf report --stdio --no-children -i /tmp/perf.datastrace -f -c -- sh -c 'dd if=/dev/zero bs=64K count=512 | sha256sum'task-clock measures CPU time and cpu-clock samples software CPU time; these examples do not require a hardware performance counter. strace -f -c summarizes system calls, including those made by child processes. Use strace -f -p PID to attach to a running program and Ctrl+C to detach. Tracing adds overhead, so compare the program’s behavior without it as well.
The supplied perf supports software counters and CPU sampling with a text report. It is built without libtraceevent, libdw or libunwind: perf sched, perf trace and DWARF call graphs are unavailable. Use tracefs for kernel tracing. Store short captures under /tmp; it uses the phone’s RAM.
Check display presentation
Section titled “Check display presentation”Debug images include fplinux-display-test. It uses the native display size and the normal DRM presentation and console handoff. geometry shows color corners and one-pixel detail; gray holds a constant field. Both present once, hold until --duration-ms, and restore the console. ids and motion repeat complementary 16-bit frame markers at the top, middle and bottom; the moving edge advances eight pixels per completed frame.
fplinux-display-test --pattern geometry --duration-ms 3000fplinux-display-test --pattern gray --duration-ms 3000fplinux-display-test --pattern motion --fps 0 --duration-ms 3000 > /tmp/display.csvfplinux-display-test --renderer gpu --pattern geometry --verify --duration-ms 3000Software drawing is the default. --renderer gpu requires a supported GPU and uses the shared GPU-to-DRM presentation path; initialization failures remain errors. --verify compares every visible RGB565 pixel with the software reference before presentation. It adds CPU readback and comparison, so omit it when measuring performance.
GPU scene rendering overlaps the preceding display transfer. Its CSV completion timestamp records when the previous presentation is observed complete after preparing the next frame; it is not the kernel’s exact completion timestamp. The last presentation is drained before restoring the console. Use completed-frame throughput to compare these modes, rather than interpreting the GPU rows as isolated rendering or SPI latency.
--fps 0 removes application pacing. The CSV records frame ID, drawing start, submission and completed presentation as monotonic nanoseconds. The summary counts completed presentations. Runs are limited by both --frames (default: 120) and --duration-ms (default: 3000, maximum: 60000); an in-flight presentation can finish after the deadline. For one minute of motion, use --pattern motion --fps 0 --frames 65536 --duration-ms 60000. These timings do not measure optical refresh or prove the absence of tearing or flicker. A camera’s exposure, sampling rate and rolling shutter also affect recorded transitions. Run fplinux-display-test --help for the remaining options.
Trace the kernel
Section titled “Trace the kernel”The debug kernel enables debugfs, tracefs, function and function-graph tracing, kprobe/uprobe events and syscall tracing. Check the mounted tracing filesystem and the facilities exposed by the running kernel before selecting a tracer or event. If tracefs is not mounted, mount it first:
mountpoint -q /sys/kernel/tracing || mount -t tracefs nodev /sys/kernel/tracingcat /sys/kernel/tracing/available_tracerscat /sys/kernel/tracing/current_tracercat /sys/kernel/tracing/available_eventsUse a separate trace instance for a capture so its tracer, enabled events and buffer do not replace another capture’s state. Choose an unused instance name and keep the same shell open until cleanup:
trace_instance=/sys/kernel/tracing/instances/fplinux-debug-$$mkdir "$trace_instance" || exit 1cleanup_trace() { printf 0 > "$trace_instance/tracing_on" printf 0 > "$trace_instance/events/enable" printf nop > "$trace_instance/current_tracer" rmdir "$trace_instance"}trap cleanup_trace EXITConfigure the capture through files inside that instance. When finished, stop it, disable its events, restore its tracer and remove only that instance:
cleanup_tracetrap - EXITDynamic probe definitions are shared between instances. Disable your probe in each instance that uses it, then remove only that definition with printf '%s' '-:GROUP/EVENT' >> /sys/kernel/tracing/kprobe_events or the corresponding uprobe_events file. Replace GROUP/EVENT with the name you created; do not clear the shared probe files.
Build a test program for the phone
Section titled “Build a test program for the phone”probe-build compiles one C file from the checkout into a static ARMv7 hard-float musl program for the phone. Create the C source first, outside the working data directory. Its path is relative to the checkout; the output must be inside the selected working directory’s tools/ and can be absolute:
./fplinux probe-build diag.c --output "$(./fplinux data-path)/tools/diag-arm"Copy it to a running phone and start it:
./fplinux console nokia-ta1618 --build-type debug --upload "$(./fplinux data-path)/tools/diag-arm" /tmp/diag-arm./fplinux console nokia-ta1618 --build-type debug --exec 'chmod +x /tmp/diag-arm && /tmp/diag-arm'probe-build compiles using local inputs. It does not add the program to an image. A failed compile leaves an earlier output unchanged. Prepare the shared build environment with ./fplinux setup first; if another input is missing, the command reports the required setup selection.
Report a problem
Section titled “Report a problem”Follow Report a problem for the information to include and the data to keep private. For a phone without a target, use the new-phone checklist and bring-up route.
Log command reference
Section titled “Log command reference”latest is selected after applying filters, including --build-type release or --build-type debug. Runs without recorded build type show unknown and do not match either filter. A directory basename is accepted only when it identifies one run. --stage accepts a stage name or complete stage path; a shared name selects all matches. An unknown stage reports the available IDs. Use --tail 0 to list stage headings without their existing output.
show --failed filters stages of the chosen run, rather than selecting another run. It includes unfinished child stages when their parent run failed or was interrupted; the heading preserves the child’s recorded status and explains the unfinished state. Reading logs does not change their recorded metadata. To select the latest failed build, use logs show latest --command build --status failed --failed. With no matching stages, the reader explains that result and exits successfully. follow stays with its selected invocation and prints new stages until completion; Ctrl+C stops only the reader.
Times are UTC. Output is grouped by stage, not globally merged; verbose parent logs may repeat child output. Log inspection needs no prepared build environment. Exit status is 0 for successful inspection, including a failed run, 1 for missing/ambiguous runs or read errors, 2 for invalid arguments and 130 for Ctrl+C. A running record without a surviving process is reported as incomplete.