Re: [PATCH] ftrace: add 'version' special file for ring buffer format

[Steven Rostedt <rostedt@goodmis.org>]

On Tue, 2011-03-15 at 17:33 -0700, David Sharp wrote:
> On Mon, Mar 14, 2011 at 7:31 PM, Steven Rostedt <rostedt@goodmis.org> wrote:
> > On Mon, 2011-03-14 at 15:42 -0700, Slava Pestov wrote:
> >> The intention here is that if the ftrace ring buffer format changes
> >> in the future like it did in the past with ktrace, we can increment
> >> the version number and update clients appropriately.
> >
> > I purposely avoided "versions", and instead use the
> > tracing/events/header_page and .../header_event to describe how the ring
> > buffer format is laid out. If the format changes, then so should those
> > files.
> >
> > -- Steve
> 
> Those are useful files, but do not encompass the entirety of the API.
> Specifically, they do not encode the semantics of those values, nor
> the control interface.
> 
> For example, when the ring buffer header changed from type:2;len:3 to
> type_len:5, while this would have been reflected in header_event, how
> to interpret the different versions is not something that could be
> automatically understood by a parser.

We do want to make the parser aware of these changes. As that change
happened, I have parse_events understand it.

> 
> These files also do not cover the semantics of the control files. For
> example, it is imaginable that buffer_size_kb could be changed from
> per-core size to a total size, or that it would reflect the actual
> total amount of memory used, instead of the "non-header" space. The
> grammar of filter expressions is another example of something that
> could change without notice.

Then we need to make sure that a change can be detected. Version numbers
for ABI in the kernel has been looked down upon. Again, if a change is
needed, I find a way to make it detected. I thought about adding to
buffer_size_kb:

1408 (total 5632)

or something of that matter.

Again, if we can not determine the features by reading a file or finding
if a syscall exists or not, then we are doing something wrong and need
to fix that.

Lets put it another way. Instead of making it easy for a parser, lets
make it easy for humans to know. If I look at the files I can quickly
figure out what type of features are available. I would be clueless to
know if all I had was "v1.0.2". One more thing: Version numbers are like
documentation. They are great when you start out, but soon become out of
sync with reality.

-- Steve