Skip to content

Own selected Cortex-M cores and retain partial outcomes. #82

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jon merged 3 commits into from
Oct 4, 2026
Merged

Own selected Cortex-M cores and retain partial outcomes. #82

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
89ecdf0
Acquire and release explicit Cortex-M groups.
jon Oct 2, 2026
0098318
Control selected Cortex-M group members.
jon Oct 2, 2026
4331bf6
Access Cortex-M group members through their owned targets.
jon Oct 2, 2026
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: 7 additions & 2 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,12 @@ their framing.

A target owns one processor. Several targets may borrow distinct MEM-APs from
one `armdebug.Conn`; all calls over that shared owner remain serialized.
Independent RP2350 core control has [physical evidence][dual-core]. It does not
provide group ownership, CTI routing, or a simultaneous memory snapshot.
`cortexm.Group` acquires and owns an explicit set of those targets, retaining
member outcomes and cleanup after partial failure. It supplies selected control,
register access, and stepping without lending raw targets. Independent RP2350
core control has [physical evidence][dual-core], and the [group bench][group]
exercises selected control and cleanup through one group. Neither path owns CTI
routing or supplies a simultaneous memory snapshot.

## Discovery and opening

Expand Down Expand Up @@ -416,3 +420,4 @@ Callers should always complete the documented release sequence, including when
the primary operation fails.

[dual-core]: cortexm.md#rp2350-independent-core-bench
[group]: cortexm.md#rp2350-group-bench
35 changes: 18 additions & 17 deletions docs/capabilities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -291,20 +291,21 @@ skips have hardware-independent test coverage.

## Cortex-M target operations

