1.1   Upload system guidelines

Follow these guidelines:

1. Your submission should contain config.h file (see below) in addition to the source code *.c.

2. Entry point functions should be names as:

   1. entry point function for Downloadable Kernel Module is named CreateTasks, and
   2. entry point function for Real-Time Process is named main.

3. (Downloadable Kernel Module only) Use sysClkRateSet(CLOCK_RATE) at the beginning of your program.

4. Created tasks should be named as follows:

   1. low priority task is named tLPrio,
   2. middle priority task is named tMPrio, and
   3. high priority task is named tHPrio.

5. The tasks have to be spawned (or activated) in the following order: tLPrio, tMPrio, tHPrio. This way, the measurement won't be affected by the values obtained when there is no competing task.

6. The first parameter of the entry point function selects the mode of operation:

   1. passing value 1 runs the tasks without priority inheritance,
   2. passing value 2 runs the tasks with priority inheritance, and
   3. passing other values terminates the application.

7. The second parameter configures the number of measurements.

8. Report start of the measurement by printing measurement started and end of the measurement by printing measurement finished. As measurement finishes, all created tasks should end as well.

   • This behaviour is controlled by the high priority task. When the target number of the measurements is reached, a global variable (e.g. end) should be set to a certain value, that allows the other tasks to end.

9. Measured worst-case mutex blocking time is printed to standard output each time it changes as integer number of milliseconds (without units) followed by a newline character.

10. Example of application output is shown below:

    Measurement started
    0
    440
    500
    Measurement finished
    

Note: Proper termination of Downloadable Kernel Module is to call return within the entry point function (or proceed to the end of it). Don't use exit() in this case.

Note: Entry point function has to end right after starting the measurement (i.e., after spawning all the tasks). This is important for DKM.

Note: Don't use ARMARCH7gnu_SMP build spec as it is not supported on the simulator. Use it only when uploading to the real hardware.

1.2   Lab submission guidelines

In order to submit this assignment during the lab, please prepare:

1. Run CreateTasks(1, 200) on board.
   • Show output of the function.
2. Run CreateTasks(2, 200) on board.
   • Show output of the function.
   • Run System Viewer and record your application. Show segment with priority inheritance.

2.1   Pseudo code of tasks in the application

Pseudo-code of the highest priority task can look like this:

while (/* loop NUMBER_OF_MEASUREMENTS times */) {
  struct timespec tstart, tend, result;
  clock_gettime(CLOCK_MONOTONIC, &tstart);
  if (semTake(mutex, WAIT_FOREVER) == ERROR)
    fprintf(stderr, "semTake error\n");
  clock_gettime(CLOCK_MONOTONIC, &tend);
  semGive(mutex);
  timespec_subtract(&result, &tend, &tstart);
  /* Handle measurement and print if necessary */
  taskDelay(HIGH_PRIORITY_DELAY); /* let other tasks run */
  n++;
}

end = 1; /* Signal the other tasks to end */

info libc "Elapsed Time"

/* Subtract the `struct timespec' values X and Y,
   storing the result in RESULT (result = x - y).
   Return 1 if the difference is negative, otherwise 0.  */

int
timespec_subtract (struct timespec *result,
           struct timespec *x,
           struct timespec *y)
{
  /* Perform the carry for the later subtraction by updating Y. */
  if (x->tv_nsec < y->tv_nsec) {
    int num_sec = (y->tv_nsec - x->tv_nsec) / 1000000000 + 1;
    y->tv_nsec -= 1000000000 * num_sec;
    y->tv_sec += num_sec;
  }
  if (x->tv_nsec - y->tv_nsec > 1000000000) {
    int num_sec = (x->tv_nsec - y->tv_nsec) / 1000000000;
    y->tv_nsec += 1000000000 * num_sec;
    y->tv_sec -= num_sec;
  }

  /* Compute the time remaining to wait.
     `tv_nsec' is certainly positive. */
  result->tv_sec = x->tv_sec - y->tv_sec;
  result->tv_nsec = x->tv_nsec - y->tv_nsec;

