Add explicit PC metadata for instructions (#1825)

[Aman (amkr6207)]

Fixes #1825.

Add explicit instruction-level metadata for whether an instruction references and/or changes the PC, rather than inferring that from operation() IDL.

This change:

• adds optional pc.references / pc.changes fields to the instruction schema
• makes the metadata available through the Ruby instruction model
• adds a small test for the new metadata
• documents the new metadata
• annotates representative instructions:
  • auipc
  • jalr
  • mret

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.19%. Comparing base (7259e0e) to head (f011b75).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1827      +/-   ##
==========================================
- Coverage   72.21%   72.19%   -0.03%     
==========================================
  Files          52       52              
  Lines       27740    27746       +6     
  Branches     6012     6002      -10     
==========================================
- Hits        20033    20030       -3     
- Misses       7707     7716       +9     

Flag	Coverage Δ
idlc	76.11% <ø> (-0.05%)	⬇️
udb	66.25% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Paul Clarke (ThinkOpenly)]

Neat! I think this is a good addition. Derek Hower (@dhower-qc) ? Sam Elliott (@lenary) ?

If adopted, we need to annotate many other instructions, of course:

$ grep -l -E -i 'jump\(|jump_halfword\(|\$pc' $(find gen/resolved_spec/_/inst -type f)
gen/resolved_spec/_/inst/Smrnmi/mnret.yaml
gen/resolved_spec/_/inst/Zcmt/cm.jalt.yaml
gen/resolved_spec/_/inst/Zcmt/cm.jt.yaml
gen/resolved_spec/_/inst/Zcmp/cm.popret.yaml
gen/resolved_spec/_/inst/Zcmp/cm.popretz.yaml
gen/resolved_spec/_/inst/C/c.ebreak.yaml
gen/resolved_spec/_/inst/C/c.j.yaml
gen/resolved_spec/_/inst/C/c.bnez.yaml
gen/resolved_spec/_/inst/C/c.jr.yaml
gen/resolved_spec/_/inst/C/c.jal.yaml
gen/resolved_spec/_/inst/C/c.beqz.yaml
gen/resolved_spec/_/inst/C/c.jalr.yaml
gen/resolved_spec/_/inst/S/sret.yaml
gen/resolved_spec/_/inst/I/bne.yaml
gen/resolved_spec/_/inst/I/bge.yaml
gen/resolved_spec/_/inst/I/bgeu.yaml
gen/resolved_spec/_/inst/I/jalr.yaml
gen/resolved_spec/_/inst/I/blt.yaml
gen/resolved_spec/_/inst/I/beq.yaml
gen/resolved_spec/_/inst/I/ebreak.yaml
gen/resolved_spec/_/inst/I/jal.yaml
gen/resolved_spec/_/inst/I/auipc.yaml
gen/resolved_spec/_/inst/I/bltu.yaml
gen/resolved_spec/_/inst/I/mret.yaml

[Paul Clarke (ThinkOpenly)]

Suggested change

	pc:
	pc: # program counter

[Aman (amkr6207)]

Updated. Thanks!

[Paul Clarke (ThinkOpenly)]

Subjective, but these might be better as read/write:

Suggested change

	references: true # Optional: instruction semantics reference the current PC
	changes: false # Optional: instruction semantics update the PC
	reads: true # Optional: instruction semantics reference the PC
	writes: false # Optional: instruction semantics update the PC

If adopted here, these changes would be needed throughout this PR, of course.

[Paul Clarke (ThinkOpenly)]

For consistency with other definitions here:

Suggested change

	"description": "Explicit metadata describing whether the instruction reads and/or writes the program counter",
	"description": "Whether the instruction reads and/or writes the program counter",

[Aman (amkr6207)]

Updated. Thanks!

[Paul Clarke (ThinkOpenly)]

I'm also not sure how a really weird instruction like qc.cm.ilut should be annotated, since as part of its semantics, it executes other instructions which may or may not reference/update the PC.

[Paul Clarke (ThinkOpenly)]

I'm also not sure how a really weird instruction like qc.cm.ilut should be annotated, since as part of its semantics, it executes other instructions which may or may not reference/update the PC.

Maybe nevermind on that concern. That instruction does not permit executing PC-relative instructions .

[Paul Clarke (ThinkOpenly)]

Another way of implementing this would be adding an implicit operand to the instructions. The operand definitions are emerging in #1527. One nice thing that's already present there is the concept of "source" (read) and "destination" (write). Not yet present there, but probably needs to be is "implicit" operands. Program counter is certainly one. Stack pointer is another.

[Derek Hower (dhower-qc)]

Not opposed to this, but would like to see a regression test that ensures IDL and the YAML annotation agree.

[Aman (amkr6207)]

Paul Clarke (@ThinkOpenly) Derek Hower (@dhower-qc)

Addressed the requested changes.

I added the regression test, the doc comment, and the schema wording update. I left references / changes unchanged since the reads / writes suggestion seemed optional.

Thanks!

[Aman (amkr6207)]

Paul Clarke (@ThinkOpenly), Derek Hower (@dhower-qc)

Please review the PR. Thanks!

[Aman (amkr6207)]

Paul Clarke (@ThinkOpenly), Derek Hower (@dhower-qc)

PTAL. Thanks!

[Paul Clarke (ThinkOpenly)]

Aman (@amkr6207), could you take a look at the latest in #1527? In there,

• operand_schema.json defines the schema for including the pc as an operand, including source, destination, and implicit attributes.
• pc.yaml describes an implicit source program counter operand.
• bne.yaml shows a use of an implicit pc operand which is both source and destination.

(An open question, perhaps, is whether an implicit opcode field is also needed. That would be slightly redundant with the operand definition, but it might be helpful for use-cases like a decoder which may not care about assembly operands.)