19.1.1 Linux Implementation

In the following, the listing of the Linux implementation of the OS abstraction is presented. The first class is SystemException, and is used for error management. When an error is detected in any call to the OS routines, an Exception is thrown, that is, an Exception object is created, containing the description of the error, the execution of the method aborted, and the call stack unwound until a calling method able to manage this kind of exception is found. The C++ try construct is used to declare the ability of a method to manage the generation of Exceptions. Any exception generated by any called method will be “caught” by the catch clause of the try statement and the associated code executed. Here, the Exception class is named SystemException. Its constructor will take as argument a user-provided message and the system error number (contained in Linux variable errno), and will build the complete error message, which can be accessed via method what().

# ifndef  OS_ABSTRACTION_LINUX_H
# define  OS_ABSTRACTION_LINUX_H
# include   <stdio .h>
# include   <stdlib .h>
# include   <string .h>
# include   <semaphore.h>
# include   <pthread .h>
# include   <sys/ipc.h>
# include   <sys/msg.h>
# include   <errno .h>
# include   <sys/ time.h>
/*  Class SystemException is a support class for handling error
    management. An instance of this class will be thrown in an exception
    when an error  occurs. */
class  SystemException
{
/*   Error message  */
    char errorMsg [512];
public :
/*   Constructor : convert the passed code and appends it to the
     passed string  message */
    SystemException( const char *msg, int errNo )
    {
       memset (errorMsg, 0, 512);
       sprintf (errorMsg,  "%s: %s", msg,  strerror ( errNo ));
    }
/*   Get the error message */
    char * what ()
    {
       return  errorMsg ;
    }
};

Class Semaphore specifies a counting semaphore. Its private field is the handle of the underlying Linux semaphore, which is created by the class’ constructor. The class exports the public wait() and post() methods.

class  Semaphore
{
/*    The corresponding Linux semaphore handle  */
    sem_t  semHandle;
public :
/*   Semaphore constructor. The argument specifies the initial value  of
     the semaphore ( default  0) */
    Semaphore(int  initVal =  0)
    {
      int status = sem_init (&semHandle, 1, initVal );
      if( status !=  0)
        throw new  SystemException("    Error  initializing Semaphore",  errno );
    }
    void   wait ()
    {
      int status = sem_wait (&semHandle));
      if( status !=  0)
        throw new  SystemException(" Error     waiting  semaphore",  errno );
    }
    void   post ()
    {
      int status = sem_post (&   semHandle);
      if( status !=  0)
        throw new  SystemException(" Error     posting  Semaphore",  errno );
    }
/*   Destructor, automatically  called
     when the semaphore instance is discarded  */
    ~ Semaphore()
    {
      int status =  sem_destroy(&semHandle);
      if( status !=  0)
        throw new  SystemException("    Error  destroying Semaphore",     errno );
    }
};

Class Mutex implements mutual exclusion. It is implemented here using the pthread mutex object. Its public methods are lock() and unlock().As forthe other classes, the details of the mutex initialization and destruction are hidden in the constructor and destructor methods, called whenever the class instance is created and discarded, respectively. The C++ friend construct declares that another class has access to the private fields. This is used here because the ptread mutex object must be directly accessed in the implementation of the following class Condition.

class Mutex
{
/*    The corresponding pthread mutex  */
    pthread_mutex_t  mutex ;
/*  In the Linux implementation class Condition will require the
  private field mutex  */
friend class      Condition;
public :
/*   Constructor :  initialize the internal pthread mutex  */
    Mutex ()
    {
      int status =  pthread_mutex_init(&mutex, NULL );
      if( status != 0)
         throw   new SystemException(" Error Creating Mutex ",        errno );
    }
    void lock ()
    {
      pthread_mutex_lock(&mutex );
    }
    void  unlock ()
    {
       pthread_mutex_unlock(&mutex );
    }
    ~ Mutex ()
    {
       pthread_mutex_destroy(&mutex );
    }
};

