Peter's Blog - Nodes for c

Testing Firmware Code

I've described before how I've been testing Firmware code written in C by compiling it into Ruby Extensions and using ruby's excellent unit testing framework.

Up till now I've been testing the 'middle tier' algorithmic code but how to go about testing the low level stuff, that which pokes the hardware?

The firmware I am developing is for the ST ARM750 microcontroller and I am using ST's own standard library which is very useful driver code for all the peripherals embedded on the chip. It is a very useful resource as the peripherals on this chip are very complex and the user manual is written in hardware engineer gobbledygook that you have to study like a legal document, looking for the small print (e.g. running it at 60MHz it kept crashing until I found the small print that advised me to enable 'burst mode').

Scanning through the source to this library I saw some #ifdef DEBUG statements that implied that it could be compiled into an emulation library. The code was written very cleanly so it took me very little time to write something in (of course) ruby to scan the header files and generate 5250 lines of C code to emulate this library. Here is an example of one of the generated library functions:

   1  /*
   2   * Emulate the function TIM_ClearFlag
   3   */
   4  void TIM_ClearFlag(TIM_TypeDef* TIMx, u16 TIM_FLAG)
   5  {
   6    VALUE nRet;
   7    VALUE oArgs = rb_ary_new();
   8    VALUE strFuncName = rb_str_new2( "TIM_ClearFlag");
   9    ID nId = rb_intern( "Function");
  10  
  11    rb_ary_push( oArgs, PassStructureArg( (void *)TIMx, sizeof( TIM_TypeDef)));
  12    rb_ary_push( oArgs, LONG2NUM( TIM_FLAG));
  13  
  14    nRet = rb_funcall( g_oCallBack, nId, 2, strFuncName, oArgs);
  15  
  16    /* nRet is not used */
  17  }

TIM_ClearFlag is the name of the function in the ST standard library. The emulation code takes the name of the emulated function and the two arguments to the function, converts them into ruby objects and passes them to a method called 'Function' in a ruby object. In the testing case, this object is something that will make sure the functions are being called in the correct sequence and with the correct parameters and will return the appropriate return value. Structure arguments are passed as binary objects which the ruby can decipher from the structure definitions in the ST library header files (also parsed using ruby).

Note that my system has a few limitations that are acceptable because of the simplicity of the ST library and the way it was coded:

The parser I wrote just about handles the coding style of this library
The calls to ruby do not support the case where the library may poke the values within a structure passed to it by pointer.
It doesn't handle passing structures by value.

