Skip to content

Support halted Cortex-M33 register access. #79

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 1 commit into from
Sep 28, 2026
Merged

Support halted Cortex-M33 register access. #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,8 @@ posted access-port reads and a Cortex-M identity read through a MEM-AP. They
compose the public packages explicitly without duplicating their framing. The
`target/cortexm` package reads and decodes the architectural CPUID value through
any compatible target-word reader. It also provides acquired Cortex-M0 and
Cortex-M33 halt/resume control over word memory, plus Cortex-M0 stepping and
halted register access; see [Cortex-M control](docs/cortexm.md).
Cortex-M33 halt/resume control and halted register access over word memory, plus
Cortex-M0 stepping; see [Cortex-M control](docs/cortexm.md).

The FTDI path uses the standard H-series MPSSE port and endpoint layout.
Descriptor-driven FTDI port binding is not implemented yet. J-Link instead
Expand Down
5 changes: 3 additions & 2 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,9 @@ and how to assemble them without duplicating lower-level behavior.
posted AP access, power handshakes, and MEM-AP details worth testing.
- [CoreSight component inspection](coresight.md) describes identification
registers, ROM entry decoding, bounded traversal, and the inspection example.
- [Cortex-M control](cortexm.md) describes Cortex-M0 acquisition, halt/resume,
restoration, and the explicitly gated control example.
- [Cortex-M control](cortexm.md) describes Cortex-M0/M33 acquisition,
halt/resume, register access, restoration, and the explicitly gated control
example.
- [Composition](composition.md) maps common tasks to the narrowest public
package that implements them and gives coding agents a selection checklist.
- [Capabilities](capabilities.md) distinguishes implemented behavior from
Expand Down
5 changes: 3 additions & 2 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ service.
| `dap` | Bind SW-DP or baseline ADIv5 JTAG-DP, manage identity and power, execute ordered DP/AP transactions, and provide scalar or block MEM-AP access. |
| `dap/sim` | Model the DP, AP, and byte-addressed target-memory state consumed by `dap`. |
| `coresight` | Identify debug components and walk ROM tables through borrowed scalar memory, with explicit bounds and no resource acquisition or target-memory writes. |
| `target/cortexm` | Identify Cortex-M processors and own Cortex-M0/M33 halting debug, with Cortex-M0 register access, over borrowed word memory. |
| `target/cortexm` | Identify Cortex-M processors and own Cortex-M0/M33 halting debug, with halted register access, over borrowed word memory. |
| `examples/...` | Demonstrate public package compositions as executable programs. |
| `cmd/ost` | Provide a small command hierarchy over the same public packages. |

Expand Down Expand Up @@ -334,7 +334,8 @@ pending operations before restoring debug control; the target must be released
before the memory owner. Register writes persist after release. It does not know
about USB, adapters, or wire protocols. See [Cortex-M control](cortexm.md) for
restoration and failure boundaries. Cortex-M33 control requires Secure invasive
debug permission and excludes register access and stepping.
debug permission. Its stack register selectors use the halted security state;
register access does not change security state. Stepping remains Cortex-M0-only.

## Host implementations

Expand Down
30 changes: 15 additions & 15 deletions docs/capabilities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -291,23 +291,23 @@ 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; register access and stepping remain M0-only. |
| 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). |
| Register reads | Yes | Halted Cortex-M0 R0–R12, SP, LR, PC, XPSR, MSP, and PSP through `ReadRegister`. Two fresh CMSIS-DAP micro:bit sessions read all 19 registers; transfer failures and cleanup have behavioral coverage. |
| Register writes | Yes | Halted Cortex-M0 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 micro:bit sessions wrote and restored R4, SP, MSP, PSP, and PC before resuming; see the [register bench](cortexm.md#register-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. |
| 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; stepping remains M0-only. |
| 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). |
| 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. |
| 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 and excludes register
access and stepping. See [Cortex-M control](cortexm.md) for its effects and
cleanup limits.
Cortex-M33. M33 requires Secure invasive debug permission and excludes stepping.
Register access uses the halted security state. See
[Cortex-M control](cortexm.md) for its effects and cleanup limits.

## Executable surfaces

Expand Down
10 changes: 5 additions & 5 deletions docs/composition.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ data-register write can write target memory.
| Identify a Cortex-M through any compatible word reader | `cortexm.Identify` | `examples/simple/cortexm-info` |
| Acquire, halt, inspect registers, and resume a Cortex-M0 | `cortexm.Acquire`, `Target.Halt`, `Target.ReadRegister`, `Target.Resume`, `Target.Release` | `examples/simple/cortexm-control` |
| Step a Cortex-M0 from an owned halt | `Target.Step` | `examples/simple/cortexm-control -step` |
| Read or write a halted Cortex-M0 register | `Target.ReadRegister`, `Target.WriteRegister` | [Register reads](cortexm.md#register-reads), [writes](cortexm.md#register-writes) |
| Read or write a halted Cortex-M0/M33 register | `Target.ReadRegister`, `Target.WriteRegister` | [Register reads](cortexm.md#register-reads), [writes](cortexm.md#register-writes) |
| Test SWD and DAP behavior without hardware | `swd/sim`, `dap/sim` | Package tests |

The examples are intentionally small, executable compositions of public
Expand Down Expand Up @@ -738,10 +738,10 @@ CSW, then release and reconnect the debug port.
Use `target/cortexm` when the desired result is processor identity. It accepts
the word-reader behavior supplied by `dap.MemAP`, so target code remains
independent of the host, adapter, and wire protocol. `cortexm.Acquire` also uses
`WriteWord` to enable Cortex-M0 halting debug. Use `ReadRegister` for halted
core registers and `WriteRegister` for intentional changes. The target tracks
transfer completion but does not roll back writes. Release it before its memory
owner and retain both after failed target restoration. See
`WriteWord` to enable Cortex-M0 or Cortex-M33 halting debug. Use `ReadRegister`
for halted core registers and `WriteRegister` for intentional changes. The
target tracks transfer completion but does not roll back writes. Release it
before its memory owner and retain both after failed target restoration. See
[Cortex-M control](cortexm.md) for the full composition and effects.

## Release in reverse order
Expand Down
Loading
Loading