Sayan Sivakumaran's Blog

Performance Experiments are Hard

Sayan Sivakumaran — Sun, 26 Oct 2025 00:00:00 +0000

Running good experiments is obviously hard. This is exemplified by the numerous resources you can find online about the reproducibility crisis in various scientific fields. Naturally, running performance experiments in computer science is also hard, and it is too easy to misinterpret the results or to present data which hides the complete story.

I found it interesting how multiple fields of computer science have papers that talk about benchmarking pitfalls in their domains, and wanted to start compiling a list for myself. Maybe it's useful for you too.

Systems Programming

A note on performance counters. Depending on how paranoid you are, you should double check that the performance counters your tool advertises are actually listed in your processor manual. For example, when using perf list, the tool advertises that I can measure l2_latency.l2_cycles_waiting_on_fills, even though I couldn't find that event anywhere in my Zen3 manual. It seems like the PR that added support for measuring that event added that event because the measured count was non-zero, even though it wasn't listed in the manual. It was submitted and approved by AMD employees, so I might just be overly cautious, but I personally wouldn't feel comfortable using that event for any rigorous measurement (and would wonder why there wasn't a revision to the documentation if it is a valid event).

Java

Networking

Observing network interface statistics with iproute2

Sayan Sivakumaran — Sun, 26 Oct 2025 00:00:00 +0000

I am a big fan of tools that lets you observe the behavior of low level systems, as it is great for learning. For example, hardware performance counters are great for observing processor behavior that is otherwise transparent for the developer. Similarly, the herdtools7 suite is great for observing the behavior of your processor's memory model.

I've been running a networking book club at my workplace, and I'm happy that the the ip -s -s link show command can give me similar low-level visibility into the networking stack of my machine (although in much less detail than the previous two tools). The kernel documentation describes the output of this tool in a lot of detail. The only thing I was confused by was what the transns entry in the TX errors row meant, as I couldn't find it in the documentation:

$ ip -s -s link show dev wlo1
3: wlo1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DORMANT group default qlen 1000
    link/ether 50:c2:e8:ee:f3:57 brd ff:ff:ff:ff:ff:ff
    RX:  bytes packets errors dropped  missed   mcast
     478520149  452566      0       0       0       0
    RX errors:  length    crc   frame    fifo overrun
                     0      0       0       0       0
    TX:  bytes packets errors dropped carrier collsns
      44078438  164580      0       3       0       0
    TX errors: aborted   fifo  window heartbt transns
                     0      0       0       0       4
    altname wlp41s0
    altname wlx50c2e8eef357

Thankfully, we can go spelunking in the iproute2 repository to see what exactly it represents. Searching the for the string transns finds us the code we want relatively easily, but it's still not clear to me what a carrier_change is, or what a carrier even is in the first place. The thorough git commit message helps us a lot though:

