DEV Community: Steffen Ronalter

Embedded Programming: Loose Coupling Best Practices

Steffen Ronalter — Wed, 20 Mar 2019 08:19:34 +0000

When creating Embedded Software, system complexity that grows over lifetime makes it increasingly harder to reason about certain behaviors of the program.
As always in engineering, it helps to divide one big problem into several smaller problems in order to be able to eventually solve it. This is what this article is all about.

Note: This post has originally been published on deardevices.com.

In his book Working Effectively with Legacy Code, Michael Feathers introduces the idea of a seam as:

a place where you can alter behavior in your program without editing in that place.

Although originally intended as a means for getting legacy code under test, we will use this idea as a guide for designing software in the first place. This is a key aspect of loose coupling, after all: the ability to make changes in units of production code without changing the units themselves.

Before diving into the details, let's talk about units first.

Units and their Dependencies

Let's say you are about to start a new embedded project.

You may not even think about designing a system separated into different units at all -- and that's perfectly fine. When building prototypes, we want to see whether something is working, especially whether our software plays well together with the hardware.

In that phase of a project, it's probably not that important to make a distinction between different units at all. Everything may be coupled very tightly, maybe even within just a single unit or module (Forgive me that I use the terms unit and module interchangeably in here).

As the project grows, it becomes more and more complex, and we usually want to do something about that to stay in control. What we can do is split up the code and put it into different compilation units (i.e. .c/.cpp files) to reach some kind of logical separation.

These logically separated pieces of code we will call unit for the rest of this article.

Let's imagine a project about:

Measuring a voltage level using an ADC,
Averaging that number over time and
Showing the result on an LCD.

Additionally, via the serial port, the user should be able to:

See the averaged number every few seconds and
Start and stop the sampling process by issuing a command.

From that description, we can divide the system into four units: ADC, AverageFilter, Display, and Serial. The following diagram shows some dependencies between these units based on how they would probably communicate with each other. Does this make sense?

You can see from the diagram that all of these units are coupled somehow. An arrow here reads as depends on or includes a header file. AverageFilter depends on Serial because it calls its print() function.

Loosen the Coupling

At some point, we might want to replace one or more units by a different implementation -- without any impact on the rest of the system.
And without any impact here even means: without changing any of the other unit's code. There are various reasons you might want to do that. For example:

Switch averaging filters at runtime, depending on user configuration
Swap the serial interface between RS232 and USB, depending on build parameters
Replace the display unit by some stub in the test build

And here comes the tricky part: you cannot simply remove or replace units that are pointed to by a dependency. To make this possible, we need to decouple units from each other.

As the post title suggests, there are (at least) three ways to realize this in C and C++. We are going to take a look at each of them in the sections below.

Best Practice #1: Decoupling At the Object Level

This method is the most flexible one. At runtime, you pass a dependency into a unit. In C++, you would create an interface (an abstract base class) and let the unit implement it. Something similar can be done in C, by letting the unit depend on a set of function pointers.

The following snippet shows a C++ example for breaking up the tight coupling of the AverageFilter to the ADC unit:

class FilterInterface {
public:
  virtual ~FilterInterface() {}
  virtual void reset() = 0;
  virtual void update(uint8_t) = 0;
};

class AverageFilter : public FilterInterface {
public:
  void reset() override {
  }

  void update(uint8_t) override {
  }
};

class ADC {
public:
  ADC(FilterInterface& interface) : interface(interface) {
    interface.reset();
  }

  void process(void) {
    interface.update(42);
  }

private:
  FilterInterface& interface;
};

[...]

int main(void) {
  AverageFilter filter;
  ADC adc(filter);

  while(1) {
    adc.process();
  }
}

The class ADC depends on the interface of type FilterInterface and stores a reference to it. Thereby it is agnostic to the concrete implementation passed in.

In C, we don't have the concept of polymorphism (which is the mechanism that makes it possible to use concrete implementations transparently through base class pointers). You can always emulate it using function pointers, though:

typedef struct {
  void (*reset)(void);
  void (*update)(uint8_t);
} FilterInterface;

static FilterInterface interface_;

