= 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 [wiki:WaveformDeveloperGuide Waveform Developer Guide].

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

[[BR]]

== 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.

[[BR]]

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] [-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.
 * ''-o [output_file]'': File to redirect standard output when running as background. ''Default'': output.log


[[BR]]

== 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. 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 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. 
 * ''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
 
'''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.

[[BR]]

== 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.
 5. 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.
 6. Finally, you can kill ALOE by sending a INT signal. ALOE installs a simple shell command to do such:
  {{{
  killph
  }}}
 

[[BR]]


== 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
}}}

[[BR]]


== 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.

[[BR]]

== 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.


[[BR]]
[[BR]]
[wiki:ALOE "[Back to ALOE]"]