P-HAL 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 P-HAL Developer Guide? and the P-HAL 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.

At this point we assume that you have downloaded and installed P-HAL on your computer (see Install Guide?) and that your are familiar with Linux at user level.

Launching P-HAL

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:

svn checkout http://147.83.118.229/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
• swman_execs: Here modules' binaries can be reached (can contain symbolic links)
  • linux: Path for Linux modules' binaries
• swman_apps: Path for application definitions (e.g.: wimax.app)
• statsman: Initialization parameter definitions, separated by application
  • app_x: Parameters for app_x

If you follow this guide and plan to launch Wimax waveform (see next), you won't need to modify any of these files.

NOTE: Make sure that swman_execs/linux contains (or links to) the binaries for your waveform 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:

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.

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]

Where:

• [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
• -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.

Downloading a waveform: Wimax

You can download the latest version of the Wimax waveform from our repository: Remember that you will be prompted for a valid username.

svn checkout http://147.83.118.229/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 Subversion Manual to learn more about this powerful tool.

Running a waveform: Basic P-HAL 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:

Once P-HAL has been started with the appropriate arguments (see first section), we will load the waveform by typing in the prompt:

runph$: phload wimax

then initialize:

runph$: phinit wimax

and finally run:

runph$: phrun wimax

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

runph$: hwcmd info
runph$: hwcmd ps

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

runph$: phpause wimax

runph$: phrun wimax 1000

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:

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?). The CPU configuration section, has two fields:

• mips: Capacity in MIPS of your computer.
• tslot: Duration of the time slot, in microseconds.

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:

• 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

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.

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