Robust C Code Part 3 – Wrapping C

In the last segment in this series “Robust C Code Part 2 – Advanced C Preprocessor” I talked about the preprocessor concatenation directive.  In this segment I will talk about using the preprocessor to wrap C code, and what an L-value is. Now this is getting a little technical, so you might want to brush up on C.

The macros I defined in parts 1 and 2 of the series are rather simple. Many times I want to wrap multiple C statements in a macro and use them just as a regular statements.  This seems rather straight forward we could do the following

#define setup_some_hardware()            hw_register1=0x12;hw_register2=0x34;hw_register3=0x56

This will work most of the time since the statements are executed one after another, however this is dangerous because the statements are not grouped in the same scope.  You can think of scope as groups of variables that can ‘see’ each other.  If you have 2 functions, one with ‘int x’ inside and one with ‘int y’ inside, the variables can not ‘see’ each other since they are are in different functions, which means you can’t do x=y; they exist in different scope. A new scope can be created with curly braces {}, which means loops, if statement  and functions all have their own scope.  The three statements in the previous macro can exist in different scopes like in this example:

// Check the hardware and enabled if off
if(HWREGISTER.ON == false)
setup_some_hardware();

An if() statement without curly braces {} will execute the single next statement if the condition is true.  This causes a problem because the preprocessor expands the macro to:

// Check the hardware and enabled if off
if(HWREGISTER.ON == false)
hw_register1=0x12;hw_register2=0x34;hw_register3=0x56

This results in hw_register2 and hw_register3 ALWAYS being set and only hw_register1 affected by the if() statement.  In C you can’t have semicolons in parentheses, so what do you do to group the statements? One solution is to add curly braces {} to macros that don’t return a value so all statements are in the same scope. This seems logical however in C you can’t have a semicolon after a brace which means you have some statements with semicolons and some without, which can lead to some really hard to find bugs.

The solution for this problem is to wrap the multiple statements in do{ }while(0). If you took CS101, the do{}while() loop will always allow one execution before evaluating the condition in the while(). Since while(0) is always false any good ANSI C preprocessor will remove the do{}while(0) and only execute the code once. Since the loop uses curly braces to create a new scope, all statements are in the same scope and a semicolon can be used on the statement.

#define setup_some_hardware()            do{hw_register1=0x12;hw_register2=0x34;hw_register3=0x56;}while(0)

// Check the hardware and enabled if off
if(HWREGISTER.ON == false)
setup_some_hardware();

An additional benefit of the scope created by the do{ }while(0) is that new variables can be created in the new scope.

#define swap_int(val1,val2)              do{int tmp; tmp=val1; val1=val2; val2=tmp;}while(0)

if(some_condition)
swap_int(x,y);

A little known/understood element in C is the L-value. L-values can be though of as the value returned from the right side of a C statement to the left side of the statement. a do{ }while() loop has no L-value and will result in a compiler error if an L-value is expected, so any statement that returns a value should NOT use do{ }while(0) wrapping. A good rule of thumb is if the statement returns a value use parathenses, if it doesn’t, use do{ }while(0).

The following is an excerpt from a UART C header which uses the preprocessor to give more developer friendly names to sequences of statements and convoluted register names:

#define uart1_interrupt_rx_enable()      do{IEC0bits.U1RXIE = 1;}while(0)
#define uart1_interrupt_rx_disable()     do{IEC0bits.U1RXIE = 0;}while(0)
#define uart1_interrupt_rx_clear()         do{IFS0bits.U1RXIF = 0;}while(0)
#define uart1_interrupt_rx_set()             do{IFS0bits.U1RXIF = 1;}while(0)
#define uart1_interrupt_tx_enable()      do{IEC0bits.U1TXIE = 1;}while(0)
#define uart1_interrupt_tx_disable()     do{IEC0bits.U1TXIE = 0;}while(0)

#define uart1_tx_buffer_full()              (U1STAbits.UTXBF == 1)
#define uart1_tx_last_done()               (U1STAbits.TRMT==1)
#define uart1_rx_overrun_get()           (U1STAbits.OERR)

