Skip to content

refactor(cpu): add unknown opcode tracking infrastructure#3

Merged
Sakery merged 1 commit into
mainfrom
feat/z88headless-trace-enhancements
May 14, 2026
Merged

refactor(cpu): add unknown opcode tracking infrastructure#3
Sakery merged 1 commit into
mainfrom
feat/z88headless-trace-enhancements

Conversation

@Sakery
Copy link
Copy Markdown
Owner

@Sakery Sakery commented May 14, 2026

This is a minimal, observability-only change that enables z88headless to collect and report unknown opcodes without modifying core emulation semantics.

Changes:

  • Add UnknownOpcode struct to track PC and opcode byte
  • Add m_unknownOpcodes vector to accumulate all unknown opcodes
  • Add m_traceUnknown flag for runtime control of output
  • Add setTraceUnknown() public method for controlling trace
  • Add unknownOpcodes() getter for accessing collected data
  • Add recordUnknown() private method to handle both tracking and optional printing
  • Refactor CB prefix unknown handling to use recordUnknown()
  • Refactor ED prefix unknown handling to use recordUnknown()

Rationale:

  • No opcode behavior changes: all dispatch logic unchanged, only tracking added
  • No emulation semantics changes: instruction execution identical to before
  • Unknown opcodes are passively collected; printing is opt-in via setTraceUnknown()
  • This enables z88headless to provide detailed diagnostics for regression testing
  • Memory overhead is minimal (two bytes per unknown opcode encountered)

Summary

Describe clearly what this PR changes.

Checklist

  • Project builds successfully
  • Tests pass locally
  • CI passes
  • New logic includes tests where possible
  • No ROM binaries committed
  • No warnings introduced

Technical notes

Explain implementation details, tradeoffs or TODOs.

This is a minimal, observability-only change that enables z88headless to collect
and report unknown opcodes without modifying core emulation semantics.

Changes:
- Add UnknownOpcode struct to track PC and opcode byte
- Add m_unknownOpcodes vector to accumulate all unknown opcodes
- Add m_traceUnknown flag for runtime control of output
- Add setTraceUnknown() public method for controlling trace
- Add unknownOpcodes() getter for accessing collected data
- Add recordUnknown() private method to handle both tracking and optional printing
- Refactor CB prefix unknown handling to use recordUnknown()
- Refactor ED prefix unknown handling to use recordUnknown()

Rationale:
- No opcode behavior changes: all dispatch logic unchanged, only tracking added
- No emulation semantics changes: instruction execution identical to before
- Unknown opcodes are passively collected; printing is opt-in via setTraceUnknown()
- This enables z88headless to provide detailed diagnostics for regression testing
- Memory overhead is minimal (two bytes per unknown opcode encountered)
@Sakery Sakery merged commit ad3da6b into main May 14, 2026
2 checks passed
@Sakery Sakery deleted the feat/z88headless-trace-enhancements branch May 14, 2026 16:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant