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.

Here you will learn how to download a waveform from our repository (you will need a user/pwd to access) and launch it. You will also get familiar with most of ALOE commands.

At this point we assume that you have downloaded and installed ALOE on your computer (see Install 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 'examples' directory. There you will see the implementation of 3 ALOE objects (source, decimator and sink) and another folder called repository. This directory is where Manager Daemons will look for configuration files, waveform definitions files and executables (and more things...). This path will be passed as the first argument to the ALOE launcher.

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

• logs: Here waveform's modules will store their logs, in per-waveform sub-directories.
• reports: This is where statistics value reports are written
• swman_execs: Here modules' binaries can be reached (can contain symbolic links), in per-platform sub-directories.
• swman_apps: Path for application definitions (e.g.: wimax.app)
• statsman: Initialization parameter definitions, in per-waveform sub-directories.

NOTE: Make sure that swman_execs/linux contains (or links to) your waveform binaries compiled for the platform you plan to launch them. In the case of the example waveforms, the executables at placed at /usr/local/bin during the installation then, this is where the linux folder should link to.

Also during the installation, the default repository folder has been set to one provided in the source package, relative to the path where you untar'd it.

So, launching ALOE is as easy as going to the source directory and type:

runph

More optional arguments can be passed to runph in the shell. The command accepts the following arguments:

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

Where:

• -r [repository_path]: Location where cofiguration, executables and applications subdirectories are found (see before).
• -c [platform_cfg_file]: Configuration file for platform parameters and list of daemons to launch, see Customizing your Platform, below. Default: /usr/local/etc/daemons.conf
• -i [xitf_cfg_file]: Configuration file for external interfaces, see Customizing your Platform. Default: /usr/local/etc/xitf.conf
• --daemon: Run PHAL in background. You should specify an output file (for standard output) so you can track what's happening. Also cmdman daemon should be launched as a daemon preventing to read from input (see below, Launching ALOE as a Daemon). Default: Foreground.
• -o [output_file]: File to redirect standard output. Default: None, terminal stdout.

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, initialize and run the example waveform.

Once ALOE has been started (by default typing runph from the source directory, we will load the waveform by 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

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 has one mandatory section, [cpu_info], and N optional sections, [daemon]. The second selects which daemons (and their path) will be launched by runph. You can add or remove them according to which daemons you need in your platform (see PhalManual?). This sections have two fields only:

• path: Path where the executable is.
• output: File to redirect standard output (for logging purposes)

In the CPU section, you can specify some default ALOE configuration parameters. Note: This parameters are overridden by the ones passed as arguments to the ALOE Launcher. See section above for more details.

• name: The name of the processor.
• mips: Capacity in MIPS of your computer.
• tslot: Duration of the time slot, in microseconds.
• run_as_daemon: Run in background.
• output_file: File to redirect standard output.
• report_file: File where save hw info reports
• priority: Priority level for objects

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.
• 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 prevented to happen if the user launches ALOE with the daemon option (as an argument or in the platform configuration file, see above) and appropriate selects an output file.

When running in this mode, CMDMANAGER daemon must be also launched as daemon as it can't read commands from standard input any more, and a tcp socket should be created for this purpose. Then, another CMDMANAGER process (local or remote) can connect to it and send normal ALOE commands (as if it was local).

To do so, make sure you follow these steps:

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. Modify Platform configuration file, changing the arguments of the cmdman enabling it to listen to input connections (-l) and run as daemon (-d). At this step, your configuration file should show something like the following:

     [cpu_info]
      mips=...
      tslot=...
      ...
      run_as_daemon=yes
      output_file=/path/to/mylog/hwapi_output.log
      work_path=/path/to/phal-repositories/
      ...
     [daemon]
      ...
     [daemon]
      path=cmdman -l -d
   

   4.Then, if you specified work_path field in your configuration file, note that you can launch ALOE without specifying a work directory, as it has already been defined. You can, thus, simply do:

     runph
   

   from any directory and ALOE will be started at background.
4. Now to perform commands you must connect to it (from a local or remote machine):

     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
   

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, e.g.:

   gcc -O3 -march=native -mfpmath=sse
  

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

• Run waveform processes with higher priority. Run runph as root to set a lower kernel priority to your waveform processes. Normal kernel priorities are 0 and higher, if you choose lower priority for waveform processes, they will low with lower priority which may increase performance and/or time resolution. Use this option with caution, because if your component hangs (i.e. because of an infinite loop), any process would get scheduled, preventing it to be killed, which may totally freeze your computer.

• Increase Kernel time resolution. Another measure you can adopt to achieve a higher performance can be increasing the kernel timer frequency. To do such 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. Setting that to 1000 Hz implies a resolution of 1ms which, with at 10ms slot duration should be enough.

[Back to ALOE]