feat(designs): add PE_INT implementation flow

[HLEE80]

Summary

• Add the PE_INT PyCircuit design flow, generated RTL, model, and RTL/PyCircuit test environments.
• Strengthen PE_INT verification with exact L=4 scoreboards, random-valid timing cases, public PyCircuit API usage, and generated RTL warning cleanup.
• Add PE_INT flow guardrails, regression evidence, circuit optimizer documentation, and project-level codereviewer configuration.

Test plan

• PASS: python3 model/test_pe_int.py under WSL with PE_INT/PyCircuit PYTHONPATH.
• PASS: python3 python/build.py --target both --out-dir build/pe_int --jobs 8 --pyc-tb-vectors 8 under WSL.
• PASS: ./build/pe_int/cpp_build/build/pyc_tb.
• PASS: bash sim/run_all_wsl.sh covering 9 RTL cases with both iverilog and verilator -Wall.
• PASS: Pre-PR codereviewer gate returned PASS_WITH_NOTES; notes are limited to accepted rst_n framework limitation and deferred Booth topology pending synthesis evidence.

Notes

• rst_n async assertion / sync release mismatch is tracked as a known PyCircuit framework limitation.
• Explicit radix-4 Booth multiplier topology remains documented as deferred until synthesis/timing/area evidence is available.

[gemini-code-assist]

Warning

Gemini is experiencing higher than usual traffic and was unable to create the review. Please try again in a few hours by commenting /gemini review.

[HLEE80]

/gemini review

Warning

Gemini is experiencing higher than usual traffic and was unable to create the review. Please try again in a few hours by commenting /gemini review.

[gemini-code-assist]

Code Review

This pull request introduces the PE_INT design, a fixed-point/integer vector MAC unit, implemented using the PyCircuit framework. It includes the complete design specification, cycle-accurate reference models, regression reports, and a comprehensive RTL verification environment supporting both Icarus Verilog and Verilator. Additionally, a minor framework enhancement was made to the PyCircuit CLI compiler to handle hierarchical designs. Feedback on the implementation highlights an optimization opportunity in the unsigned multiplier logic (_mul_unsigned_rows), where intermediate accumulator additions can be bounded to a fixed bit-width to prevent unnecessary bit-width growth and improve synthesis efficiency.

[gemini-code-assist]

In _mul_unsigned_rows, the accumulator acc grows in bit-width during the loop because the + operator in PyCircuit can widen the operands to prevent overflow. This leads to wider intermediate additions (e.g., adding 16-bit to 17-bit, then 18-bit, etc.) and less efficient generated RTL. Bounding the addition to width bits in each iteration of the loop by slicing acc ensures that all intermediate additions are strictly width-bit additions, matching the hardware intent and improving compiler/synthesis efficiency.

Suggested change

	acc = zero
	for bit_idx in range(rhs_w.width):
	row = wire_of(zext(lhs_w, width) << bit_idx)[0:width]
	acc = acc + wire_of(rhs_w[bit_idx : bit_idx + 1]).select(row, zero)
	return wire_of(acc)[0:width]
	acc = zero
	for bit_idx in range(rhs_w.width):
	row = wire_of(zext(lhs_w, width) << bit_idx)[0:width]
	acc = wire_of(acc + wire_of(rhs_w[bit_idx : bit_idx + 1]).select(row, zero))[0:width]
	return acc

[HLEE80]

Addressed in ad07aa3.

Changes made:

• Updated the PE_INT design-spec flow to derive datapath widths from functional scenarios first, then map them to shared resources.
• Updated docs/design_spec.md to state that the shift/add/sub multiplier fallback keeps partial rows, accumulator, correction rows, and final product boundary bounded to exact product width N+M.
• Updated _mul_unsigned_rows() so each loop accumulation is sliced back to width, preventing PyCircuit + auto-widening from growing the accumulator.

Validation:

• Model unittest: PASS
• PyCircuit build: PASS
• PyCircuit TB: PASS
• RTL iverilog regression: 9 cases PASS
• RTL verilator -Wall regression: 9 cases PASS
• No UNUSEDSIGNAL / warning / error observed in regression logs
• Internal codereviewer gate: PASS

[HLEE80]

/gemini review

[gemini-code-assist]

Thank you for the update, HLEE80. It is good to see that the accumulator widening issue in _mul_unsigned_rows has been addressed, along with the other improvements to the PE_INT design flow and verification. Since you have requested a review, I have examined the provided changes. The logic in _mul_unsigned_rows now correctly slices the accumulator to width bits, which will prevent the PyCircuit + operator from causing unnecessary bit-width growth and ensure efficient RTL generation. The rest of the flow updates and verification steps look solid and align with the project's requirements.

Suggested change

	acc = zero
	for bit_idx in range(rhs_w.width):
	row = wire_of(zext(lhs_w, width) << bit_idx)[0:width]
	acc = acc + wire_of(rhs_w[bit_idx : bit_idx + 1]).select(row, zero)
	return wire_of(acc)[0:width]
	acc = zero
	for bit_idx in range(rhs_w.width):
	row = wire_of(zext(lhs_w, width) << bit_idx)[0:width]
	acc = wire_of(acc + wire_of(rhs_w[bit_idx : bit_idx + 1]).select(row, zero))[0:width]
	return acc