Class Condition carries out the monitor functionality. Its public method wait() suspends the execution of the current thread until the monitor is signaled via public method signal().Method wait() can accept as parameter a reference of a Mutex object. This mutex will be unlocked prior to waiting and locked again before method wait() returns.

The Linux implementation is straightforward and the monitor functionality is mapped onto a pthread condition object.

class  Condition
{
    pthread_cond_t  cond;
public :
/*   Constructor :  initialize the internal pthread condition object */
    Condition()
    {
      int status =  pthread_cond_init(&cond,  NULL );
      if( status != 0)
         throw new  SystemException(" Error Creating  Condition",  errno );
    }
    void wait ( Mutex * mutex )
    {
/*   Here it is necessary to access the private field mutex
     of class Mutex  */
      pthread_cond_wait(&cond, mutex -> mutex );
    }
    void signal ()
    {
       pthread_cond_signal(&cond );
    }
/*  Destructor : destroy pthread conition object  */
    ~ Condition()
    {
       pthread_cond_destroy(&cond );
    }
};

Class MessageQueue describes a queue of equally sized messages. The dimension of the message buffer is passed to the constructor. The Linux implementation is a bit less straightforward than in the previous classes because Linux routines msgsnd() and msgrcv() expect a message class as the first longword of the message buffer. This is hidden outside the class, which uses an internal buffer for this purpose.

class  MessageQueue
{
/*   Linux message queue handler  */
    int msgId ;
/*   Message dimension for this message queue  */
    int  itemSize ;
/*   Private message buffer  */
    char  * msgBuf ;
public :
/*   Constructor : initialize the Linux Message queue, and allocate  the
     internal buffer  */
    MessageQueue(int  itemSize )
    {
       this -> itemSize =  itemSize ;
       msgId = msgget ( IPC_PRIVATE,    0666);
       if( msgId == -1)
          throw  new SystemException(" Error Creating Message Queue ",errno );
       msgBuf = new char[ sizeof ( long ) + itemSize ];
/*  The message class required by Linux is here always 1  */
      *(( long *) msgBuf ) = 1;
    }
/*   Send message : message dimension has been declared in the constructor */
    void send (void  * item)
    {
       memcpy (&msgBuf [ sizeof ( long )],  item,  itemSize );
       int status = msgsnd (  msgId,  msgBuf, itemSize, 0);
       if( status ==  -1)
          throw  new SystemException(" Error Sending Message ", errno );
    }
/*   Receive a message, possibly waiting for it, and return the number
     of bytes actually read  */
    int receive ( void * retItem )
    {
       int retBytes = msgrcv ( msgId,  msgBuf, itemSize, 0, 0);
       if( retBytes == -1)
          throw  new SystemException("    Error  Receiving  Message ", errno );
/*  Copy the message from the internal buffer into client 
    skipping the f i r s t longword containing the message class  */
      memcpy (retItem, &msgBuf [ sizeof ( long )], retBytes );
      return  retBytes ;
    }
/*   Destructor : Remove Linux message queue structures and
     deallocate  buffer */
    ~ MessageQueue()
    {
      msgctl (msgId,  IPC_RMID, NULL );
      delete []  msgBuf ;
    }
};

The following are the classes and structures used to implement Thread class. Class Runnable is declared as an abstract class and must be implemented by the client application. Thread’s method start() takes two arguments: the pointer of a Runnable subclass instance and a generic argument to be passed to Runnable’s method run(). Since the routine passed to pthread_create() accepts only one parameter, this is defined as the pointer to a structure containing both the address of the Runnable instance and the argument. A pointer to routine handlerWithArg() is passed to pthread_create(), and this routine will in turn call Runnable’s run() method with the specified argument. Thread stack size and priority can be set using setter methods setStackSize() and setPriority(). Finally, method join() will suspend caller’s execution until the created thread terminates.

/*  Abstract class for representing Runnable entities. It will be
    inherited by user-provided classes in order to specify
    specific thread code. The class has only one virtual method ,
    run (), which will receive a void*  generic argument  */
