Bare Metal programming on Leon processors

Frank Singhoff
Université of Brest, Lab-STICC UMR CNRS 6285

Exercise 1 : how to cross-compile, simulate and run on a GR740 board

Exercise 2 : offline scheduling with a dispatcher

Solutions of the exercises

Exercise 1 : how to cross-compile, simulate and run on a GR740 board

In this lab, we will write bare metal programs running either on a simulator or GR740 boards. Most of hardware and software components are GAISLER/Frontgrade material and are currently used in many space products.
Several documentations for those exercises are available here:

Directory GAISLER-DOCS : contaims user guide of the bare metal cross-compiler, simulators and debuggers for Gaisler/Frontgrade products.

Setting up remote working space:

For these labs, we will:

Edit programs on your login machine (.i.e the Linux station in the lab room on which you are connected).
Compile and run programs on pomelos.univ-brest.fr. Please do not launch any other programs on pomelos.univ-brest.fr such as, for example, a web browser.

We will use the POMELOS platform to do this labs. To setup your working space:

Connect to the pomelos.univ-brest.fr machine with ssh as follows:

$ssh yourloginname@pomelos.univ-brest.fr
We now mount your vador files in your pomelos.univ-brest.fr home directory.
- In your login directory on pomelos.univ-brest.fr, create a folder called home-vador by:
  mkdir home-vador
- Mount your vador home directory with the following sshfs command:
  sshfs yourlogin@vador-fs.univ-brest.fr:/home/etudiants/master2/yourlogin home-vador
Finally, download and save in your home directory the following file and put it in a sub-directory called EXO1. These files should be seen on pomelos.univ-brest.fr from home-vador.
Now you are ready to compile and run your first bare metal program.

To compile and run with the TSIM simulator :

In exercise 1, we experiment the C cross-compiler. On Linux, we will generate programs that are able to run on SPARC/Leon processor architectures. To compile programs for Leon processors, we need a specific compiler. All GAISLER tools we need are installed in the /opt folder.
To have these tools on your shell PATH, run the following command:

source /opt/bm.bash
Compile this first example of C program with the following command:

make clean make

