These days we rarely have to worry about the amount of code space we are using.  It’s all demand loaded, unused code never gets loaded, and disk space is cheap.  However, back when I started writing embedded code, back when photosynthesis was still a recent innovation looked on with skepticism by the establishment, every byte that went into your EPROM had to be accounted for; your CPU may have had 64KB of address space, but no-one made EPROMs that big, and even if they did you couldn’t afford them anyway.

When processing a static library .a file, the C linker only uses object .o files from within the library .a file that actually define symbols referenced by the program.  So, when implementing a static library of code, to be used in an embedded program, it was important that the user of the library only linked code from the library that was actually used, and didn’t link in any library code that wasn’t used.

The problem comes when you are implementing a bunch of related functions, such as the <string.h> portion of the Standard C Library.  If an object .o file contained definitions of both the memcpy and memmove functions, but the program only used the memcpy function, unused code (memmove) would also be included.  There are two traditional ways to avoid this wasted code space.

1. The first is to sprinkle the library source code with #ifdef directives used to select which pieces of the library to omit or include.  This pretty much defeats the point of having a library, making it project specific.  You may as well just include the source code in your project instead.  It’s also tedious when you decide to use another function already in the library, you have to find and fix the necessary #ifdef. And when you stop using one, you have to remember to turn off the #ifdef.

2. The second way is to put every (non-static) function definition and variable definition in its own source .c file, and then in its own object .o file, within the library .a file.  The linker will then, without change, only pull in library functions and global variables from the library .a file that the program actually uses.

This tends to make the compilation of the library slower, because there are so many invocations of the C compiler for very small C functions.  This cost is amortized over the much larger number of times the library .a file is linked to, compared to the cost of compiling it once.

3. Times have changed, and photosynthesis is pretty well established in the ecosystem.  The GNU C compiler now provides a third way, if you are using the ELF object file format, and a modern-ish version of gcc.  There are two compiler options and a linker option you need to understand.

The gcc -ffunction-sections and -fdata-sections options place each function or data item into its own section in the output file if the target supports arbitrary sections, as ELF format object files do.  The name of the function or the name of the data item determines the section’s name in the object .o file.  The GNU ld –gc-sections option (or gcc -Wl,–gc-sections from the gcc command line) is used to ignore sections in object .o files if they are not referenced by the program.  The result of combining these two options means that, effectively, if you were to implement all of <string.h> in a single source file, only the functions actually used will appear in the final executable.

These features were introduced in gcc and binutils in 1999.  And, yes, some Windows compilers and linkers had functionally equivalent features 15 years earlier.

Most recently, I came across this using an Arduino board, but any embedded SoC (MIPS, ARM, AVR, etc) will benefit.  This also helps when C++ code generates numerous functions, especially with templates, and not all of them are actually used.

Hanging out with AfC today, and I mentioned that I observed that the bottles used to take blood for blood cultures, when full, look like they belong in a vampire’s mini-bar.

This segued rapidly to “What is your favorite vampire novel?”  More-or-less in order my preferences are:

1. Barbara Hambly‘s James Asher novels: Set in the early 1900s, vampire Simon Ysidro seeks the assistance of James Asher, former spy for the British government, to find the person killing the vampires of London.
2. Tanya Huff‘s Victory Nelson novels: ex-detective Vicki Nelson teams up with vampire Henry Fitzroy, historical romance writer, and bastard son of Henry VIII
3. Kim Harrison‘s Rachael Morgan series: private detective Rachael Morgan is a witch, and her business partner Ivy Tamwood is a vampire.
4. The Hominds of the Ringworld were clever, and included vampires, but the books aren’t actually about vampires.

I am not so keen on True Blood or Twilight.

Of course, when you are having chemo for CLL, you tend to be very pale, and the drugs they give you mean that you should vigorously avoid sunburn.  If fact, you could play an extra in a vampire movie without any make-up.  Which led my wife to conclude that the authors are all wrong: actually, vampires are just normal people having chemo for leukemia.