commit 30b557929f2aaeeee59e1bbaad7c804bcae40e7b
Author: david decotigny <decot@googlers.com>
Date:   Mon May 5 20:38:18 2014 -0700

    iproute2: show counter of carrier on<->off transitions

    This patch allows to display the current counter of carrier on<->off
    transitions (IFLA_CARRIER_CHANGES, see kernel commit "expose number of
    carrier on/off changes"):

      ip -s -s link show dev eth0
      32: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 ...
        link/ether ................. brd ff:ff:ff:ff:ff:ff
        RX: bytes  packets  errors  dropped overrun mcast
        125552461  258881   0       0       0       10150
        RX errors: length  crc     frame   fifo    missed
                   0        0       0       0       0
        TX: bytes  packets  errors  dropped carrier collsns
        40426119   224444   0       0       0       0
        TX errors: aborted fifo    window  heartbeat transns
                   0        0       0       0        3

    Tested:
      - kernel with patch "net-sysfs: expose number of carrier on/off
        changes": see "transns" column above
      - kernel wthout the patch: "transns" not displayed (as expected)

    Signed-off-by: David Decotigny <decot@googlers.com>

Sadly, I wasn't able to immediately figure out what a carrier was from the mentioned kernel commit either. Some resources online seem to imply that carrier_changes count the number of times a specific interface went up or down, which seems plausible as the transns number seems to go up whenever I manually toggle my computer's wlo1 interface on and off.

A Brief Look at the Mathematics of Structure Packing

Sayan Sivakumaran — Fri, 01 Aug 2025 00:00:00 +0000

It's common knowledge that the memory layout of a structure in C can change depending on the order its members were declared in. For example, on my x86-64 processor, sizeof(Foo) is not equal to sizeof(Bar), even though they effectively have the same members. You can try it out yourself on Godbolt.

struct Foo {
    char firstChar;
    double firstDouble;
    char secondChar;
};

struct Bar {
    double firstDouble;
    char firstChar;
    char secondChar;
};

It's also common knowledge that ordering the members of your structure from largest alignment to smallest will usually (?) give you a size minimizing layout. If this discussion is new to you, there are lots of good articles and videos on the topic, though "The Lost Art of Structure Packing" seems to be the most popular.

I was curious if we could get a more precise answer on when the strategy above is or isn't optimal. More specifically, I had two questions:

Does ordering structure members from largest to smallest alignment always give a size minimal layout?
As most people know, the answer is no, and it is trivial to construct a counterexample. But we can describe a class of "simple" structures where the answer always is yes!
Clang's optin.performance.Padding analyzer uses a slightly different algorithm than what is commonly recommended to find an order that minimizes a structure's size. Does this algorithm always find a size minimal layout?
It turns out the answer is still no! Once again, we can construct an admittedly contrived counterexample that we can optimize better by hand.

I tried to find formal mathematical answers to the problems above, but I didn't have much luck outside of people concluding the correctness of these algorithms from trying them out on a couple of very simple examples, giving handwavy proofs that missed edge cases, or just calling the problem trivial.

It's almost certain that mathematical answers are available in literature I'm unfamiliar with. But I wasn't able to find them, so my curiosity led me to try and give answers to the problems above on my own. It was definitely a good homework problem for me, at the very least!

The rest of this blog post fills in the details needed for providing an answer to the first question above. We don't need any powerful mathematical tools here - because we add so many restrictions on the problem, a familiarity with modular arithmetic will be enough. Of course, I haven't done any math since my undergrad, so my skills may be rusty and the proofs may contain errors. Please let me know if you find any. 🙂

Disclaimers

This can become a complicated topic if the scope is too wide, so let's narrow the scope a bit.

I will not analyze structures with bitfield members. From a cursory reading, it seems like the layout of bitfield members in a structure is a complicated implementation-defined topic. I don't really have the knowledge to reason about this in any real way across every potential target out there. So let's ignore this case for now.
- Interestingly enough, Clang's static analyzer also considers this case to be hard.
I will not make any claims about the 'performance' of a size minimal layout. Performance is obviously a complicated topic, and what is 'performant' can change depending on the metric you are defining performance by. Even worse, designing good experiments is famously hard. The hope is, however, that a size minimal layout will increase the density of data in cache, which might make your memory-bound workload faster.
- Figuring out an "optimally performing" layout of a structure seems to be an active area of research. You can search for the keywords structure splitting and field reordering if you're curious. The literature seems to suggest that it's often smarter to find structure layouts accounting for access patterns rather than purely minimizing size, although that does require having knowledge about what the access pattern of a program looks like.
I will assume that we care about alignment. If not, we can trivially solve the problem by adding __attribute__((__packed__)) to the structure. There has been some discussion questioning how important alignment is on modern processors, but to my understanding there are still platforms that trap upon unaligned reads or writes. In any case, let's assume we want to find a size minimal layout while respecting alignment requirements.
- In case you're curious, it seems you can make x86 trap on unaligned reads or writes if you want! The mentioned flag was also present in the manual for my Ryzen 5950x processor, anyway.

Vocabulary

We'll use:

$S$ to denote some arbitrary structure with $n \gt 0$ members.
- Again, for the sake of simplicity, let's ignore structures with bitfield members for now.
$m_i$ to denote the $i$th member of the structure, with $0 \lt i \leq n$.
$s_i$ to denote the sizeof member $m_i$.
$a_i$ to denote the alignment of member $m_i$, where $a_i=2^{k_i}$ for some integer $k_i \geq 0$
- My hope is that restricting $a_i$ to be a power of 2 is a reasonable assumption. I don't know if there are any exotic architectures where that doesn't apply, but if there are this blog post does not apply to those architectures.
$a_\text{max}$ to denote the maximum alignment out of all $a_i$ in $S$. In other words, $a_\text{max}$ is the smallest integer such that $a_\text{max} \geq a_i$ for all $i$.
$p_i$ to denote the padding between members $m_i$ and $m_{i+1}$ (or the trailing padding if $m_i$ is the last member of the structure)

Some might be curious why we make a distinction between the size $s_i$ and alignment $a_i$ of structure members, as I see people conflate the two sometimes. This is because they aren't always equal. For example, executing this program on Godbolt shows that when compiling for 32 bit systems with the -m32 flag, gcc will report that sizeof(double) is 8 bytes but the alignof(double) is 4 bytes.

Formulating a mathematical definition of `sizeof`

We can't do any mathematics here unless we know how to write sizeof down as an equation. Let's attempt to formulate one, and we'll then prove an important property of sizeof that is normally taken for granted.

A potential ambiguity in the definition of `sizeof`

First off, the definition of sizeof from 6.5.3.4, paragraph 4 of the C23 standard (PDF) is:

When [sizeof is] applied to an operand that has structure or union type, the result is the total number of bytes in such an object, including internal and trailing padding.

However, unless I'm grossly misunderstanding something, I think this definition ambiguous. For example, consider the following structure Foo in an x86-64 environment:

struct Foo {
    short a; // Takes up bytes 0 and 1 

    int b;   // Pad to a 4 byte boundary, then takes up bytes 4 through 7 

    short c; // No padding needed. Takes up bytes 8 and 9. 

             // Trailing padding needed to make sure consecutive 
             // copies of Foo in an array are aligned. As the 
             // alignment of Foo is 4, add 2 final bytes of padding.
}

The sizeof this structure should be 12 bytes. Indeed, this is how sizeof is normally computed (try it out on Godbolt), and this computation is correct as long as the structure Foo is aligned on the largest alignment of its members, which happens to be $a_\text{max}=4$.

Here is another way to state this. Let $M$ be the memory address that Foo starts at. Then this computation is correct as long as:

$$M \equiv 0\pmod{4}$$

and we could visualize the sizeof computation above as follows (hope you can forgive the sloppy Inkscape):

If you're confused why we need to add 2 bytes of trailing padding, suppose that we have an array of Foo. Without the trailing padding in the example above, the int in the second instance of Foo would be misaligned.

However, suppose that we hypothetically had a memory allocator that could allocate a memory address $M$ such that

$$M \equiv 2\pmod{4}$$

That is, it could allocate memory such that the address it returns would have a remainder of 2 when divided by 4. Then, if we start Foo at that memory address, it would have a size of 8 bytes:

The first member short a would already be aligned, and would take up bytes 2 and 3.
The second member int b would already be aligned because it would start at a memory address divisible by 4, and would take up bytes 4 through 7.
The third member short c would already be aligned, and would take up bytes 8 and 9.
There is no trailing padding needed, since in an array the first instance of Foo would end on a memory address that has remainder 2 when divided by 4, so we can immediately start the next instance of Foo.

We could visualize this computation as follows:

As far as I can see, there is nothing mathematically wrong with this scenario besides requiring a hypothetical memory allocator that is flexible enough to support allocations like this.

Indeed, I was curious why it was required for a structure to have an alignment equal to the largest alignment of its members. I failed to find anything in the standard about this, and most online resources I could find claimed that it was to allow successive members in an array of structures to be aligned.

(StackOverflow) Is the alignof of a struct always the maximum alignof of its constituents?
(StackOverflow) Why does size of the struct need to be a multiple of the largest alignment of any struct member?
- Yes, I know C and C++ are very different. I think this discussion is still relevant to C though, and ultimately I'm hoping that our discussion here is abstract enough to be language agnostic.
(Quora) In C, why must the size of a struct be divisible by the size of its largest member?

However, note that in this constructed example we have a structure that is not aligned by the largest alignment of its members, and it still allows sensible array layouts that guarantee that all structure members are aligned.

Of course, it probably isn't useful to create a memory allocator that is flexible enough to support the allocations above. The struct Foo has an ordering of its members that ensures that sizeof(struct Foo) = 8 even when $M \equiv 0 \pmod{4}$:

// Ordering the members of Foo from largest alignment
// to smallest will give it the smallest size possible.
struct Foo {
    int b;
    short a;
    short c;
}

Furthermore, being able to use this trick for structures like Foo doesn't necessarily mean it would work for other structures. It is likely we can construct structures where we can show mathematically that the only "valid" alignment of that structure is at $a_\text{max}$. Not to mention that this would be an ABI break if other programs aren't using the same trick for Foo that this hypothetical program is.

However, the point of this example is to show that it isn't immediately obvious that sizeof will give the same value no matter what memory address we place an arbitrary structure at, even if we restrict placing the structure at memory addresses that result in usable array layouts. The example structure Foo can start at memory addresses $M \equiv 0 \pmod{4}$ and $M \equiv 2 \pmod{4}$ and we would have no issues with inconsistent member offsets and alignments when in an array, although the value of sizeof(struct Foo) would differ in both cases.

From this, I claim that sizeof is, in reality, a function of two arguments when applied to structures:

$$ \text{sizeof}(S,M) $$

where the first argument $S$ is the structure in question, and the second argument $M$ is the memory address the structure starts at. We'll resolve this strange inconsistency later, and we'll prove that:

$$\text{sizeof}(S,0) = \text{sizeof}(S,M)$$

if the memory address $M$ is divisible by the largest alignment $a_\text{max}$ in the structure $S$. In other words, we will mathematically prove what we usually take for granted: as long as a structure is aligned in a particular way, sizeof is a unary operator and we can compute sizeof pretending that the structure starts at memory address 0.

The equation for `dsizeof`

Before we tackle the problem of sizeof, I would like to inspect a simpler concept that will hopefully make the proof of the consistency of sizeof easier to digest.

We're going to steal a concept from LLVM known as __datasizeof, which is defined to be the sizeof a structure but without the tail padding. We'll examine the properties of __datasizeof first to reduce edge cases needed in our analysis of sizeof, and we'll denote this function mathematically as $\text{dsizeof}$.

Similar to sizeof, it turns out that $\text{dsizeof}$ is a function of two arguments:

$$ \text{dsizeof}(S,M) $$

where, once again, the first argument $S$ is the structure in question, and the second argument $M$ is the memory address the structure starts at.

To compute an example, let's examine our structure Foo again, and determine what $\text{dsizeof}(\text{Foo}, 0)$ ends up being:

struct Foo {
    short a; // Takes up bytes 0 and 1 
    int b;   // Pad to a 4 byte boundary, then takes up bytes 4 through 7 
    short c; // No padding needed. Takes up bytes 8 and 9. 
}

This is basically the same computation as before, except we don't add the 2 bytes of trail padding, so we end up getting:

$$\text{dsizeof}(\text{Foo}, 0) = 10$$

Similarly, if we want to compute $\text{dsizeof}(\text{Foo}, 2)$, we can recall from the previous section that:

struct Foo {
    short a; // Takes up bytes 2 and 3 
    int b;   // No padding needed. Takes up bytes 4 through 7 
    short c; // No padding needed. Takes up bytes 8 and 9. 
}

and so we compute:

$$ \text{dsizeof}(\text{Foo}, 2) = 8 $$

Armed with some examples, let's come up with a general equation for $\text{dsizeof}$. Let $M$ be the memory address that a structure $S$ starts at. Then we can compute $\text{dsizeof}(S,M)$ as follows:

$$ \text{dsizeof}(S, M) = s_1 + p_1 + s_2 + p_2 + \ldots + s_{n-1} + p_{n-1} + s_n $$

All this is really saying is that the dsizeof some structure is the sum of the structure member sizes and the needed padding between those members.

However, for $0 \lt i \lt n$, we know that $p_i$ cannot be some arbitrary integer - it must satisfy two constraints. First, the choice of $p_i$ must make it so the memory address of $m_{i+1}$ is divisible by $a_{i+1}$. In other words, the padding must be chosen to make sure the memory address of the structure's next member respects that member's alignment.

If we notice that the expression $M + s_1 + p_1 + \ldots + s_i + p_i$ represents the starting memory address of member $m_{i+1}$, we can encode this requirement recursively as:

$$ M + s_1 + p_1 + \ldots + s_i + p_i \equiv 0 \pmod{a_{i+1}} $$

Second, we must ensure that $p_i$ is the smallest positive solution to the above equation. This is because if we have some integer solution to the above equation $p_i=k$, then $p_i=k+ca_{i+1}$ is also a solution for any arbitrary integer $c$. So we add the final restriction on the value of each $p_i$:

$$ 0 \leq p_i \lt a_{i+1} $$

which guarantees the uniqueness of $p_i$.

Proving the consistency of `dsizeof`

As an intermediary step to proving the consistency of sizeof, we would like the prove the following lemma:

Lemma 1: Let $M$ be any memory address evenly divisible by $a_\text{max}$, the largest alignment in $S$. Then we have that: $$ \text{dsizeof}(S,0) = \text{dsizeof}(S,M) $$

Proof: We'll need to come up with some notation to differentiate the paddings in both sides of the equation. For $0 \lt i \leq n-1$, we'll write $p_i$ to denote the paddings inside of $\text{dsizeof}(S, 0)$, and we'll write $b_i$ to denote the paddings inside of $\text{dsizeof}(S, M)$. Thus, our equations become:

$$ \text{dsizeof}(S, 0) = s_1 + p_1 + s_2 + p_2 + \ldots + s_{n-1} + p_{n-1} + s_n $$ $$ \text{dsizeof}(S, M) = s_1 + b_1 + s_2 + b_2 + \ldots + s_{n-1} + b_{n-1} + s_n $$

All we need to show is that for any $i$, we have $b_i = p_i$, at which point we know that $\text{dsizeof}(S, 0) = \text{dsizeof}(S, M)$.

First, recall our restrictions that each padding must satisfy. We know that for each $p_i$ and $b_i$:

$$ \begin{align} 0 + s_1 + p_1 + \ldots + s_i + p_i \equiv 0 \pmod{a_{i+1}} \\ M + s_1 + b_1 + \ldots + s_i + b_i \equiv 0 \pmod{a_{i+1}} \end{align} $$ $$ \begin{align*} 0 \leq p_i \lt a_{i+1} \\ 0 \leq b_i \lt a_{i+1} \end{align*} $$

However, in the case of equation (2), we know that by definition $M$ is divisible by the greatest alignment $a_{\text{max}}=2^{k_{\text{max}}}$ in $S$. Since we know that each $a_i=2^{k_i} \leq 2^{k_{\text{max}}}$, that means that $M$ is divisible by any ${a_i}$, and so $M \equiv 0 \pmod{a_i}$ for all $i$.

So we can instead transform equation (2) into:

$$ \begin{align*} M + s_1 + b_1 + \ldots + s_i + b_i \equiv 0 \pmod{a_{i+1}} \\ 0 + s_1 + b_1 + \ldots + s_i + b_i \equiv 0 \pmod{a_{i+1}} \\ s_1 + b_1 + \ldots + s_i + b_i \equiv 0 \pmod{a_{i+1}} \end{align*} $$

We now have the pair of equations below that we can do mathematical induction over to show that each $b_i = p_i$:

$$ \begin{align} s_1 + p_1 + \ldots + s_i + p_i \equiv 0 \pmod{a_{i+1}} \\ s_1 + b_1 + \ldots + s_i + b_i \equiv 0 \pmod{a_{i+1}} \end{align} $$

Let's start with the case of $i=1$. Then we have the equations:

$$ \begin{align} s_1 + p_1 \equiv 0 \pmod{a_2} \\ s_1 + b_1 \equiv 0 \pmod{a_2} \end{align} $$

However, since the lefthand sides of (5) and (6) are both equivalent to $0 \pmod{a_2}$, we can then write: $$ \begin{align} s_1 + p_1 \equiv s_1 + b_1 \pmod{a_2} \\ p_1 \equiv b_1 \pmod{a_2} \end{align} $$

So we know that $p_1$ and $b_1$ are in the same equivalence class. However, by our constraints on the padding between structure members, we know that $0 \leq p_1 \lt a_2$, and $0 \leq b_1 \lt a_2$. From there, we know that $p_1=b_1$, and we are done with the base case.

Now, we need to handle the induction step. We need to show that, for any $1 \lt i \leq n - 1$, if $p_{j}=b_{j}$ for all $1 \leq j \lt i$, then $p_{i}=b_{i}$. However, we can solve this by similar techniques used to prove the base case. Recall from equations (3) and (4) that we have:

$$ \begin{align*} s_1 + p_1 + \ldots + s_i + p_i \equiv 0 \pmod{a_{i+1}} \\ s_1 + b_1 + \ldots + s_i + b_i \equiv 0 \pmod{a_{i+1}} \\ \end{align*} $$

Once again, since the lefthand sides of (3) and (4) are both equivalent to $0 \pmod{a_{i+1}}$, we can set them equal to each other:

$$ \begin{equation} s_1 + b_1 + \ldots + s_i + b_i \equiv s_1 + p_1 + \ldots + s_i + p_i \pmod{a_{i+1}} \end{equation} $$

And by the induction step we know that $b_j=p_j$ for each $j$, so we can rewrite (9) by substituting each of the $b_j$ on the lefthand side with $p_j$:

$$ \begin{equation} s_1 + p_1 + \ldots + s_i + b_i \equiv s_1 + p_1 + \ldots + s_i + p_i \pmod{a_{i+1}} \end{equation} $$

so we can subtract the terms $s_1 + p_1 + \ldots + s_i$ from both sides of (10) to get:

$$ \begin{equation} b_i \equiv p_i \pmod{a_{i+1}} \end{equation} $$

So $b_i$ and $p_i$ are in the same equivalence class. However, once again, because $0 \leq b_i \lt a_{i+1}$, and $0 \leq p_i \lt a_{i+1}$, we know that $p_i=b_i$ for any $i$. That completes the induction, and since all of the paddings are pairwise equal, we are done with the proof. $\blacksquare$

The equation for `sizeof`

Okay, we now have a mathematical formula for $\text{dsizeof}(S,M)$ and we know it's consistent when we have certain restrictions on the memory address $M$. We would like to use this to come up with an equation for sizeof.

This should be simple enough. Since $\text{dsizeof}$ is simply sizeof without the trailing padding, we can write:

$$ \text{sizeof}(S,M) = \text{dsizeof}(S,M) + p $$

where $p$ represents the trailing padding of the structure. Once again, $p$ cannot be arbitrary. If we denote by $a_{\text{max}}$ the maximum alignment of all structure members in $S$, we must choose $p$ such that $0 \leq p \lt a_\text{max}$ and:

$$ M + \text{dsizeof}(S,M) + p \equiv 0 \pmod{a_\text{max}} $$

so that in an array, the next instance of $S$ will be aligned.

However, recall that the above statement isn't completely correct, as it assumes that the only valid alignment for $S$ is for it to be aligned on $a_\text{max}$. As the discussion in "A potential ambiguity in the definition of sizeof" shows, we can have "valid" alignments of $S$ that are not just the largest alignment in $S$.

In order to simplify things, I will again restrict this scope of this blog post - we will only study the mathematics of structures aligned on the largest alignment of their members. Thus, the equation above becomes valid again.

Proving the consistency of `sizeof`

We finally get to the important lemma that we need before we can even begin to think about finding the minima of sizeof.

Lemma 2: Let $M$ be any memory address evenly divisible by the $a_\text{max}$, the largest alignment in $S$. Then we have that: $$ \text{sizeof}(S,0) = \text{sizeof}(S,M) $$ Proof: Expanding the definition of $\text{sizeof}$, we have:

$$ \begin{align} \text{sizeof}(S,0) = \text{dsizeof}(S,0) + p \\ \text{sizeof}(S,M) = \text{dsizeof}(S,M) + b \end{align} $$

where $p$ and $b$ respectively must satisfy the constraints:

$$ \begin{align} \text{dsizeof}(S,0) + p \equiv 0 \pmod{a_\text{max}} \\ M + \text{dsizeof}(S,M) + b \equiv 0 \pmod{a_\text{max}} \end{align} $$

Recall that by Lemma 1 we know that $\text{dsizeof}(S,0)=\text{dsizeof}(S,M)$, so it suffices to show that the trailing paddings $p$ and $b$ are equal.

By our choice of $M$, we know that $M \equiv 0 \pmod{a_\text{max}}$, and so with (14) and (15) we have:

$$ \begin{align} \text{dsizeof}(S,0) + p \equiv \text{dsizeof}(S,M) + b \pmod{a_\text{max}} \\ p = b \pmod{a_\text{max}} \end{align} $$

And since we have both $0 \leq p \lt a_\text{max}$ and $0 \leq b \lt a_\text{max}$, we know that $p=b$ and we are done. $\blacksquare$

When is ordering by alignment optimal?

We finally have a good mathematical definition of sizeof, and we have shown that the value of sizeof is consistent as long as we align the structure $S$ on the largest alignment of its members $a_\text{max}$. Let's try to find out when the value of sizeof is minimized.

Primitive structures

To keep our mathematics simple, we're going to restrict the class of structures that we study once more. To start with, we're going to define a primitive structure as any structure where, for each member $m_i$, we have it that $s_i = ca_i$ for some $c \geq 0$. In other words, the size of each structure member is a multiple of the same member's alignment.

Loosely speaking, this is a structure whose members are all primitives, and so is one of the simplest structures we can reason about. Furthermore, no structure members have "unusual alignments" that were manually given to them by the programmer through specifiers such as alignas.

For example, Foo and Bar would be primitive structures, but Baz is not:

// Nothing out of the ordinary here, this is definitely primitive.
struct Foo {
    int first;
    double second;
    char third;
}

// First off, recall when targeting 32-bit x86, GCC asserts that double has an alignment
// of 4, so this specifier is not a no-op. Secondly, even though the programmer manually
// overrides the alignment, this is still a primitive structure as the size is a multiple
// of its alignment.
struct Bar {
    int first;
    alignas(8) double second;
}

// This is definitely not primitive, as (assuming we are on 32-bit or 64-bit systems),
// 32 does not evenly divide into the double's size of 8.
struct Baz {
    int first;
    alignas(32) double second;
}

You might have already noticed that it is not just structures with primitive members that can be considered primitive structures - structures containing fixed length arrays and nested structures qualify as well, as long as they weren't given unusual alignments. However, we'll get to that later.

Ordering members of a primitive structure by alignment minimizes dsizeof

We're going to prove an intermediary lemma. I've seen people online use this style of argument to justify that ordering the members of a structure from largest to smallest alignment optimizes the size, albeit in a handwavy way. We'll fill in the skipped details here.

Lemma 3: Let $S$ be a primitive structure aligned on $a_\text{max}$, the largest alignment in $S$. Ordering the members of $S$ from largest to smallest alignment will minimize the value of $\text{dsizeof(S, M)}$.

Proof: Recall the definition of $\text{dsizeof}(S, M)$:

$$ \text{dsizeof}(S, M) = s_1 + p_1 + s_2 + p_2 + \ldots + s_{n-1} + p_{n-1} + s_n \ $$

It suffices to show that ordering the members of $S$ from the largest to smallest alignment will make each of the intermediary paddings $p_i=0$, for $0 \lt i \leq n-1$. We do this by mathematical induction.

First, we prove the base case. We want to show that if we choose an ordering of structure members such that $a_1 \geq a_2$, then $p_1=0$, where $p_1$ must satisfy:

$$ \begin{align} M + s_1 + p_1 \equiv 0 \pmod{a_2} \\ 0 + s_1 + p_1 \equiv 0 \pmod{a_2} \\ s_1 + p_1 \equiv 0 \pmod{a_2} \end{align} $$

However, since $S$ is a primitive structure, we know that $s_1=c_1a_1$ for some positive integer $c_1$. Since $2^{k_1} = a_1 \geq a_2 = 2^{k_2}$, we know that $a_1$ is evenly divisible by $a_2$, and thus $s_1$ is evenly divisible by $a_2$.

However, by equation (20) we know that $p_1 \equiv 0 \pmod{a_2}$ and since $0 \leq p_1 \lt a_2$ we immediately know that $p_1=0$.

Next, we prove the induction step. We need to show that, for any $1 \lt i \leq n$, if $p_{j}=0$ for all $1 \leq j \lt i$, then $p_{i}=0$. Recall that $p_i$ must satisfy the following:

$$ \begin{align} M + s_1 + p_1 + \ldots s_{i-1} + p_{i-1} + s_i + p_i \equiv 0 \pmod{a_{i+1}} \\ 0 + s_1 + p_1 + \ldots s_{i-1} + p_{i-1} + s_i + p_i \equiv 0 \pmod{a_{i+1}} \\ s_1 + p_1 + \ldots s_{i-1} + p_{i-1} + s_i + p_i \equiv 0 \pmod{a_{i+1}} \end{align} $$

But since all $p_j=0$, we know from equation (23) that:

$$ s_1 + s_2 + \ldots s_{i-1} + s_i + p_i \equiv 0 \pmod{a_{i+1}} $$

and since each $s_i=c_ia_i$, we can rewrite the above as:

$$ \begin{equation} c_1a_1 + c_2a_2 + \ldots c_{i-1}a_{i-1} + c_ia_i + p_i \equiv 0 \pmod{a_{i+1}} \end{equation} $$

Recall that since we have chosen an order of structure members that goes from largest alignment to smallest alignment, we also have:

$$ a_1 \geq a_2 \geq a_3 \geq \ldots \geq a_{i-1} \geq a_i \geq a_{i+1} $$

And since each alignment is a power of two, we know that $a_{i+1}$ must evenly divide $c_1a_1 + c_2a_2 + \ldots c_{i-1}a_{i-1} + c_ia_i$. Putting this together with equation (24) we immediately know that:

$$ p_i \equiv 0 \pmod{a_{i+1}} $$

and we are done, as $p_i=0$ by our constraints on $p_i$. $\blacksquare$

On minimizing structure size on ternary computers

Notice that, in the above proof, the fact that each $a_i$ was a power of 2 didn't play any particularly important role, besides ensuring that $a_i$ evenly divides by $a_j$ if $i \geq j$.

Assuming a hypothetical ternary computer follows similar rules for alignment as today's binary computers, that seems to imply that the above lemma would be true even if each $a_i=3^{k_i}$ for some positive $k_i$. In other words, on such a ternary computer ordering the members of a structure from largest to smallest alignment would minimize $\text{dsizeof}(S,M)$.

In fact, we could extrapolate that the above lemma would be true as long as each $a_i=b^{k_i}$ for some base $b$, and so ordering the members of a primitive structure aligned on $a_\text{max}$ from largest to smallest alignment would minimize the size even on computers based on powers of $b$.

Ordering members of a primitive structure by alignment minimizes sizeof

With Lemma 3 in our belt, proving that ordering structure members of a primitive structure by alignment will minimize sizeof becomes significantly easier.

Lemma 4: Let $S$ be a primitive structure aligned on $a_\text{max}$, the largest alignment in $S$. Ordering the members of $S$ from largest to smallest alignment will minimize the value of $\text{sizeof}(S, M)$.

Proof: Let $S_\alpha$ be the structure formed from taking the members of $S$ and ordering them from the largest to smallest alignment, and let $S_\beta$ be the structure formed from any permutation of the members of $S$. We wish to prove that:

$$\text{sizeof}(S_\alpha, M) \leq \text{sizeof}(S_\beta, M)$$

Expanding the definition of $\text{sizeof}$, we know that:

$$ \begin{align} \text{sizeof}(S_\alpha,M) = \text{dsizeof}(S_\alpha,M) + p_\alpha \\ \text{sizeof}(S_\beta,M) = \text{dsizeof}(S_\beta,M) + p_\beta \end{align} $$

Furthermore, by our constraints on the tail padding $p_\alpha$, we know that:

$$ \begin{align} M + \text{dsizeof}(S_\alpha,M) + p_\alpha \equiv 0 \pmod{a_\text{max}} \\ \text{dsizeof}(S_\alpha,M) + p_\alpha \equiv 0 \pmod{a_\text{max}} \\ \end{align} $$

However, if we notice the lefthand side of equation (28) is just the definition of $\text{sizeof}(S_\alpha, M)$, we know that:

$$ \text{sizeof}(S_\alpha, M) \equiv 0 \pmod{a_\text{max}} $$

And in particular, it means that $\text{sizeof}(S_\alpha,M) = c_{\alpha}a_\text{max}$ for some positive integer $c_\alpha$. By a similar argument, we can conclude that $\text{sizeof}(S_\beta,M) = c_{\beta}a_\text{max}$ for some positive integer $c_\beta$.

However, recall that $0 \leq p_\alpha \lt a_\text{max}$, and $0 \leq p_\beta \lt a_\text{max}$. We can put this information together with equation (28) to notice that:

$$ \begin{equation} (c_{\alpha} - 1)a_\text{max} \lt \text{dsizeof}(S_\alpha, M) \leq c_{\alpha}a_\text{max} \end{equation} $$

and we can copy-paste that argument to come to a similar conclusion about $\text{dsizeof}(S_\beta, M)$:

$$ \begin{equation} (c_{\beta} - 1)a_\text{max} \lt \text{dsizeof}(S_\beta, M) \leq c_{\beta}a_\text{max} \end{equation} $$

By Lemma 3, we know that $\text{dsizeof}(S_\alpha, M) \leq \text{dsizeof}(S_\beta, M)$, and if we put that together with equations (29) and (30) we know that:

$$ \begin{gather} (c_{\alpha} - 1)a_\text{max} \lt \text{dsizeof}(S_\alpha, M) \leq \text{dsizeof}(S_\beta, M) \leq c_{\beta}a_\text{max} \\ (c_{\alpha} - 1)a_\text{max} \lt c_{\beta}a_\text{max} \\ (c_{\alpha} - 1) \lt c_{\beta} \end{gather} $$

And since $c_{\alpha}$ is the smallest integer greater than $c_{\alpha} - 1$, we in particular have that $c_{\alpha} \leq c_{\beta}$. Thus:

$$ \text{sizeof}(S_\alpha,M) = c_{\alpha}a_\text{max} \leq c_{\beta}a_\text{max} = \text{sizeof}(S_\beta,M) $$

and we are done with the proof. $\blacksquare$

What other structures can be classified as primitive structures?

Remember that our only requirement for a structure to be a primitive structure is that all members $m_i$ satisfy $s_i = ca_i$ for some $c \geq 0$.

If a member is a primitive data type, these conditions are surely true. But these conditions also hold if a structure member is a structure itself. This is because the starting address of a structure $S$ is always some multiple of $a_\text{max}$, and since we choose trailing padding for the structure so that the structure ends on a multiple of $a_\text{max}$, the difference between the starting and ending memory addresses of $S$ reveals that the size of $S$ is also a multiple of $a_\text{max}$.

The above conditions also hold true if a structure member is a fixed length array of primitive members. This is because the alignment of the array is just the alignment of the primitive member itself, and the size of the array is just a multiple of the size of the primitive member.

In other words, Lemma 4 is applicable to a wider variety of structures than just those whose members are primitive data types.

Counterexample to the 'ordering by alignment' algorithm

It's easy to generate a counter example for why the 'ordering by alignment' algorithm doesn't always minimize the size of a structure. For example, consider the following structure on a 32-bit system:

struct Foo {
    __attribute__((aligned(8))) int someInt;
    __attribute__((aligned(8))) double someDouble;
    short someShort;
}

It is clear that the members are sorted by alignment, but we can find a layout of Foo that is smaller than the layout found previously:

struct Foo {
    __attribute__((aligned(8))) int someInt;
    short someShort;
    __attribute__((aligned(8))) double someDouble;
}

You can try both of these examples on Godbolt.

This might imply that some kind of "gap-filling" algorithm would always give the optimal output. However, you have to be careful here - it is possible that "filling the gap" earlier might result in an unfillable gap later that's larger than the gap we were trying to fill. Clang attempts to write an algorithm like this, and while it's mostly correct, we can still find structures where it fails to find the optimal size.

Counterexample to Clang's optin.performance.Padding Analyzer

As mentioned before, Clang comes with an optional analyzer that will attempt to check for excessively padded structures. The comments in the optin.performance.Padding implementation gives us hints at what it tries to do.

First, here is the promised counterexample on x86-64. The construction is admittedly contrived, and I'm not sure if there are any real life structures that would have a shape similar to it. In any case, we know that Clang's algorithm is not always correct (but is probably good enough for the vast majority of usecases).

I tried to get the static checkers working in Godbolt, but failed to for some reason. So I hope you'll be willing to try this on your own machine.

#include <stdint.h>
#include <stdio.h>

struct Foo {
    __attribute__((aligned(8))) uint32_t id;
    __attribute__((aligned(8))) uint8_t flags[9];
    struct {
        uint16_t foo;
        uint16_t bar;
        uint16_t blah;
    };
};

struct FooInefficient {
    __attribute__((aligned(8))) uint32_t id;
    struct {
        uint16_t foo;
        uint16_t bar;
        uint16_t blah;
    };
    __attribute__((aligned(8))) uint8_t flags[9];
};

// Clearly "inefficient" structure to test that clang's
// static analyzer is running at all.
struct Baz {
    char firstChar;
    double firstDouble;
    char secondChar;
};

int main(void) {
    printf("Size of struct Foo: %zu\n", sizeof(struct Foo));
    printf("Size of struct FooInefficient: %zu\n", sizeof(struct FooInefficient));
}

To run the clang padding checker, you can invoke the following command, assuming you copied the above code into the file main.c:

clang --analyze -Xclang -analyzer-checker=optin.performance.Padding -Xclang -analyzer-config -Xclang optin.performance.Padding:AllowedPad=0  main.c

On my x86-64 machine, when using clang version 20.1.8, notice how there are only warnings for the structure Baz, and none for FooInefficient:

$ clang --analyze -Xclang -analyzer-checker=optin.performance.Padding -Xclang -analyzer-config -Xclang optin.performance.Padding:AllowedPad=0  main.c
main.c:24:8: warning: Excessive padding in 'struct Baz' (14 padding bytes, where 6 is optimal). Optimal fields order: firstDouble, firstChar, secondChar, consider reordering the fields or adding explicit padding members [optin.performance.Padding]
   24 | struct Baz {
      | ~~~~~~~^~~~~
   25 |     char firstChar;
      |     ~~~~~~~~~~~~~~~
   26 |     double firstDouble;
      |     ~~~~~~~~~~~~~~~~~~~
   27 |     char secondChar;
      |     ~~~~~~~~~~~~~~~~
   28 | };
      | ~
1 warning generated.

However, if you run the compiled binary, we can see that FooInefficient is clearly larger than Foo, and the static analyzer did not realize that there existed a smaller layout for FooInefficient:

$ ./a.out
Size of struct Foo: 24
Size of struct FooInefficient: 32

Further Questions

There were a couple of interesting questions to explore, but I decided against including them in this blog post as it was already getting long.

Ability of other field reordering algorithms to minimize size

While we gave a counterexample to the correctness of Clang's algorithm, it would be interesting to mathematically characterize a group of structures where Clang's algorithm can always minimize their size. It would be interesting to try and analyze the algorithm of pahole as well, although I vaguely remember it not accounting for alignas specifiers (you should double check, I could be remembering incorrectly).

Furthermore, the problem of reordering field members to minimize size is clearly not unique to C. It would be interesting to:

Analyze the ability of Java's layout algorithm to minimize size
- There is a thorough writeup about this in Oracle's Java Bug Database if you're curious.
- As mentioned earlier, it seems like most research into Java layout organization seems to favor layouts that are friendly to the access patterns of the program. This is probably better for performance than purely trying to minimize size, and so perhaps this line of questioning isn't useful.
Analyze the ability of Rust's layout algorithm to minimize size
- Again, there is a thorough writeup about this by Austin Hicks if you're curious (although probably a bit outdated).
Try to come up with a layout algorithm for C++ classes, and characterize what kind of data structures it will create an optimal layout for.
- This might be trivial to do once we know how to optimize a C structure layout, but I don't really know enough about the memory layout of C++ classes to say.

Usefulness of memory allocators flexible enough to allocate memory at exotic alignments

Earlier, we noticed that there are other valid alignments for a structure $S$ that is not just $a_\text{max}$. In particular, in our discussion in "A potential ambiguity in the definition of sizeof", we saw that a given layout of Foo could be denser depending on what memory address we started it out on.

It turned out to not be useful in that case because we found a layout of Foo that was just as dense at $M \equiv 0 \pmod{4}$ as the initial layout of Foo was at $M \equiv 2 \pmod{4}$. However, this begs another question.

Suppose that a structure $S$ has "valid alignments" at both memory addresses $M_\alpha$ and $M_\beta$ such that:

$$ \begin{gather*} M_\alpha \equiv 0 \pmod{a_\text{max}} \\ M_\beta \equiv b \pmod{c} \end{gather*} $$

for some positive integers $b$ and $c$. Is it true that the minimal size that we could find when starting $S$ at $M_\alpha$ is equal to the minimal size that we could find when starting $S$ at $M_\beta$? Can we ever find denser/smaller layouts of $S$ at $M_\beta$ than we could at $M_\alpha$?

The answer to the above question might have interesting implications on how flexible memory allocator implementations should be!

Plotting the distribution of floating point numbers

Sayan Sivakumaran — Thu, 07 Nov 2024 00:00:00 +0000

There is an interesting post from 2010 that plotted the distribution of a custom 6-bit floating point format. I was curious what the resulting graph would look like if we plotted IEEE single precision floating point numbers, instead. Luckily, this turns out to be very easy using the gnuplot utility!

The trick is to use the nextafterf (manpage) function to create an enumeration of the floating point numbers. There are too many floating point numbers to plot every single one, so we'll arbitrarily choose to only plot every hundred-thousandth floating point number, counting up to the hundred-millionth floating point number. We'll do this in both the positive and negative directions.

Here is the code we'll use to generate the data.txt file for gnuplot to plot from. All we need to do is generate a text file with two space-delimited columns. The first column will hold the current index during iteration, and the second column will hold the decimal approximation of the floating point number.

#include <float.h>
#include <math.h>
#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>

#define INDEX_MAX (100 * 1000 * 1000)
// Plotting every single floating point number would bloat the
// data file way too much. Let's only plot every floating point
// number in steps of INDEX_STEP.
#define INDEX_STEP (100 * 1000)

int main(void) {
  FILE *file = fopen("data.txt", "w");
  if (!file) {
    perror("Failed to open 'data.txt' for writing");
    exit(EXIT_FAILURE);
  }

  // Plotting positive numbers
  int index = 0;
  float current = 0.0f;
  while (index <= INDEX_MAX && current != HUGE_VALF) {
    bool should_print = index % INDEX_STEP == 0;
    if (should_print &&
        fprintf(file, "%d %.*g\n", index, FLT_DECIMAL_DIG, current) < 0) {
      perror("Failed to write to 'data.txt'");
      exit(EXIT_FAILURE);
    }
    current = nextafterf(current, FLT_MAX);
    index += 1;
  }

  // Plotting negative numbers
  index = 0;
  current = 0.0f;
  while (index <= INDEX_MAX && current != HUGE_VALF) {
    bool should_print = index % INDEX_STEP == 0;
    if (should_print &&
        fprintf(file, "-%d %.*g\n", index, FLT_DECIMAL_DIG, current) < 0) {
      perror("Failed to write to 'data.txt'");
      exit(EXIT_FAILURE);
    }
    current = nextafterf(current, -FLT_MAX);
    index += 1;
  }

  exit(EXIT_SUCCESS);
}

What is FLT_DECIMAL_DIG in the code?

Approximately paraphrasing the C23 standard (PDF), it gives us the number of digits we need to write a single precision floating point number in decimal form such that it can be converted back into the exact same floating point number. The decimal form is not exact, but since we can map the decimal back to precisely one floating point number, it's good enough for this graphing exercise.

Thanks to this stack overflow post which taught me about this macro.

After running this code, we can generate the graph using the following gnuplot script:

set title "Enumeration of Floating Point Numbers using nextafterf()" font ",18" offset 0,1
set xlabel "Index during iteration (negative values represent iteration towards -FLT\\\_MAX)" font ",11" offset 0,-2
set ylabel "Approximate value of nextafterf() at index" offset -4,0 font ",11"
unset key
set xtics axis
set ytics axis
set zeroaxis
set margin 12,12,5,5
unset border
set xtics -1e8,2e7,1e8

plot "data.txt" lc 2
pause -1 "Hit any key to continue"

Putting it all together, we get the following image:

With the accompanying table giving the coordinates of key points on the graph if you're curious. Note that, as mentioned in the graph, the negative values in the "Index during iteration" column represent iterations towards -FLT_MAX):

Index during iteration	Approximate value of nextafterf() at index
-1×10⁸	-2.31223412×10^-35
-8×10⁷	-4.62446824×10^-36
-6×10⁷	-8.67087796×10^-37
-4×10⁷	-1.66296864×10^-37
-2×10⁷	-3.25420516×10^-38
0	0
2×10⁷	3.25420516×10^-38
4×10⁷	1.66296864×10^-37
6×10⁷	8.67087796×10^-37
8×10⁷	4.62446824×10^-36
1×10⁸	2.31223412×10^-35

The most interesting part of this data is that we can notice the gaps get bigger between the points the farther away we get from zero! This makes sense, as incrementing the last bit in the fractional part of a floating point number (which is basically what takes us to the next floating point number) gives us a larger and larger difference as the exponent for the number grows.

RIP relative addressing in x86-64

Sayan Sivakumaran — Thu, 18 Apr 2024 00:00:00 +0000

I was attempting to learn about how dynamic linking worked in Unix systems, and along the way I encountered the concept of the GOT (Global Offset Table) and PLT (Procedural Linkage Table). I wanted to see these concepts in action for myself, so I decided to compile a very simple 'Hello World' C program and debug its assembly:

#include <stdio.h>

int main(void) {
    printf("Hello World");
}

If you're already familiar with dynamic linking, you'll know that if we don't link this statically then the printf symbol will be unresolved at compile time, and we'll need to consult the .got.plt section to figure out where the definition lives (or load it if it isn't already accessible). Here is what that looks like in x86-64 assembly, after using objdump -D on the binary:

0000000000001030 <printf@plt>:
    1030:	ff 25 e2 2f 00 00    	jmp    *0x2fe2(%rip)
    1036:	68 00 00 00 00       	push   $0x0
    103b:	e9 e0 ff ff ff       	jmp    1020 <_init+0x20>

The instruction at 1030 is where we consult the .got.plt table, but how do we resolve the address to see where our jump instruction will take us? It turns out that this kind of addressing mode is called RIP relative addressing (also known as PC relative addressing), and Volume 3 of the AMD64 Programmer's Manual (PDF) tells us how to resolve this in chapter 1.7:

In 64-bit mode, addressing relative to the contents of the 64-bit instruction pointer (program counter)—called RIP-relative addressing or PC-relative addressing—is implemented for certain instructions. In such cases, the effective address is formed by adding the displacement to the 64-bit RIP of the next instruction.

Something that is very important is that the displacement is added to the address of the next instruction, not the current one. In other words, we look at the address obtained from adding 0x1036 and 0x2fe2, giving us 0x4018. The value at that address should either point to the printf symbol, or point to the invokation of the dynamic linker to load the needed shared object (and only then call printf).

$ readelf -x .got.plt a.out

Hex dump of section '.got.plt':
 NOTE: This section has relocations against it, but these have NOT been applied to this dump.
  0x00004000 f83d0000 00000000 00000000 00000000 .=..............
  0x00004010 00000000 00000000 36100000 00000000 ........6.......

Aha! It seems that dereferencing 0x4018 resolves to 0x1036 (note that my machine is little endian), which will jump us to the instruction right after our original jump instruction at 0x1030, as expected. From here, the dynamic linker will take over and find the definition of printf for us.

Other types of addressing modes

While perusing Volume 1 of the AMD64 Programmer's Manual (PDF), I found out that there are apparently other types of addressing modes besides absolute addressing and RIP relative addressing. I encourage you to check out chapter 2.2.3 if you're curious!

Configuring YCM to allow the restrict keyword in header files

Sayan Sivakumaran — Fri, 22 Mar 2024 00:00:00 +0000

When doing some C development earlier today, I noticed I was getting a very particular error in vim. Given a simple header file like this:

struct Foo {
    int* restrict ptr;
};

YCM would give an error saying [expected_semi_decl_list] Line 2: expected ';' at end of declaration list, even though this is perfectly valid C.

The reason this happened is because my configuration of YCM was using clangd for parsing the code, and there was no .clangd file specifying what types of files were in this project. Because both C and C++ have header files, clangd guessed that the header file was a C++ header file.

C++ doesn't have the restrict keyword, and so it throws the error above. The fix is simple: make a .clangd configuration file at the root of your project, and then tell clangd that we are writing in C. Something like this should do it:

CompileFlags:
  Add: [-xc]

Inspecting LLVM inlining decisions with LLVM logging

Sayan Sivakumaran — Wed, 20 Mar 2024 00:00:00 +0000

I was curious about how LLVM makes decisions on whether to inline a function or not, and wanted to get a high level overview of its strategy. Thankfully, it seems like there is some relevant logging in InlineCost.cpp that we can take advantage of!

All we have to do is compile Clang in debug mode, then invoke clang with the arguments -mllvm -debug. All this does is pass the -debug flag to the llvm backend, which enables logging statements for us.

For example, if we wanted to analyze why the function foo may or may not be inlined below:

#include <stdio.h>
#include <stdlib.h>

int foo(int a) {
    if (a < 10) return 5;

    for (int i = 0; i < a; i++) {
        printf("%u ", i);
    }
    puts("");
    puts("");
    puts("");
    puts("");
    return 0;
}

int main(int argc, char** argv) {
    if (argc < 2) {
        puts("Please enter an integer.");
    }
    // You'll want error handling in a real application here,
    // but for simplicity we're omitting it.
    int i = strtol(argv[1], 0, 10);
    return foo(i);  
}

We would invoke clang main.c -mllvm -debug -O2 and look at the outputted logs. Here are the interesting log lines after redirecting the logs to a file:

  Initial cost: -35
  NumConstantArgs: 0
  NumConstantOffsetPtrArgs: 0
  NumAllocaArgs: 0
  NumConstantPtrCmps: 0
  NumConstantPtrDiffs: 0
  NumInstructionsSimplified: 4
  NumInstructions: 14
  SROACostSavings: 0
  SROACostSavingsLost: 0
  LoadEliminationCost: 0
  ContainsNoDuplicateCall: 0
  Cost: 170
  Threshold: 225
Inlining (cost=170, threshold=225), Call:   %call2 = call i32 @foo(i32 noundef %conv), !range !9

Note that the -debug argument won't work if clang is not compiled in debug mode.

Storage of Compound Literals in C

Sayan Sivakumaran — Wed, 13 Mar 2024 00:00:00 +0000

Some subtle details about compound literals confused me while going through Modern C. For example, what do you think will be returned if we compile and run the following code?

struct foo { int i; };

int main (void)
{
    struct foo* p = 0, *q;
    int j;

    for (j = 0; j < 2; j++)
        q = p, p = &((struct foo){ j });
    return p == q;
}

If you read the code, you might assume that this will return 0, since q should always be pointing to the "old" value of p at the end of each loop, right?

It turns out that main will always return 1, and the C standard offers some clarification about what is going on here.

What is going on?

If we look at the C23 standard (PDF), section 6.5.2.5p17 has the following to say:

EXAMPLE 9: Each compound literal creates only a single object in a given scope.

In other words, since we only have a single compound literal expression in the code snippet above, we only allocate space for one struct foo when we enter main. As we go through the for loop, each foo we initialize is placed into the same address, no matter what j we initialize it with. This is because all of the structures we initialize share the same block scope and come from the same expression.

Thus, the two pointers share the same address at the end of main, and we return 1.

Looking at the LLVM IR

If you aren't already aware, LLVM IR is a very convenient way to represent assembly in an architecture independent way. Here is an annotated output of compiling the above file with optimization level 0:

%struct.foo = type { i32 }

; Function Attrs: noinline nounwind optnone uwtable
define dso_local i32 @main() #0 {
  %1 = alloca i32, align 4
  %2 = alloca %struct.foo*, align 8             ; struct foo* p
  %3 = alloca %struct.foo*, align 8             ; struct foo* q
  %4 = alloca i32, align 4                      ; int j
  %5 = alloca %struct.foo, align 4              ; Compound literal address
  store i32 0, i32* %1, align 4
  store %struct.foo* null, %struct.foo** %2, align 8
  store i32 0, i32* %4, align 4
  br label %6

6:                                                ; preds = %13, %0
  %7 = load i32, i32* %4, align 4
  %8 = icmp slt i32 %7, 2
  br i1 %8, label %9, label %16

9:                                                ; preds = %6
  %10 = load %struct.foo*, %struct.foo** %2, align 8
  store %struct.foo* %10, %struct.foo** %3, align 8
  %11 = getelementptr inbounds %struct.foo, %struct.foo* %5, i32 0, i32 0
  %12 = load i32, i32* %4, align 4
  store i32 %12, i32* %11, align 4
  store %struct.foo* %5, %struct.foo** %2, align 8
  br label %13

13:                                               ; preds = %9
  %14 = load i32, i32* %4, align 4
  %15 = add nsw i32 %14, 1
  store i32 %15, i32* %4, align 4
  br label %6, !llvm.loop !6

16:                                               ; preds = %6
  %17 = load %struct.foo*, %struct.foo** %2, align 8
  %18 = load %struct.foo*, %struct.foo** %3, align 8
  %19 = icmp eq %struct.foo* %17, %18
  %20 = zext i1 %19 to i32
  ret i32 %20
}

If you take the time to read the code, you'll notice that %5 holds a pointer to a struct foo. In other words, that register holds the memory allocated for our compound literal.

The body of the for loop is represented by label 9, where we repeatedly update the integer in %5. We are not seeing multiple alloca calls to initialize a new compound literal in the loop, which tracks with what the C23 standard says should happen.

Interestingly, it turns out that compiling the same code with -O2 instead of -O0 is enough for clang to give this extremely simplified output!

; Function Attrs: nofree norecurse nosync nounwind readnone uwtable
define dso_local i32 @main() local_unnamed_addr #0 {
  ret i32 1
}

This is probably expected, but I still think it's cool that the compiler is smart enough to take all of the code above and simplify it to this small little chunk 🙂

Don't know how to read LLVM IR?

That's okay - I don't know much about it either.

I used this conference talk to get the basics down, at least enough to somewhat understand the emitted code above. I personally found it to be a very gentle introduction.

Afterwards, searching for instructions that I didn't know about and taking some time to read about it in the LLVM Programmer's Manual was very helpful to me.

Why was this behavior chosen?

I attempted to go through the WG 14 documents to find the answer. After doing some digging, I found that the first time this was brought up was in N759, which brought up an issue with the C99 standard. It seems that this behavior was chosen because the alternative would introduce complexity for implementers:

Consider the situation where a compound literal is evaluated more than once during the lifetime of its block, such as the second compound literal in example 8. The wording is unclear whether a new object is created each time the compound literal is evaluated, or whether a single object is simply reinitialized. If the former is the case, a burden will be placed on implementations, which will now have to handle dynamic allocation with block-related lifetime.

Experimenting with AMD64 Alignment Checks

Sayan Sivakumaran — Sun, 03 Mar 2024 00:00:00 +0000

While going through the Modern C book, the author mentioned a very cool blog post by Ygdrasil that showed how to enable alignment checks for Intel x86 processors.

I've heard in some casual conversations that data alignment is largely not relevant for Intel and AMD processors anymore, although I don't have the personal experience or expertise to verify the truth of that! However, naively running the tests in this blog post showed that misaligned accesses were consistently around 10% slower on my machine, so I guess it isn't obvious to me that the claim is true (or if I did something wrong in my tests).

In any case, I wanted to try enabling this check for myself just to see what would happen.

The Code

This code is more or less copy-pasted from the code in Modern C and Ygdrasil's blog post.

#include <stdio.h>

union DoubleInspect {
    double val[2];
    unsigned char buf[sizeof(double)*2];
};

int main(void) {
    __asm__("pushf\n"
            "orl $0x40000, (%rsp)\n"
            "popf");

    union DoubleInspect inspect = { .val = {1,2} };
    printf("base address:\t%p\n", &inspect.buf);

    // Let's do explicit flushes since we don't know if crashing
    // will automatically flush the buffers or not.
    for (size_t offset = sizeof(double); offset; offset /= 2) {
        printf("offset:\t%zu\n", offset);
        fflush(stdout);

        double* misaligned_pointer = (double*)&inspect.buf[offset];
        printf("address with offset:\t%p\n", misaligned_pointer);
        fflush(stdout);

        printf("value at address:\t%f\n", *misaligned_pointer);
        printf("\n");
        fflush(stdout);
    }

    return 0;
}

The most important parts of the code above are the inline assembly instructions.

__asm__("pushf\n"
        "orl $0x40000, (%rsp)\n"
        "popf");

While Ygdrasil's blog post is specific to Intel processors, the trick they talk about thankfully seems to be supported by AMD processors, too! One can verify this by taking a look at the AMD64 programmer's manual — all we're doing is setting bit 18 of the RFLAGs register.

Running the Code

Strangely, when running the above program, glibc seems to immediately crash with this check enabled. I assume the library does some special things on x86-64 processors, and so assumes that misaligned data will never crash.

This even happens when running an extremely minimal hello.c file:

#include <stdio.h>

int main(void) {
    __asm__("pushf\n"
            "orl $0x40000, (%rsp)\n"
            "popf");

    printf("Hi");
    return 0;
}

Here is the backtrace from running the above program in gdb if you're curious. It seems that we crash at this line of code.

Program received signal SIGBUS, Bus error.
0x00007ffff7e37078 in __printf_buffer (buf=buf@entry=0x7fffffffd8b0, format=format@entry=0x7ffff7fc0004 "Hi", ap=ap@entry=0x7fffffffd9a8, mode_flags=mode_flags@entry=0) at vfprintf-internal.c:638
638	  __va_copy (ap_save, ap);
(gdb) bt
#0  0x00007ffff7e37078 in __printf_buffer (buf=buf@entry=0x7fffffffd8b0, format=format@entry=0x7ffff7fc0004 "Hi", ap=ap@entry=0x7fffffffd9a8, mode_flags=mode_flags@entry=0)
    at vfprintf-internal.c:638