#define uart1_reset()             do{U1MODE = 0;U1STA = 0;}while(0)
#define uart1_enable()         do{U1MODEbits.UARTEN = 1;}while(0)

All the preprocessor macros that I have shown will compile down into “in line” instructions.  This speeds up execution compared to functions since the processor doesn’t have to create a stack frame and branch to another location in code just to do a simple bit set. The one downside is highly used macros with multiple statements will be injected into the source each time they are used, which can lead to larger code.  I try and keep preprocessor macros short and simple to reduce this.

Robust C Code Part 2 – Advanced C Preprecessor

I my last post ‘Robust C Code Part 1 – C Preprocessor‘ I talked about the C preprocessor and how it can be used to hide registers from the user without adding code space for lots of functions.  In this post I will talk a little more about the preprocessor and some of the more advanced features.

The C preprocessor also takes arguments, just like functions. Take a look at this example

#define days_in_years(value)        (365*value)

int x,y,x;
x = days_in_years(1);
y = days_in_years(10);
z = days_in_years(65);

This code works similar to the code in the first post, it replaces days_in_years(value) with (365*value), the text ‘value’ is replaced with the argument to result in (365*1), (365*10) and (365*65). The C preprocessor isn’t just a copy and paste tool for strings of text, in addition to direct replacement of text the preprocessor allows concatenation of strings using the ‘##’ directive.  Take the following example:

// Allow PortA, pin 1 to be accessed with led1() macro
#define led1(func)  porta_pin_1_##func

// PIC24 PortA pin 1 register macros
#define porta_pin_1_output()               (TRISAbits.TRISA1 = 0)
#define porta_pin_1_input()                (TRISAbits.TRISA1 = 1)
#define porta_pin_1_high()                 (LATAbits.LATA1 = 1)
#define porta_pin_1_low()                   (LATAbits.LATA1 = 0)

This example uses the same port macros as part 1 of this series.  The new line is how to hide register access and name pins in a more developer friendly way.  Read over the next part a few times, I will take it one step at a time.

First the ‘##’ in the macro is the concatenation directive for the preprocessor, it says we should take the argument ‘func’ and replace ‘##func’ with whatever we passed in.  Lets say we have the following in our C code:

led1(somejunktext);

This would replace ‘##func’ in the macro with ‘somejunktext’ and concatenate the text string ‘porta_pin_1_’ with ‘somejunktext’ to make a new sequence of text:

porta_pin_1_somejunktext;

Now, this result is very similar to the format of the pin macros we have listed above, but instead of ‘somejunktext’ the ‘porta_pin_1_’ is followed by ‘output()’, ‘input()’, ‘high()’ and ‘low()’.  Because the preprocessor does direct text replacement you can have these strings of characters as arguments:

led1(output());
led1(high());

This results in:

porta_pin_1_output();
porta_pin_1_high();

Which turns into:

TRISAbits.TRISA1 = 0;
LATAbits.LATA1 = 1;

The really nice thing about using preprocessor string concatenation  is you can switch all references to a pin very quickly with just changing the directive:

// Allow PortA, pin 1 to be accesses with led1() macro (Not used)
//#define led1(func)  porta_pin_1_##
// Allow PortA, pin 4 to be accesses with led1() macro (Now this is on pin 4 and all the code still works)
#define led1(func)  porta_pin_4_##

Now, to really blow your mind, you can use multiple concatenation operators in a single macro, which can allow for lots of macros without the code space required for a function:

#define porta_pin_high(pinnum)       porta_pin_##pinnum##_high()
#define porta_pin_low(pinnum)         porta_pin_##pinnum##_low()

porta_pin_high(1);
porta_pin_high(2);
porta_pin_low(3);
porta_pin_low(4);
porta_pin_high(5);

Multiple concatenation makes the set function I mentioned in part 1 of the series really easy:

#define pin_output(portname,pinnum)       ##portname##_pin_##pinnum##_output()

pin_output(porta,1);
pin_output(portb,2);
pin_output(portb,7);

