mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-18 15:33:22 +09:00
Two things land together: the plan and contract draft P6 needs before it starts, and the
working notes that until now existed on exactly one machine.
1. P6's plan and contract draft (neither started; not one line of code)
docs/Disaggregated/P6-SPAWN-PLAN.md the package plan
docs/Disaggregated/P6-CONTRACT-DRAFT.md the contract draft (moves to
MG_Remote/CONTRACT-P6.md when c6 lands)
The three findings that mattered, all written into the documents:
a. P6 is SMALLER than its roadmap cell suggests. The transport primitives are already in
the tree and already tested: SocketDoorbell including hangup detection and the two
lost-wakeup fences (Doorbell.cpp:211-360, four cases in FdPassingTest), SCM_RIGHTS fd
passing, ShmSegment::Adopt, and the SurfaceOp / WindowKind schema already defined in
protocol.fbs. inproc uses a real second shm mapping rather than an alias, and
SessionRings.h:22-28 says that was done so today is not the first time it runs. P6 is
assembly plus a control plane plus a process, not "write a socket transport".
b. The evidence for "P6 is only a transport swap" has EXPIRED. It was bought by P5c, whose
audit found 59 direct memory accesses in a tree that already looked clean. P5e changed
the tree again. So the first package, a6, is a read-only audit that writes no code, and
every contract row that depends on it is marked PENDING a6 rather than decided in
advance.
c. P6 does not get a game running on the phone. ANativeWindow* is meaningless in the child,
and protocol.fbs:186-196's own comment says Android transfers the window out of band -
that band is P12. P6 lands pbuffer / surfaceless / offscreen, which is what HeadlessGL,
the split-equivalent lane and trace replay need, and which is exactly what P6's own exit
gate measures. A real window reaching the server is a named refusal. This gets its own
section because "P6 is done" would otherwise read as "the game runs now".
The contract adds rule G: a role may not name a process-local handle. It extends P5c's
rule E (a role may not name the other role's memory) from memory to identity - EGLDisplay /
EGLSurface / EGLContext / ANativeWindow* / fd number / pid / mapped address either cross as
a token this contract defines or they do not cross, and a descriptor crosses only through
SCM_RIGHTS, where the kernel renumbers it.
What P5e left for P6 gets its own section. The latch semantics are already designed
(ARCHITECTURE.md:504) and are copied unchanged. What is new is that after run-ahead the
client no longer waits while the peer process can DIE: the client holds records that were
published and will never be applied, and Android's freezer suspends the child without
closing anything. So slow and dead must be distinguishable WITHOUT a timeout threshold.
That is P6's only new design; everything else is carriage. It shares a predicate with E1's
outstanding re-specification (ID-122), and the two should be designed together.
Two gates carried over from P5e's lessons: G2 requires integration-spawn's test-name set to
match integration-split's name for name, because a differing set means the lane is quietly
running less; and the arm-proof gate requires every entry to record the child pid and
transport=spawn in its OWN private log - ID-124 established that this kind of false green
really happens, and a spawn lane that actually ran monolith would pass every other gate.
S2's shape must be settled before it is written, and the document says why: E1 is the
cautionary case.
2. The working notes move into the repository (docs/Disaggregated/notes/, 415 .md files)
ROADMAP / CURRENT_STAGE_PROGRESS / MEASUREMENTS cite ruling numbers, audit line numbers and
the provenance of gate figures from ~/w7/notes/, a directory that exists on one machine and
is under no version control. A record cited hundreds of times that lives only locally is not
a record, so it moves in whole, with its directory structure intact.
Only .md moves. Scripts, run logs, census and gate result JSON, patches, APKs and nm dumps
stay where they are: they are evidence DATA rather than documents - large, regenerated per
run, and mostly carrying absolute paths and device serials that mean something only on the
machine that produced them. The mapping and this split are written in
docs/Disaggregated/notes/README.md.
Two exceptions are recorded there too: P6's BRIEF has been promoted to a first-class
document and keeps no copy under notes/, so the two cannot drift apart; and recovered/ holds
material salvaged from failed workflow runs, which may duplicate the like-named phase
directories and is kept because a few of those were the only complete version at the time.
CI's citation lint takes docs/Disaggregated/*.md only (non-recursive), and notes/ is
deliberately outside it: those notes' file:line citations were written against their own
code heads, and resolving them against today's HEAD would fail wholesale - which is not an
error, it is their correct state as a historical record. To check one, use the revision it
declares (--rev).
3. Inconsistencies fixed in passing
- README.md's status line still said P5e was in progress while the stage table already said
closed.
- CURRENT_STAGE_PROGRESS's next-step item 1 still listed the exit gate as pending, though
(a) and (b) were run in the previous commit; rewritten to closed plus the one item that
actually remains (E1).
- ROADMAP's P6 row still had the pre-phase plan in three of its cells; it now carries the
package order, the scope boundary and the two new gates.
Checked with check_doc_citations.py: 125 citations across docs/Disaggregated/*.md, 0 problems.
226 lines
13 KiB
Markdown
226 lines
13 KiB
Markdown
# ap — P5 trace APK build and plumbing evidence
|
||
|
||
## Scope and source
|
||
|
||
**Complete:** final recipe run exited 0 with `P5_APK_DONE`,
|
||
2026-09-16 10:01:22–10:05:01 UTC−04:00. All three APKs are debug-signed,
|
||
verified and ready for the separate device step. Only the two cited failed-build
|
||
logs remain; no `~/w7/p5-ap-*` temporary files remain.
|
||
|
||
Build tree: `/home/swung/w7/p5-joint`, branch `p5/joint`, HEAD
|
||
`e61d00123c41d74f98cd06b63768be12d9b6348a` (ID-63's scratch head, not the final merged head).
|
||
No commits, checkout/merge/reset, device access, LFS fetch, or changes to any `build-*`
|
||
directory or another P5 worktree. All commands run in Arch WSL. `~/w7/pipe` is only
|
||
read as the source of hydrated dependency links and history.
|
||
|
||
## Plumbing truth
|
||
|
||
The premise that no Gradle file references `pipePush` is false: it is absent from
|
||
the Kotlin scripts but present in the **repository-root Groovy `build.gradle`**.
|
||
`android-plugin/settings.gradle.kts:18` includes `:MobileGL`, and line 19 maps it
|
||
to `..`; `android-plugin/app/build.gradle.kts:223` declares the library dependency.
|
||
`build.gradle:23-25` reads `rootProject.findProperty('mobilegl.pipePush')`, falls
|
||
back to `MOBILEGL_PIPE_PUSH_APK`, then `OFF`. `build.gradle:84` passes
|
||
`-DMOBILEGL_PIPE_PUSH=...` in the library's trace flavor. Its CMake path is the
|
||
root `CMakeLists.txt` (`build.gradle:93`), not the replay runner's CMake project.
|
||
History: `7a2e2561 [Build] (Android): let the trace APK be built in the push shape for the paired A/B`.
|
||
|
||
The surviving P4a files were inspected with
|
||
`unzip -p <apk> lib/arm64-v8a/libMobileGL.so | strings`:
|
||
|
||
| P4a APK | Lines containing `MGPipe` | Push-only function-name diagnostic |
|
||
|---|---:|---|
|
||
| `~/w7/notes/p4a/apk/trace-pull.apk` | 3 | `MGPipeApplySetVertexAttribDefaults` absent (0 lines) |
|
||
| `~/w7/notes/p4a/apk/trace-push.apk` | 109 | `MGPipeApplySetVertexAttribDefaults` present |
|
||
|
||
`MGPipeEmit` itself is not visible in the stripped P4a push APK. Absence of that
|
||
private symbol's spelling is not evidence of a pull build. The push APK contains
|
||
the function-name diagnostic `MGPipe: MGPipeApplySetVertexAttribDefaults does not
|
||
reproduce the carried value on this build ...`, along with push-only protocol
|
||
and handle diagnostics. P4a therefore used a real compile-time push arm, not
|
||
just the runtime mask. `ConfigLoader.cpp:260-270` separately parses the runtime
|
||
`MOBILEGL_PIPE_PUSH` mask; in compiled push it defaults to the migrated subsystem
|
||
mask, and the runtime setting cannot compile absent push code into a pull binary.
|
||
|
||
## Minimal uncommitted mapping
|
||
|
||
The existing push mapping is unchanged. Five lines in
|
||
`android-plugin/build.gradle.kts` expose the two split options in the existing
|
||
`com.android.library` configuration, which reaches `:MobileGL`. Both default OFF.
|
||
No change to `android-plugin/app/build.gradle.kts` is needed, because its native
|
||
project builds `libtrace_replay_runner.so`, not `libMobileGL.so`.
|
||
|
||
```diff
|
||
diff --git a/android-plugin/build.gradle.kts b/android-plugin/build.gradle.kts
|
||
index c351d75e..f118094d 100644
|
||
--- a/android-plugin/build.gradle.kts
|
||
+++ b/android-plugin/build.gradle.kts
|
||
@@ -29,6 +29,11 @@ subprojects {
|
||
}
|
||
externalNativeBuild {
|
||
cmake {
|
||
+ // P5 trace A/B: :MobileGL owns libMobileGL.so, not :app's replay runner.
|
||
+ arguments += listOf(
|
||
+ "-DMOBILEGL_BUILD_DISAGGREGATED=${project.findProperty("mobilegl.buildDisaggregated") ?: "OFF"}",
|
||
+ "-DMOBILEGL_BUILD_DISAGGREGATED_INPROC=${project.findProperty("mobilegl.buildDisaggregatedInproc") ?: "OFF"}",
|
||
+ )
|
||
mobileGlCmakeCompilerLauncher().takeIf(String::isNotEmpty)?.let { compilerLauncher ->
|
||
arguments += listOf(
|
||
"-DCMAKE_C_COMPILER_LAUNCHER=$compilerLauncher",
|
||
```
|
||
|
||
Suggested integrator commit subject (not committed here):
|
||
`[Build] (Android): expose disaggregated trace APK options`.
|
||
|
||
| Arm | `mobilegl.pipePush` | `mobilegl.buildDisaggregated` | `mobilegl.buildDisaggregatedInproc` |
|
||
|---|---|---|---|
|
||
| pull | OFF | OFF | OFF |
|
||
| push | ON | OFF | OFF |
|
||
| split | ON | ON | ON |
|
||
|
||
Root CMake defaults these options OFF (`CMakeLists.txt:23,30,35`), makes INPROC
|
||
imply DISAGGREGATED (`:460-464`) and DISAGGREGATED imply PUSH (`:496-501`).
|
||
|
||
## Recipe and validation
|
||
|
||
Reusable command, after applying/merging the mapping into the chosen final tree:
|
||
|
||
```sh
|
||
bash ~/w7/notes/tools/wsl_build_p5_apks.sh /path/to/final-tree p5
|
||
```
|
||
|
||
The second argument is optional and defaults to `p5`; output is
|
||
`~/w7/notes/<phase>/apk/trace-{pull,push,split}.apk`. The recipe rejects the
|
||
read-only integration tree and any other `~/w7/p5-*` worktree. It never runs adb.
|
||
Use a separate permitted final-tree checkout if the final merged head lives in
|
||
the read-only integration tree.
|
||
|
||
Each arm uses Gradle 8.10.2, JDK 21, SDK `~/android-sdk`, NDK 27.3.13750724,
|
||
`:app:assembleTraceRelease`, arm64-v8a only, debuggable release, INFO logging,
|
||
and `-Pmobilegl.apkSuffix=p5<arm>`. AGP selects optimized native
|
||
`RelWithDebInfo` (`-O2 -g -DNDEBUG`) for the debuggable release variant, matching
|
||
the P4a recipe; it does not compile an unoptimized Debug library.
|
||
The final recipe uses Gradle `--offline` with the existing populated dependency
|
||
cache, avoiding repository revalidation delays and downloads. A fresh machine
|
||
must have these Gradle/SDK dependencies provisioned before running it.
|
||
The recipe explicitly passes all three CMake switches for every arm, so Gradle's
|
||
argument-specific `.cxx` configurations cannot silently retain split flags in pull.
|
||
It uses only Android `.cxx`/`build` output directories, never desktop `build-*`.
|
||
|
||
`apkSuffix` changes the output filename only. For actual side-by-side installation,
|
||
the recipe also passes `-Pmobilegl.applicationIdSuffix=.p5<arm>`. The final
|
||
manifest package IDs are recorded by `aapt` in each arm's `.badging.txt`.
|
||
Each APK is signed with `~/.android/debug.keystore`, alias `androiddebugkey`,
|
||
and checked by `apksigner verify --verbose --print-certs`. V4 sidecars are disabled.
|
||
|
||
Evidence files beside the APKs: `build-provenance.txt`, `build-plumbing.diff`,
|
||
`trace-<arm>.proof.json`, `.cmake.txt`, `.badging.txt`, `.signing.txt`, and
|
||
`.symbols.txt`. APK extraction is to a `~/w7/p5-ap-*` temporary file, removed
|
||
automatically. GNU `strings` counts matching lines, not occurrences within lines.
|
||
Private symbols are stripped from release APKs; the report distinguishes retained
|
||
function-name diagnostic strings from true ELF symbol definitions. The recipe also
|
||
uses NDK `llvm-nm --defined-only --demangle` on the unstripped native output and
|
||
requires `llvm-strip --strip-unneeded` to reproduce the packaged `.so` **byte for
|
||
byte**, tying those definitions to the delivered binary without inflating APKs.
|
||
|
||
Initial configure failed because all thirteen submodule gitlink paths in the joint
|
||
tree were empty directories. Failure evidence is retained at
|
||
`~/w7/p5-apk-pull-missing-dependencies.log`. The recipe links only missing/empty
|
||
dependency paths to existing hydrated local copies under `~/w7/pipe`, refuses
|
||
broken links/missing source dependencies, and never initializes/fetches submodules.
|
||
The links are left in place. Successful build logs are removed individually.
|
||
During the first push attempt the links were externally replaced by empty
|
||
directories again (10:00 timestamps; HEAD unchanged), causing another CMake
|
||
failure. Evidence: `~/w7/p5-apk-push-dependency-links-removed.log`. The full
|
||
recipe was restarted after restoring the links. Other owners must not toggle
|
||
joint-tree dependency links while an APK build is running.
|
||
|
||
## Three-APK proof table
|
||
|
||
All sizes are exact bytes. Each `.so` is `lib/arm64-v8a/libMobileGL.so` extracted
|
||
from the named APK, not a desktop library.
|
||
|
||
| APK under `~/w7/notes/p5/apk/` | APK bytes | `.so` bytes | `MGPipe` string lines | Push-only name in APK (`MGPipeApplySetVertexAttribDefaults`) | Remote names in APK | `MOBILEGL_TRANSPORT` string lines |
|
||
|---|---:|---:|---:|---|---|---:|
|
||
| `trace-pull.apk` | 8,504,077 | 15,461,752 | 3 | absent | absent | 0 |
|
||
| `trace-push.apk` | 8,626,957 | 15,699,448 | 116 | present | absent | 0 |
|
||
| `trace-split.apk` | 8,737,549 | 15,941,584 | 190 | present | present | 5 |
|
||
|
||
Push-only function-name strings are diagnostic literals, not exported ELF symbols.
|
||
Split additionally retains genuine RTTI type-name strings such as
|
||
`N8MobileGL9MG_Remote9Transport18InProcessTransportE` and
|
||
`N8MobileGL9MG_Remote6Client20BackendObject_RemoteE`, plus the diagnostic naming
|
||
`ServerLoop::Start before ServerSession::Accept`. None occurs in pull or push.
|
||
|
||
The exact-strip-equal native binaries provide the stronger ELF-symbol check:
|
||
|
||
| Arm | `llvm-nm` defined `MGPipeEmitResourceSubData` | `llvm-nm` defined lines containing `MG_Remote` | Stripped bytes equal APK `.so` |
|
||
|---|---|---:|---|
|
||
| pull | absent | 0 | PASS |
|
||
| push | present (function plus its once-log latch) | 0 | PASS |
|
||
| split | present (function plus its once-log latch) | 459 | PASS |
|
||
|
||
The five split transport string lines, absent in both other APKs, are:
|
||
|
||
```text
|
||
MOBILEGL_TRANSPORT
|
||
Config: MOBILEGL_TRANSPORT=inproc - the MGPipe record stream crosses a real ring to an apply thread
|
||
Config: MOBILEGL_TRANSPORT='%s' names a transport P6 implements and P5 does not; staying on monolith. This run is NOT a split run.
|
||
Config: Ignoring invalid env variable MOBILEGL_TRANSPORT='%s'; expected monolith|inproc|spawn|unix:<path>|pipe:<name>, using monolith
|
||
MG_Remote client: MOBILEGL_TRANSPORT=%s%s is refused by name - P5 implements `inproc` only, and falling back to monolith would make this lane green for the wrong reason. spawn / unix: / pipe: are P6's
|
||
```
|
||
|
||
| Arm | Verified manifest package | APK SHA-256 |
|
||
|---|---|---|
|
||
| pull | `top.mobilegl.plugin.p5pull.trace` | `8dd7154f6e25c1cb998669cb3ea0e62a16c6595aa44dd4322b0118c6b628ed47` |
|
||
| push | `top.mobilegl.plugin.p5push.trace` | `998c83b5782194555756a49826407f2efaf4c499b9f330f4fcab2dcd2e0e3965` |
|
||
| split | `top.mobilegl.plugin.p5split.trace` | `bce8c6f751179ffe68124198819ee15c6871b8642d21ff03c17ea99f12a3cbda` |
|
||
|
||
All three manifests contain `application-debuggable`, minSdk 26, targetSdk 34,
|
||
and only `native-code: 'arm64-v8a'`. All three pass APK signature schemes v2 and
|
||
v3 with the same RSA-2048 Android Debug certificate, SHA-256
|
||
`97818b7025d0da0df79d1398306a699e18e06c1f15ea9626ece996526574148d`.
|
||
Their `.cmake.txt` records confirm INFO, optimized RelWithDebInfo, PUSH
|
||
OFF/ON/ON, DISAGGREGATED OFF/OFF/ON and INPROC OFF/OFF/ON; VERIFY is OFF throughout.
|
||
|
||
The final source delta remains the five-line Kotlin mapping plus the thirteen
|
||
local dependency symlinks (git reports those gitlink-to-symlink type changes).
|
||
**Do not commit the dependency symlinks.** The mapping is the only source edit to
|
||
integrate. HEAD remained `e61d00123c41d74f98cd06b63768be12d9b6348a` for every arm.
|
||
|
||
## Runtime handoff — no device work performed
|
||
|
||
The **split APK defaults to monolith**. The third A/B arm must use it with
|
||
`--env MOBILEGL_TRANSPORT=inproc --env MOBILEGL_PIPE_STATS=1` (and the same stats
|
||
period and all other benchmark settings as pull/push). A fourth control arm uses
|
||
the same split APK with `MOBILEGL_TRANSPORT` absent and stats still enabled; it
|
||
must equal push within measurement noise. This is a requirement for the separate
|
||
device run, not a performance result measured by this package.
|
||
|
||
This is an **environment variable on Android, not a config-file setting**:
|
||
`MobileGL/ConfigLoader.cpp:43` accepts the `MOBILEGL_` prefix; `:53-59` selects
|
||
`::environ` on POSIX/Android; `:63-72` captures key/value pairs; `:78-84` queries
|
||
that map; `:321` reads `MOBILEGL_TRANSPORT` with default `monolith`, and `:331-335`
|
||
selects inproc. `android-plugin/app/src/trace/cpp/trace_replay_core.cpp:143-149`
|
||
applies runner overrides with `setenv`, and `:237` invokes it.
|
||
`~/w7/notes/tools/p4a_ab_redmi.sh:88` already passes generic `--env` settings.
|
||
|
||
The existing wrapper `tools/trace_replay/run_android_retrace_local.py:26,31`
|
||
hardcodes `top.mobilegl.plugin.trace` and passes that at `:147-148`; the separate
|
||
A/B owner must target the actual per-arm package IDs and APK paths recorded here,
|
||
including for force-stop/activity/run-as operations. `android-plugin/trace-replay-ci.sh`
|
||
already accepts `--package`. No runner/device script is changed by this package.
|
||
|
||
Canonical sizes from ID-47 / `MG_Remote/Transport/SessionRings.h:83-97` are
|
||
command ring 8 MiB, stage 32 MiB, reply pool 16 MiB, event ring 256 KiB; command
|
||
and event mappings additionally include a 4096-byte control page. Reply pool has
|
||
eight 2 MiB slots, each with 16-byte header: max payload 2,097,136 bytes. The
|
||
640x480 RGBA8 readback (1,228,800 bytes) fits. A full 2400x1080 RGBA8 readback
|
||
does not fit and is a named refusal/P6 readback debt (ID-47), so the A/B owner
|
||
must preserve the reduced-path surface sizes.
|
||
|
||
No desktop gate rerun is claimed: the user supplied the owner's completed gate
|
||
and forbade touching its build directories. This package validates Android build
|
||
configuration, artifacts, signatures and identity; runtime equivalence belongs to
|
||
the separately guarded device A/B.
|