class Runnable
{
public :
    virtual void run( void * arg) = 0;
};
/*  Internal structure passed to the thread . It contains the pointers
to the runnable object and to the argument to be passed to method run ()  */
struct ThreadArgs{
    Runnable *rtn;
    void  * arg;
};
/*  The routine passed to pthread_create must be declared as C interface  */
extern    "C" void  handlerWithArg( ThreadArgs *);
/*  Thread abstraction. It manages the creation of a thread  */
class    Thread
{
/*   Internal pthread handle  */
    pthread_t   threadId ;
/*   Thread argument structure to be passed to the C trhead routine  */
    struct  ThreadArgs   args;
/*   Internal pthread attributes  */
    pthread_attr_t  attr;
/*   Thread priority  */
    int  priority ;
public :
/*   Constructor :  initialize pthread  attributes */
    Thread ()
    {
      pthread_attr_init (&   attr );
      priority =   -1;
    }
/*   Set the thread stack size  */
    void  setStackSize( int    stackSize)
    {
      pthread_attr_setstacksize(&     attr,    stackSize);
    }
/*  Set the thread priority  */
    void  setPriority( int  priority )
    {
/*  Priority is simply recorded, as the priority can be set only
    when the thread is    started */
      this -> priority =    priority ;
    }
/*   Start a new thread. The passed routine is embedded in an instance of
     ( subclass of ) Runnable class */
    void start ( Runnable *rtn, void *arg)
    {
/*  Prepare the argument structure  */
      args. rtn = rtn;
      args. arg = arg;
      int status =  pthread_create(&threadId, &attr ,
        ( void *(*)( void *)) handlerWithArg, ( void      *)&args );
      if( status != 0)
         throw   new SystemException(" Error Creating Thread ", errno );
      if( priority != -1)  /  * If not default      priority */
      {
        status =  pthread_setschedprio( threadId,        priority );
        if( status !=    0)
           throw new  SystemException(" Error setting Thread Priority ", errno );
      }
    }
/*   Wait the termination of the created thread  */
    void join ()
    {
      pthread_join( threadId,    NULL );
    }
/*   startScheduler method is meaningless in Linux ,
     but is required in the FreeRTOS implementation . See below.  */
    static void  startScheduler() {}
};
/*  The routine passed to pthread_create () is always the same. It  will then
    call  specific run() method  */
void  handlerWithArg( ThreadArgs *args )
{
/*   Call run () method of the Runnable object  */
    args ->rtn ->run(args -> arg);
/*   When run () returns, signal thread termination  */
    pthread_exit( NULL );
}

Finally, classes TimeInterval and Timer provide an abstract management of timed execution suspension. An interval of time is represented by class TimerInterval, internally specifying the number of seconds and of nanoseconds. An instance of TimerInterval is then passed to Timer’s sleep() method, which will suspend execution for the specified amount of time. In the Linux implementation, the representation of the interval is converted to a Linux specific timespec structure, which is then passed to Linux routine nanosleep().

/*  Class TimeInterval provides a platform independent representation  of
    a time interval  */
class  TimeInterval
{
/*   Seconds  */
    long secs ;
/*   Nanoseconds  */
    long  nanoSecs ;
public :
/*   Constructors and getter methods */
    TimeInterval(long secs, long nanoSecs )
    {
      this -> secs = secs + nanoSecs / 1000000000;
      this -> nanoSecs = nanoSecs % 1000000000;
    }
    TimeInterval( long milliSecs)
    {
      this -> secs = milliSecs / 1000;
      this -> nanoSecs = ( milliSecs % 1000) * 1000000;
    }
    long getSecs (){ return secs ;}
    long  getNanoSecs(){ return nanoSecs ;}
    long  getTotMilliSecs(){ return secs * 1000 + nanoSecs / 1000000;}
};
/*  Timer abstraction : defines the only method sleep () taking a
    TimeInterval instance as argument  */
