Changes between Version 14 and Version 15 of PhalUserGuide

Timestamp:

03/23/09 12:41:19 (16 years ago)

Author:

ismael (IP: 62.57.1.15)

Comment:

--

PhalUserGuide

@@ -1 @@
-= P-HAL User Guide =
+= ALOE Linux User Guide =
 
-This section describes first steps on launching and running a waveform in P-HAL. 
-If you plan to develop applications or you just want to learn more about P-HAL, you should read the [wiki:PhalDeveloperGuide P-HAL Developer Guide] and the [wiki:PhalManual P-HAL Manual].
+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:PhalDeveloperGuide ALOE Developer Guide] and the [wiki:PhalManual ALOE Manual].
 
-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 P-HAL commands.
+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 P-HAL on your computer (see [wiki:PhalInstallGuide Install Guide]) and that your are familiar with Linux at user level.
+At this point we assume that you have downloaded and installed ALOE on your computer (see [wiki:PhalInstallGuide Install Guide]) and that your are familiar with Linux commands at user level.
 
 [[BR]]
 
-== Launching P-HAL ==
+== Launching ALOE ==
 
-Before starting P-HAL, you must create a directory where Manager Daemons will look for configuration files, application definitions and executables (PhalManual). This path will be passed as the first parameter to the P-HAL launcher. You can download a sample directory from our repository:
+Before starting ALOE, you must create a directory where Manager Daemons will look for configuration files, application definitions and executables (PhalManual). This path will be passed as the first parameter to the ALOE launcher. You can download a sample directory from our repository:
 
 {{{
-svn checkout http://147.83.118.229/svn/phal-apps/trunk/phal-repositories
+svn checkout http://flexnets.upc.edu/svn/phal-apps/trunk/phal-repositories
 }}}
 
 You will see that this directory as, 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)
@@ -28 +29 @@
 '''NOTE''': Make sure that swman_execs/linux contains (or links to) your waveform binaries compiled for the platform you plan to launch them.
 
-Now you can launch P-HAL console passing the phal-repositories path (just downloaded) as an argument:
+Now you can launch ALOE console passing the phal-repositories path (the one you downloaded) as an argument:
 {{{
 runph phal-repositories
 }}}
 
-You just got into the P-HAL environment! By the moment, you can't do anything because you need to download an application first. This will be explained in the following section. After that, we will see how it can be loaded and run. 
+You just got into the ALOE environment! By the moment, you can't do anything because you need to download an application first. This will be explained in the following section.
 
 [[BR]]
@@ -39 +40 @@
 More optional arguments can be passed to runph in the shell. The command accepts the following arguments:
 {{{
-runph [repository_path] -c [platform_cfg_file] -i [xitf_cfg_file] -p [priority] -d [debug_level] -r [fifo_report] [--daemon] [-o output_file]
+runph [repository_path] -c [platform_cfg_file] -i [xitf_cfg_file] -p [priority] -d [debug_level] [--daemon] [-o output_file]
 }}}
 Where:
@@ -47 +48 @@
  * ''-p [priority]'': Needs root privileges. Kernel priority level for waveform processes, see Performance Notes. ''Default'': 20
  * ''-d [debug_level]'': Sets platform debug level. Currently only 2 modes are supported, level=0 or level!=0, where the first means normal operation and the second prevents EXEC daemon to kill processes which violated real time policies. ''Default'': 0
- * ''-r [fifo_report]'': File where the platform will log (in columns, for Matlab compatibility) the instantaneous waveform internal fifo utilization (in kilobytes). ''Default'': No report.
- * ''--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 P-HAL as a Daemon). ''Default'': Foreground.
+ * ''--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.
 
@@ -59 +59 @@
 
 {{{
-svn checkout http://147.83.118.229/svn/phal-apps/trunk/wimax
+svn checkout http://flexnets.upc.edu/svn/phal-apps/trunk/wimax
 }}}
 