#1  0x00007ffff7e392c1 in __vfprintf_internal (s=0x7ffff7fae7a0 <_IO_2_1_stdout_>, format=0x7ffff7fc0004 "Hi", ap=ap@entry=0x7fffffffd9a8, mode_flags=mode_flags@entry=0)
    at vfprintf-internal.c:1544
#2  0x00007ffff7e2f162 in __printf (format=<optimized out>) at printf.c:33

We get a similar crash if we replace the call to printf with a call to puts. Is this a problem? I'm not too sure if this is a crash the library maintainers need to care about. But it does make enabling the alignment check useless if you link against glibc and use printf in your program (at least on my machine).

If we remove all printing functions from our first code example instead:

union DoubleInspect {
    double val[2];
    unsigned char buf[sizeof(double)*2];
};

int main(void) {
    __asm__("pushf\n"
            "orl $0x40000, (%rsp)\n"
            "popf");

    union DoubleInspect inspect = { .val = {1,2} };

    for (size_t offset = sizeof(double); offset; offset /= 2) {
        double* misaligned_pointer = (double*)&inspect.buf[offset];
        *misaligned_pointer *= *misaligned_pointer;
    }

    return 0;
}

And we then compile with debug symbols, we do crash when misaligned_pointer is dereferenced, as expected.

(gdb) r
Starting program: /home/sayan/Development/experiments/c/alignment/a.out
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".

Program received signal SIGBUS, Bus error.
0x00005555555551a4 in main () at main-minimal.c:18
18	        *misaligned_pointer *= *misaligned_pointer;
(gdb) p offset
$1 = 4
(gdb)

What exactly is the accessibility API?

Sayan Sivakumaran — Thu, 24 Aug 2023 00:00:00 +0000

I notice that a lot of content introducing the accessibility API (Application Programming Interface) only talk about how it might be used by screen readers. I'm guessing this is one of the reasons that people don't ever consider voice control or other assistive technologies when doing accessibility testing, and why people add questionable labels to certain controls.

I wrote this blog post to try and give an introduction to the accessibility API that doesn't only consider screen readers, and introduces what kinds of things a browser considers when generating an accessibility tree for the accessibility API. I hope I can share what I learned over the past year of doing open source work and digging into native accessibility code.

Foreword

All the content in this blog post will assume the basics of HTML and CSS. I will link to C++ or Python source code that you can explore if you like, but it is by no means required to understand this topic at a high level.

While any browser source code I link to will be biased to Chromium, any browser behavior I mention below should be true for the following major browsers, unless explicitly mentioned otherwise:

Chromium (Version 116)
Firefox (Version 116)
Safari (Version 16.6)

Finally, all links to source code, whether it be to browsers or assistive technology or otherwise, will be locked to a specific revision — their latest revision as of the time of this writing. I do this so future readers won't experience the phenomena where I'm pointing to a line of code and that specific line of code doesn't do what I point out anymore.

What is assistive technology?

Before introducing the concept of an accessibility API, it's important to think about what kind of technology we're trying to support.

Assistive technology is any piece of technology that disabled people use to improve their quality of life. This can include things like:

Wheelchairs
Refreshable braille displays
Magnification software
Screen readers
Voice recognition software

For the purpose of this post, let's focus on the last two bullet points in more detail.

Wikipedia gives a decent summary:

A screen reader is a form of assistive technology (AT) that renders text and image content as speech or braille output. Screen readers are essential to people who are blind, and are useful to people who are visually impaired, illiterate, or have a learning disability.

- Wikipedia's Screen Reader Article

There are different popular screen readers depending on the platform you are on.

JAWS and NVDA on Windows
VoiceOver on Mac and iOS
Orca on Linux
Talkback on Android
ChromeVox on ChromeOS

Regardless of platform, however, screen readers are able to do things like:

Announce what control is currently focused
Announce any relevant state information of the control (Is it checked? Is it expanded?)

along with any other visually important information that a screen reader user should know.

Screen readers are highly customizable. For example, screen reader users can control how fast or slow text is announced, or filter out specific bits of information they might not care about.

Demo of NVDA by Deque Systems

What is voice recognition software?

Voice recognition software is a form of assistive technology that allows a user to interact with their machine through voice commands. For example, if there is a link called "See my projects", such as the dummy link below:

See my projects

a voice recognition user should be able to say something like "Click see my projects", and the software will programmatically click the link. The user can also do things such as dictate text to type into some editable text area, and the voice recognition software will automatically enter that text for the user.

Some examples of voice recognition software:

Windows Speech Recognition and Dragon Speech Recognition on Windows
Voice Control on Mac and iOS
Voice Access on Android

Demo of Dragon by Nuance Communications

What information does assistive technology need to gather?

Suppose that we are developers for screen readers or voice recognition software. What kind of information would we need from any application that wants to support us?

Screen readers would need a way to do the following for any application:

Programmatically access all user interface (UI) elements.
Query for the name of a UI element: if focused, what should I announce?
Query for what kind of UI element something is: Is it a button? Is it a link?
Query for any state of those UI elements: Is it checked? Is it pressed?
Programmatically ask the application to activate an element that might not be currently focused: for instance, to programmatically activate a control under a virtual cursor.

Voice recognition software would need a way to do the following for any application:

Programmatically access all interactive UI elements of an application.
Query for the name of a UI element: is my user trying to activate this element?
Programmatically ask the application to activate an element for us: for instance, if the user commands us to activate a button that isn't currently focused.
Programmatically insert text somewhere in the application if the user starts dictating.

These are very similar asks. We are asking for an API that lets us programmatically read and interact with an application, and that is precisely what an accessibility API is.

What is the accessibility API?

As mentioned above, an accessibility API allows for a consumer to do two main things:

Programmatically determine what is in the UI
Programmatically interact with the UI

In the accessibility API, the UI of an application is exposed as something called the accessibility tree, with each node in the tree being some individual unit in the UI. Depending on the UI element a node represents, a consumer can query for the state of a node, or ask to programmatically take some kind of action on a node.

Depending on the operating system, the accessibility API can have different implementation details, but the general idea remains the same. The average web developer does not have to concern themselves with this.

What does an accessibility tree look like?

An accessibility tree is a normal tree data structure that you might explore in your computer science class. For example, in the context of the browser, suppose we have some HTML like the following:

<header>...</header>
<main>
	<h1>Hello World</h1>
	<img
		src="..."
		alt="..."
	/>
	<p>
		This is a paragraph.
		<span> This is more text. </span>
	</p>
</main>
<footer>...</footer>

The browser might generate an accessibility tree similar to the following for this HTML:

root
- header
- main
  - heading
  - image
  - paragraph
- footer

Each of these nodes may have a plethora of accessibility-related information, but we can get to that later. Notice that the accessibility tree also isn't necessarily one-to-one with the DOM tree generated from the HTML. For example, it might not be justified to give that <span> element its own accessibility node, and so it's just absorbed into the parent paragraph node instead.

From the above example, let's zoom in to the image node specifically. What kind of information might it have?

image

Name: "Some alt text"
Role: Image

Name: The node will need an accessible name if the image is not decorative. This can let screen readers know what to read when encountering this image.
Role: The node will need to have some kind of attribute marking what type of UI element it is. This lets assistive technologies know what kinds of actions they can take on this node, as well as what kind of information they can query on it. In this case, the node should be an image node.

If we instead take something stateful, like a checkbox:

<label for="check">Stay logged in</label>
<input
  type="checkbox"
  id="check"
  <!-- Any other relevant attributes... -->
/>

The accessibility node for the checkbox might look something like this:

checkbox

Name: "Stay logged in"
Role: Checkbox
State: IsChecked: true

Name: Once again, the name lets the screen reader know what to announce when the checkbox is focused, and lets voice recognition software know what to click when the user says this checkbox's name.
Role: Because of the role, assistive technology knows that it can query for the "checked" state of this node. It also knows that it can ask the browser to programmatically click the checkbox.
State: Allows assistive technology to query whether this checkbox is checked or not. For example, screen readers might use this to decide what to announce.

This is the common trio of name, role, value which can be important to make sure your website is accessible.

As far as web developers are concerned, the name, role, value, and state of a node are the main parts of the accessibility tree that you need to worry about. However, there is a lot of other information calculated in the accessibility tree that you might not be aware of. For example, if we just restrict our attention to the UIAutomation accessibility API:

Bounding boxes: Where is the element located on the screen?
Locale: What language should I be interpreting this object with?
FrameworkId: What is the source of this accessibility tree? Is this an accessibility tree coming from Chrome? Is this an accessibility tree coming from Microsoft PowerPoint?

Moving our attention to another accessibility API, IAccessible2, gives us more interesting information to look at, with both examples being custom properties that don't seem to formally be part of the IAccessible2 spec:

LayoutTable: For the purpose of semantics, is this a real or fake table?
CSS Display: What is the CSS display for this node?

There is a lot of other information that I am leaving out. While this information isn't the most important to know (although it is good practice to specify locale with the lang attribute), it can be useful to know that the accessibility tree can't be generated just by scanning the DOM — we need information from CSS as well.

Regarding CSS Display in an accessibility node

Finding this property surprised me. I double checked the source of this data in Chromium, and it does appear to be the computed CSS style for the display property.

I tried searching for similar logic in Firefox, but wasn't able to find anything interesting besides this comment.

I don't expect Safari to calculate this, since it seems to be logic specific to IAccessible2 and AT-SPI. Neither of those accessibility APIs are used in Mac products as far as I can tell.

What is this ever used for? No idea. I naively searched for it in the NVDA and Orca codebase, and got the following hits.

How can I view the accessibility tree?

You have two choices here, depending on the amount of detail that you need.

The first choice is to use the browser's built-in accessibility tree viewer. You don't see the exact information that is given to assistive technology, as the information needs to be expressed in terms of the platform accessibility APIs, but it's extremely rare that you need that level of detail.

Regarding Chromium's accessibility tree inspector

The accessibility tree you see in the Chromium developer tools is what is internally known as the Blink tree. For all intents and purposes, this is a peek into the exact data that is being translated into the platform APIs - this isn't some special intermediate representation that the code makes just for the developer tools, in other words.

This logic is handled in InspectorAccessibilityAgent.

The second choice is to use an external tool that can display the native accessibility tree to you. You have different tools depending on your platform.

Dump Tree Utility
Accessibility Insights for Windows (UIAutomation only)
Accessibility Inspector on OS X
Accerciser

These tools are a good way to play around with the native accessibility APIs if you want to take the time. I think it's very rare these tools are useful for web development, though.

What technologies use the accessibility API?

Remember that an accessibility API allows you to do two things:

It allows you to programmatically read off the UI of an application through an exposed accessibility tree.
It allows you to programmatically interact with the UI of an application through nodes on the exposed accessibility tree.

As previously discussed, this allows screen readers to know what to read out when interacting with a page, and allows voice recognition software to know how to respond to specific voice commands from the user. However, there are lots of other assistive and non-assistive technologies that use the accessibility API.

For the following links below, you'll want to copy the link address and paste it into your navigation toolbar rather than trying to activate the link. It seems that Chromium browsers won't let you link directly to the about://histograms page, and you'll instead get an empty page.

Furthermore, depending on how powerful your CPU is, I highly recommend you don't navigate directly to the about://histograms page, and instead navigate to the specific histograms I talk about below, listed here for convenience:

The performance on the general about://histograms page is terrible when I'm using anything that queries the accessibility tree, even on my computer which has a relatively expensive CPU (Ryzen 5950x).

To find out what applications use the accessibility API, we can use the about://histograms page on a Chromium based browser to determine whether the browser is calculating accessibility information or not (for performance purposes, the browser doesn't kick off accessibility-related code until it has to).

As a a decent hueristic, if the histogram for HandleAXEvents has more than one data sample, we know that accessibility must have been turned on for some duration while the Chromium browser was running. In other words, some application has been making calls to the accessibility API. You can use this heuristic on any platform Chromium runs on.