  /* Return 1 if result is negative. */
  return x->tv_sec < y->tv_sec;
}

In order for the task to block at some time, there must be another task contending for the same mutex:

while (!end) {
  semTake(mutex, WAIT_FOREVER);
  do_something_while_the_mutex_is_locked();
  semGive(mutex);
  taskDelay(LOW_PRIORITY_DELAY); /* this delay can be even zero - do you know why? */
}

If our application had only the two above tasks, priority inversion would never happen. Therefore, a third middle-priority task has to be added. Note, that this task can be completely independent of the other tasks (doesn't share mutexes with them).

while (!end) {
  do_something_very_long();
  taskDelay(MID_PRIORITY_DELAY); /* wait to let the low priority task run */
}

2.2   do_something_*()

Functions do_something_*() in the above examples are filled with a code with long, but finite-time execution. Example of such a function is given below:

void do_work_for_some_time(int x)
{
    long int len = x * 100000000;
    while (len > 0) len--;
}

/*
 * Deprecated
 * Use function 'do_work_for_some_time()' instead.
 */
void do_work_for_x_milliseconds(int x)
{
    struct timespec begin, end, result;
    int milliseconds = 0;
    clock_gettime(CLOCK_MONOTONIC,&begin);
    while (milliseconds < x)
    {
        clock_gettime(CLOCK_MONOTONIC,&end);
        timespec_subtract(&result, &end, &begin);
        milliseconds = result.tv_sec*1000 + result.tv_nsec/1000000;
    }
}

2.3   Used macros

In the functions above some macros are used. Their definition should be located in config.h. Values of these macros are specified below:

/* Clock rate for 'sysClkRateSet()' function. */
#define CLOCK_RATE              1000

/* Priority of three tasks -- lower number = higher priority. */
#define HIGH_PRIORITY           210
#define MID_PRIORITY            211
#define LOW_PRIORITY            222

/* Work factors of the tasks for 'do_work_for_some_time()'. */
#define MID_PRIORITY_WORK       10
#define LOW_PRIORITY_WORK       3

/* Delays of the tasks. Fill them with your own values */
#define HIGH_PRIORITY_DELAY     ?
#define MID_PRIORITY_DELAY      ?
#define LOW_PRIORITY_DELAY      ?

Feel free to modify them as you like and observe behaviour of the system. Stick to these values only when submitting the assignment to BRUTE and when showing the application to the teacher.

2.4   Passing parameters to the functions

Parameters can be passed to your application by filling the appropriate field in Run → Run Configurations... → Launch Context → General → Arguments. This is valid for both Downloadable Kernel Modules and Real-Time Processes.

1. In case of a kernel module, parameters are passed as arguments to a regular C function, therefore entry point function receive one integer parameter as shown below:

   void CreateTasks(int i) {};
   

2. In case of a real-time process, parameters are passed as arguments to a regular C application, therefore main function receive parameters as shown below:

   int main(int argc, char** argv) {};
   

2.5   Setting a CPU affinity for a task (example)

cpuset_t affinity;
int tid;

/* Create the task but only activate it after setting its affinity */
tid = taskCreate ("myCpu1Task", 100, 0, 5000, printf,
(int) "myCpu1Task executed on CPU 1 !", 0, 0, 0,
0, 0, 0, 0, 0, 0);

if (tid == NULL)
    return (ERROR);

/* Clear the affinity CPU set and set index for CPU 1 */
CPUSET_ZERO (affinity);
CPUSET_SET (affinity, 1);

if (taskCpuAffinitySet (tid, affinity) == ERROR)
{
    /* Either CPUs are not enabled or we are in UP mode */
    taskDelete (tid);
    return (ERROR);
}

/* Now let the task run on CPU 1 */
taskActivate (tid);

2.6   Traces

Here we show the traces of the program with priority inheritance switched off and on. You can compare them with your application's traces when to tune the delay constants. (Thanks to Ondrej Kucera)

Priority inheritance switched off

Priority inheritance switched on