They say that hell is reading other people’s code.  One of the things that gets my dander up is when bool functions or variables are redundantly tested against true or false.  In C there is also a very real risk that the underlying language semantics will shoot you in the foot.

Here is an example of what I mean:

#include <stdbool.h> /* FYI: available for over 12 years */

bool djq7egc;
.
.
.
if (djq7egc == true)
{
    ...
}

Here we have a bool value, being tested against a constant bool value.

You could justify this on the grounds that it isn’t clear from djq7egc‘s name that it is bool, and that testing it against a bool makes this more clear, especially if it is crusty old C and djq7egc is actually declared as an int.  I do not find this argument compelling, but it is an very good argument to rename djq7egc to something less cryptic.

This C code has a bigger problem.  In C, any non-zero value is “true”.  To be semantically correct, the test should have been written as

if (djq7egc != false)

but then you have a double negative, and the readers’ brains start to melt and run out their ears.

So, what would I recommend to fix this code?  Rename the variable.  For example, perhaps this was an indicator that parsing a file found one or more errors:

#include <stdbool.h>

bool there_were_errors;
.
.
if (there_were_errors)
{
    exit(EXIT_FAILURE);
}

By the correct choice of variable name, the natural usage results in very readable code.  The places that have to say

there_were_errors = true;

are also reasonably natural sentences, and easily grokked by the reader.

There is another case worth mentioning, and it smacks into double negative territory again:

if (djq7egc == false)
{
    ...
}

or worse (because it probably gets the semantics wrong):

if (djq7egc != true)
{
    ...
}

These code fragments are easy to mis-read in a code review.  They are a ! operator (logical not) in disguise.  Both are (intended to be) equivalent to

if (!djq7egc)
{
    ...
}

In this instance, the fix from before may not yield the best possible reading

#include <stdbool.h>

bool there_were_errors;
.
.
if (!there_were_errors)
{
    party_party_party();
}

In this case, choosing a variable name that reads well if the code is read as “if not something” where something is usually an adjective.  If the scope is fairly tight, something like this may do the trick:

#include <stdbool.h>

bool ok = true;
.
.
if (!ok)
{
    see_a_doctor();
}

There are instances where the ! operator is a useful C and C++ idiom: when talking about pointers.  Testing pointers against NULL can sometimes take you back into double negative territory, and the judicious use of ! can often read well, even though it isn’t perfect English:

for (T *p = head; p; p = p->next)
{
    ...
}

can also be written as

for (T *p = head; ; p = p->next)
{
    ...
    if (!p)
        break;
    ...
}

This form of loop can be useful if you have something to do in the loop before the decision to terminate.  And, yes, the above is standard conforming usage, even on a system where the NULL pointer is not all-bits-zero.

I will give one final example of boolean-to-boolean comparison that I do accept, and I most commonly see it with memory allocation, although it also occurs in other settings:

size_t array_size;
void *array;
.
.
.
assert(!array_size == !array);

The ! operator here effectively turns dissimilar left and right types into similar ones, and then tests that the values agree.  The assertion then says “if the array has been allocated it has a size, but if it hasn’t been allocated it doesn’t have a size”.

assert((array_size == 0 && array == NULL) ||
       (array_size != 0 && array != NULL));

The version using ! is much easier to write, and the code reviewers doesn’t have to do de Morgan’s laws in their heads to see if the code author forgot an included middle somewhere.

The usage of bool in C++ is similar, but now you have the additional possibility of poor choice of method names:

if (object->shbgxebf())
    frob(rusty);

Again, the correct choice of method name can yield quite readable text:

if (object->is_dead())
    delete object;

This, of course, assumes that the “object” variable’s name was also chosen to produce readable code.

My previous blog post spoke about not second-guessing the compiler and other facilities provided by the system, such as the C Standard library. Prompted, in part, by a real-world example: see if you can spot the bug in the following code…

