Validate `EXTERNAL_HPM_EVENT_NUM` configurations

[tejassinghbhati]

Hi, this is Tejas Singh Bhati. I’m new to the project and may be missing some context, but while reviewing the external HPM event integration I noticed that the supported configuration widths appear to be implicit in the RTL rather than enforced. I’m opening this issue to confirm the intended behavior and, if appropriate, make the supported configurations explicit to prevent invalid or partially connected PMU event mappings.

Summary

top_drac supports external PMU/HPM events through the EXTERNAL_HPM_EVENT_NUM compile-time macro. The implementation assumes the
macro is set to one of 4, 6, or 10, but unsupported values are not rejected.

This can lead to invalid vector indexing, partially undriven HPM event bits, or silently incomplete performance-counter data.

Current behavior

When EXTERNAL_HPM_EVENT_NUM is defined:

• Events 41–44 always read external_hpm_i[3:0].
• Events 45–46 are only connected for a width of 6.
• Events 45–50 are only connected for a width of 10.
• Any other value has no explicit error or fallback behavior.

For example, a value below 4 makes the [3:0] access invalid. A value such as 5, 7, or 8 creates an HPM event vector wider than the implemented mapping, leaving some event bits unassigned.

Relevant code: rtl/top_drac.sv, HPM event mapping block.

Expected behavior

Only these configurations should be accepted:

• macro undefined: no external HPM events
• EXTERNAL_HPM_EVENT_NUM=4: L2/L1.5 access and miss events
• EXTERNAL_HPM_EVENT_NUM=6: above events plus NOC-S flow/stall events
• EXTERNAL_HPM_EVENT_NUM=10: above events plus per-NOC-channel flow/stall events

Any other value should fail elaboration with a clear diagnostic.

All valid configurations must assign every declared HPM event bit deterministically.

Proposed solution

1. Add an elaboration-time guard for unsupported macro values.
2. Structure the external-event mapping as explicit generate branches for 4, 6, and 10 event configurations.
3. Give unsupported configurations a clear $error/$fatal message.
4. Ensure external-event vector widths and accesses are consistent for each supported configuration.
5. Document the external event IDs and meanings in events.md.

Acceptance criteria

• No external event logic is elaborated when the macro is undefined.
• Configurations 4, 6, and 10 elaborate without out-of-range selects.
• Every HPM event bit declared by each valid configuration has a defined driver.
• Unsupported values fail at elaboration with an actionable error message.
• events.md documents events 41–50 and which configurations expose them.
• Add a lint/elaboration regression covering undefined, 4, 6, 10, and one
  invalid configuration.

Notes

This is an integration/configuration robustness issue. It does not change the behavior of the default configuration, where EXTERNAL_HPM_EVENT_NUM is not defined.

[Udaytaneja]

Hi mantainers , I am interested in doing this work . Please assign this to me

[narcisrodas]

We do not want to enforce the value of EXTERNAL_HPM_EVENT_NUM, so we will not make changes to add this kind of logic. We do appreciate the update of the events.md file, so if you change the PR (or make another one) to only have those changes, we will add it to our internal version to appear in the next release.

[tejassinghbhati]

@narcisrodas Thank you so much for the clarification. I understand that leaving EXTERNAL_HPM_EVENT_NUM unconstrained is intentional.

I’ll update PR #8 to remove the configuration-validation logic and keep only the events.md documentation changes, including the missing event 40 entry. Thank you for considering the documentation update for the next release.

[narcisrodas]

I see you have also removed the documentation for the external HPM events from the PR, but that was fine to keep.

[tejassinghbhati]

I have restored the external HPM events documentation in #8. The PR now covers events 40–50 with the configurations (4/6/10) that expose each, verified against the mapping in top_drac.sv. Documentation-only, no RTL changes.
Thankyou for taking the look