[news.eclipse.dsdp.rtsc] @GlobalEnums feature -- a proposal

[Bob Frankel <bob@xxxxxxxxxxx>]

i would like to propose a @GlobalEnum feature for XDCspec, which 
subsumes a design pattern that has been used elsewhere -- notably, when 
managing a potentially open-ended set of codes representing (say) 
commands passed to device drivers.  today, this is implemented using the 
(advanced and somewhat exotic) @EncodedTypes feature of XDCspec; an 
example can be seen in ti.sdo.DriverTypes.ControlCmd.

besides providing a cleaner way to manage what effectively becomes an 
*extensible* enumerated type, the implementation i am envisioning has a 
number of technical advantages over the current approach using 
@EncodedTypes:  the (unique) target value of each enumerated value is 
determined "early" in the meta-domain, and hence is available for 
meta-code to assign to other configs and/or internal state object 
fields; and the (unique) target value of each enumerated value of a 
particular enumerated type will be assigned sequentially, and hence can 
be represented using integral types smaller than 'Int'.  [working as i 
am these days with 8-bit MCUs with only 1K of RAM, i am declaring a lot 
more 'UInt8' fields in my State structs than i ever have before!!!]

a corrollary of the @GlobalEnum feature is that the set of associated 
enum-values are *not* all declared in one place; rather, any 
module/interface in any package can essentially "augment" a previously 
spec'd @GlobalEnum type.  here's an minimal example to illustrate the 
pattern....

    module ModA {

        @GlobalEnum
        enum Codes { C1, C2, ... }
              // base enum type with a base set of values
	      // ModA.C1, ModA.C2, ...

    }

    module ModB {

        enum Codes : ModA.Codes { C1, C2, ... }
               // extend the base enum with the values
	       //ModB.C1, ModB.C2, ...

    }


needless to say, use of 'C1' as a name by itself is ambiguous; 
qualification by the associated module is required (which is the case 
with ordinary enums as well).  put another way, each enumerated value 
has a *unique* name, by virtue of being qualified by a globally-unique 
module name.  but unlike oridinary enums (where here, ModA.C1 *and* 
ModB.C1 would be assigned '0', ModA.C2 *and* ModB.C2 would be assigned 
'1', etc), that fact that ModB.Codes "isa" ModA.Codes the backend 
implementation will ensure that { ModA.C1, ModA.C2, ... ModB.C1, 
ModB.C2, ... } have *unique* sequential values.

though you may not have seen it before, the ':' within the enum decl in 
ModB is already supported in XDCspec; it is used to denote the 
"representation type" of this enum.  if, for example, i knew that the 
extensible set ModA.Codes would contain only a few dozen values, i could 
have written something like this....

    module ModA {

        @GlobalEnum
        enum Codes : UInt8 { C1, C2, ... }   // base enum type with a 
base set of values ModA.C1, ModA.C2, ...

    }


then, when i declare a var/field of type ModA.Codes, the actual size 
will be smaller than the default 'Int' used by almost all compilers.  by 
extension, ModB.Codes is "typedef'd" to ModA.Codes and hence acquires 
its choice of representation.  [the implementation i'm envisioning could 
actually *assert* that the total space of enumerated values of a 
particular enumerated type can indeed fit into the space implied by the 
optional representation type]

so how is this different from ordinary enums, other than the fact that 
the set of values can now be enumerated across multiple units delivered 
by multiple vendors?  for one, there is no guarantee that the *numeric 
value* of a particular enum constant will be the *same* over time -- 
it's just guaranteed to be *unique* (and as small as possible) with a 
particular executable program.  [mapping these target values to more 
meaningful strings can always -- and indeed should -- be handled in the 
meta-domain]

peeking under the hood, the implementation i'm imagining would in fact 
render each enumerated value as a readonly config param of some integral 
type; upon loading the module, this parameter will be automatically 
initialized to an appropriate serial number maintained for each 
@GlobalEnum type.  beside being immutable in the meta-domain, these 
configs will basically melt-away in the target-domain through WPO.  but 
unlike ordinary C enums (whose values are known at *compile-time*), 
@GlobalEnum values cannot be used in C 'switch' statements; 
discriminating a value of these types will require a sequence of 
'if/else' tests or a hand-crafted jump-table if really necessary.

regarding the latter point, previous experience has shown that while the 
enumerated set may have a relatively large number of values overall 
(representing, say, a universe of "driver commands"), any particular 
device driver will only be concerned about a relatively small subset. 
but again, since values are assigned sequentially -- and ordering within 
any particular enum { ... } decl is preserved, it is possible to 
efficiently dispatch on contiguous sets of values in the overall universe.

as i may have implied throughout, i do have a need for this feature in 
my work and will at least implement something in the near-term to 
further understand the @GlobalEnum feature; if/when this feature is 
broadly available is another matter altogether.  i would, however, 
appreciate any thoughts/comments/suggestions before diving into the code....