Reduce C language coding errors with X macros: Part 3

Andrew Lucas

March 02, 2013

Andrew LucasMarch 02, 2013

Editor's note: This article, last in a series of discussions of x macro usage, examines how to use x macros to automate the task of configuring jump tables and lookup tables used by communication handlers.

Part 2 in this series showed how to develop the following x macro table with the caveat that the command codes needed to be contiguous:

/* ------ NAME ------- FUNCTION --- CODE --- */
  #define COMMAND_TABLE \
  ENTRY(COMMAND0,    command0,     0x00) \
  ENTRY(COMMAND1,    command1,     0x01) \
  ENTRY(COMMAND2,    command2,     0x02) \
  ...
  ENTRY(COMMANDX,    commandX,     0x0X)

 
One  nice thing about having contiguous codes is that the test for index validity is simple:

  ASSERT(command < N_COMMANDS);
  command_jump_table[command]();


When command codes are not contiguous, you need to ensure that you don’t jump to a non-existing function. The simplest way to do this is to make the jump table large enough to support every possible index. However, this is at the expense of memory. You will need 512 bytes (assuming an 8-bit command code size) if the architecture uses 16-bit pointers or 1024 bytes if it uses 32-bit pointers.

With this implementation, instead of the simple ASSERT statement, define an error handling function that can be embedded into the jump table for all invalid commands.

Here is how to do that with x macros, together with some other preprocessor trickery:

  #define INIT_X1     process_reserved,
  #define INIT_X2     INIT_X1   INIT_X1
  #define INIT_X4     INIT_X2   INIT_X2
  #define INIT_X8     INIT_X4   INIT_X4
  #define INIT_X16   INIT_X8   INIT_X8
  #define INIT_X32   INIT_X16  INIT_X16
  #define INIT_X64   INIT_X32  INIT_X32
  #define INIT_X128  INIT_X64  INIT_X64
  #define INIT_X256  INIT_X128 INIT_X128
 
  #define EXPAND_JUMP_TABLE(a,b,c) [c] = process_##b,
 
  static const p_func_t command_jump_table[256] = {
     /* initialize all pointer to the  reserved function */
     INIT_X256,
     /* overwrite pointers to valid  functions */
     COMMAND_TABLE(EXPAND_AS_JUMP_TABLE)
  };


This requires the use of a C99 compiler for the designated initializer syntax, furthermore the compiler may warn you that you are overriding a previously initialized value. If a C99 compiler is not available, then the valid function pointers can be updated at run time, at the expense of not being able to place the jump table in ROM. Here's how to this:

#define EXPAND_JUMP_TABLE(a,b,c) \
   command_jump_table[c] = process_##b;
/* during run-time initialization */
COMMAND_TABLE(EXPAND_AS_JUMP_TABLE)


Optimizing jump tables
For many applications where memory is limited, this implementation is not practical. What can be done instead is to add an extra level of indirection as follows:

  command_jump_table[command_offset_table[command]]();

In this case a second table is utilized that has one entry for every possible command code. Each entry contains an offset into the actual jump table. The memory requirements for this implementation are significantly less than the initial implementation. We need 256 bytes for our offset table, but only 2 or 4 bytes for each function pointer in the jump table. Therefore implementing a communications handler with a dozen commands would need 280/304 bytes instead of 512/1024.

One side-effect of this implementation is that we need to reserve one of the command codes since invalid commands need to resolve to a valid offset so that the correct error handler can be called. The most logical offset value to use is zero (simplifies initialization) and thus the new command table looks like this:

/* ------ NAME ------- FUNCTION --- CODE --- */
  #define COMMAND_TABLE \
  ENTRY(RESERVED,    reserved,     0x00) \
  ENTRY(COMMANDA,    commandA,     0x02) \
  ENTRY(COMMANDB,    commandB,     0x09) \
  ...
  ENTRY(COMMANDZ,    commandZ,     0xef)


A nice side-effect of this implementation is that it is actually easier to automate the creation of these two separate tables than it is to automate the creation of the single jump table.

The creation of the jump table has not changed from our original example with contiguous command codes. The caveat being that we can no longer use the table directly via the command code.

#define EXPAND_AS_JUMP_TABLE(a,b,c) process_##b,
static const p_func_t command_jump_table[N_COMMANDS] = {
  COMMAND_TABLE(EXPAND_AS_JUMP_TABLE)
};


The creation of the offset table is as follows (recall the following struct from last month):

#define EXPAND_AS_STRUCT(a,b,c) uint8_t b,

typedef struct{
  COMMAND_TABLE(EXPAND_AS_STRUCT)
} size_struct_t;

#define N_COMMANDS sizeof(size_struct_t)


This struct can be used for multiple purposes. In addition to taking the size of the struct, we can calculate the offsets of each element in the struct to use when initializing the offset table:

#define EXPAND_AS_OFFSET_TABLE_INITIALIZER(a,b,c) \
  [c] = (uint8_t) offsetof(size_struct_t,  b);


…where offsetof() is a standard library macro defined in "stddef.h". If the reader is unfamiliar with the offsetof() macro I highly recommend reading the article by Nigel Jones, Learn a new trick with the offsetof() macro. Use this new x macro do the following:

/* statically declare our offset table, valid commands  initialized to the correct offsets and invalid command initialized to 0 */
uint8_t command_offset_table[256] = {
  COMMAND_TABLE(EXPAND_AS_OFFSET_TABLE_INITIALIZER)
};


As before, this macro expansion relies on a C99 compiler. If a C99 is not available, do the following:

uint8_t command_offset_table[256] = {0};
 
#define EXPAND_AS_OFFSET_TABLE_INITIALIZER(a,b,c) \
  command_offset_table[c] = (uint8_t)  offsetof(size_struct_t, b);

/* during run-time initialization */
  COMMAND_TABLE(EXPAND_AS_OFFSET_TABLE_INITIALIZER)


A nice side-effect of the offset table implementation is that if we need to implement a function which identifies if a given code is a valid command; the resulting function is a one-liner:

bool command_is_valid(uint8_t command){
  return command_offset_table[command];
}



< Previous
Page 1 of 2
Next >

Loading comments...

Most Commented

  • Currently no items

Parts Search Datasheets.com

KNOWLEDGE CENTER