void *
memmove(const void *src, void *dst, uint32_t len)
{
    const uint8_t *s = (const uint8_t *)src;
    uint8_t *d = (uint8_t *)dst;
    const uint8_t *e = s + len;
    /* (s == d) could go either way */
    if (s < d && d < e)
    {
        d += len;
        s += len;
        while (len--)
            *--d = *--s;
    }
    else
    {
        while (len--)
            *d++ = *s++;
    }
    return dst;
}

Actually, it was a trick question: there are at least 3 bugs in the above code.

1: The first bug, and most egregious, is the first and second arguments: they are reversed.  Anyone linking against this land-mine is going to get their foot blown off, real soon now.

Even if you disagree with the standard about the order of the arguments, and it is easy to see how some one could, do not mess with stuff that will be used internally by numerous libraries, including the uses made of it by what little of the compiler’s libc you are actually using.

Coders, not unreasonably, expect standard conforming behavior from functions defined by the C Standard.

2: The second bug is that the third argument should be size_t, because size_t is not always the same as uint32_t, just think of 64-bit machines (or, 32-bit machines with address spaces of more than 32 bits, like some 40-bit SoC chips).

Fortunately, modern versions of gcc are going to catch the mismatch between the prototype and the definition.  Assuming, of course, the the compiler’s standard conforming <string.h> is being used, and not some home-grown brain-damage.

Coders, not unreasonably, expect standard conforming behavior from functions defined by the C Standard.

3: The third bug is that the sizeof operator returns multiples of char, with the standard guaranteeing only that sizeof(char) == 1.  Look in <limits.h> for the CHAR_BIT symbol definition, it exists for a reason.  When the C standard was first written, 36-bit machines were still in active use; those machines had a 9-bit char type.  No matter how insane or outdated you think the concept is, the function above should not be using uint8_t, is should be using one of the char types.

In addition, if the machine has no integer type of exactly 8 bits, the standard requires that the uint8_t type not be declared by <stdint.h> at all. So the above code will simply fail to compile on such a machine.  Of course, such a machine could be seen as an anachronism, surely no modern machine would have a non-power-of-2 register size?  Well then, consider the case of a machine with 256-bit long long, 128-bit long, 64-bit int, 32-bit short and 16-bit char.  Again, uint8_t would not be declared by the <stdint.h> header.

The correct way to determine the availability of uint8_t at compile time is the presence or absence of the UINT8_MAX preprocessor symbol.

#include <stdint.h>
#ifndef UINT8_MAX
#error "this code is not that portable"
#endif

See also uint8_least_t for a type with at least 8 bits, but not guaranteed exactly 8 bits; it would be defined for both the 36-bit example and also the 256-bit example.

Many years ago, when my pet dinosaur was still alive, I recall the painful transition from C on 16-bit machines, to C on 32-bit machines.  Many lessons from that era were incorporated into the the C89 standard, which happened in almost the same time frame.

Years later, and some folks are once again struggling, this time with the 32-bit to 64-bit transition.  This time, the C standard got there ahead of you, and has a nifty <stdint.h> include file, and a whole bunch of useful standard types.

The embedded code base I am currently working with is riddled with 32-bit assumptions.  First, they decided to define their own <wrong_types.h> (names changed to protect the guilty) with, you guessed it, typedefs and/or #defines for a whole bunch of symbols very nearly identical to the standard types in <stddef.h>, <stdint.h> and <stdbool.h>.  And, in some cases, with incorrect implementations of standard types.  Of course, compiling this code with a native 64-bit compiler, rather than the 32-bit cross compiler, has excrement exploding in all directions.

This article contains several portability lessons that folks seem to have forgotten (or, probably, are too young to have ever learned).

Lesson 0:

Why am I compiling it native when it is embedded code?  Test Driven Development (TDD).  It will save your sanity.

With a native build of (most of) the embedded code, I can put automated tests into the build system, for anything that I can run without having to be on the target, such as (I kid you not) the BCD arithmetic library.  The code download takes ~8 minutes, so running all those tests as part of the build is way faster at spotting regressions.  Also, my desktop build host is an order of magnitude faster than the target, and quad core.