Now I have my low level testing library I will be able to do my testing using something I call signature analysis (I'm not sure there is a better software engineering term). I write the code, test it on the real hardware, then I can record the sequence of function calls made including the values of function arguments. Later on, in leiu of real hardware to test it on I can run the test code and compare it against the previously recorded signatures. Et voila, the reassurance that I haven't broken anything and I can sleep at night.

UPDATE:

My test library now includes a YamlFaker that can be used in two modes:

it will record a sequence of function calls
it will ensure a sequence of function calls matches a previous recording

The yaml script looks like this:

#
# This file is maintained by the YamlFaker module DO NOT EDIT
#
---
- test_CommandPWMSet Demand -200:
  - :Comment: |-

      Looking for demand to be correct according to the requested range and the
      scaling factors. Also ensure that for the fifth channel, the period is
      large for small demand as the output of this channel is inverted
  - TIM_SetPulse:
      args:
      - TIMx: TIM0
      - TIM_Channel: "0x2"
      - Pulse: "0x0"
  - TIM_SetPulse:
      args:
      - TIMx: TIM1
      - TIM_Channel: "0x2"
      - Pulse: "0x0"
  - TIM_SetPulse:
      args:
      - TIMx: TIM2
      - TIM_Channel: "0x2"
      - Pulse: "0x0"
  - PWM_SetPulse:
      args:
      - PWM_Channel: "0x2"
      - Pulse: "0x0"
  - PWM_SetPulse:
      args:
      - PWM_Channel: "0x4"
      - Pulse: "0x12c"
- test_CommandPWMSet Demand -100:
  - TIM_SetPulse:
      args:
      - TIMx: TIM0
      - TIM_Channel: "0x2"
      - Pulse: "0x0"

Most of the entries in the script describe the expected sequence of function calls, complete with arguments. I can ensure that the demand being sent to my PWM channels is what I expect. These recorded scripts could be quite useful, it is a complete log of the interaction with the hardware. If I ever had to change the code that poked the hardware I can compare the script recorded from the new code against my old script and make sure that any changes are what I would expect. This way I can be far more certain that my changes are correct before they hit real hardware.

Problems with Multiple Ruby Extensions

I've been testing my C libraries by compiling them into ruby extensions and then using ruby's unit testing to test them. Under Windows I had it all running nicely and I could run a main test script that would invoke all the other test scripts. Sweet.

Then it came to getting it running under linux (the target system) and while the unit tests ran fine individually, when I tried my main test script I was getting weird errors from my test extensions, including segment violations (!).

It took me a while to track down the problem but it turned out to be due to the behaviour of gcc and the linux program loader. All my test libraries were loaded into one ruby process and because they all contained functions with similar names it became a bit of a lottery as to which function in which library was called. I am used to the behaviour of windows dll's where all functions are by default hidden from the outside world unless you explicity export them. gcc/elf/whatever seems to export everything from shared libraries (linux equivalent of a dll) by default with hilarious results.

In version 4 of gcc they have added a facility for hiding these internal functions. I solved my problem as follows:

Add '-fvisibility=hidden' to the gcc arguments to cause all functions to be hidden by default.

Add this code to my stddefs.h:

   1  #ifdef _MSC_VER
   2    #ifdef BUILDING_DLL
   3      #define DLLEXPORT __declspec(dllexport)
   4    #else
   5      #define DLLEXPORT __declspec(dllimport)
   6    #endif
   7    #define DLLLOCAL
   8  #else
   9    #define DLLEXPORT __attribute__ ((visibility("default")))
  10    #define DLLLOCAL __attribute__ ((visibility("hidden")))
  11  #endif

Change the functions that ruby calls to load the ruby extension to the following form (i.e. add DLLEXPORT):

   1  /*
   2   * Initialise the test class.
   3   */
   4  DLLEXPORT void Init_testtimer( void)
   5  {
   6      VALUE oMyClass = rb_define_class( "TestTimer", rb_cObject);
   7      rb_define_method( oMyClass, "initialize", test_initialise, 1);
   8      rb_define_method( oMyClass, "TimerSet", test_TimerSet, 1);
   9      rb_define_method( oMyClass, "TimerUpdate", test_TimerUpdate, 1);
  10      rb_define_method( oMyClass, "TimerStart", test_TimerStart, 1);
  11      rb_define_method( oMyClass, "TimerTest", test_TimerTest, 0);
  12  }

These functions are the only ones that need to be visible outside the library.

Results:

SDCC interrupt woes

If anyone else has been trying to figure out why the SDCC 8051 compiler doesn't seem to generate interrupt code that works, the secret is that if the function is defined is a file other than the main program file then a prototype of the interrupt vector function has to be declared in the main program file:

timer.c:

void TimerInterrupt( void) interrupt 3
{
   blah();
}

main.c:

extern void TimerInterrupt( void) interrupt 3;

This causes sdcc to generate an interrupt vector table.

I found this here. It is reassuring to me that a company like Maxim is endorsing this compiler.

Protothreads

I am about to start work on a couple of embedded firmware projects and I just happened to come across protothreads which use a clever C trick to implement pseudo-threading. Each thread uses only two bytes of memory (thats two: the threads do not need a stack) so it should be great on a 8051.

The trick relies on a quirk of C where it is possible for a switch statement to jump to case labels inside control statements like for loops. This code very cleverly uses the line number within the file (i.e. __LINE__) as the target for a later switch jump. Hence to 'resume' a thread the code just uses a switch statement to jump to the place within the function where it last yielded.

This offers the hope of efficient multitasking without loathsome state machines. Nice sequential coding: bliss. Compared to 'real' threads or interrupt service routines, these protothreads should not be too sensitive to obscure bugs as you know where task switching is likely to happen. This means you don't necessarily need mutexes and whatnot scatterred around. I've always been a believer in doing as much as possible in the foreground and as little as possible under interrupts and this technique will make it easier for me to do this.

The only shortcomings of the trick (apart from relying on am obscure quirk of the compiler) are that you cannot use switch statements as your thread is based on a switch statement, there are limitations regarding blocking in subroutines and local variables do not hold their values (which also applies to state machines).

I'm tempted to use the SDCC 8051 compiler as the old version of the Keil compiler we have at work does not run on Windows XP. It remains to be seen whether this trick will work with this compiler: I have no hardware to test it and I cannot get the sdcdb emulator to support serial IO so I could only tell if it worked by setting breakpoints and seeing if they are reached.

Thought: if the thread was within the first 255 lines of the source file, each thread would only need one byte to store it's state.