I was today years old when I learned something that modern C can do. Thank you, Bing Copilot, for offering this up and learnin’ me somethin’ new.

At my day job I am porting various WIZnet (and hardware TCP/IP ethernet chip) services over to a new circuit board. We are using the W5500 chip, and making use of the provided I/O library from WIZnet:

Wiznet/ioLibrary_Driver: ioLibrary_Driver can be used for the application design of WIZnet TCP/IP chips as W5500, W5300, W5200, W5100, W5100S, W6100, W6300.

For this project, I have gotten basic Ethernet TCP running, then moved on to port their HTTP server code, followed by their SNMP server. While I may have encountered SNMP during my 1990s employment at Microware when I taught an OS-9 networking course, I have not touched it since then so this was “all new” again to me.

Part of configuring SNMP was an array of structures like this:

dataEntryType snmpData[] =
{
    // System MIB
    // SysDescr Entry
    {
        8, {0x2b, 6, 1, 2, 1, 1, 1, 0},
        SNMPDTYPE_OCTET_STRING, 30, {"Description String"},
        NULL, NULL
        },
    // SysObjectID Entry
    {
        8, {0x2b, 6, 1, 2, 1, 1, 2, 0},
        SNMPDTYPE_OBJ_ID, 8, {"\x2b\x06\x01\x02\x01\x01\x02\x00"},
        NULL, NULL
        },

…and so on. You can find this file here:

ioLibrary_Driver/Internet/SNMP/snmp_custom.c at master · Wiznet/ioLibrary_Driver

When I got to the part where I was adding the ability to send an “SNMP trap” (kind of a push notification to a specific IP address), I saw that it would duplicate the values in this array:

void sendTrap_sysObjectID(void) {
    // Create a dataEntryType for sysObjectID
    dataEntryType sysObjectEntry = {
        8, {0x2b, 6, 1, 2, 1, 1, 2, 0},
        SNMPDTYPE_OBJ_ID, 8, {"\x2b\x06\x01\x02\x01\x01\x02\x00"},
        NULL, NULL
    };
    // Send the trap
    snmp_sendTrap( ...params...);
}

Above, the “sysObjectEntry” array is a duplicate of the entry in my definition table.

This would mean keeping two parts of the code in sync, which is a terrible idea since it creates extra places for error, and also doubles the work. The A.I. suggested using the entry in the array, like this:

snmp_sendTrap(
  managerIP,
  agentIP,
  (int8_t*)"public",
  snmpData[1], // SysObjectID or your custom OID
  6,           // enterpriseSpecific
  1,           // specific trap ID
  1,           // one variable binding
  snmpData[10].oid, SNMPDTYPE_INTEGER, (uint8_t[]){1}, 1 // HighTempState = 1
);

Using “snmpData[1]” is more better, since now I can just change the definition table instead of multiple places hard-coding that information.

BUT, how do I know which entry is [1] versus [7]? I’d have to ensure the table entries stayed in order, then I could use a #define as an index, like this example:

typedef struct
{
	int x,y,w,h;
} BoxStruct;
// Declare an array of boxes, the old fashioned way.
BoxStruct box[] = // Initialize four boxes
{
	{ 0, 0, 100, 10},
	{ 10, 10, 90, 10 },
	{ 20, 20, 80, 10 },
	{ 30, 30, 70, 10 }
};
// Declare an array of boxes, the new fangled way.
#define BOX1    0
#define BOX2    1
#define BOX3    2
#define BOX4    3

That would let me get the data for box[BOX1] or box[BOX4]. Easy.

But if this was a long list of entries, like my SNMP was, and later I added something in between, I’d have to update the array as well as make sure this #define table is updated. Again, more place for error and more work.

The first thought was to declare the array as fixed size and initialize it like this:

// Declare an array of boxes, the new fangled way.
#define BOX1    0
#define BOX2    1
#define BOX3    2
#define BOX4    3
#define BOX_MAX 4
BoxStruct box[BOX_MAX];
box[BOX1] = { 1,1,1,1 };
box[BOX2] = { 2,2,2,2 };
box[BOX3] = { 3,3,3,3 };
box[BOX4] = { 4,4,4,4 };

That makes it easy and obvious, BUT you cannot have those initializes with global variables. You can only initialize that way from a function. This is fine if you want to declare your global array, then initialize like…

void initBoxes (void)
{
    box[BOX1] = { 1,1,1,1 };
    box[BOX2] = { 2,2,2,2 };
    box[BOX3] = { 3,3,3,3 };
    box[BOX4] = { 4,4,4,4 };
}

And that is the approach I would probably take on my “C-like” embedded compilers that do not support all of modern C.

However, the A.I. showed me something I had not seen before. Initializing the array like this:

// Initialize by element number, in order.
BoxStruct box[BOX_MAX] =
{
	[BOX1] = { 0, 0, 100, 10},
	[BOX2] = { 10, 10, 90, 10 },
	[BOX3] = { 20, 20, 80, 10 },
	[BOX4] = { 30, 30, 70, 10 }
};

Huh? I did a quick check on the Online GDB compiler, and that was valid. It even lets you initialize out of order:

// Initialize by element number, out of order.
BoxStruct box[BOX_MAX] =
{
	[BOX3] = { 20, 20, 80, 10 },
	[BOX1] = { 0, 0, 100, 10},
	[BOX4] = { 30, 30, 70, 10 },
	[BOX2] = { 10, 10, 90, 10 }
};

By doing it that way, I could “see” the label match the data, regardless of whatever the number the label was set to. And, if I messed up the #defines later (duplicate value or whatever), a “good compiler” with warnings enabled should alert me of that (at least, GCC does).

For my specific use, this is a great solution, and it works in whatever compiler the Microchip MPLAB X IDE is using for PIC24 processors.

Here is my test code:

/******************************************************************************
Welcome to GDB Online.
GDB online is an online compiler and debugger tool for C, C++, Python, Java, PHP, Ruby, Perl,
C#, OCaml, VB, Swift, Pascal, Fortran, Haskell, Objective-C, Assembly, HTML, CSS, JS, SQLite, Prolog.
Code, Compile, Run and Debug online from anywhere in world.
*******************************************************************************/
#include <stdio.h>
/*---------------------------------------------------------------------------*/
// Typedef
/*---------------------------------------------------------------------------*/
typedef struct
{
	int x,y,w,h;
} BoxStruct;
/*---------------------------------------------------------------------------*/
// Globals
/*---------------------------------------------------------------------------*/
// Declare an array of boxes, the old fashioned way.
BoxStruct foo[] = // Initialize four boxes
{
	{ 0, 0, 100, 10},
	{ 10, 10, 90, 10 },
	{ 20, 20, 80, 10 },
	{ 30, 30, 70, 10 }
};
// Declare an array of boxes, the new fangled way.
#define BOX1    0
#define BOX2    1
#define BOX3    2
#define BOX4    3
#define BOX_MAX 4
// Initialize by element number, in order.
BoxStruct foo2[BOX_MAX] =
{
	[BOX1] = { 0, 0, 100, 10},
	[BOX2] = { 10, 10, 90, 10 },
	[BOX3] = { 20, 20, 80, 10 },
	[BOX4] = { 30, 30, 70, 10 }
};
// Initialize by element number, out of order.
BoxStruct foo3[BOX_MAX] =
{
	[BOX3] = { 20, 20, 80, 10 },
	[BOX1] = { 0, 0, 100, 10},
	[BOX4] = { 30, 30, 70, 10 },
	[BOX2] = { 10, 10, 90, 10 }
};
/*---------------------------------------------------------------------------*/
// Prototypes
/*---------------------------------------------------------------------------*/
void ShowBox (BoxStruct box);
/*---------------------------------------------------------------------------*/
// Functions
/*---------------------------------------------------------------------------*/
void ShowBox (BoxStruct box)
{
	printf ("x:%d y:%d w:%d h%d\r\n", box.x, box.y, box.w, box.h);
}
int main()
{
	printf ("---foo---\r\n");
	for (int idx=0; idx<4; idx++)
	{
		ShowBox (foo[idx]);
	}
	printf ("---foo2---\r\n");
	for (int idx=0; idx<4; idx++)
	{
		ShowBox (foo2[idx]);
	}
	printf ("---foo3---\r\n");
	for (int idx=0; idx<4; idx++)
	{
		ShowBox (foo3[idx]);
	}
	return 0;
}
/*---------------------------------------------------------------------------*/
// End of main.c

You can mess with it online here:

https://onlinegdb.com/G73hxWSQuN

I wonder what other stuff has been added to C over the years that I do not know about…

Until next time…

See Also: part 1 and part 2.

In the previous installment, I discussed how lazy I am and shared my general dislike of doing things manually when they can be automated.

So let’s automate…

If you program in C, you are likely familiar with using #define to set a value you can use elsewhere in the code:

#define NUMBER_OF_GUESSES 10

int answer = RandomNumber (100);
for (int try=1; try<=NUMBER_OF_GUESSES; try++)
{
    printf ("Try #%d of %d - guess a number from 1-100: ",
             try, NUMBER_OF_GUESSES);

    guess = InputNumber ();

    // ... logic continues ...
}

Now instead of updating multiple places in the file for the number of guesses, only the #define has to be changed. The #define has the advantage of not taking extra code or memory space like a variable would, which is important when you are working on embedded systems with 8K of RAM.

You probably have also seen #defines used for marking code to be included or not included in a program:

#define DEBUG_MODE

void Function ()
{
#if defined(DEBUG_MODE)
    printf ("Inside Function()\n");
#endif

    // ...logic continues...
}

WIth “#define DEBUG_MODE” there, the printf() will be included. Remove that #define (or comment it out) and it will not.

But #defines can also become macros with parameters, such as this:

#define SNOOZE(x) SleepMs(x*1000)

If you want to sleep for seconds, you could use a macro that turns into the call to the millisecond sleep with the passed-in value multiplied by 1000:

void Function ()
{
    printf ("Pausing for 5 seconds...\n");

    SNOOZE (5);

    // ...logic continues...
}

The C preprocessor will take that “5” and substitute where the “x” is in the replacement text, becoming:

void Function ()
{
    printf ("Pausing for 5 seconds...\n");

    SleepMs (5*1000);

    // ...logic continues...
}

Now if the code is ported to a system with a different sleep call, the #define can be changed to use whatever is available.

I’d expect anyone who has programmed in C has done one or all of these things.

But wait, there’s more!

But a macro does not have to be a simple number, string or function name. It can be a whole block of code that gets substituted. You can put in many lines, just by adding a “\” at the end of the line to continue parsing the next line after it:

#define DISPLAY_COUNTDOWN(x) \
    for (int idx=x; idx>=0; idx++) \
    { \
        printf ("%d...", idx); \
        sleep (1000); /* 1000ms, 1 second sleep */
    }

void Function ()
{
    printf ("Self-destruct activated...\n");

    DISPLAY_COUNTDOWN (10);

    // ...logic continues ...
}

And that would be processed to replace the “DISPLAY_COUNTDOWN(10)” with the C code in the #define:

void Function ()
{
    printf ("Self-destruct activated...\n");

    for (int idx=x; idx>=0; idx++) {         printf ("%d...", idx);         sleep (1000); /* 1000ms, 1 second sleep */     }

    // ...logic continues ...
}

Yeah, it would look ugly if you could see how the C preprocessor puts it in, but it builds and runs and you never see it (unless you specifically look at preprocessed output files).

But that is probably dumb. You should just make a “DisplayCountdown()” function and have it be more normal.

But wait, there’s less dumb…

But in the case of my panel functions, each one of them had a unique panel name and panel identifier, so using a function for them was not really possible. Each one had to be its own function since the functions contained the name of the panel (“PanelMainInit()”, “PanelMainTerm()”, etc.).

But a #define can do that…

#define GENERATE_PANEL_PROTOTYPES(panel_name) \
    int panel_name##Init (void); \
    int panel_name##GetHandle (void); \
    int panel_name##Display (void); \
    int panel_name##Hide (void); \
    int panel_name##Term (void);

The macro uses “panel_name” as the substitution “variable” passed in, and will place whatever text is there anywhere in the macro where “panel_main” appears. Since I wanted to pass in the filename (without extension) of the panel such as “PanelMain” or “PanelFaults”) and build a function name out of it, I use the ## concatenate feature that will glue the items before and after it together. That macro used like this:

