ALOE Linux User Guide

This section describes first steps on launching and running a waveform in ALOE for Linux. If you plan to develop applications or you just want to learn more about ALOE, you should read the Waveform Developer Guide.

At this point we assume that you have downloaded and installed ALOE on your computer (see Start Guide) and that your are familiar with Linux commands at user level.

Launching ALOE

If you downloaded ALOE from source, take a look at the 'example-repository' directory. This directory is where Manager Daemons will search for configuration files, waveform definitions files and executables (and so on).

You will see that this directory has, among others, the following mandatory subdirectories:

• logs: Module logs in a directory for each waveform.
• reports: Module statistic reports in a directory for each waveform.
• statsman: Module initialization parameters in a directory for each waveform.
• swman_execs: Module binaries in a directory for each platform.
• swman_apps: Application descriptions.

NOTE: Make sure that swman_execs/linux contains (or links to) your waveform binaries compiled for linux. Distributed objects are configured to be installed at /usr/local/bin, therefore, swman_execs/linux should link to that path.

ALOE Linux needs to access this repository. Path can be selected permanently in a configuration file or as an argument in the launcher. By default, it is defined in a configuration file and points to 'example-repository/', relative to the current directory. Therefore, ALOE can be launched from the downloaded source directory by simply typing:

runph

NOTE: To run ALOE with real-time priorities, run it with root permissions.:

sudo runph

This will launch a default single-processor configuration.

runph is configured with a platform configuration file. However, shell arguments can be used to override some options. The command accepts the following arguments:

runph -r [repository_path] -c [platform_cfg_file] -i [xitf_cfg_file] [--daemon]|[--no-daemon] [--debug] [-o output_file]

Where:

• -r [repository_path]: Path to the repository directory.
• -c [platform_cfg_file]: Platform parameters configuration file. See #CustomizingyourPlatform. Default: /usr/local/etc/daemons.conf
• -i [xitf_cfg_file]: External interfaces configuration file. See #CustomizingyourPlatform. Default: /usr/local/etc/xitf.conf
• --daemon: Run PHAL in background. Default: Foreground.
• --no-daemon: Run PHAL in foreground.
• --debug: Run in debug mode. Do not kill objects at real time failures.
• -o [output_file]: File to redirect standard output when running as background. Default: output.log

Customizing your Platform

ALOE Linux launcher admits two configuration files as arguments which modify certain Platform parameters. In this section we describe how to configure such parameters and what implications do they have:

Platform Configuration File: This file configures processor options and selects which daemons will be launched by runph. You can add or remove them according to which daemons you need in your platform. By default, any platform should run the following daemons:

• frontend
• swload
• exec
• bridge
• sync
• stats

Optionally, the following daemons can be set:

• swman
• hwman
• statsman
• sync_master

A single-processor configuration should launch all the daemons except sync and sync_master (synchronization is not needed). See MultiProcessorGuide to learn how to work with multi-processors. In the Platform Configuration File, you will find typical configuration sets.

Some of the parameters can be overriden by arguments in the runph command. The following parameters are available in the Platform Configuration File, also documented in the file:

• name: The name of the processor.
• mips: Capacity in MIPS of your computer.
• nof_cores: Number of SMP cores.
• tslot: Duration of the time slot, in microseconds.
• run_as_daemon: Run in background.
• output_file: File to redirect standard output.
• work_path: Path to the repository directory
• printbt_atexit: Print backtrace at object's real time fault
• printbt_atexit: Print backtrace at object's exit (overrides atrtfault)
• itfs_delay: Object Interfaces default delay. Typical values are: [0,1,2]
• debug_mode: Disable real time monitoring (Debug mode)

External Interfaces Configuration File: This files has one section for each external TCP interface of your platform. Before creating a network of ALOE platforms, you should be very familiar with the ALOE Environment concepts as it compromises selecting which daemons will run every platform, which depends on your network architecture. The format of the file is a set of sections ([xitf]) with the following mandatory fields:

• id: Identification of the interface (hexadecimal 16-bit integer). Not any value is accepted as it is used by daemons to discover the purpose of the interface. It must be one of the following:
  • 0x1: Master Control Interface.
  • 0x1n: n=[0..F], Slave Control Interface.
  • 0xpq: p=[2..F],q=[0..F], Data Interfaces