void ADC_init(FilterInterface interface) {
  interface_ = interface;
  interface.reset();
}

void ADC_process(void) {
  interface_.update(42);
}

This tends to be a bit less explicit and more error-prone than the C++ implementation. It might still be worth it (and people actually do it: systemd, Linux drivers).

This solution, no matter if implemented in C or C++, comes with a runtime cost while giving you the freedom of modifying dependencies at runtime as well.

Best Practice #2: Decoupling At the Link Level

In the next step we are going to explore another method. This will be based on yet another stage of the software build process -- the linking.

Let's see what Michael Feathers has to say about Link seams:

In many language systems, compilation isn’t the last step of the build process. The compiler produces an intermediate representation of the code, and that representation contains calls to code in other files. Linkers combine these representations. They resolve each of the calls so that you can have a complete program at runtime.

Linking Overview

Here, Feathers does a great job describing how the linking works. For C and C++, this is enough to know for now.

You can see a flowchart of the process below. Each .c file is compiled individually as a compilation unit. This means the compiler outputs a .o object file for each of them:

All object files are then passed on to the linker whose job is to put everything together -- in order to get an executable program:

One important part of linking is to look for unresolved symbols needed by objects (function names, for example) and to try to satisfy those using symbols exported by other objects.

Exploiting the Linking Process

As described by Feathers, we may exploit this process by offering different sets of symbols, based on what our build configuration looks like.

Let's take a look at this Makefile snippet to get the idea:

release.elf:
  gcc driver_release.o production.o -o release.elf

test.elf
  gcc driver_test.o production.o -o test.elf

There are two different targets, one for each build configuration we wish to maintain:

release: results in a shippable executable.
test: contains debug code for testing that should never go out to the customer.

As shown in the diagram below, to build each of the two ELF executables we pass the exact same object file production.o to the linker in either case.

The linker now strives to find matches for symbols demanded by production.o. For that, it happily considers any object file it is offered. Assuming driver_release.o and driver_test.o adhere to the same API convention, the linker doesn't see the difference and builds two different configurations for us.

The fact that we were able to switch implementations, depending on the build configuration suggests some level of decoupling between the units used in the example above.

This decoupling method has no runtime cost at all, which comes at the price of decreased flexibility compared to the previous approach. To switch over to a different configuration, you will at least need to re-run the linker. You do not need to recompile your objects though -- This may improve build time significantly, depending on the size of your project.

Speaking about runtime cost: there might be some kind of indirect runtime cost for this solution. Because functions are implemented within different compile units, the compiler doesn't have the big picture that would be useful for optimization. This might be compensated by Link Time Optimization (LTO) though.

Best Practice #3: Decoupling At the Preprocessing Level

After talking about decoupling units at the linker level, this section is going to be about achieving the same goal, but at the preprocessing stage of the build process. At the end of the article, you will find a comparison of all three methods.

Let's start with another quote from Michael Feathers. In Working Effectively with Legacy Code, he tells us about yet another type of seams:

Only a couple of languages have a build stage before compilation. C and C++ are the most common of them. [...] I’m actually glad that C and C++ have a preprocessor because the preprocessor gives us more seams.

That stage before compilation, the preprocessing, is what we interested in during the course of this article.

How to get from `.c` to `.o`

So, before passing source code on to the compiler, C and C++ employ a preprocessing stage. During this phase, the preprocessor fulfills some basic tasks -- with its output still being valid C or C++ code. This output is called preprocessed source code, according to the preprocessor docs of the GNU project.

The diagram below shows the two steps involved in converting a C source file into an object file: preprocessing and compiling.

Tip: To inspect the preprocessed source file, you can use gcc -E foo.c. This will skip the compile step and print the preprocessor result right to the terminal.

The Preprocessor Produces Units

For the matter of decoupling units, we may utilize the preprocessed source file.

In fact, there's another way to look at it: The preprocessor generates different instances of the same source file for each configuration we wish to have, before they are passed on to the compiler:

Having several instances is a great achievement already. To make each instance somewhat unique, we will now introduce parameters.
We may even, in Object-Oriented terms, think of source files as classes.
Each preprocessed file can then be modeled as an instance of that class, i.e. as an object.