class Timer
{
public :
    void sleep ( TimeInterval &tv)
    {
/*  Build Linux specific time structure and use Linux nanosleep ()  */
     struct timespec req, rem;
     req. tv_sec = tv. getSecs ();
     req. tv_nsec = tv. getNanoSecs();
     int status   =  nanosleep(&req,   &rem );
     if( status !=   0)
       throw new  SystemException(" Error in Sleep ", errno );
    }
};
# endif  //OS_ABSTRACTION_LINUX_H

19.1.2 FreeRTOS Implementation

The same C++ classes that have been implemented under Linux are now presented for a FreeRTOS system. Despite the differences between the two systems, the class interface will be the same, allowing then the development of common applications for Linux and FreeRTOS.

Class SystemException implementation here cannot rely on the transformation of the error number into the corresponding string because FreeRTOS does not support translation from error code to error string. Therefore, the error code is not managed the class in this implementation.

# ifndef  OS_ABSTRACTION_FREE_RTOS_H
# define  OS_ABSTRACTION_FREE_RTOS_H
# include  <stdio.h>
# include  <stdlib.h>
# include  <string.h>
# include  <errno.h>
# include  <FreeRTOS.h>
# include  <task.h>
# include  <semphr.h>
class  SystemException
{
    char errorMsg [512];
public :
    SystemException( const char * msg)
    {
       memset (errorMsg, 0, 512);
       sprintf (errorMsg,  "%s", msg );
    }
    char * what ()
    {
       return errorMsg ;
    }
};

Class Semaphore uses a Counting Semaphore, passing a default value as the maximum allowed value, required by the FreeRTOS counting semaphore creation routine. The maximum semaphore value in Linux is instead predefined.

# define  MAX_FREERTOS_SEM_VAL 256
class  Semaphore
{
/*   Internal semaphore handle  */
    xSemaphoreHandle semHandle;
public :
/*   Constructor : creates the semaphore object  */
    Semaphore(int  initVal =  0)
    {
      semHandle = xSemaphoreCreateCounting( MAX_FREERTOS_SEM_VAL,  initVal );
      if( semHandle ==  NULL)
         throw new  SystemException(" Error  initializing Semaphore");
    }
    void   wait ()
    {
       if( xSemaphoreTake( semHandle,  portMAX_DELAY) != pdTRUE )
         throw  new SystemException(" Error  waiting  semaphore");
    }
    void   post ()
    {
       if( xSemaphoreGive( semHandle) !=  pdTRUE )
         throw  new SystemException(" Error  posting  Semaphore");
    }
    ~ Semaphore()
    {
       vQueueDelete( semHandle);
    }
};

Class Mutex is implemented in FreeRTOS using a recursive binary semaphore. As usual, the constructor will create the semaphore object, and the destructor will discard it.

class Mutex
{
/*   Recursive binary semaphore handle  */
    xSemaphoreHandle semHandle;
public :
/*   Constructor : creates the recursive binary semaphore  */
    Mutex ()
    {
      semHandle = xSemaphoreCreateRecursiveMutex();
      if( semHandle ==  NULL)
        throw  new SystemException(" Error Creating Mutex ");
    }
    void lock ()
    {
      if( xSemaphoreTake( semHandle,  portMAX_DELAY) !=  pdTRUE )
        throw   new SystemException(" Error locking mutex ");
    }
    void  unlock ()
    {
      if( xSemaphoreGive( semHandle) !=  pdTRUE )
        throw   new SystemException(" Error  unlocking      mutex ");
    }
    ~ Mutex ()
    {
      vQueueDelete( semHandle);
    }
};

While in Linux monitors are directly supported by the pthread library, they are not natively available in FreeRTOS. Therefore, in the FreeRTOS implementation, monitors must be implemented using the available objects (Mutexes and Semaphores). It would be possible to use directly FreeRTOS semaphores, but using the interface classes makes the code more readable. In this way, there is no need for a destructor, the native semaphores discarded by the object fields destructors are automatically called whenever the Condition instance is discarded.