We can do better on the Windows platform, though. On Windows, Chromium has a WinAPIs histogram that lets us know how many times specific Windows accessibility APIs were called. The values of the histogram correspond with this collection of enums. So not only do we know if an application is using the accessibility API or not, but we also know precisely what kind of information it is asking for. While not all accessibility API calls are logged, this should still give us some interesting information!

Onscreen Keyboard

I was very surprised to see that the onscreen keyboard was making accessibility API calls to Chromium. I launched the onscreen keyboard and typed some random gibberish into google (the "fdtgdgejcd/cgj" string to be precise) and got the following results.

UMA_API_GET_ACC_FOCUS: 6 hits
UMA_API_GET_ACC_PARENT: 10 hits
UMA_API_GET_ACC_STATE: 7 hits
UMA_API_GET_UNIQUE_ID: 8 hits
UMA_API_GET_WINDOW_HANDLE: 8 hits
UMA_API_IA2_GET_ATTRIBUTES: 1 hit
UMA_API_QUERY_SERVICE: 108 hits
UMA_API_ROLE: 4 hits

Windows Magnifier

Magnification software also makes good use of accessibility APIs. In this workflow, I used the Windows Magnifier and then launched Chromium to the WCAG 2.1 guidelines. I then zoomed in to 200%, then zoomed back out to 100%. Here are the results:

UMA_API_ACC_LOCATION: 18 hits
UMA_API_GET_ACC_CHILD: 41 hits
UMA_API_GET_ACC_FOCUS: 37 hits
UMA_API_GET_ACC_NAME: 2 hits
UMA_API_GET_ACC_PARENT: 112 hits
UMA_API_GET_ACC_ROLE: 25 hits
UMA_API_GET_ACC_STATE: 101 hits
UMA_API_GET_UNIQUE_ID: 186 hits
UMA_API_GET_WINDOW_HANDLE: 23 hits
UMA_API_IA2_GET_ATTRIBUTES: 29 hits
UMA_API_QUERY_SERVICE: 708 hits
UMA_API_ROLE: 61 hits

Power Automate

Power Automate is a tool that automates tasks in a UI. I have a simple workflow where I launch an instance of Chrome that navigates to a google search results page for "test", then clicks on the first link in the results. We get the following hits:

UMA_API_GET_ACC_PARENT: 19 hits
UMA_API_GET_ACC_STATE: 1 hit
UMA_API_GET_UNIQUE_ID: 4 hits
UMA_API_IA2_GET_ATTRIBUTES: 1 hit
UMA_API_QUERY_SERVICE: 82 hits
UMA_API_ROLE: 1 hit

Grammarly

Grammarly is a tool that attempts to improve your writing skills. The native application seems to have a natural usecase for using the accessibility API - we want to get text from some editable text area in an application, then programmatically insert some different text back if the user accepts Grammarly's suggestions.

Note that in this test I explicitly used the native application version of Grammarly, not the browser extension. The browser extension will not need to use accessibility APIs since it can simply scrape the DOM.

In this workflow, I launched MDN's textarea article and typed in the word "salaid" into the provided <textarea> element. I then waited for Grammarly to give me an autocorrect suggestion to "salad", and accepted the suggestion. We get the following hits:

UMA_API_ACC_LOCATION: 306 hits
UMA_API_ADD_SELECTION: 1 hit
UMA_API_GET_ACC_CHILD: 134 hits
UMA_API_GET_ACC_CHILD_COUNT: 10 hits
UMA_API_GET_ACC_NAME: 157 hits
UMA_API_GET_ACC_PARENT: 871 hits
UMA_API_GET_ACC_ROLE: 20 hits
UMA_API_GET_ACC_STATE: 325 hits
UMA_API_GET_ACC_VALUE: 50 hits
UMA_API_GET_CARET_OFFSET: 12 hits
UMA_API_GET_CHARACTER_EXTENTS: 64 hits
UMA_API_GET_INDEX_IN_PARENT: 8 hits
UMA_API_GET_N_SELECTIONS: 14 hits
UMA_API_GET_SELECTION: 3 hits
UMA_API_GET_STATES: 19 hits
UMA_API_GET_TEXT: 34 hits
UMA_API_GET_TOOLKIT_NAME: 22 hits
UMA_API_GET_UNIQUE_ID: 408 hits
UMA_API_GET_WINDOW_HANDLE: 142 hits
UMA_API_IA2_GET_ATTRIBUTES: 364 hits
UMA_API_QUERY_SERVICE: 6411 hits
UMA_API_ROLE: 277 hits
UMA_API_SET_SELECTION: 1 hit

On Grammarly's accessibility API usage

These results really surprised me - I didn't expect Grammarly to make such heavy use of these accessibility APIs. I even did this workflow 3 times to make sure I wasn't missing anything, and confirmed that before I launched Grammarly that the WinAPIs histogram had zero entries.

I wonder how many redundancies are here, although it's hard for me to say without knowing the reasons behind all of these API calls.

Mobile Password Managers

OK, I don't have data here since this is clearly not on Windows. However, notice how you can give accessibility permissions to password managers on Android, and that they can start overlaying their own UI on password fields after you do that. Visiting the histogram for HandleAXEvents on android Chromium does confirm that accessibility mode is turned on, although I can't comment on what API calls they are making.

How does the browser generate the accessibility tree?

Generating and updating an information dense structure like the accessibility tree in a performant way can be a very interesting technical challenge. This is even more true when the source of data comes from dynamic HTML and CSS, which can be combined in a variety of ways.

While there are lots of things to keep in mind when generating the accessibility tree, we'll restrict our discussion to the basics: how do we generate the name and role for a given accessibility node?

Generating the name

Although I'm simplifying a bit, there are three main ways a name can be generated for a node:

Name from content
Name from labelling element
Name from author

Name from content is a strategy where the name of a node is derived from its text content. For example, suppose we have the following markup:

<a href="/projects">See my projects</a>

For the link's accessibility node, browsers are smart enough to make the node's name be the same as the node's text content. This gives screen readers the appropriate name to read, and also allows voice recognition software to click on this link if the user requested it.

link

Name: "See my projects"
Role: Link

Browsers adopt a similar strategy for something like a button:

<button type="button">Dark theme</button>

which would lead to generating an accessibility node that looks something like:

button

Name: "Dark theme"
Role: Button

However, note that this strategy can't be implemented in a sensible way for all HTMLElements. For example, could we generate a good name from content for even a simple table like the one below?

<table>
	<tr>
		<th>Countries</th>
		<th>Capitals</th>
		<th>Population</th>
		<th>Language</th>
	</tr>
	<tr>
		<td>USA</td>
		<td>Washington, D.C.</td>
		<td>309 million</td>
		<td>English</td>
	</tr>
	<tr>
		<td>Sweden</td>
		<td>Stockholm</td>
		<td>9 million</td>
		<td>Swedish</td>
	</tr>
</table>

Countries	Capitals	Population	Language
USA	Washington, D.C.	309 million	English
Sweden	Stockholm	9 million	Swedish

Name from labelling elements is the second strategy browsers use to generate a name for an accessibility node. Certain HTMLElements can source their name from a specific HTMLElement that serves as a natural label.

For example, going back to the table example from above, we can add a <caption> element to source the name from.

<table>
	<caption>
		Some title
	</caption>
	...
	<!-- Same table content as before -->
	...
</table>

Some title
Countries	Capitals	Population	Language
USA	Washington, D.C.	309 million	English
Sweden	Stockholm	9 million	Swedish

The table can then have an accessibility node that looks something like this:

table

Name: "Some title"
Role: Table

An even more natural example is the pairing of an <input> and <label> element.

<label for="input">
  Some label
</label>
<input
  id="input"
  type="checkbox"
  <!-- Whatever other attributes you want -->
/>

which will generate an accessibility node that looks something like this:

checkbox

Name: "Some label"
Role: Checkbox

Name from author is the third strategy browsers can use to generate a name. In this case, the browser relies on the web developer to manually supply an accessible name using the aria-label or aria-labelledby attributes. A name from author always overrides other naming strategies - assuming that the role supports name from author, anyway. For example, if we had some HTML as follows:

<a
	aria-label="Not a chance!"
	href="/projects"
	>See my projects</a
>

the accessibility node that is generated would have the name "Not a chance!":

link

Name: "Not a chance!"
Role: Link

Note that using ARIA in this case is extremely bad, as browsers already have a great name it can generate from content. Overriding the name in this way can also make it so voice recognition software won't be able to find the link if a user says "Click see my projects", as this link has a completely different accessible name. See the Label in Name criterion for a related discussion.

Musings on name from content

Even though the ARIA spec says that elements with the row role must compute their name from content, Chromium only does this conditionally for performance purposes.

This codepen for conditional row name computations allows you to play around with this behavior. I have only tested this in Chromium, but I haven't tested this behavior in other browsers to see if they also try to make similar optimizations.

Musings on CSS contributions to name

Did you know that CSS pseudoelements can also contribute to the accessible name of an element? I suggest that you try the CSS pseudoname contribution codepen and use the accessibility inspector of your choice to see for yourself. This behavior is spec'd out, so you should see this behavior in all major browsers.

Interestingly, Chromium does some additional work to not expose CSS pseudocontent coming from the micro clearfix hack in the accessibility tree. I don't have the time to make a codepen to test this, along with seeing what other browsers do at this time. I'll probably make an edit when I do later, though. 🙂

Generating the role

The role of an accessibility node is generally simple to calculate if it has a corresponding HTMLElement. We can first use the role given to us by the ARIA role attribute if it exists. Otherwise, we can just look at the HTML tagname.

For example, consider the following HTML:

<button>This is some text</button>

The button element when translated would just have the button role. Assistive technology know that it can interact with this control as a button, and query for state relevant for buttons.

However, if we added a role attribute to it:

<button role="link">This is some text</button>

Then the <button> element would be translated into having the link role. Note that you should generally not do this - if you really need a link, just use the <a> element.

There are some amounts of complexity to consider though. For example, not all ARIA roles are valid on all HTMLElements.

Second, browsers don't always respect the semantics coming from an HTMLElement, although this is restricted to tables and lists as far as I'm aware:

All major browsers implement interesting heuristics to determine if a table should be exposed as a table. This is done to compensate for bad HTML where the <table> element is used as a styling tool rather than to communicate table semantics.
Safari specifically attempts to do something similar for lists. Other browsers don't seem to implement similar heuristics.

Wrapup

If you take nothing else, the accessibility API is an API that lets you programmatically read off and interact with an application. When generating the accessibility API, the browser has to consider both HTML and CSS to generate the accessibility tree.

Edit History

9/17/2023: Clarified that aria-label only overrides the name on roles that support name from author. Per the spec, it should not do anything otherwise.

On anxiety and becoming a better software engineer

Sayan Sivakumaran — Mon, 24 Jul 2023 00:00:00 +0000

FYI, this is a somewhat unintelligible stream of thoughts that have been bothering me over the past year.

I've recently been thinking a lot about whether I am a "good" or "bad" developer, to the point where it was probably a bit unhealthy. Ever since I started contributing to open source and doing things that are traditionally associated with "hacker culture", I've started to realize how much there is to know.

This is something that every long-time developer says, but I think this is one of those things that you don't truly understand until you come to that conclusion through your own experiences, instead of someone else's.

There is a plethora of talent out there.

The more you immerse yourself in developer culture, the more you realize just how much talent there is in this space.

There are developers that have been coding since they were in middle school, high school, or similar.
There are developers that formally studied computer science in top-tier colleges and have done cool professional work, whether that be through internships or research or similar.
There are developers with amazing design skills that make breathtakingly beautiful and usable software, all without the help of a UX designer.

I could go on. A lot of these developers don't realize how strong they are, because what they know is so normal to them.

In comparison:

I only started to learn how to program in my senior year of college, mostly teaching myself with Udemy courses.
I have a mathematics degree from an average college instead of a computer science degree. I did not have cool opportunities to apply my knowledge.
I don't have great design skills (there is a reason why I made my website so minimal).