-This will download all the files to a directory called wimax. You can enter there and compile your files as usually, paying attention on '''linking them to the P-HAL SW API Library''' (see DeveloperGuide).
-
-Remember that you can commit your changes in the application using the Subversion service, just get into the wimax directory and type:
-{{{
-svn commit 
-}}}
-
-To download the latest version in the server type (again, from the downloaded directory):
-{{{
-svn update
-}}}
-
-These commands, however, can create conflicts if other users are working with the same files, we recommend to read [http://svnbook.red-bean.com/nightly/en/svn-book.html Subversion Manual] to learn more about this powerful tool.
+This will download all the files to a directory called wimax. You can enter there and compile your files as usually, paying attention on '''linking them to the ALOE SW API Library''' (see DeveloperGuide).
 
 [[BR]]
 
-== Running a waveform: Basic P-HAL commands ==
+== Running a waveform: Basic ALOE commands ==
 
-PHAL can be controlled from a text console typing commands. Again, we recommend you to read PhalManual if you are not familiar with the P-HAL environment. Basically, running a waveform compromises 3 steps: ''loading'', ''initializing'' and ''running''. You will do such by typing the appropiate commands in the input console. In the next example, we will load, initialize and run the example waveform Wimax:
+ALOE can be controlled from a text console 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 Wimax:
 
-Once P-HAL has been started with the appropriate arguments (see first section), we will load the waveform by typing in the prompt: 
+Once ALOE has been started with the appropriate arguments (see first section), we will load the waveform by typing in the prompt: 
 {{{
 runph$: phload wimax
@@ -112 +100 @@
 == Customizing your Platform ==
 
-P-HAL 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:
+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:
@@ -118 +106 @@
  * ''output'': File to redirect standard output (for logging purposes)
 
-In the CPU section, you can specify some default P-HAL configuration parameters. '''Note''': This parameters are overridden by the ones passed as arguments to the P-HAL Launcher. See section above for more details.
+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.
@@ -127 +116 @@
  * ''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 P-HAL platforms, you should be very familiar with the P-HAL 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:
+'''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.
@@ -142 +131 @@
 [[BR]]
 
-== Launching P-HAL as a Daemon ==
+== Launching ALOE as a Daemon ==
 
-Running P-HAL 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 P-HAL processes as they inherit from user session. This can be prevented to happen if the user launches P-HAL with the ''daemon'' option (as an argument or in the platform configuration file, see above) and appropriate selects an output for text messages.
+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 anymore, and a tcp socket should be created for this purpose. Then, another CMDMANAGER process (local or remote) can connect to it and send normal P-HAL commands (as if it was local).
+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 P-HAL with the '''--daemon''' argument.
- 2. Modify Platform configuration file, adding the field '''output_file'''=''hwapi_log_file'' to the CPU section or launch P-HAL with the '''-o''' ''hwapi_log_file'' argument.
+ 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:
   {{{
@@ -166 +155 @@
    path=cmdman -l -p
   }}}
- 4.Then, if you specified '''work_path''' field in your configuration file, note that you can launch P-HAL without specifying a work directory, as it has already been defined. You can, thus, simply do:
+ 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 P-HAL will be started at background.
+  from any directory and ALOE will be started at background.
  5. Now to perform commands you must connect to it (from a local or remote machine):
   {{{
-  cmdman -c 192.168.1.1
+  cmdman -c 127.0.0.1
   }}}
-  where 192.168.1.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. P-HAL will keep running at background. When you login again, connect again with the previous cmdman command. Also, keep track of the output files (specifiyed at the configuration file) for errors or unusual behaviour.
- 6. Finally, you can kill PHAL by sending a INT signal. P-HAL install a simple shell command to do such:
+  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
@@ -194 +183 @@
  if you have a pentium/athlon processor with sse extensions.
 
- * '''Disable statistics or logs'''. These services may use a certain amount of CPU and bandwidth resources, disabling them may increase global performance. You can do that entering the following command in the P-HAL console:
- {{{
- runph$: hwcmd stats_off
- runph$: hwcmd logs_off
- }}}
- You can re-enable them substituting 'off' by 'on'.
-
  * Run waveform processes with '''higher priority'''. Use the optional argument ''-p [priority]'' 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 may be quite enough.
+ * '''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.