Lesson 1:

Do not create a file called <wrong_types.h> and try to second-guess the C compiler.  You will always and forever be wrong, plus your code is not reusable if you do this.  This is a non-portable highway straight to hell.  Always have a second system for building embedded code, each with different numbers of bits (e.g. 32-bit embedded target and 64-bit build host).  That way assumptions will explode at compile time or automated test time, not in front of a customer.  If you can arrange things so that the two systems you are testing on also have different endian-ness, that’s also good for exposing assumptions.

The idea is for the code to compile correctly on both platforms, with no code changes required. Zero edits.  Build both, every day, with your Continuous Integration (CI) build server.  It is possible, but you have to use the types the compiler provides to tell you how big everything is.

Use <stddef.h>, <stdint.h> and <stdbool.h> instead of your own types header file.  They are standards compliant, portable, and the standard’s authors have thought more deeply about the semantics than you have.  Never heard of them?  Find a copy of the standard and read it, now.  Google for “ansi-c 2011 n1570 pdf”, it should be on the first page.

Oh, and don’t replace libc.a with your own implementation, either.  The stuff in the libc.a provided by the compiler vendor is probably way better than yours, and will also be standards compliant.  (Did you know strcmp is required by the standard to use unsigned chars for the comparison?  Didn’t think so.)  Don’t replace libgcc.a with your own implementation, either.  When (not if) the compiler is upgraded, you don’t want all the bug fixes and security fixes in their libc.a and libgcc.a to pass you by.

Lesson 2:

Always, always, always compile with at least -Werror -Wall -Wextra, and then fix all the problems revealed.  If they aren’t bugs now, they will be when the clueless maintenance guys get done with it.  (Marooned on a proprietary compiler?  Just use GCC in parallel, it’s free.)

Don’t just add more casts to make the warnings go away.  Actually think about what the compiler is telling you, and then fix the underlying flaw in how you are doing things. The third and fourth lessons are some specific instances of this.

“But they’re just warnings.”  Bzzt, wrong.  Spot the defect in the following code:

(volatile long)x = bigness;

Gcc has been warning about this for almost 20 years.  As of Gcc 4.4, this is now a fatal error, and about time, too.  Still can’t figure it out?  The C standard (since 1989, 22+ years ago) says that the output of a cast is never an lvalue (“What’s an lvalue?”  An expression that may appear on the left of an assignment, a subset of all the possible expressions that can appear on the right hand side).  The code should read

*(volatile long *)&x = bigness;

Even this re-written version probably still contains a design flaw. Unless you are talking to a device register, and even then it is questionable.

Lesson 3:

You can’t fit a pointer into a long.

void *p = blah;
long fake_ptr = (long)p;

Use intptr_t or uintptr_t for this job.  Better yet, ask yourself why you are pushing an integer type around, not a pointer type.  This often reveals design flaws, dinosaur sized ones.  BTW, using casts to make the compiler shut up, like this…

void *p = blah;
long fake_ptr = (long)(intptr_t)p;

simply obfuscates the bug.  The compiler is trying to tell you that your conversion will, one day, if not already, lose bits of representation.  When you

p = (void *)fake_ptr;

the pointer that went in isn’t guaranteed to be the pointer that comes out.  “But this will only ever be used on a 32-bit machine.”  Bzzzt, wrong.  I’m still scraping excrement off the walls.

Lesson 4:

You can’t fit what sizeof returns into an int

int len = sizeof(something);

use size_t for this job.  It isn’t guaranteed to fit into a long, either.  And, just to be clear, size_t is guaranteed to be unsigned. Use ssize_t (POSIX) or ptrdiff_t (ANSI C) for the signed variety, although any modern version of GCC is going to give zillions of signed-vs-unsigned warnings, and for good reason: the type promotion rules around these cases are almost certainly not what you think they are.

