Skip to content

Comment every module port consistently - #1955

Open
davidharrishmc wants to merge 15 commits into
openhwfoundation:mainfrom
davidharrishmc:dh/port-comments
Open

Comment every module port consistently#1955
davidharrishmc wants to merge 15 commits into
openhwfoundation:mainfrom
davidharrishmc:dh/port-comments

Conversation

@davidharrishmc

@davidharrishmc davidharrishmc commented Oct 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Builds on #1952; review only the last commit until that merges.

  • Adds a definition comment to every port in src/ that had none, except clk and reset, which are left uncommented.
  • Rewrites 953 existing comments so the same signal is described the same way everywhere (stage families share a template, e.g. "Stall Decode stage"), and fixes several that were wrong (e.g. LSUFlushW, SelAdrData, IEUAdrExtM).
  • Keeps module-specific text only where a name genuinely means something different (e.g. A/D in the SRAM macros vs. the FPU, Y in generic blocks).

Comments and whitespace only: code tokens are identical to the base, coverage-exclusion GetLineNum targets still match, and lint-wally passes.

🤖 Generated with Claude Code

davidharrishmc and others added 3 commits October 10, 2026 06:19
@davidharrishmc @claude
Clean up comments and whitespace in src/; delete unused modules
c9e8c1a 
Fix spelling, grammar, and wrong or garbled comments; normalize
indentation and operator spacing; and add short comments explaining
hard-to-follow control-bit logic, especially in the FPU. Code tokens
are unchanged. Delete eight modules that are never instantiated.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@davidharrishmc @claude
Merge upstream/main (cache set width fix openhwfoundation#1948) into …
5ae0b5b 
…dh/sv-cosmetics

Resolve the src/cache/cache.sv conflict by taking openhwfoundation#1948's code (OFFSETLEN
and SETLEN as parameters, NextSet sized OFFSETLEN+SETLEN) and keeping this
branch's comment/whitespace cleanup.  The NextSet comment no longer says
"lower 12 bits", and the new localparams openhwfoundation#1948 added to ifu.sv and lsu.sv
get aligned comments.  After stripping comments and whitespace, every src/
file still matches main.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: David Harris <David_Harris@hmc.edu>
@davidharrishmc @claude
Keep fdivsqrtuslc4, prioritythermometer and two RAMs
2a9b232 
Restore fdivsqrtuslc4, prioritythermometer, ram2p1r1wbe_128x64 and
ram2p1r1wbe_2048x64 as they are on main, and put the two RAMs back in
run_vcs's list of memories generated per FPGA target.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: David Harris <David_Harris@hmc.edu>
@davidharrishmc @claude
Relax unimportant comment changes
8583548 
Revert capitalization-only, punctuation-only, and no-gain rewording
edits, restore contributors' informal notes, and keep commented-out code
such as the rom1p1r bootloader initialization and the RAM preload
blocks. Spelling fixes, corrections to wrong comments, added explanatory
comments, and whitespace consistency stay.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
davidharrishmc and others added 3 commits October 10, 2026 07:48
@davidharrishmc @claude
Delete commented-out code with no future value
042cd13 
Keep alternate designs, the ROM bootloader initialization, and
optimization notes; drop superseded one-liners, dead predictor flops,
and blocks that reference signals that no longer exist.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@davidharrishmc @claude
Comment every module port consistently
0844d87 
Add a definition comment to the 1,430 ports that lacked one and make
comments for the same signal consistent across modules, keeping a
module-specific comment only where the name means something different.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@davidharrishmc @claude
Comment ports of the four files kept in openhwfoundation#1952
096d38f 
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@davidharrishmc davidharrishmc mentioned this pull request Oct 10, 2026
Open
davidharrishmc and others added 3 commits October 15, 2026 15:34
@davidharrishmc @claude
Merge upstream main into dh/sv-cosmetics
6a0b7b8 
Conflicts were main's logic changes in lines this branch re-indented or
re-commented; each keeps main's code with this branch's formatting:
- fdivsqrtfsm.sv, div.sv: FlushE & ~StallM (openhwfoundation#1925) and its comment; the
  fdivsqrtfsm DONE-state exclusion tag stays removed
- controller.sv: sfence.inval.ir refetch (openhwfoundation#1929)
- tlbcamline.sv: TLBWrite/WritePTE_G/WritePTE_NAPOT ports (openhwfoundation#1927)
- tlbcontrol.sv: ~UpperBitsUnequal in TLBMiss (openhwfoundation#1928), new BadNAPOT comment
- csrc.sv: time/timeh read only with Zicntr (openhwfoundation#1951)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: David Harris <David_Harris@hmc.edu>
@davidharrishmc @claude
Merge dh/sv-cosmetics (with upstream main) into dh/port-comments
a5e7949 
Comment the ports main added: hptw ENVCFG_PBMTE, and TLBWrite,
WritePTE_G and WritePTE_NAPOT in tlbcam and tlbcamline (one per line).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: David Harris <David_Harris@hmc.edu>
@davidharrishmc
Merge remote-tracking branch 'hwf/main' into dh/sv-cosmetics
e12a8af 
# Conflicts:
#	src/hazard/hazard.sv
#	src/privileged/csr.sv
#	src/privileged/privdec.sv
@davidharrishmc davidharrishmc mentioned this pull request Oct 16, 2026
Open
@davidharrishmc

davidharrishmc commented Oct 16, 2026

Copy link
Copy Markdown
Contributor Author

Merge order: this is part of the cosmetic stack, merged strictly #1952 → #1955 → #1959 so each delta shows on its own. Merge the open bug-fix PRs first: #1949, #1958, #1967, #1969, #1972, #1982, #1986 and #1987. The stack conflicts textually with them, and re-applying formatting is easier than re-applying fixes.

🤖 Generated with Claude Code

@davidharrishmc davidharrishmc mentioned this pull request Oct 16, 2026
Merged
davidharrishmc and others added 5 commits October 16, 2026 03:35
@davidharrishmc
Merge branch 'dh/sv-cosmetics' into dh/port-comments
b2623d6 
# Conflicts:
#	src/hazard/hazard.sv
#	src/mmu/hptw.sv
#	src/privileged/csr.sv
#	src/privileged/csrc.sv
#	src/privileged/privdec.sv
#	src/privileged/privileged.sv
#	src/privileged/trap.sv
@davidharrishmc @claude
lsu, ebu: LSUHREADY is gated while the IFU owns the bus
c15e246 
LSUHREADY = HREADY & ~LSUDisable, and the arbiter sets LSUDisable while the
IFU holds the bus, so the port comment saying it is never gated was wrong.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@davidharrishmc
Merge remote-tracking branch 'ohw/main' into dh/sv-cosmetics
a746c1c 
Signed-off-by: David Harris <David_Harris@hmc.edu>

# Conflicts:
#	src/fpu/fctrl.sv
#	src/fpu/postproc/fmashiftcalc.sv
#	src/fpu/postproc/postprocess.sv
#	src/ifu/bpred/RASPredictor.sv
#	src/ifu/bpred/bpred.sv
#	src/ifu/bpred/icpred.sv
#	src/ifu/ifu.sv
#	src/ifu/spill.sv
#	src/lsu/align.sv
#	src/lsu/lsu.sv
#	src/privileged/csrm.sv
#	src/uncore/uartPC16550D.sv
@davidharrishmc
Merge branch 'dh/sv-cosmetics' into dh/port-comments
dd3d618 
Signed-off-by: David Harris <David_Harris@hmc.edu>

# Conflicts:
#	src/generic/mem/ram2p1r1wbe_2048x64.sv
#	src/ifu/bpred/RASPredictor.sv
#	src/ifu/bpred/icpred.sv
#	src/ifu/spill.sv
#	src/lsu/align.sv
#	src/mmu/pmachecker.sv
@davidharrishmc @claude
Leave clk and reset ports uncommented
0a3c6b9 
As the PR description says, ports that declare only clk and/or reset carry
no comment; lines that also declare other ports keep theirs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: David Harris <David_Harris@hmc.edu>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@davidharrishmc