assuming you are in the EXO1 directory.
If everything is OK, you should find a file named init.exe.
Launch the command file init.exe : what is the meaning of the displayed information?
Can we directly launch the binary init.exe from your Unix Shell?
Now, we will use a Leon processor simulator to run this program. This simulator is gracefully provided by the Gaisler Research company (See http://www.gaisler.com). To launch this simulator, call the following command from your Unix Shell:

$tsim
tsim>
Now, load the binary into the memory of the simulator and run it with the following commands:
```
tsim> load init.exe 
tsim> run
```
You may get the following result
Answer to these questions:
- Can you say what does this program do?
- How many tasks do we have in this program?

To compile and run with a GR740 board:

When a program has been tested on the simulateur, one would like to run it on a real Leon board. We have 6 GR740 boards availables for such a purpose and we see now how to run the program on such platform.

To run programs with TSIM, we were using the BSP for Leon 3 processors with the following Makefile variable:
CFLAGS = -qbsp=leon3 -O2 -g
To run the same program on a GR740, we need to use a different BSP. Indeed, a GR740 board hosts a 4-core Leon 4FT processor and various hardware components that are not managed by the leon3 BSP. To run the program on a GR740 board, we need to use a specific BSP by updating the Makefile as follows:
CFLAGS = -qbsp=gr740 -mcpu=leon3 -O2 -g
Update the Makefile and compile the program with the following command:
make clean make
Several GR740 boards are available to run the init.exe program. Programs can be launched on those boards with the scripts stored in /opt/bin. Each script allows users to run one program on a specific board. Scripts rtfaix, rtstiff, rtjument and rtkereon can be used to run a program on one of the boards currently connected to pomelos.univ-brest.fr.
For example, to run init.exe on the rtfaix board, do the following commands:

$source /opt/bm.bash
$rtfaix grmon.cmd init.exe

Where grmon.cmd is a script that loads the init.exe program on the board and launches it. Be aware that such command requires the use of sudo because you need to read/write data on a serial link owned by root which connects the board to the Linux host computer. Be aware also that tsim use the run command to start the program execution while the program is executed with the go command on the GR740 boards.

Exercise 2 : offline scheduling with a dispatcher

In this exercise, we implement a nonpreemptive dispatcher. A dispatcher is a software component that run an offline scheduling. Download and save the following file and put it in a directory called EXO2.

The dispacher we want to implement provides a nonpreemtive scheduling and then intends to run high critical systems. The dispatcher contains a table, called the scheduling table, storing the offline scheduling. Each item of the table store the function to run and the timing budget each function is allowed to use to run. Each item of the scheduling table is a C struct as follows:
```
typedef struct nonpreemptive_entry_t {
  int duration;
  function_type entrypoint;
  void* arg;
} nonpreemptive_entry_t;
```
where:
- duration is the budget of the task/function.
- entrypoint is the function/task to run
- arg is an optional parameter for the function/task.
The dispatcher is implemented by the nonpreemptive.h component and provides the following function to programmers:
- ```
extern void nonpreemptive_init(void)
```
  Perform all initializations needed by the dispatcher. Must be called before any interaction with the dispatcher.
- ```
extern void nonpreemptive_active_wait(uint32_t duration)
```
  This function produces an active wait for the current function/task of at least duration microseconds.
- ```
extern void nonpreemptive_add_function(nonpreemptive_entry_t entry)
```
  This function adds one function/task entry in the scheduling table.
- ```
extern void nonpreemptive_add_array_function(nonpreemptive_entry_t entries [], int size)
```
  This function adds size function/task entries in the scheduling table. The entries to add are stored in a table (the entries argument).
- ```
extern void nonpreemptive_start(int iteration)
```
  Start to run tasks/functions declared in the scheduling table. Tasks/functions are run according to their order in the scheduling table. If iteration is equal to 0, then the dispatcher restarts at the beginning of the scheduling table when it achieves the end of the scheduling table. If iteration is a positive integer, then the dispatcher runs the scheduling table iteration times and stops.
- ```
extern void nonpreemptive_stop(void)
```
  Stop the dispatcher, i.e stop to run tasks/functions of the scheduling table.
- ```
extern uint32_t nonpreemptive_get_start_time(void)
```
  Return the time at which the dispatcher starts to run functions.
- ```
extern uint32_t nonpreemptive_get_current_time(void)
```
  Return the current time (which is relative to the scheduling starting time).
- ```
extern int  nonpreemptive_get_current_entry(void)
```
  Return the entry that is currently running.
- ```
extern int  nonpreemptive_get_current_release_time(void)
```
  Return the release time of the current running function/task. Release time is relative to scheduling starting time.
Question 1:

The file init.c is the main entry point of the program of this exercise. It implements a set of 2 functions/tasks with the following parameters:
- Task/function T1, with a period of 10000 us and a capacity of 1000 us
- Task/function T2, with a period of 20000 us and a capacity of 3000 us
Your program must generate the following execution trace:

which correspond to the following scheduling (computed with a tool such as Cheddar or AADLInspector):

Work to do :
1. Fill the nonpreemptive.c file.
2. Test this program on the tsim simulator first.
3. If the program works fine on the simulator, test it again but on the GR740 boards. Do you have the same behavior?
Question 2:

Modify init.c to implement the scheduling of the following function/task set from time 0 to time 40000:
- Task/function T1, with a period of 40000 us and a capacity of 4000 us
- Task/function T2, with a period of 20000 us and a capacity of 2000 us
- Task/function T3, with a period of 10000 us and a capacity of 1000 us
We expect to schedule this task/function set according to a RATE MONOTONIC non preemptive policy.

Again, test your program on the tsim simulator and latter on the GR740 boards.

Question 3:

Now, we add a new task/function in the set of the question 2. We want to add function/task T4 with a period of 5000 us and a capacity of 1000 us.

Update your program to schedule this new function/task set (both T1, T2, T3 and T4), always with a nonpreemptive RATE MONOTONIC policy. Test this new program with tsim and on the GR740 boards.

From this new example, what is the main issue when using a dispatcher implementing an offline scheduling? Compare advantages/disadvantages between a classical online scheduling as provided on RTEMS and an offline scheduling with a dispatcher.