Does: emulators in an owned AVD home behind Simlock's own adb server, and phones on the default adb server. Flows: device selection, drivers, screen, input.
Containment:
- Ownership is root membership, proven at boot and in running observations by
emu avd pathagainst the device's own folder, never a name. Every copy's AVD is namedsimlock, so the name is never evidence. - The gate (
ownership.ts): before anyemu kill,adb emu avd pathmust name this device's own AVD folder. It is asked every time, never cached; unreachable, timed out or another path sends nothing. - Every
adb,emulatorandavdmanagercall carriesANDROID_AVD_HOME(the root; a seed's folder while it is made; a copy's own folder at its boot) andANDROID_ADB_SERVER_PORT. Without them a call reaches the user's AVD home and the shared adb server. - The user's AVD home and devices.xml are only read. The one write is
destroyLegacy, for an AVD the registry names (safety rule 1). - A stored port is not trusted after a restart (#52); pinned by
two-instances.test.ts. Adestroyafter a restart stops each attached emulator whoseemu avd pathnames this AVD; a serial that cannot answer refuses the delete, and another path is left alone. listManagednever lists<root>/sources/: a seed is never a device.
Simlock's adb server:
- It runs with the emulator scanner, USB and mDNS off (
ADB_EMU=0,ADB_USB=0,ADB_MDNS=0), so nothing attaches unless it is announced. At start the driver announces every console port of its range (PORT_MINtoPORT_MAXinconsole-ports.ts), so emulators that outlived the last daemon reattach. A serial that stays silent during a boot is announced again. drivers.android.adbServerPortis never 5037.- The server is reaped by pid, and only when that pid's command line shows
adb,-P <port>andnodaemon. An unreadable command line kills nothing and keeps the record. disposeleaves the server and its record whenadb devicesstill lists an emulator, for the next daemon to adopt: an emulator whose server is gone starts an adbfork-serveron the port, which the next start refuses asoccupied. Emulators are spawned unref'd and outlive the daemon.- A server that cannot start is
AdbServerUnavailableError: Android is skipped withdriver.adb-server-rejected. No SDK isSdkMissingError: Android is absent, with no rejection.
Seeds and copies (ADR 0061):
- Every device is a copy of its kind's seed, or of the ready baseline source a lease names (
options.source). A stale baseline source is refused, never copied. - A seed is never leased or booted after its snapshot save.
- A seed is judged stale on every provision (its system image, the emulator's version, its launch settings), then destroyed and made again.
listSourcesreports the reason, which clears when things match. - One make per kind at a time.
Seedstakes that lock (seed:<spec key>) and the device states fromDeviceTable, never a lock of its own. - A
makingrow of an earlier process, or one older than any make takes, is swept at the next listing or make of its kind; its emulator is stopped by its path first. removeComponentdestroys the image's seeds after the uninstall; one that fails stays, listed stale.- The driver counts the user's own AVDs that name an image (
foreignDevices), and core refuses the removal while there are any.
Boot:
- A copy boots from
simlock_boot. When the snapshot does not load, the emulator cold-boots the same disk itself: not an error, only the logged diagnosticsnapshot-cold-boot. - Never
-wipe-data, except once for a device made before copies. Always-no-snapshot-save. A recovery boot never wipes and never loads a snapshot. -grpcalways goes with-port: without it the emulator opens no gRPC endpoint and writes noavd/runningdiscovery file. So a console port claims three ports: itself, the adb port above it and the gRPC port (GRPC_PORT_OFFSET).-crash-report-mode never(a stale crash dump otherwise opens a modal dialog that blocks the boot) is passed only whenemulator -helplists it: emulator 36.1.9 exits on it (#1297), soandroidPrerequisitesdoes not require it.neverdeletes the dumps in the database the emulator reads, soANDROID_EMU_CRASH_REPORTING_DATABASEnames a file in the root, never the user's shared one.- Ready is more than
sys.boot_completed:emu avd pathmust name the device's own folder (elseDriverCrashError), andpm path androidmust answer, since after a snapshot load the boot properties pass beforepmdoes. - No slim:
resolveSpecignoresmode.
Physical phones:
- The 5037 server is never started, stopped or adopted on purpose. A physical
adbcommand,listAttachedPhysical'sdevices -lincluded, may start it when nothing listens. Underandroid.networkDevices(ADR 0080) a phone is itsro.serialno, not its address. - Before every command
DefaultAdbServerGate.check: the 5037 server's protocol must equal Simlock'sadb version; nothing listening is open. A mismatch or an unreadable answer sends no command and shows as advisoryadb-protocol-mismatch.
Profiles and components:
- Profile sources are read in order: the library, the SDK (
avdmanager list device), the user's devices.xml. The first case-insensitive name match wins and classes the model. A devices.xml name the library shadows is advisorydevice-profile-hidden. - The sdkmanager catalog is never read.
- Existing devices are not re-checked for fit.
- A component is an API level. A licence refusal runs
sdkmanager --licensesonly underdownloads.acceptAndroidLicenses, elseAndroidLicenseNotAcceptedError: licence consent is never implied by download permission.
Tunnels (device-tcp.ts):
reverselistens on a free loopback port of the worker's tunnel range (TUNNEL_PORT_FIRSTtoTUNNEL_PORT_LAST) and runsadb reverse --no-rebindon the device's own server: Simlock's for an emulator, the 5037 one behind the gate for a phone.cannot rebind existing socketisTUNNEL_PORT_IN_USE.connectopens the device port throughopenDeviceSocketon the screen's target, with noadb forward, so a worker that dies leaves nothing listening.closeremoves the rule, then the listener. A removal that fails keeps the listener, which closes every connection at once, until the driver'sdestroyof an emulator orreclaimof a phone frees the port (release).- Safety rule 1 on a phone: only the tunnel's own
reverse --removeat close touches its rules. Its reclaim runs noreverse --remove-alland noforward --remove; it readsreverse --listand frees only the ports no rule points to (a failed read frees none). sweep, which the daemon calls before any request is served, removes from every present, idle, owned emulator the rules whose host side is in the tunnel range. On a leased emulator, and on any phone, it removes nothing and holds the ports those rules point to. A failed removal is a warning; reclaim and start go on.
- Simlock's adb server is stopped by pid only.
ADB_REJECT_KILL_SERVER=1refuses itskill-server. No record →occupied: find it withlsof(Windows:Get-NetTCPConnection -LocalPort <port>; the message nameslsofonly), or movedrivers.android.adbServerPort(one per instance). - A physical command can restart a 5037 server of another protocol (ADR 0022 §5). One started between the gate and the command is restarted by adb's client. Run every adb on the host from one platform-tools.
- Port checks are partial. A port handed out but not yet booted reads free to another instance.