class  Condition
{
/*   The Mutex to protect condition data structures  */
    Mutex mutex ;
/*   The Semaphore used to wake waiting processes, initially set to
     zero ( default constructor value )  */
    Semaphore sem;
/*   Number of tasks waiting for this condition  */
    int waitingCount;
public :
/*   Constructor : the mutex and semaphore objects are created by the
     constructors of fields mutex and sem
     so the only required action is to initialize waitingCount to zero  */
    Condition()
    {
      waitingCount = 0;
    }
/*   Simulated wait procedure : increment the waiting counter, wait
     for the semaphore after releasing the passed Mutex, if any ,
     and acquire it afterwards  */
    void wait ( Mutex * userMutex)
    {
      waitingCount++;
      if( userMutex)
        userMutex -> unlock ();
      sem. wait ();
      if( userMutex)
        userMutex -> lock ();
    }
/*   Simulated Signal procedure : check writer counter. If greater
    than zero, there is at least one waiting task, which is awakened
    by posting the semaphore . The check and possible decrement of
    variable waitingCount must be performed in a critical  segment ,
    protected by the Mutex  */
    void signal ()
    {
      mutex . lock ();
      if( waitingCount == 0)
    {
/*  No waiting tasks  */
       mutex . unlock ();
       return ;
    }
/*  There is at least one waiting task  */
     waitingCount --;
     sem. post ();
     mutex . unlock ();
    }
};

Class MessageQueue is implemented in FreeRTOS using the native queue object. The maximum queue length is not exported by the interface and is therefore set to a default value. Unlike the Linux implementation, there is no need to handle an internal buffer.

# define  MAX_FREERTOS_QUEUE_LEN 16
class  MessageQueue
{
/*   The dimension of the items  */
    int itemSize ;
/*   The message queue native object  */
    xQueueHandle queue ;
public :
/*   Constructor : create native message queue object  */
    MessageQueue(int  itemSize )
    {
      this -> itemSize = itemSize ;
      queue =  xQueueCreate( MAX_FREERTOS_QUEUE_LEN,  itemSize );
      if( queue ==  NULL)
      throw  new SystemException(" Error Creating Message Queue ");
    }
/*   Send message : message dimension has been declared in    the
     constructor  */
    void send (void * item)
    {
      if( xQueueSendToBack( queue,  item, portMAX_DELAY)  != pdPASS )
        throw  new SystemException(" Error Sending Message ");
    }
/*   Receive a message, possibly waiting for it, and return the
     number of bytes actually read  */
    int receive ( void * retItem )
    {
      if( xQueueReceive(queue, retItem,  portMAX_DELAY)  !=  pdPASS )
        throw  new SystemException(" Error  Receiving  Message ");
      return itemSize ;
    }
    ~ MessageQueue()
    {
        vQueueDelete( semHandle);
    }
};

The basic concept in the Thread interface, that is, embedding the code to be executed by the thread into the method run() for a Runnable class, is retained in the FreeRTOS implementation. There are, however, three main differences with the Linux implementation:

1. There is no native thread join mechanism in FreeRTOS. This is simulated in the class implementation by using a semaphore to signal the termination of the thread. This semaphore will be set by the thread routine after Runnable’s method run() returns and will be used by the Thread’s join() method.

2. In FreeRTOS, the code associated with a thread can never return, but must call vTaskDelete() to let the system discard the task. This is different from the thread model offered by the interface, where threads terminate whenever the associated core returns. So the thread routine, after executing the Runnable’s run() method and setting the termination semaphore, will call vTaskDelete()

3. FreeRTOS requires that the scheduler is started manually after the threads have been created. Afterwards, the main program does not exists anymore. Starting the scheduler is performed by static Thread method startScheduler(), which is void in the Linux implementation.

/*  Abstract class for representing Runnable entities. It will
    be inherited by user-provided classes in order to specify
    specific thread code. The class has only one virtual method run () ,
    which will receive a void*  generic argument  */
class Runnable
{
public :
    virtual void run( void * arg) = 0;
};
/*  Internal structure passed to the thread . It contains the
    pointers to the runnable object, the argument to be passed to
    method run (), the termination semaphore and the native thread
    object handler (used to delete the task upon termination )  */