GENERATE_PANEL_PROTOTYPES(PanelMain)

GENERATE_PANEL_PROTOTYPES(PanelFaults)

GENERATE_PANEL_PROTOTYPES(PanelAdmin)

…effectively generates the prototypes like this:

int PanelMainInit (void);
int PanelMainGetHandle (void);
int PanelMainDisplay (void);
int PanelMainHide (void);
int PanelMainTerm (void);

int PanelFaultsInit (void);
int PanelFaultsGetHandle (void);
int PanelFaultsDisplay (void);
int PanelFaultsHide (void);
int PanelFaultsTerm (void);

int PanelAdminInit (void);
int PanelAdminGetHandle (void);
int PanelAdminDisplay (void);
int PanelAdminHide (void);
int PanelAdminTerm (void);

…though it actually looks like one long run-one line for each one if you looked at the pre-processed C output, but the result is the same.

A similar macro could generate the actual functions:

#define STRINGIFY(x) #x
#define TOSTRING(x) STRINGIFY(x)

#define GENERATE_PANEL_FUNCTIONS(panelName, panelResourceID) \
    static int S_##panelName##Handle = 0; /* Zero is not a valid panel handle. */ \
    \
    int panelName##Init (void) \
    { \
        int panelHandle = 0; \
        if (S_##panelName##Handle <= 0) \
        { \
            panelHandle = LoadPanel (0, TOSTRING(panelName)".uir", panelResourceID); \
            if (panelHandle > 0) \
            { \
                S_##panelName##Handle = panelHandle; \
                \
                panelName##UserInit (panelHandle); \
            } \
        } \
        else \
        { \
            panelHandle = S_##panelName##Handle; \
        } \
        return panelHandle; \
    } \
    \
    int panelName##GetHandle (void) \
    { \
         return panelName##Init (); \
    } \
    \
    int panelName##Display (void) \
    { \
        int status = UIEHandleInvalid; \
        int panelHandle = panelName##Init (); \
        if (panelHandle > 0) \
        { \
            status = DisplayPanel (panelHandle); \
        } \
        return status; \
    } \
    \
    int panelName##Hide (void) \
    { \
        int status = UIEHandleInvalid; \
        if (S_##panelName##Handle > 0) \
        { \
            status = HidePanel (S_##panelName##Handle); \
        } \
        return status; \
    } \
    \
    /* Unload the panel, if valid. */ \
    int panelName##Term (void) \
    { \
        int status = UIEHandleInvalid; \
        if (S_##panelName##Handle > 0) \
        { \
            status = DiscardPanel (S_##panelName##Handle); \
            if (status == UIENoError) \
            { \
                S_##panelName##Handle = 0; \
            } \
        } \
        return status; \
    }

That macro would be used like this:

GENERATE_PANEL_FUNCTIONS(PanelMain, PANEL_MAIN)

GENERATE_PANEL_FUNCTIONS(PanelFaults, PANEL_FAULTS)

GENERATE_PANEL_FUNCTIONS(PanelAdmin, PANEL_ADMIN)

…and it would create a fully populated set of functions for those panels.

This allowed me to have a header file that had those macros, such as “PanelMacros.h”, and then have a .c and .h for each panel, or one big file that had them all in it.

// Panels.h
GENERATE_PANEL_PROTOTYPES(PanelMain);
GENERATE_PANEL_PROTOTYPES(PanelFaults);
GENERATE_PANEL_PROTOTYPES(PanelAdmin);

// Panels.c
GENERATE_PANEL_FUNCTIONS(PanelMain, PANEL_MAIN)
GENERATE_PANEL_FUNCTIONS(PanelFaults, PANEL_FAULTS)
GENERATE_PANEL_FUNCTIONS(PanelAdmin, PANEL_ADMIN)

And it worked great! And, if I later decided I wanted to add debugging output or something else, instead of editing one hundred different panel functions I could just modify the macro. For example:

#define GENERATE_PANEL_FUNCTIONS(panelName, panelResourceID) \
    static int S_##panelName##Handle = 0; /* Zero is not a valid panel handle. */ \
    \
    int panelName##Init (void) \
    { \
        int panelHandle = 0; \
        if (S_##panelName##Handle <= 0) \
        { \
            panelHandle = LoadPanel (0, TOSTRING(panelName)".uir", panelResourceID); \
            if (panelHandle > 0) \
            { \
                DebugPrintf ("Panel %s loaded.\n", TOSTRING(panelName)); \
                S_##panelName##Handle = panelHandle; \
                \
                panelName##UserInit (panelHandle); \
            } \
        } \
        else \
        { \
            DebugPrintf ("Panel %s already initialized.\n", TOSTRING(panelName)); \

There are a few things to unpack in this example, such as the use of macros STRINGIFY(x) and TOSTRING(x), but those probably could be their own blog post.

Anyway, if you are lazy, and faced with generating dozens or hundreds of almost identical functions, this macro approach can save a ton of time. The macros I made for my original project, dealing with message functions, are vastly more complex than these, but I figured if I started with those most would run away screaming. (I know I sure would if I had been presented them by a coworker.)

I am sure there will be more to say about this, so perhaps a part 3 will show up.

Until then, I’d love to hear what an experienced C macro programmer has to say about this. I bet there are some better techniques and things I am completely unaware of. I’d love it if you’d share.

Thanks…

Addendum: Since I began writing this post, I have converted about 50 panels at work using a much more complex set of #define macros. They keep evolving as I needed to add support for “parent/child” panels, or extra debugging, or even new functions to check if a panel is displayed at the moment. All I did was update the macro, and the next build could use the new functions. I expect it has already saved me days of typing…