Curious... Have you tried to change this to CTF_VERSION_3 to see what happens with this patch stack applied? Do things just work?

Since there's already a diff against these, I wonder if adding some clarification on what k, r and l are? The other macros are fairly obvious, but this one had me puzzled until I looked at the man page and found:

#define CTF_TYPE_INFO(kind, isroot, vlen) \
        (((kind) << 11) | (((isroot) ? 1 : 0) << 10) | ((vlen) & CTF_MAX_VLEN))

which is a much clearer description of the macro than this version.

Same as above

Have you tried changing this to v3? Does it break anything? In other words, could we at some point in the future change these typedefs and have things "magically" just be better?

One of the subsequent patches in this series does exactly this. It does not work at this point in the series since libctf etc. are not yet patched.

At the end of this series, these typedefs are not used at all and could possibly be removed. There's no sensible way to use them; it's better to provide accessors which know the backing CTF version and can cast a void * to the versioned type. For instance, at the end of the series, libctf's ctf_lookup_by_id() returns a void * that can be passed to ctf_get_ctt_size() etc.

vers 0x03 now?

Should we make these 0x0000 0x0042 0x0036 now?
And similar elsewhere.

32767 or 32768?

It's been helpful in the past, so I prefer to keep it. This document describes a file format that's useful to a vanishingly small number of developers who work on kernel tracing utilities.

Having worked in the past for a few years for someone who relied a screenreader and wrote some elaborate system software based on dense Infiniband specs replete with tables, diagrams, etc., please forgive me for being skeptical that deleting this diagram represents much of an accessibility improvement. Nonetheless, feel free to submit a patch which does as you request, I will merge it.

It's a prefix sometimes used to indicate octal representation. I'm not sure why it's used here.

Well, to be pedantic it should really be 0x00000000, 0x00000042, 0x00000036, no? I don't know that it's really useful to expand the sample values to the proper width when the offsets are provided as well.

The header is unchanged.

From the description of child containers above, there are two type identifier spaces [0x1, 0x7ffffffe] and [0x80000001, 0xfffffffe] which have a one-to-one correspondence. 0xffffffff is not a valid type identifier, so 0x7fffffff cannot be valid either.

Well, to be pedantic it should really be 0x00000000, 0x00000042, 0x00000036, no? I don't know that it's really useful to expand the sample values to the proper width when the offsets are provided as well.

Oh, indeed, it should have been 0x0000, 0x0042 already if my comment was to hold. Fine.

They may have found it possible. That doesn't mean it was at all easy or that others may have succeeded, and I believe this kind of difficulty is the same as what Fred Brooks calls "accidental complexity" in one of the essays in The Mythical Man Month. The gist of that essay is that every change that lowers accidental complexity (as opposed to essential complexity) is worth making for that very reason.

So if no one beats me to that, I will indeed submit an accessibility patch as soon as I have time for that.

Looking at the 0t36+ctf_*off offsets in this diagram and the text below, for instance;

Therefore, something with an offset of 0 is at an offset of thirty-six
bytes relative to the start of the
.Nm
file.

implies those offsets aren't octal at all (which is one interpretation of "not sure why", another being "the offsets should use decimal instead"). Can you confirm that 36 is actually decimal 36, not octal 36 = decimal 30?

Yes, it looks like it should indeed be decimal. Apparently in Solaris "0t" is supposed to denote a decimal number, not an octal number, at least based on their printf man page: https://docs.oracle.com/cd/E19683-01/806-6545/api-21/index.html

So the man page is correct, but uses some rather unfamiliar notation.