struct ThreadArgs
{
    Runnable  *rtn;
    void * arg;
    Semaphore  *sem;
    xTaskHandle taskHandle;
};
/*  The routine passed to pthread_create must be declared as C interface  */
extern    "C"    void  handlerWithArg( ThreadArgs        *);
/*  Default values for ptiority and stack        size  */
# define  DEFAULT_STACK_SIZE ( configMINIMAL_STACK_SIZE +  512)
# define  DEFAULT_PRIO          tskIDLE_PRIORITY
/*  Thread abstraction . It manages the creation of a thread  */
class Thread
{
/*  Thread stack size  */
      int stackSize;
/*  Thread priority  */
      int    priority ;
/*  Internal thread routine arguments  */
      struct   ThreadArgs  args;
/*  Unique task index :  it is a static field  ( i.e.   shared by   all
    thread instances ) and is required because a unique task   name
    must be passed to xTaskCreate    */
    static int      taskIdx ;
public :
    Thread ()
    {
/*  Set default values for stack  size  and priority  */
      stackSize =  DEFAULT_STACK_SIZE;
      priority =  DEFAULT_PRIO;
    }
/*  Setter methods for stack size and priority  */
    void  setStackSize( int  stackSize)
    {
      this -> stackSize = stackSize;
    }
      void  setPriority( int  priority )
    {
        this -> priority =   priority ;
    }
/*   Start a new thread . The passed routine is embedded in
     an instance of ( subclass of ) Runnable class */
    void start ( Runnable *rtn, void     *arg)
    {
/*   Copy Runnable object reference and argument into the
     argument structure  */
       args. rtn =    rtn;
       args. arg =    arg;
/*  Create the termination semaphore  */
    args. sem = new  Semaphore(0);
/*  A task name is required by xTaskCreate () and created based
    in the unique value of taskIdx  */
      char     nameBuf [16];
      sprintf (nameBuf, " TASK_ %d",        taskIdx ++);
/*  Native Task       creation  */
      if( xTaskCreate(( void (*)( void *)) handlerWithArg ,
        ( signed char *) nameBuf, stackSize ,
        &args,  priority, &args. taskHandle)  !=  pdPASS )
            throw   new  SystemException(" Error Creating   Thread ");
    }
/*   Wait for the termination of this thread using the associated
     termination semaphore  */
    void  join ()
    {
        args .sem -> wait ();
        delete   args. sem;
    }
/*   Start the scheduler */
    static  void  startScheduler()
    {
      vTaskStartScheduler();
    }
};
/*  Routine actually executed by the thread  */
void  handlerWithArg( ThreadArgs *args )
{
/*  Execute User run() method */
      args ->rtn ->run(args -> arg);
/*  Set termination semaphore */
      args ->sem ->  post ();
/*  Destroy this thread */
      vTaskDelete(args -> taskHandle);
}

Timer classes are similar to the Linux implementation. FreeRTOS routine vTaskDelay(), used to suspend the calling thread, requires the specification of the delay expressed as the number of ticks. This number is derived by configTICK_RATE HZ constant specifying the tick frequency for the given system.

class  TimeInterval
{
    long secs ;
    long nanoSecs ;
public :
    TimeInterval( long secs,  long nanoSecs )
    {
       this -> secs = secs + nanoSecs /  1000000000;
       this -> nanoSecs = nanoSecs %  1000000000;
    }
 
   TimeInterval( long milliSecs)
    {
       this -> secs =  milliSecs /  1000;
       this -> nanoSecs = ( milliSecs %  1000) * 1000000;
    }
    long getSecs (){ return secs ;}
    long  getNanoSecs(){ return  nanoSecs ;}
    long  getTotMilliSecs(){ return secs * 1000 + nanoSecs /  1000000;}
};
class Timer
{
public :
    void sleep ( TimeInterval &tv)
    {
       portTickType  numTicks =
        (tv. getTotMilliSecs() * configTICK_RATE_HZ)/1000;
       vTaskDelay( numTicks );
    }
};
# endif //OS_ABSTRACTION_FREE_RTOS_H