Let's say we define a class SourceFile that has a config attribute. Then, the preprocessed files can be modeled as objects of that type, parameterized by the specific value of the config attribute:

A Practical Example

In practice, there are no such classes of course. So let's see how you would do that in a Makefile:

CONFIG_PRODUCTION = 0
CONFIG_TEST = 1

driver.o: driver.c driver.h
  gcc -c driver.c -o driver.o

foo_production: foo.c driver.o
  gcc -DCONFIG=$(CONFIG_PRODUCTION) foo.c driver.o -o foo_production

foo_test: foo.c driver.o
  gcc -DCONFIG=$(CONFIG_TEST) foo.c driver.o -o foo_test

The first thing being built is the driver. It is the same for both configurations. For each of the build configurations, there is a corresponding foo_ target. You will notice that the same source file (foo.c) is used for both of these. This is intentional, as we
want the preprocessor to modify them right before compilation.

Here, the value of the config attribute (now the CONFIG macro) is determined by the -D flag passed to the compiler. You would then put some extra preprocessor statements into the code:

// foo.c

#include "driver.h"

#define CONFIG_PRODUCTION 0
#define CONFIG_TEST 1

int main(void) {
#if CONFIG == CONFIG_PRODUCTION
  driver_doA();
#elif CONFIG == CONFIG_TEST
  driver_doB();
#else
#error "Invalid CONFIG!"
#endif
}

That way, the preprocessor effectively switches between two code blocks, depending on how it is called by the Makefile.

Tip: Inspect the preprocessed files to watch how the code is actually swapped!

That's probably all we need in order to accomplish our goal: software units, decoupled from each other using the preprocessor.

This approach has the obvious drawback that your code gets cluttered with ifdefs. Compared to link time decoupling though, the compiler can probably do a better job optimizing, as you don't need to separate code into different compile units (c files) for this to work.

Tool Support

In my experience, tool support for both the link and preprocessor approach is somewhat better than for decoupling on the object level. Jumping to function definition as well as single stepping in the debugger works seamlessly without an indirection through function pointers. Also, code sections disabled by preprocessor macros are usually highlighted accordingly by IDEs.

Now that I'm thinking about it: Do you know of an IDE that supports following function pointers the way you want it? Do not hesitate to get in touch with me via Twitter!

No need to Re-build

Before doing a comparison of all three approaches, I would like to highlight one aspect of the link level method I think is really important:
This is the only approach that allows you to leave your object files untouched. That's really a great feature if you think about it: no need to re-compile anything when switching from testing to production. There is a perfectly clear separation of internal debugging code and code that's going to be shipped with the actual product.

Summary

To sum it up, here's a table of all pros and cons, at a glance.

	Object	Link	Preprocessor
Runtime Performance	- -	-	+
Tool Support	-	++	++
Runtime Flexibility	+	-	-
UML Modelling	++	+	-
Testability	++	++	++
Compile-Time Checking	+	++	++
Readability	+	++	-

These are mostly subjective metrics, of course. It depends on your project's requirements which method suits you best -- it may even be a combination of all three of them.

References

GNU Linker Manual

Fixing Typos while Writing -- Two Ideas

Steffen Ronalter — Sun, 23 Sep 2018 09:31:57 +0000

Here are some thoughts on text editing. No matter what kind of text you write -- source code, articles, to-do lists, books -- there's always a chance you get a single letter wrong at one point. Depending on your touch typing skills, this might not happen very often. But when it happens, what do you do?

Do you press and hold the backspace key until you get back to the typo?
Do you jump back to the bad letter, fix it like a surgeon¹ and continue writing?

My experience

Personally, I used to (rather unconsciously) adhere to the second approach. One day, however, I found out that even the Vim editor has support for deleting the last word before the cursor while typing in insert mode. This is not typical though. Usually, there are two steps involved: first, you use movement commands to get to the desired text position and then enter insert mode.

