pm3py/docs/plans/2026-07-03-firmware-upstream-rebase-plan.md

Firmware Upstream Rebase Plan (2026-07-03)

Rebase the firmware/ submodule (fork dangerous-tac0s/proxmark3-pm3py) onto current RRG upstream/master without losing our sim / sniff / inventory patch. Backed by a non-destructive dry-run (worktree + merge-tree).

Current state (measured)

• merge-base: c7086c227 (2026-02-20) — where we branched.
• our patch: 33 commits on top of merge-base (main == 35db99fa5).
• upstream ahead: 1049 commits (tip 87388b389, 2026-07-03) — ~4.5 months.
• Firmware is on main; ALM branch already scrapped.

Dry-run findings — the conflict surface is small and concentrated

A squash-then-rebase (all 33 commits applied as one combined diff, per git merge-tree) conflicts in exactly 3 files; everything else auto-merges or is untouched:

File	Verdict	ours vs upstream (lines)
armsrc/iso15693.c	⚠️ real work — 13 hunks	+599/−146 vs +523/−214
client/src/cmdhf15.c	⚠️ moderate	+372/−7 vs +544/−45
include/pm3_cmd.h	✅ trivial (textual re-append)	+21/−0 vs +94/−113
appmain.c, iclass.c, iso15693.h, iso15.h, Makefile	✅ auto-merge	—
sim_table.c/h, sim_crypto.c/h, Standalone/hf_15sniff.c, Standalone/hf_unisniff.c	✅ upstream never touched	—

A sequential rebase (replay 33 commits) is worse: it conflicts on commit #1 and, because 24 of the 33 commits touch iso15693.c, it re-conflicts that file many times. → Squash first, resolve once.

CMD-ID collision check — CLEAR ✅

All six IDs we added are free in upstream (upstream's 0x033x block only reaches CSETUID_V2 0x0333; 0x095x is empty):

0x0336 CMD_HF_ISO15693_SIM_TRACE    0x0950 CMD_SIM_TABLE_UPLOAD
0x0337 CMD_HF_SNIFF_STREAM          0x0951 CMD_SIM_TABLE_CLEAR
0x0338 CMD_HF_SNIFF_STATUS          0x0952 CMD_SIM_TABLE_UPDATE

So pm3_cmd.h is a pure textual re-append (drop our #defines at a clean spot in the churned region), not a semantic collision.

iso15693.c hunk map (13 hunks, 2 functions)

• 15693 sniff loop (~L1598–1853): our streaming-sniff feature (ring buffer, button-toggle, idle flush) vs upstream sniff edits. Biggest hunk ~53 lines (our idle/flush block) — mostly keep-ours-add-both.
• SimTag / sim loop (~L2475–3372): our sim handler (table lookup, access control, random UID, periodic field report) + the CheckCrc15 4-byte-frame fix vs upstream. ~10 hunks: three large (span 36–43, our inserted blocks → take-ours), the rest small (≤16) needing genuine line-level reconciliation — notably our CheckCrc15 vs upstream's CalculateCrc15 at ~L2591 (keep ours; it fixes 4-byte frames).

Effort estimate: ~half a day of focused merge work, dominated by iso15693.c; cmdhf15.c moderate; pm3_cmd.h ~10 min.

Strategy: squash-to-one → rebase (single 3-file resolution) → validate → re-split

Resolve conflicts exactly once (matching the merge-tree preview), validate the build, then restore clean per-file commits for cheap future rebases (the design-doc "atomic single-file commit" model).

Procedure (all in an isolated worktree — real checkout never moves)

FW=/home/work/pm3py/firmware
WT=<scratchpad>/fw-rebase
git -C $FW fetch upstream master
git -C $FW worktree add -b rebase-wip "$WT" 35db99fa5

cd "$WT"
# 1. collapse 33 commits into one diff on our base (no upstream yet → no conflicts)
MB=$(git merge-base HEAD upstream/master)
git reset --soft "$MB"
git commit -m "pm3py sim+sniff+inventory patch (squashed for rebase)"

# 2. rebase the single commit → conflicts in the 3 known files, resolved once
git rebase upstream/master      # resolve iso15693.c, cmdhf15.c, pm3_cmd.h
# ... resolve, git add, git rebase --continue

# 3. re-split into logical per-file commits (soft reset + staged adds)
git reset --soft upstream/master
#   commit A: sim_table.c/h + sim_crypto.c/h        (new modules)
#   commit B: pm3_cmd.h + iso15.h + iso15693.h      (IDs + struct fields)
#   commit C: appmain.c                              (dispatch)
#   commit D: iso15693.c                             (sim + sniff + inventory)
#   commit E: cmdhf15.c                              (client reader/inventory)
#   commit F: Makefile + Standalone/*                (build glue)

Validation (all local per build-workflow — ARM builds here, not the Mac)

1. make -C "$WT" clean && make -C "$WT" PLATFORM=PM3GENERIC — ARM compiles.
2. make -C "$WT" client — validates cmdhf15.c.
3. python -m pytest tests/ in pm3py — sim tests are transport-mocked, so they stay green; confirms no Python-side regression.
4. Hardware smoke test (user, has PM3): flash, then hf 15 scan + 15693 sim + a phone read (the known-good sim path). This is the only check the dry-run can't cover — upstream may have altered 15693 wire behavior around our insertions.

Landing

• Show resolved iso15693.c diff for review before anything touches main.
• Fast-forward firmware main to rebase-wip, bump the submodule pointer in a pm3py commit, force-push the fork (--force-with-lease).
• Remove the worktree (git worktree remove, no --force).

Risks & rollback

• Semantic drift in iso15693.c: upstream may have changed shared helpers our sim path calls. Compile catches signature breaks; behavior needs the hardware smoke test.
• Rollback: old main is preserved. Recovery ref for pre-rebase tip: 35db99fa5. Nothing is force-pushed until build + review pass.
• Safety Net: branch -D, rm -rf, git clean -f, worktree remove --force are blocked — use -d/plain rm/worktree remove (no force), or hand force-ops to the user.

Go-forward (close the gap that let us drift 1049 commits)

From the earlier maintenance discussion, still unbuilt:

• pm3py/firmware_compat.py — pin UPSTREAM_TESTED_COMMIT = 87388b389.
• A real rebase-check CI (the existing firmware/.github/workflows/ rebase.yml is upstream's Changelog Reminder, not ours).