enumeration - Is it just for documentation ?

[arnonsha]

I am wondering what is the purpose of enumeration in RDL.
Lets take the following example (snippet taken from the Caliptra project )

    reg {
        name = "DOE Command control register";
        desc = "Controls the de-obfuscation command to run";

        default sw = rw;
        default hw = r;

        field {
            desc = "Indicates the command for DOE to run";

            enum doe_cmd_e {
                DOE_IDLE = 2'd0 {
                    desc = "DOE is in idle state.";
                };
                DOE_UDS = 2'd1 {
                    desc = "Request DOE to run UDS flow.";
                };
                DOE_FE = 2'd2 {
                    desc = "Request DOE to run FE flow.";
                };
                DOE_CLEAR_OBF_SECRETS = 2'd3 {
                    desc = "Sets the UDS, FE, and OBF KEY flops to zeroes.";
                };
            };
            encode = doe_cmd_e; hwclr; swmod;} CMD[2]=0;
        field {desc = "Key Vault entry to store the result.";} DEST[5] = 0;

    } DOE_CTRL;

I modified the code above and removed the enumeration completely from the CMD field:

        field {
            desc = "Indicates the command for DOE to run";

            hwclr; swmod;
        } CMD[2]=0;

I do not see any differences in RTL/UVM or the generated C headers.

I do see however the enum values appear in the generated html documentation:

Is it right to say that enumeration is only used for documentation ?

thank you

[amykyta3]

It really depends on the context and the view being generated. Emitting enums for the HTML views is the natural first step since the information is in the database, and it provides readers information about design intent. For other views the utility varies.

• C header
  • Currently does not emit the enum definitions, but I'm open to ideas on how this should look.
  • Some open questions in my mind on how that ought to look if enabling bit-field struct generation, but at the very least, emitting the definition could be useful. Since this is the newest of the tools, I had intentionally deferred this feature.
• SystemVerilog regblock
  • Currently emits the enum definitions in the generated package, but does not actually use them in any of the hardware interface signals.
  • This is because SystemVerilog's enum casting rules are slightly cumbersome to use in practice, especially if a sparse enum is defined
• UVM
  • Currently enums are ignored as you noticed, but I could do the same as the regblock generator and at the very least, emit the definitions.
  • Not sure how much utility there is in tying in the enum into the UVM class model itself. Open to ideas.
• IP-XACT
  • The IP-XACT importer/exporter fully supports transcribing enums to/from the RDL database

So yes, currently enums are essentially only for documentation, but the information exists in the compiled database and I am open to expanding the support for them in the situations that it makes sense to do so.

[arnonsha]

I think it would be helpful for sw developers to have the enum exported to the headers file.
I'll update this once I get better understanding of the requirments.

thanks

[mpriestleyidex]

FWIW I have some home-grown exporters that expose the enums.

With C headers, the main pain is that RDL enums are nicely scoped and namespaced, but in C they're very much not. So you end up writing long explicit enum typenames and member names in your RDL to not break the C. Maybe some kind of name mangling could be done, but I imagine it'd quickly lead to very unwieldy names.

With SV I've not found casting back and forth between enums too painful (though I've not used any sparse enums).

[arnonsha]

Yes, I also think that long names would be cumbersome.
Maybe a good solution is to export all enums to a dedicated file with the long "hierarchical" names _ENUM, after which the sw developer can modify it to a more suitable (shorter) name.