[lttng-dev] CTF2-PROP-1.0: Proposal for a major revision of the Common Trace Format, version 1.8

[Philippe Proulx]

----- Original Message -----
> From: "Jérémie Galarneau" <jeremie.galarneau at efficios.com>
> To: "Philippe Proulx" <pproulx at efficios.com>
> Cc: "diamon-discuss" <diamon-discuss at lists.linuxfoundation.org>, "lttng-dev" <lttng-dev at lists.lttng.org>,
> "tracecompass-dev" <tracecompass-dev at eclipse.org>, "etienne bergeron" <etienne.bergeron at gmail.com>, "francois doray"
> <francois.doray at gmail.com>
> Sent: Friday, 4 November, 2016 19:35:40
> Subject: Re: [lttng-dev] CTF2-PROP-1.0: Proposal for a major revision of the Common Trace Format, version 1.8

> On 25 October 2016 at 14:26, Philippe Proulx <pproulx at efficios.com> wrote:
>> .Minimal enumeration field type
>> ====
>> JSON representation:
>>
>> [source,json]
>> {
>>   "field-type": "enum",
>>   "members": {
>>     "": [0]
>>   }
>> }
>> ====
> 
> Hi,
> 
> A short comment/feature request with regards to enumerations.
> 
> The CTF 1.8.2 spec states that:
> "Overlapping ranges within a single enumeration are implementation defined."
> 
> I am currently trying to instrument code where a "command" flag has
> possible values that are determined at build time. Some of them may
> have different values and/or not exist depending on various build
> configuration options.
> 
> To work around this, I am trying to define an enumeration of the form
> 
> enum my_thingy_commands {
>    UNKNOWN_CMD = 0..UINT_MAX,
>    FOOIFY = 0,
>    BARIFY = 1,
> #ifdef SOME_CONFIG
>    LOLIFY = 2,
> #endif
>    YOU_GET_IT_IFY = 3,
> };
> 
> rather than explicitly "filling-in" every hole between defined values
> for this particular build config.
> 
> I think a default value attribute would be helpful here rather than
> leaving this to be implementation defined.
> 
> Is a recommendation of what to present when overlapping ranges are
> encountered beyond the scope of this spec?
> In the case of a default value, the course of action is pretty clear
> (prefer the "overriding" value, otherwise present the default). What
> to do with explicit overlaps is a bit more... interesting... from a UX
> standpoint (but they may have use cases ?).
> 
> In fact, are overlapping enums addressed at all in CTF 2.x?

A default label is a good idea, and pretty straightforward to support 
for a consumer:

    {
      "field-type": "enum",
      "alignment": 16,
      "size": 32,
      "signed": true,
      "default-label": "SOMETHING ELSE",
      "members": {
        "NEW": [0],
        "TERMINATED": [-1],
        "READY": [2, 17],
        "RUNNING": [-3],
        "WAITING": [
            {"lower": 19, "upper": 199},
            1000
        ],
        "RESTARTING": [
            {"base": 8, "value": "126674015"},
            {"lower": -155, "upper": -98}
        ]
      },
      "user-attrs": {
        "my-namespace": {
          "my-attr": "desc"
        }
      }
    }

As for overlapping ranges, they're not addressed in this proposal (they
should be). I'd be tempted to explicitly disallow them. I like this
simple one-to-many mapping. It's straightforward to implement, and it
simplifies the variant field type (otherwise we would need to specify
restrictions for an enumeration field type when referenced by at least
one variant field type).

We _could_ generalize this defaut label idea and support multiple
levels, but I don't think it's necessary. Something like:

    0 --------------------------------------.
        4 --------------------------.        \
            5 ---------------.       \        \
                22 -- BANANA  > APPLE > ORANGE \
            67 --------------'       /          \
        82 -------------------------'            > GRAPE
        90 -------------.                       /
            101 -- APPLE > AVOCADO             /
        122 ------------'                     /
    127 -------------------------------------'

So:

* 2 is mapped to GRAPE
* 55 is mapped to APPLE
* 70 is mapped to ORANGE
* 85 is mapped to GRAPE
* 92 is mapped to AVOCADO
* 125 is mapped to GRAPE

Then the equivalent of your default label is the outermost range
(GRAPE).

Phil

> 
> Regards,
> Jérémie
> 
>>
>>