• address: IP address of the interface. For input interfaces it will be the one to bind to, for output ones, it will be the remote one.
• bw: Bandwidth (in bps) of the interface. Only for output interfaces.
• port: IP port for the connection.
• mode: Direction of the interface, can be one of the following:
  • in: Input interface (data only)
  • out: Output interface (data only)
  • inout: Input/Output interface, listening socket, typically for slave control interfaces
  • outin: Input/Output interface, output socket, typically for master control interface.

Launching ALOE as a Daemon

Running ALOE in background is often interesting when long time executions are going to be performed. In foreground executions, disconnecting user terminal (or ssh session) will kill ALOE processes. This can be avoided if the user launches ALOE with the daemon option (as an argument or in the platform configuration file, see above).

Running ALOE in background:

1. Modify Platform configuration file, adding the field run_as_daemon=yes to the CPU section or launch ALOE with the --daemon argument.
2. Modify Platform configuration file, adding the field output_file=hwapi_log_file to the CPU section or launch ALOE with the -o hwapi_log_file argument.
3. Launch ALOE:

     sudo runph
   

   from any directory and ALOE will be started at background.
4. Now to issue commands you must connect to cmdman daemon (from a local or remote machine) launch cmdman in remote mode specifying the IP address where ALOE is running:

     cmdman -c 127.0.0.1
   

   where 127.0.0.1 should obviously be replaced by the IP address of the host where you launched the daemon. In this screen, you can type commands as usual and exit typing Ctrl+C. You will notice as you can re-connect with the same command and perform more commands. At this point, you can exit your ssh session normally. ALOE will keep running at background. When you login again, connect again with the previous cmdman command. Also, keep track of the output files (specified in the configuration file) for errors or unusual behaviour.
5. Finally, you can kill ALOE by sending a INT signal. ALOE installs a simple shell command to do such:

     killph
   

Running a waveform: Basic ALOE commands

ALOE can be controlled from a text console by typing commands. Basically, running a waveform compromises 3 steps: loading, initializing and running. You will do such by typing the appropriate commands in the input console. In the next example, we will load, initialise and run the example waveform.

Once ALOE has been started we load the waveform typing in the prompt:

runph$: phload example

then initialize:

runph$: phinit example

and finally run:

runph$: phrun example

Now the waveform is running. We can see current processes information typing:

runph$: execinfo example

Or the available statistics

runph$: statls example

You also can pause the execution or run a finite number of steps, type:

runph$: phpause example
runph$: phrun example 1000

List of ALOE commands

This is the list of all ALOE commands:

• help: Display list of commands.
• phload: Load application. Args: phload app_name.
• phrun: Run application. Args: phrun app_name.
• phinit: Init application. Args: phinit app_name.
• phpause: Pause application. Args: phpause app_name.
• phstep: Step application. Args: phstep app_name.
• phstop: Stop application. Args: phstop app_name.
• statlist: List statistics. Args: statlist app_name [obj_name].
• statset: Modify statistic. Args: statset app_name obj_name stat_name new_value.
• statget: Get a statistic value. Args: statget app_name obj_name stat_name.
• statreport: Start/stop report. Args: statreport start/stop app_name obj_name stat_name window_len period.
• applist: List applications.
• pelist: List PE in platform.
• execinfo: Exec information. Args: execinfo app_name [obj_name].
• exit: Exit this program.

Performance Notes

To get the best performance of your waveform, the following hints may be useful:

• Compile your modules with highest optimization and specify your processor architecture. You can pass CFLAGS to the default configure script. At source type:

   ./configure CFLAGS='-O3 -march=native -mfpmath=sse'
   make clean && make && sudo make install
  

  if you have a pentium/athlon processor with sse extensions. Or:

   ./configure CFLAGS='-O3 -march=armv5te'
   make clean && make && sudo make install
  

  to optimize for the SheevaPlug?.

• Increase Kernel time resolution. Another measure you can adopt to achieve a higher performance is increasing the kernel timer frequency. To do so, you must recompile your kernel. How to do that is out of the scope of this document, however, if you use menuconfig, the option you have to change is at Processor type and features->Timer frecuency (CONFIG_HZ). Setting that to 1000 Hz implies a resolution of 1ms which, with at 10ms slot duration should be enough.

[Back to ALOE]