“What do I care?  Anyone declaring a 2GB object is an idiot.”  Bzzzt, wrong.  Try writing a malloc implementation one day.  Or, worse, reading one that assumes int32_t is big enough to hold the size of the malloc arena without losing address bits and without going negative.

Lesson 5:

(I can’t believe this one is still with us.)  Do not use sprintf or vsprintf, ever, for anything.  Always, always, always use snprintf or vsnprintf.  This usually means fixing all of your APIs so that whenever a string/buffer pointer argument is passed, it is immediately followed by a size_t argument that is the size of the aforementioned string/buffer.  (If your compiler vendor is 22 years late in providing a standards compliant snprintf function, upgrade; to Linux if necessary, it’s free.)

Also, if you are tempted to write your own strncpy that doesn’t have the ugly strncpy semantics (look it up), don’t.  Use snprintf instead (take your time, think it through, it wasn’t obvious to me, either).

Lesson 6:

Use “man gcc” and read what -Wshadow does.  Then turn it on.  And then, for any significantly old’n‘large code base, be horrified at what it tells you.  The -Werror option is your friend.

Here endeth the lesson.  (For today, anyway.)

My latest adventure into Gtkmm-3, http://canola.sourceforge.net/, left me wanting to animate a series of images, and I wanted to use a transparent borderless transient window, and move the images around within it.

Strangely, this proved to be in the “far too hard” category.  First, you need a compositing window manager.  Second, you have to ignore all of the Gnome-2 answers on the Internet.

First: A compositing window manager.  I’ve been using Ubuntu Oneiric since November, but with Gnome Classic installed.  I thought I’d opted for the special effects, but no.  The instructions for turning on Compiz are mostly OK, except for the annoying default (set by the Ubuntu folks) of Compiz having that useless Unity icon box thing on the left hand side of the screen.  Edit
.config/compiz-1/compizconfig/config to say

[gnome_session]
profile =

Second: Gnome-3 isn’t Gnome-2.

The Internet has many places that describe hacks to goose Gtk+ into having a transparent window background, with opaque widgets, but none of them work on Gmome-3, usually because the named functiosn no longer exist.

{{ I should mention, the code that follows is in a class derived from Gtk::Window, which is why there are calls like get_screen() that wraps the gtk_widget_get_screen but appear to be missing an argument, the implicit C++ this pointer. }}

The first thing I tried was Gtk::Window::set_opacity(0.).  The entire window disappears, widgets and all.  This method makes the window and its contents transparent, rather than just the window background.

A bunch of places say to use

set_rgb_colormap(get_rgba_colormap());

except that these don’t exist in Gtkmm-3.  What is needed is to set the visual, which actually makes more sense:

Glib::RefPtr<Gdk::Visual> vp = get_screen()->get_rgba_visual();
if (vp)
{
gtk_widget_set_visual(Gtk::Widget::gobj(), vp->gobj());
}

Hmmm, a naked gtk_ call, but necessary because Gtkmm has not wrapped the necessary Gtk+ function.  How exactly this helps is that you can now set the background to transparent:

Gdk::RGBA sep;
sep.set_rgba(1., 1., 1., 0.);
get_window()->set_background(sep);

This fragment of Gtkmm code sets the Gdk window’s background.  It isn’t the same as Gtk::Winow’s background (an abstraction I have only begun to start  to fathom).  But you can’t do this until the window has been realised (the first show() call), or get_window() will return the NULL pointer.

But wait, there’s more!  The above is not sufficient, and you still get an opaque white window background.  The magic call is this one:

set_app_paintable(true);

and you do this before setting the background color.  This tells Gtk+ not to paint the window background itself, meaning that it will leave alone our setting of the transparent window background.

Success: a window with a transparent background and opaque widgets moving around inside it.

Note that there is a race: depending on where the code executes during the screen refresh cycle, there is a risk that the user will see a flicker as the window is shown opaque, and then becomes transparent.  I minimsed this by not showing any of the child widgets, then set the background, then show the child widgets.