Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions native/waze-on-cluster/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@

## Unreleased

CarPlay's cluster map patch is applied in CarPlay's memory each time it
starts, and `/usr/bin/carplay` stays as it ships: no write of the system
partition to patch, remove or recover it. Updating from an earlier version
puts the original file back and keeps the map, with at most one head-unit
restart; where CarPlay already runs the earlier patch, none. The earlier
patch stays in the file where the file holds another change besides it,
where boot recovery counts a failed start, or where the patch in memory
cannot be set up.

## 0.10.12

The diagnostic journal is kept in memory and written to storage only around
Expand Down
34 changes: 32 additions & 2 deletions native/waze-on-cluster/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ WOC_SRC = src/main.cpp src/refused.cpp src/video_producer.cpp src/freeze_watch.c
CR_SRC = $(CR)/client/client.cpp $(CR)/client/protocol.cpp
SRC = $(WOC_SRC) $(CR_SRC) $(CR)/src/config.cpp $(CR)/src/log.cpp $(CR)/src/head_unit.cpp

.PHONY: all test test-bin test-cpp test-node test-x86 test-x86-in-docker test-firmware target target-in-docker clean
.PHONY: all test test-bin test-cpp test-node test-x86 test-x86-in-docker test-firmware target target-in-docker test-preload test-preload-in-docker clean

CPP_TESTS = $(BUILD)/host/nal_reader_test $(BUILD)/host/rtp_h264_test $(BUILD)/host/udp_probe_test \
$(BUILD)/host/map_feed_test $(BUILD)/host/keyframe_wait_test $(BUILD)/host/freeze_watch_test \
Expand Down Expand Up @@ -105,6 +105,7 @@ test-node:
umask 077 && $(NODE) patch/test/wifi_band_test.js
umask 077 && $(NODE) patch/test/dlt_capture_test.js
umask 077 && $(NODE) patch/test/recovery_test.js
umask 077 && $(NODE) patch/test/inmem_test.js
umask 077 && $(NODE) patch/test/journal_keep_test.js
umask 077 && $(NODE) patch/test/logs_test.js
umask 077 && $(NODE) patch/test/collect_logs_test.js
Expand Down Expand Up @@ -266,7 +267,36 @@ target:
docker run --rm --platform linux/amd64 --user "$$(id -u):$$(id -g)" -v "$(CURDIR):/w" -v "$(abspath $(CR)):/cr" -w /w $(IMAGE) \
make -s -j$(JOBS) BUILD=$(BUILD) CR=/cr target-in-docker

target-in-docker: $(T)/waze-on-cluster
target-in-docker: $(T)/waze-on-cluster $(T)/libwocpatch.so

# The in-memory carplay patch (preload/wocpatch.c, PATCH.md "In memory"):
# C, no C++ runtime, exports nothing, libc only.
PRELOAD_FLAGS = -std=gnu99 -O2 -g -Wall -Wextra -Werror -fPIC -fvisibility=hidden -D_FORTIFY_SOURCE=2
PRELOAD_LINK = -shared -Wl,-z,now -Wl,-z,relro -Wl,--no-undefined

$(T)/libwocpatch.so: preload/wocpatch.c
@mkdir -p $(@D)
gcc $(PRELOAD_FLAGS) $(PRELOAD_LINK) -o $@ $<

# The library against a test program, in the unit's toolchain image.
test-preload:
$(DOCKER_IMAGE)
docker run --rm --platform linux/amd64 --user "$$(id -u):$$(id -g)" -v "$(CURDIR):/w" -v "$(abspath $(CR)):/cr" -w /w $(IMAGE) \
make -s BUILD=$(BUILD)/x86 CR=/cr test-preload-in-docker

test-preload-in-docker: $(BUILD)/preload/libwocpatch.so $(BUILD)/preload/libwocpatch-crash.so
gcc -std=gnu99 -O2 -fPIE -pie -Wl,--build-id -o $(BUILD)/preload/target preload/test/target.c
gcc -std=gnu99 -O2 -fPIC -shared -o $(BUILD)/preload/libthread.so preload/test/thread.c -lpthread
sh preload/test/preload_test.sh $(abspath $(BUILD)/preload/libwocpatch.so) $(abspath $(BUILD)/preload/target) $(abspath $(BUILD)/preload/work)

# A test build that aborts once it has applied: an armed start that crashes.
$(BUILD)/preload/libwocpatch-crash.so: preload/wocpatch.c
@mkdir -p $(@D)
gcc $(PRELOAD_FLAGS) -DWOC_TEST_CRASH $(PRELOAD_LINK) -o $@ $<

