Step Cortex-M0 from an owned halt.

[jon]

Add Target.Step(ctx) to advance an acquired Cortex-M0 through one architectural step and return halted, with stepping disabled. It requires a halt owned by that target, preserves competing debug stops, and leaves register access available after success. The control example gains an optional -step.

With a borrowed MEM-AP:

core, err := cortexm.Acquire(ctx, memory)
// Retain every non-nil core, including after failed acquisition.
if err == nil {
    err = core.Halt(ctx)
}
if err == nil {
    err = core.Step(ctx)
}
if err == nil {
    var pc uint32
    pc, err = core.ReadRegister(ctx, cortexm.PC)
    if err == nil {
        fmt.Printf("PC after step=%#08x\n", pc)
    }
}
if err == nil {
    // Do halted things.
    err = core.Resume(ctx)
}
cleanupCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
cleanupErr := core.Release(cleanupCtx)
cancel()
err = errors.Join(err, cleanupErr)
// Close the memory owner only after target release succeeds.
// Retain both owners after failure; retry with a usable context.

Why

The target could halt, inspect registers, and resume, but could not advance execution by a step. Step settles register transfers before launch and waits for a fresh halt. It checks DFSR before and after launch to distinguish the step's halt from breakpoint, watchpoint, vector-catch, or external events, preserving all event flags. Existing competing flags prevent stepping. A competing stop remains unowned and can prevent restoring initially disabled debug.

The caller controls cancellation and deadlines. After launch is attempted, failure leaves only Release available. Cleanup can finish an accepted step and retry clearing C_STEP while halted, but never launches another step. An unconfirmed launch, ignored request, reset, changed debug control, or observed loss of the completed halt can prevent automatic cleanup.

Interrupt masking is unchanged. An architectural step can enter an exception handler or encounter another debug event, so success does not promise instruction retirement. Execution and peripheral effects cannot be undone.

Documentation

Update the Cortex-M guide, capability table, architecture and composition guidance, and control example. The API remains Cortex-M0 only; the guide describes ownership, event flags, failure states, and the hardware procedure.

Hardware evidence

On September 26, 2026, Nostalgia (macOS) ran two fresh CMSIS-DAP micro:bit sessions through SWD at a requested 1 MHz and AP0. Probe serial 9900360140124e4500279015000000360000000097969901; Cortex-M0 CPUID 0x410cc200. The test verified the counter firmware's vectors and instructions before acquiring the target.

OSTIOLE_CORTEXM_HIL_CONTROL=1 \
OSTIOLE_CORTEXM_HIL_STEP=1 \
OSTIOLE_CORTEXM_HIL_PROGRAM=sha256:ee294cc06ab6e8228161b49506675b065c0148b26421cf1f83c8e45e35cd4e5d \
go test -tags integration ./target/cortexm -run '^TestHILCortexM0Step$' -count=1 -v

Each session checked twelve consecutive steps through adds r0, #1, str r0, [r1], and the branch back to the loop. PC, R0, and the RAM counter matched the expected instruction effects after every step. The processor remained halted with stepping disabled between calls, and the counter stayed unchanged across ten samples 20 milliseconds apart after the sequence. Both sessions then resumed, halted, checked a thirteenth step, and released from that halt. Counter progress returned after resume and release. DHCSR was 0x01000000 before acquisition and after release in both sessions; initially disabled debug and running state were restored. Both target and Arm debug owners closed successfully.

The example also completed with -provider cmsisdap -serial 9900360140124e4500279015000000360000000097969901 -ap 0 -clock 1000000 -allow-control -step, printing PC before and after the step and resuming.

Instruction effects were not rolled back. The firmware disables configurable interrupts; exception entry, competing debug events, and failure cleanup are covered only by behavioral tests. Sleeping instructions and state after Arm owner close were not measured.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-27T21:05:00.035302Z	93257b2	Manual request
🔒 Security Review	✅ Completed 2026-09-27T20:15:36.377278Z	2997736	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[jon]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 2997736046

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[jon]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit: 93257b2560

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".