Take a look at this example of a header file for the PIC24 microcontroller for an idea of what can be done with this technique.

Robust C Code Part 1 – C Preprocessor

For years I tried to write C code for microcontrollers that was robust, modular, and reusable  with limited success.  It always seemed that there was some requirement that caused a module to become dedicated to a specific piece of hardware or switching to another processor caused hours of reworking register bits.  Over the last few years I was exposed to some really cool ways to make C code more robust and flexible which allows code reuse and reduces fat-finger errors of setting the wrong bits.  I wanted to create a series of posts on this and one of the first places to start is using the C preprocessor to make accessing hardware more user friendly.

Microcontroller development differs from operating system development in C in many ways, one of which is accessing hardware directly from the C language. Each microcontroller has special hardware that interfaces with the real world, for example a general purpose IO pin is used to interact with the real world using logic signals (high and low). Accessing the port pins differs wildly from processor to processor, to access the PortA pin 1 of a Microchip PIC24 chip in C would look something like this:

// Make PortA pin 1 an output
TRISAbits.TRISA1 = 0;
// Make PortA pin 1 a high value
LATAbits.LATA1 = 1;

This can look a little confusing to some, it would be much easier if there was a function that the developer could call, for example pin_output(porta,1), which would do this for you.  Now you could make a function that does that, however since microcontrollers usually have limited FLASH and RAM, making functions for each register and bit can get out of hand quickly.  The solution is the C preprocessor. The preprocessor uses ‘directives‘ which are like instructions that get run before the compiler. Some directive examples are #define, #include, and #pragma. The #define directive replaces sequences of text in C sources.  If you have ever wrote basic C the following macro will look familiar:

#define DAYS_IN_A_YEAR    365

The C preprocessor searches for the sequence of characters DAYS_IN_A_YEAR in the C source and replaces it with the numbers 365.  No checking is done, so having “#define bit 44” would replace the characters ‘bit’ with 44, which can result in the previous example turning into:

// Make PortA pin 1 an output
TRISA44s.TRISA1 = 0;
// Make PortA pin 1 a high value
LATA44s.LATA1 = 1;

Since there is no TRIS44 register in the PIC24, this won’t compile.  However you can use the direct replacement of the preprocessor to make setting bits very easy to remember and look like functions.  Take the following preprocessor #define directive for example

#define days_in_a_year()    (365)

This replaces days_in_a year() with the characters (365).  This is called a macro. Now you can have some C code that does the following

int x;
x = days_in_a_year();

days_in_a_year() is a macro, not a function, it looks like one, but when the C preprocessor runs you get the following:

int x;
x = (365);

No function code is developed and the code will (most likely) compile to a single instruction or two, to move the value 365 into the variable x. The same ‘function’ trick can be done with the port pin assignment mentioned above.  Take a look at these preprocessor directives

// PIC24 PortA pin 1 register macros
#define porta_pin_1_output()               (TRISAbits.TRISA1 = 0)
#define porta_pin_1_input()                (TRISAbits.TRISA1 = 1)
#define porta_pin_1_high()                 (LATAbits.LATA1 = 1)
#define porta_pin_1_low()                   (LATAbits.LATA1 = 0)

// Make PortA pin 1 an output
porta_pin_1_output();
// Make PortA pin 1 a high value
porta_pin_1_high();

If you put the directives in a header file and include it in your code, you will never have to set a bit register again.  Also, if you move processors, lets say to an Atmel Atmega, you can change the preprocessor directives and all the code is changed automatically:

// Atmel Atmega PortA pin 1 register macros
#define porta_pin_1_output()               (DDRA.1 = 1)
#define porta_pin_1_input()                (DDRA.1 = 0)
#define porta_pin_1_high()                 (PORTA.1 = 1)
#define porta_pin_1_low()                   (PORTA.1 = 0)

// Make PortA pin 1 an output
porta_pin_1_output();
// Make PortA pin 1 a high value
porta_pin_1_high();

That’s it for this post, there is MUCH more you can do with C and the preprocessor, so check back for some more posts in the series.