| Capability | Implemented | Validation and boundary |
| -------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CPUID read and decode | Yes | Accepts any aligned-word reader and validates a plausible Arm Cortex-M identity. |
| Physical identity read | HIL | Opt-in FTDI/SWD/DAP/MEM-AP integration test. |
| Cortex-M0 acquisition and halt/resume | HIL | Two CMSIS-DAP micro:bit sessions at a requested 1 MHz stopped a CPU counter during halt and observed progress after resume and release. Both restored initially disabled debug and running state before Arm debug owner close. Earlier sessions preserved initially enabled debug. Cleanup failures remain covered only by behavioral tests; see the [control evidence](cortexm.md#hardware-evidence). |
| Cortex-M33 acquisition and halt/resume | HIL | Two RP2350 core-0/J-Link sessions at 1 MHz stopped a RAM counter during halt, observed counter progress after resume and release, and restored disabled debug. Secure invasive debug permission is required. |
| Cortex-M0 step | HIL | `Target.Step` requires an owned halt and returns halted. Two fresh micro:bit sessions checked PC/R0/RAM across 13 steps each, resume, and release with disabled debug restored. Competing events and failure cleanup have behavioral coverage; see the [step bench](cortexm.md#step-bench). |
| Cortex-M33 step | HIL | Two fresh RP2350 core-0/J-Link sessions at 1 MHz checked PC/R0/RAM across 13 steps each, resume, and release with disabled debug restored. Secure counter state and DSCSR were preserved. Permission, snap-stall, restart after completion, and failure cleanup have behavioral coverage; see the [RP2350 step bench](cortexm.md#rp2350-step-bench). |
| Register reads | Yes | Halted Cortex-M0/M33 R0–R12, SP, LR, PC, XPSR, MSP, and PSP through `ReadRegister`. Two fresh sessions each on CMSIS-DAP/micro:bit and J-Link/RP2350 core 0 read all 19 registers; transfer failures and cleanup have behavioral coverage. |
| Register writes | Yes | Halted Cortex-M0/M33 writes except XPSR; aligned SP/MSP/PSP and even PC values. Writes persist after release. Behavioral tests cover staging, uncertain selection, and pending cleanup. Two sessions each on micro:bit and RP2350 core 0 wrote and restored R4, SP, MSP, PSP, and PC before resuming; see the [micro:bit](cortexm.md#register-bench) and [RP2350](cortexm.md#rp2350-register-bench) register benches. |
| Independent RP2350 cores | HIL | Two fresh J-Link sessions borrowed core-0/core-1 MEM-APs under one Arm owner. Each core halted and stepped while its peer advanced; both restored disabled debug and running state with inactive CTIs unchanged. See the [independent-core bench](cortexm.md#rp2350-independent-core-bench). This provides serialized per-core control, without group or CTI ownership. |
| Reset | No | No architectural or pin-reset operation exists. |
| Breakpoints or watchpoints | No | No target instrumentation API exists. |
| Firmware or runtime loading | No | No ELF loader, image-placement policy, or flash driver exists. |
| Capability | Implemented | Validation and boundary |
| -------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CPUID read and decode | Yes | Accepts any aligned-word reader and validates a plausible Arm Cortex-M identity. |
| Physical identity read | HIL | Opt-in FTDI/SWD/DAP/MEM-AP integration test. |
| Cortex-M0 acquisition and halt/resume | HIL | Two CMSIS-DAP micro:bit sessions at a requested 1 MHz stopped a CPU counter during halt and observed progress after resume and release. Both restored initially disabled debug and running state before Arm debug owner close. Earlier sessions preserved initially enabled debug. Cleanup failures remain covered only by behavioral tests; see the [control evidence](cortexm.md#hardware-evidence). |
| Cortex-M33 acquisition and halt/resume | HIL | Two RP2350 core-0/J-Link sessions at 1 MHz stopped a RAM counter during halt, observed counter progress after resume and release, and restored disabled debug. Secure invasive debug permission is required. |
| Cortex-M0 step | HIL | `Target.Step` requires an owned halt and returns halted. Two fresh micro:bit sessions checked PC/R0/RAM across 13 steps each, resume, and release with disabled debug restored. Competing events and failure cleanup have behavioral coverage; see the [step bench](cortexm.md#step-bench). |
| Cortex-M33 step | HIL | Two fresh RP2350 core-0/J-Link sessions at 1 MHz checked PC/R0/RAM across 13 steps each, resume, and release with disabled debug restored. Secure counter state and DSCSR were preserved. Permission, snap-stall, restart after completion, and failure cleanup have behavioral coverage; see the [RP2350 step bench](cortexm.md#rp2350-step-bench). |
| Register reads | Yes | Halted Cortex-M0/M33 R0–R12, SP, LR, PC, XPSR, MSP, and PSP through `ReadRegister`. Two fresh sessions each on CMSIS-DAP/micro:bit and J-Link/RP2350 core 0 read all 19 registers; transfer failures and cleanup have behavioral coverage. |
| Register writes | Yes | Halted Cortex-M0/M33 writes except XPSR; aligned SP/MSP/PSP and even PC values. Writes persist after release. Behavioral tests cover staging, uncertain selection, and pending cleanup. Two sessions each on micro:bit and RP2350 core 0 wrote and restored R4, SP, MSP, PSP, and PC before resuming; see the [micro:bit](cortexm.md#register-bench) and [RP2350](cortexm.md#rp2350-register-bench) register benches. |
| Independent RP2350 cores | HIL | Two fresh J-Link sessions borrowed core-0/core-1 MEM-APs under one Arm owner. Each core halted and stepped while its peer advanced; both restored disabled debug and running state with inactive CTIs unchanged. See the [independent-core bench](cortexm.md#rp2350-independent-core-bench). This provides serialized per-core control, without group or CTI ownership. |
| Cortex-M group ownership and control | HIL | `AcquireGroup` owns explicitly selected targets; selected halt/resume/status and member register/step access retain per-core outcomes and retryable cleanup. Two fresh RP2350/J-Link sessions exercised selected control, sequential stopping, three verified steps, and selective resume, with debug state restored and inactive CTIs unchanged before owner close. Failure paths have behavioral coverage; see the [group bench](cortexm.md#rp2350-group-bench). |
| Reset | No | No architectural or pin-reset operation exists. |
| Breakpoints or watchpoints | No | No target instrumentation API exists. |
| Firmware or runtime loading | No | No ELF loader, image-placement policy, or flash driver exists. |

Identity covers Cortex-M; acquired halt/resume control accepts Cortex-M0 and
Cortex-M33. M33 requires Secure invasive debug permission. Register access uses
Expand Down Expand Up @@ -346,9 +347,9 @@ SWD, and use the volatile DAP and MEM-AP state described above.
## Not currently provided

There is no CMSIS-DAP HID/v1 transport, automatic probe discovery policy,
automatic SoC attachment, group or CTI control, general target control,
semihosting, trace, debugger protocol server, firmware flashing, FPGA
programming, or Windows host implementation.
automatic SoC attachment, CTI control, general target control, semihosting,
trace, debugger protocol server, firmware flashing, FPGA programming, or Windows
host implementation.

Treat an absent capability as an explicit boundary. Do not infer it from the
project description or recreate its lower-level protocol inside an application.
Expand Down
Loading
Loading