It's only recently I've started recognizing the gaps I have when compared to people in the former group.

Self taught developers later in life tend to be at a disadvantage.

There seems to be a growing pattern of people saying that you don't need a degree to be a developer. I agree with this to a point - anything you can learn in college you can learn on your own with enough effort.

However, there is a practicality aspect to this. If you're learning how to code after college, you don't have as much free time as you might have had when you were younger. Depending on what kind of programming you want to do, the amount of investment you need to put in can go from approachable to absolutely intimidating.

If you primarily code with managed languages, I think this becomes much easier. There are a plenty of Udemy courses and Medium articles which will teach you to, at the very least, be a decent developer with those tools. You don't need to have indepth knowledge of how a computer works under the hood in order to do cool things, or know anything fancy that a computer science student might study. There are abstractions in place that will make sure you don't have to think about what's truly going on behind the scenes.

If you start to do work with unmanaged code, however, the amount of knowledge you need to not shoot yourself in the foot goes up exponentially. For example, I wish that I:

Had a better knowledge of the kinds of things computers do under the hood.
Had a better knowledge of how compilers work.
Had a better knowledge of assembly code so I could see what the disassembly of my code does.
Had a better knowledge of how to leverage the advantages I get with lower-level languages that I can't get with a higher-level language.

Among many other things. There aren't pretty and easily digestible Udemy courses or Medium articles for topics like this, at least for anything that is non-trivial, which is understandable as this knowledge tends to be more academic.

I especially feel these pain points since I've started contributing to Chromium - I've never thought about the performance and memory implications of the code I write so much before, even for the easiest of fixes. While I think I'm doing OK so far, it's definitely very intimidating for me.

It's ok to take your time.

The thoughts that I've listed above made me feel like I needed to rush to "catch up" with my peers. I wanted to obtain the knowledge that I missed out on so I can do the type of work I want to do. This has caused a lot of stress for me in the past year or so.

Reading the article Teach Yourself Programming in Ten Years has helped me come to terms with the fact that it will take a long time for me to get to a place I am happy with, and that's okay. There's no need to be in a race with anyone, and there will always be someone that is smarter than you anyway.

It's not realistic to expect yourself to be a very good engineer within 2 or 3 years. As long as I move slowly towards my goal, that is enough for me.

It's ok to make mistakes.

I'm a perfectionist, which isn't always a good thing. It means that I sometimes move slower than necessary, and also means that I can beat myself up pretty hard whenever I make a mistake.

Since we're human, we're naturally going to have buggy code. We can invest in tooling that can minimize these bugs, but bugs are just a fact of life. When we make a mistake, the most we can do is figure out why that bug was let through, fix it, and make sure tests are in place so that the bug doesn't appear again. Maybe hold a post-mortem if the bug was extremely bad, too.

I know that I've made my share of mistakes. My most recent one came from my implementation of enabling aria-errormessage to point to multiple HTMLElements. The crux of the Windows-only bug is that the order that accessibility nodes are returned in the accessibility API isn't always the same as the order specified in the HTML. In fact, this is true for all ARIA attributes that point to multiple HTMLElements except aria-labelledby and aria-describedby (if you're curious, the array we return is sorted by when we created the accessibility node).

I'm still not sure how I didn't catch it while I was testing, given that:

I'm an extremely paranoid person and look at my patches with a lot of scrutiny out of fear of breaking something.
I updated a fair amount of integration tests, added new integration tests, and even improved the dump tree testing code to make it more airtight when it comes to changes like this.

Thankfully, this bug shouldn't be breaking anything since:

The code I submitted is implementing a new feature of ARIA, so websites shouldn't be using it in production right now.
At most, it causes error messages to be read in the wrong order, which while confusing probably isn't a blocker.
I caught it in Chrome Canary.

Oh well, I released a buggy implementation - I'll commit a fix for it and learn from this.

This likely won't be the last time I release buggy code. Even the most talented software engineers can write buggy code at times (even if they write less bugs than other developers)! As long as I learn from my mistakes and put in the necessary tests/tools to make sure it doesn't happen again, I think I'll be able to live with myself.

It's part of being human.

You don't have to be the best.

This might be obvious to most of you, but as someone who grew up as the golden child in an Asian household, this took a long time for me to accept. I'm still working on accepting this now.

I do development because I enjoy making software that improves peoples' lives. It's a big reason why I got into accessibility. I don't need to be the best engineer in my field, or even on my team, to do that. I don't need to be the best engineer to lead a happy life - there are other things that can do that for me, like friends and family.

For me, I want to be better because that will reflect in better software for the people who need it. It doesn't matter if someone else is better than me as long as I'm slightly better than I was yesterday.

Most importantly, I think that being average isn't a bad thing. Being average is underrated, I think. Maybe the secret to happiness is not tying so much of your self worth with your career.

Helpful resources

Some resources I found helpful while thinking through all of this for the past few months.

I especially appreciate my friends who put up with me ranting about how I feel like a bad engineer. I'm happy and really lucky that I have wonderful friends like you all 🙂.

If you don't have friends that you can rant about this to, I hope that you can, at the very least, tell yourself the same things I told myself in this post. Even if not now, eventually.

Exploring the "Is this a real or fake table?" algorithm in desktop browsers

Sayan Sivakumaran — Tue, 06 Jun 2023 00:00:00 +0000

There are a lot of websites out there that, unfortunately, use the <table> HTML element as a styling tool. This poses a problem to users of assistive technology, as there is now a lot of incorrect semantic information in the page.

To mitigate this issue when creating the accessibility tree, browsers try to guess when a <table> is being used for purely styling purposes. If they guess that a <table> might not really be a table, that information is then hinted to assistive technology. For example, here is a <table> that no major browser on desktop will expose as a table - you can take any screen reader to the linked codepen to verify for yourself.

I thought it would be interesting to look at this guessing algorithm in more detail. We will look at some minimal codepens of <tables> that start out as purely stylistic layout tables, and then tweak them just barely enough to make browsers think they are real data tables. 🙂

Definitions

Accessibility tree: A tree data structure that represents a graphical user interface, commonly consumed by assistive technology (although they are not the only consumers).
Assistive technology: Software or hardware that disabled people use to improve their quality of life.
Layout table: A table that is only used for styling, and not for showing tabular data.
Data table: Any table that isn't a layout table.

Notes on testing

Only if you want to know the gritty technical details.

A note on how I tested

As this article is only concerned with how browsers expose tables in the desktop accessibility APIs, here is how I get my results for each browser:

On Windows, I will look for the layout-guess attribute on the <table's> IAccessible2 node using the dump tree utility. If a node has this attribute set to true, it's a layout table, otherwise it's a data table.
On Mac, I will look to see if the <table> is exposed as a table in the accessibility tree using the Accessibility Inspector. If it's not, it's a layout table, otherwise it's a data table.
On Linux:
- For Chrome and Edge, I will look to see if the <table> is exposed as a table in the accessibility tree using the dump tree utility. If it's not, it's a layout table, otherwise it's a data table.
- For Firefox, I will look for the layout-guess attribute on the <table's> AT-SPI node using Accerciser. If a node has this attribute set to true, it's a layout table, otherwise it's a data table.

At the time of this writing, I am testing with versions:

Chrome Version 114.0.5735.90
Edge Version 114.0.1823.37
Firefox Version 113.0.2
Safari Version 16.4 (18615.1.26.11.23)

Finally, for simplicity's sake, I will not list browser + platform combinations as each individual browser's results don't seem to change with the desktop platform. I will just list the results of each browser, and you can assume those results are true for Windows, Mac, and Linux.

A note if you want to test

If you don't want to verify these results in the same way I did, here are some shortcuts you can use, which aren't as rigorous, but can give you a basic way of verifying what I'm saying:

On Chrome and Edge, you can use the Accessibility Inspector in the developer tools. Layout tables will be explicitly called out as layout tables here.
On Firefox, you can use:
- NVDA on Windows and use NVDA table shortcuts to see if it detects a table.
- Voiceover on Mac and use Voiceover table shortcuts to see if it detects a table.
- Orca on Linux and use Orca table shortcuts to see if it detects a table.
On Safari, you can use Voiceover and use Voiceover table shortcuts to see if it detects a table.

Finally, if you plan on modifying the HTML to experiment, you should use the CodePen editor instead of modifying the HTML directly through the developer tools.

I'm seeing that browsers don't necessarily update the guess of whether a table is a layout table or a data table if the table is modified after being rendered, so edits through the developer tools won't always work. Edits in the codepen work as they refresh the embedded <iframe>.

Determining table-ness via HTML

All major browsers will attempt to search for certain table-specific semantic elements. If it finds any, it will abort the algorithm early and just declare the table to be a data table. Browsers seem to agree that tables with a <caption>, <thead>, or <tfoot> are all data tables.

Codepen: Determining table-ness via the presence of HTML elements

Determining table-ness via the number of rows

All major browsers will attempt to count the number of rows that a table has, and if it has sufficiently many it will be declared a data table. Chrome, Edge, Firefox, and Safari all agree that a table with at least 20 rows is a data table.

As soon as we make the table have 19 rows, however, every browser except Firefox considers the table a layout table.

Thoughts on Firefox behavior

I was a little bit confused at first on why Firefox thought the extremely minimal table with 19 rows was a data table. Especially since Firefox seems to do a similar row count check that other browsers use, from reading the code.

My immediate guess as to why (without examining with a debugger) is that Firefox seems to assume every table is a data table until proven otherwise, while other browsers assume that a table is a layout table until proven otherwise. Again, this is just speculation from reading the code, and I would need to use a debugger to verify my hypothesis.

Codepen: Determining table-ness via the number of rows

Determining table-ness via the CSS `background-color` of table rows

The incorporation of CSS in this guessing algorithm is very interesting to me.

All four browsers seem to agree that a table with alternating background-colors on its rows is a data table, as long as the table has more than two rows. Firefox is the only browser that does not enforce a minimum of three rows when checking that the rows have alternating backgrounds.

Codepen: Determining table-ness via the CSS background-color of table rows

Determining table-ness via the CSS `background-color` of table cells

Chrome, Edge, and Safari all check if any kind of background-color CSS property is defined on the table cell. If this is true for at least half of the cells in the table, then it becomes a data table. However, note that the background-color has to be explicitly defined on the <td> - defining the background-color on the <tr> won't work.

Firefox does not seem to employ this heuristic at all.

Codepen: Determining table-ness via the CSS background-color of table cells

Determining table-ness via the CSS `border` of table cells

All major browsers do checks on the border of table cells to help determine whether something is a data table or not.

Chrome, Edge, and Safari check to see if any side of the table cell has a border. If this is true for at least half of the cells in the table, those browsers expose the table as a data table.

Firefox does it slightly differently - it only checks the first table cell, and checks if it has a border on all sides. If so, Firefox exposes the table as a data table.

Codepen: Determining table-ness via the CSS border of table cells

Source code

Reading the source code for this algorithm was really helpful in constructing these minimal codepens.

If you're curious, here is where you can walk through the algorithm's logic yourself in Chromium. Note how you can opt out of this entire guessing logic by just manually setting role="table" on the element. (Of course, don't use ARIA unless you need to)

Chromium's layout table guess

If you can't access Chromium code search

I've been told by some users that the Chromium code search isn't accessible 🙁. While not ideal, I hope this raw text version of the code can be a temporary workaround.

As for the other browsers, I'm not exactly sure where the logic is since I haven't debugged those browsers and am not as familiar with their codebases, but I can give a fairly likely guess from reading the code:

There is some logic I didn't cover - for example, Firefox seems to do checks on how wide the <table> is relative to the entire page. I also left out mobile platforms in order to simplify this post, as the mobile behavior doesn't seem as consistent at an initial glance and would require some nuance. I encourage you to read the code yourself if you want to learn more!

Finally, here is some more code speculation/archaeology that I did while doing research for this post:

Again, there might be some context I'm missing, but I think it's cool to see how everything connects together.