$(BUILD)/preload/libwocpatch.so: preload/wocpatch.c
@mkdir -p $(@D)
gcc $(PRELOAD_FLAGS) $(PRELOAD_LINK) -o $@ $<

# Link-only stubs exporting the unit libraries' symbols. Each carries the real
# SONAME, so the binary records the right DT_NEEDED.
Expand Down
38 changes: 23 additions & 15 deletions native/waze-on-cluster/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ driven from the HMI by the companion app
Both send the cluster map only as H.264 video, with no map data, so this is
a video pipeline:

1. **Ungate the second display.** A reversible patch to
`/usr/bin/carplay` makes `KI_KOMBI_VARIANT` 7 resolve to a supported
1. **Ungate the second display.** A patch of carplay, applied in its
memory at start while `/usr/bin/carplay` stays as it ships, makes `KI_KOMBI_VARIANT` 7 resolve to a supported
cluster variant, makes CarPlay start the cluster stream itself, and
advertises the size the map is shown at ([patch/PATCH.md](patch/PATCH.md)).
Another to `/usr/bin/aapd` and `/etc/aapd.conf` does the same for Android
Expand All @@ -44,17 +44,21 @@ The Store installs it with the app `robertn_waze_cluster`; it requires
`cluster-render` and `mgu-deploy` (`component.json`, `"requires"`).

**Install.** The deploy tool runs `patchd.js activate` as root. On a car
coded `KI_KOMBI_VARIANT` 7 with a proven carplay build (or one CarPlay's
Patch button patched before), it writes the patch and never stops, kills or
coded `KI_KOMBI_VARIANT` 7 with a proven carplay build, it plans the patch
in memory and arms CarPlay's next start, and never stops, kills or
restarts CarPlay: the Store shows a restart pending, the app `Status:
Patched after restart`, and one head-unit start runs the patched CarPlay.
It then writes the Android Auto patch the same way on a proven aapd build.
Anywhere else it leaves the binary as it is, and the app's Status says why
(PATCH.md "Install-time activation").
Patched after restart`, and one head-unit start runs CarPlay with the
patch. Over an earlier release's patch of `/usr/bin/carplay` it puts the
shipped file back in the same step; the earlier patch keeps running until
CarPlay next starts, which then applies the patch in memory, so no restart
is needed for it. It then writes the Android Auto patch on a proven aapd
build. Anywhere else it leaves everything as it is, and the app's Status
says why (PATCH.md "Install-time activation", "In memory").

**Remove.** In the Store, remove the app, then the tool (refused while the
app is installed). `patchd.js deactivate` reverts our edits to carplay,
aapd and aapd.conf and drops our backups; the deploy tool then removes this
app is installed). `patchd.js deactivate` turns the patch in memory off,
reverts our edits to aapd and aapd.conf (and to carplay, where an earlier
release wrote them) and drops our backups; the deploy tool then removes this
tool's services and files. The next head-unit start runs the original
CarPlay and aapd.

Expand All @@ -70,9 +74,10 @@ restarts it at once only where that cannot restart the head unit (PATCH.md
on SIGTERM, which restarts the head unit.

**Boot recovery.** If a patch keeps the head unit restarting, the boot step
restores the original binary before CarPlay (or aapd) starts: after one
failed start for a patch not yet proven on that car, after two for a proven
one. CarPlay comes back without the map, its Status reads `Removed — head
stops arming CarPlay's patch in memory (and restores the original aapd)
before CarPlay (or aapd) starts: after one failed start for a patch not yet
proven on that car, after two for a proven one. CarPlay comes back without
the map, its Status reads `Removed — head
unit kept restarting`, and its Patch button applies the patch again
(PATCH.md "Boot recovery"). Android Auto's patch is removed at the first
crash of the patched aapd, and aapd is started again after every end, so
Expand Down Expand Up @@ -264,8 +269,10 @@ sources are left out.
### The patches

`patch/carplay_patch.js` and `patch/aapd_patch.js` (Node 8, no
dependencies) find their edit sites in the build, check them, take a
verified full backup, and write by atomic rename. The install patches only
dependencies) find their edit sites in the build and check them.
carplay's edits go into a plan that `preload/wocpatch.c`
(`libwocpatch.so`, preloaded into carplay) applies in memory; aapd's are
written to the file with a verified full backup, by atomic rename. The install patches only
a proven build; another build whose sites are all found is patched once a
Patch button (or `apply --unproven`) asks. Edits, sites and proven builds:
[patch/PATCH.md](patch/PATCH.md).
Expand All @@ -289,6 +296,7 @@ It remounts `/` read-write only for the write.