Although I'm a big fan of Vim's fantastic movement commands, this made me change my view to another perspective. What kind of habit would you develop if every typo was really easy to fix? Your brain may think something like: "It's not critical to get it right the first time -- it's not a big deal anyway". So there's no motivation for typing words correctly on the first attempt.

Better use the first approach?

To me, deleting the entire last word sounds a bit drastic at first. You did put some effort into writing it in the first place, did you? Nevertheless, I think the training effect might be worth it. So I will try it for some time and see whether there's a positive effect on my typing.

What do you think? Are there any scientific studies about this? I would love to know your opinion and personal experience.

To be complete: the Vim editor is by far not the only one to implement the delete last word feature.
You can use Ctrl-w on the terminal and inside Emacs. Many GUI applications support Ctrl-Backspace for doing the same.

This post has originally been published on steffen.ronalter.de

Example for Vim: Let's say you wrote 'house' instead of 'horse', you can do 'Furr' to fix that. ↩

From Subversion to Git: Snapshots

Steffen Ronalter — Sat, 23 Jun 2018 19:45:07 +0000

What does it mean that we talk about snapshots of our Git repository, while in Subversion we think in terms of file changes? For me at least, the key to understanding Git is that every commit is, in fact, a snapshot of the entire project. Not a list of patches. Not a difference to the previous commit. Just a snapshot of the whole thing.

Git snapshots everything, they said. Coming from Subversion, this is hard to believe. How would a version control system scale if it stored the entire project state again and again, with each and every commit?

First, let's do a little experiment on how one might approach version control intuitively, without considering neither Git nor Subversion.

Poor Man's Version Control

Let's say we have a project called myapp stored in a directory of that name. All it contains is a main.c file:

myapp
  main.c

Without version control, how would you track changes in order to be able to restore a particular state later? Easy enough, you might say: Just create a copy of the entire myapp directory and call it something like myapp-<version>. After a while, you would end up with a bunch of backup directories:

myapp-01
  main.c
myapp-<...>
  main.c
myapp-<N>
  main.c

To step back to a previous state in history, you might go and replace the entire myapp directory by one of these snapshots created previously.

In order to avoid wasting space by keeping so much redundant information, you might consider putting everything into a gzipp'ed archive and deleting all the backup directories:

tar -cvzf myapp.tgz myapp-*
rm -r myapp-*

Interestingly, this naive approach is not completely different from the way Git actually works.

How Git does it

Every time you create a commit, Git takes the content of each added or modified file, compresses it and stores it in an internal object database together with a commit object that holds some meta information¹. This approach makes it easy to reason about, as it's no more difficult than what we've done in the simple attempt mentioned above.

You may realize a big drawback here though: Although individual file contents are compressed -- which is fine--, even small changes between commits will cause massive duplication inside the object database.

In Git, this scalability problem is simply ignored at the first stage and solved later on. In a process called packing, all the objects are delta compressed and moved into one or more packfiles. This is done on several occasions; you can enforce it using git gc --aggressive.

The drawing below shows a simplified illustration of the storage of compressed file content into blob objects as well as the packfile generation.

Conclusion

Even for everyday Git usage it is vitally important to understand a bit of its inner workings; it's good to see that the basic idea is not inherently complex but more or less identical with what we might come up with anyway.

This understanding gives us the power to get a grasp of all the more advanced features like branching, merging and rebasing.

This post has originally been published on steffen.ronalter.de

References

For all the details please refer to the section Git Objects of the excellent Pro Git book. ↩

DEV Community: Steffen Ronalter

Embedded Programming: Loose Coupling Best Practices

Units and their Dependencies

Loosen the Coupling

Best Practice #1: Decoupling At the Object Level

Best Practice #2: Decoupling At the Link Level

Linking Overview

Exploiting the Linking Process

Best Practice #3: Decoupling At the Preprocessing Level

How to get from .c to .o

The Preprocessor Produces Units

A Practical Example

Tool Support

No need to Re-build

Summary

References

Fixing Typos while Writing -- Two Ideas

My experience

Better use the first approach?

From Subversion to Git: Snapshots

Poor Man's Version Control

How Git does it

Conclusion

References

How to get from `.c` to `.o`