```sh
make test # host tests
make test-preload # libwocpatch.so against a test program, with the unit's toolchain in Docker
make test-x86 # the C++ tests with the unit's toolchain in Docker (SSE2 paths)
make target # build/target/waze-on-cluster in Docker, imports checked
make test-firmware ROOTFS=<dir> # DLT capture against the unit's own dlt-daemon in Docker
Expand Down
10 changes: 10 additions & 0 deletions native/waze-on-cluster/component.json
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,16 @@
"from": "patch/recovery.js",
"mode": "0644"
},
{
"path": "inmem.js",
"from": "patch/inmem.js",
"mode": "0644"
},
{
"path": "libwocpatch.so",
"from": "build/target/libwocpatch.so",
"mode": "0644"
},
{
"path": "patch_record.js",
"from": "patch/patch_record.js",
Expand Down
144 changes: 139 additions & 5 deletions native/waze-on-cluster/patch/PATCH.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
# The carplay patch, byte for byte

Six reversible edits to `/usr/bin/carplay` let waze-on-cluster receive the
CarPlay instrument-cluster map, at the size it displays and from the phone's
connection, on a head unit coded `KI_KOMBI_VARIANT` 7. `carplay_patch.js` applies, verifies and reverts them;
`patchd.js` runs it for the app and the install hooks, `woc-patch.sh` from a
shell.
Six edits to carplay let waze-on-cluster receive the CarPlay
instrument-cluster map, at the size it displays and from the phone's
connection, on a head unit coded `KI_KOMBI_VARIANT` 7. This tool applies
them in carplay's memory at each start it arms, and `/usr/bin/carplay` stays
as it ships ("In memory"). `carplay_patch.js` locates and checks them and
makes the plan the preloaded `libwocpatch.so` applies; it also applies,
verifies and reverts them in the file, as earlier releases did and
`woc-patch.sh` does from a shell. `patchd.js` runs it for the app and
the install hooks.

## Supported head units

Expand Down Expand Up @@ -682,6 +686,136 @@ the deploy tool stops and removes the tool's units, recmgr entries and
`/var/opt/waze-on-cluster`; the renderer releases the map's slot, and the
capture restores the DLT tracing mode and default log level as it stops.

## In memory

This tool applies the six edits to carplay's memory, never to
`/usr/bin/carplay`: the file stays as it ships, and `/` is not remounted
to patch, unpatch or recover CarPlay. The edits, their sites and their
checks are the ones above, from the same locator.

**The plan.** `carplay_patch.js plan` reads carplay on disk, which must be
the pristine build, runs every check an apply's first edit runs (the head
unit, the coding, the locator, a proven build or `--unproven`) and builds
the edited image as `apply` does. For each edit region that differs it
writes one line: the region's virtual address, the bytes the build ships
there and the bytes to write. It then lays the plan over the file again
(`overlay`) and keeps it only when that gives exactly the edited image.

```
wocplan 1
build-id 5de62156575d737391ea42254e778a97dbbb51f8
edit variant 2ba4f0 ecf2f7ff bcf2f7ff
edit selfstart 18176c e8effdffff e89f000000
...
end 10
```

`patchd` keeps the plan in `/var/opt/waze-on-cluster/inmem-carplay.plan`
and its record in `inmem-carplay.json` (`inmem.js`): enabled or not, by
whom it was turned off (`user`, `recovery`), `proven` or `trial`, the
plan's SHA-256 and carplay's inode, size and modification time. The record
describes carplay only while all of them match: a firmware update that
replaces carplay, or any other write of the file, leaves nothing armed.

**The library.** `libwocpatch.so` (C, libc only, exports nothing) runs as
a constructor of a preloaded library, after the libraries' own
constructors and before carplay's: its static initialisers (Edit 5's site
is one) and `main` have not run. It reads the plan and applies every edit
or none:

- the main program's GNU build-id, from its own `PT_NOTE` in memory, must
be the plan's; any other program (one carplay starts, which inherits
`LD_PRELOAD`) is left alone and writes no result;
- the plan must be whole: its version, every line, its closing count, and
only kinds of line this library knows, so a newer plan never meets an
older library half-understood;
- each region must lie inside the file-backed part of one `PT_LOAD`,
outside `PT_GNU_RELRO`, and read exactly its stock bytes. A site that
reads patched (a patched file on disk) refuses the plan too. A region
the plan leaves as it ships (the sink in the avb mode) is listed too and
checked the same way.

It then makes each page writable, keeping a code page executable for that
moment (`libdlt`'s constructor has started two threads by then; neither
runs carplay's code, which has not started), writes, gives each page its
segment's protection back and reads every region back. A failure before
the write changes nothing; one after it makes every page writable again,
writes the stock bytes back and restores the protections. Only a page that
cannot get its protection back ends carplay (`abort`), a crash boot
recovery counts; so does a page that cannot be made writable again to
put the stock bytes back. A region inside `PT_GNU_RELRO` refuses the plan. A plan that cannot
be read or parsed is reported on stderr only. The result goes to `/run/woc-preload/carplay.result`
(`{pid, applied, edits, why}`, a file the boot step made for carplay's user;
the library never creates one) and to the journal.

**Arming.** The tool's drop-in for `carplay.service` has
`EnvironmentFile=-/run/woc-preload/carplay.env`. Without that file carplay
starts as it ships. Boot recovery writes it, only for a start it arms
(below), last after the plan copy and the empty result file:
`LD_PRELOAD` holds the unit's own preload (`carplay.service` has
`Environment=LD_PRELOAD=/usr/lib/libschedconfig.so.1`; an `EnvironmentFile`
setting replaces it, so it is read from the unit and kept first), then
this version's library, and `WOC_PATCH_PLAN` and `WOC_PATCH_RESULT`. `/run`
starts empty at every head-unit start, so a start is armed only by that
boot's decision. carplay runs as `cia_13002` and is not setuid, so the
loader honours the preload; the library and plan are world-readable.

**Activation.** A change of the patch in memory takes effect when carplay
next starts. `patchd` restarts carplay itself where it may (above,
"Activation": SIGKILL with the run recorded, then start), so CarPlay's
Patch and Remove patch buttons need no head-unit start there. Install and
removal never restart it.

| On disk before the install | `activate` | Head-unit starts to get the map |
|---|---|---|
| the pristine proven build | plans and arms; a change pending | 1 |
| an earlier release's patch, with our backup | checks the plan on the backup, then reverts the file from it, drops the backup, plans and arms, in one step | 0 when the running carplay holds the plan's bytes (the earlier patch runs them), else 1 |
| the same, with another change in the file besides our patch, a patch that would start on trial while boot recovery counts a failure, or no way to arm here (the library, carplay.service's user, `/run/woc-preload`) | nothing: the earlier patch stays in the file, which this version's boot recovery guards | — |
| the original with our backup (Remove patch was used), or a patch boot recovery removed | nothing: the patch stays off; its Patch button applies it | — |

The patch in memory keeps the earlier patch's proven state where carplay
holds exactly the plan's bytes and its record says it ran healthy on this
car; otherwise it starts on trial. After the migration carplay on disk is
the shipped file and the running
carplay keeps the earlier patch until it ends; any later start of this boot
(a crash restart included) is armed, so the map is never off between the
two.

`patchd`'s status reads the plan's overlay of carplay for `res`, `safe`,
`mapurl` and the mode, and reads the running carplay's memory at the
plan's sites (`/proc/<pid>/mem`, read-only, at the mapping of the file it
runs): `patched` while it holds the plan's bytes, else the change is
pending (`Patched after restart`), unless the library's result for the
running carplay says it refused: then the conflict `not applied in memory:
<why>`, which a restart does not change. A plan turned off while carplay
still holds it reads `Removed after restart`.

**Boot recovery.** A start armed in memory is counted as a patched start
is ("Boot recovery" below), with the same thresholds: 1 failed start or
crash for a patch on trial or unproven, 2 for a proven one. One rule is
stricter: a restart recmgr or crashhandler recorded counts even after a
healthy run, since a reset that beats the shutdown mark leaves only that
record. At the threshold the restore is: remove the env file, then turn the
record off (`by: "recovery"`). Nothing is written to `/`, and the next
start, in this boot or the next, runs carplay as it ships. A patch on
trial becomes proven after a healthy run in which the running carplay's
memory holds the plan and the library's result names its PID. After boot
recovery turned a patch off, its Patch button plans it again, on trial; a
patch the user turned off keeps its proven state for the same plan.

**Removal and rollback.** `deactivate` turns the patch off (env removed,
record and plan deleted) and reverts any patch of an earlier release left
in the file. A release installed after this one finds a stock carplay with
no backup: it patches the file as it always did, and its boot recovery
restores that patch to stock. The record no longer describes that file, so
this version, installed again, never arms the plan over it
(`rollback_test.js`, part 6). An older release's drop-in has no
`EnvironmentFile`, so an env file left in `/run` from this boot is never
read.

Android Auto's patch is written to `/usr/bin/aapd` and `/etc/aapd.conf`
("Android Auto").

## Reversibility

Before the first edit the patcher writes the backup under a temporary name and
Expand Down
Loading