Context Navigation

Changes between Version 10 and Version 11 of ALOELinuxGuide

Timestamp:: 02/13/10 20:35:53 (15 years ago)
Author:: ismael (IP: 62.57.1.15)
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

ALOELinuxGuide

v10	v11
4	4	If you plan to develop applications or you just want to learn more about ALOE, you should read the [wiki:WaveformDeveloperGuide Waveform Developer Guide].
5	5
6		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.
	6	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.
7	7
8	8	[[BR]]
…	…
10	10	== Launching ALOE ==
11	11
12		If you downloaded ALOE from source, take a look at the 'example-repository' directory. This directory is where Manager Daemons will ~~look for configuration files, waveform definitions files and executables (and so on). This path will be passed as the first argument to the ALOE launcher~~.
	12	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).
13	13
14	14	You will see that this directory has, among others, the following '''mandatory''' subdirectories:
15		* logs: Here waveform's modules will store their logs, in per-waveform sub-directories.
16		* reports: This is where statistics value reports are written
17		* swman_execs: Here modules' binaries can be reached (can contain symbolic links), in per-platform sub-directories.
18		* swman_apps: Path for application definitions (e.g.: wimax.app)
19		* statsman: Initialization parameter definitions, in per-waveform sub-directories.
20
21		'''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.
22
23		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.
24
25		So, launching ALOE is as easy as going to the source directory and type:
	15	* logs: Module logs in a directory for each waveform.
	16	* reports: Module statistic reports in a directory for each waveform.
	17	* statsman: Module initialization parameters in a directory for each waveform.
	18	* swman_execs: Module binaries in a directory for each platform.
	19	* swman_apps: Application descriptions.
	20
	21	'''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.
	22
	23	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:
26	24
27	25	{{{
…	…
29	27	}}}
30	28
31		'''NOTE:''' To run ALOE ~~at highest performance, it should be executed with '''root''' permissions. Simply launch it with sudo~~:
	29	'''NOTE:''' To run ALOE with real-time priorities, run it with '''root''' permissions.:
32	30	{{{
33	31	sudo runph
34	32	}}}
35	33
36
37		[[BR]]
38
39		More optional arguments can be passed to runph in the shell. The command accepts the following arguments:
40		{{{
41		runph -r [repository_path] -c [platform_cfg_file] -i [xitf_cfg_file] [--daemon] [-o output_file]
	34	This will launch a default single-processor configuration.
	35
	36	[[BR]]
	37
	38	runph is configured with a platform configuration file. However, shell arguments can be used to override some options. The command accepts the following arguments:
	39	{{{
	40	runph -r [repository_path] -c [platform_cfg_file] -i [xitf_cfg_file] [--daemon]\|[--no-daemon] [-o output_file]
42	41	}}}
43	42	Where:
44		* ''-r [repository_path]'': Location where cofiguration, executables and applications subdirectories are found (see before).
45		* ''-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
46		* ''-i [xitf_cfg_file]'': Configuration file for external interfaces, see Customizing your Platform. ''Default'': /usr/local/etc/xitf.conf
47		* ''--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.
48		* ''-o [output_file]'': File to redirect standard output. ''Default'': None, terminal stdout.
49
50
51		[[BR]]
52
53		== Running a waveform: Basic ALOE commands ==
54
55		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.
56
57		Once ALOE has been started (by default typing {{{ runph }}} from the source directory, we will load the waveform by typing in the prompt:
58		{{{
59		runph$: phload example
60		}}}
61
62		then initialize:
63		{{{
64		runph$: phinit example
65		}}}
66
67		and finally run:
68		{{{
69		runph$: phrun example
70		}}}
71
72		Now the waveform is running. We can see current processes information typing:
73		{{{
74		runph$: execinfo example
75		}}}
76
77		Or the available statistics
78		{{{
79		runph$: statls example
80		}}}
81
82		You also can pause the execution or run a finite number of steps, type:
83		{{{
84		runph$: phpause example
85		runph$: phrun example 1000
86		}}}
	43	* ''-r [repository_path]'': Path to the repository directory.
	44	* ''-c [platform_cfg_file]'': Platform parameters configuration file. See [#CustomizingyourPlatform]. ''Default'': /usr/local/etc/daemons.conf
	45	* ''-i [xitf_cfg_file]'': External interfaces configuration file. See [#CustomizingyourPlatform]. ''Default'': /usr/local/etc/xitf.conf
	46	* ''--daemon'': Run PHAL in background. ''Default'': Foreground.
	47	* ''--no-daemon'': Run PHAL in foreground.
	48	* ''-o [output_file]'': File to redirect standard output when running as background. ''Default'': output.log
	49
87	50
88	51	[[BR]]
…	…
92	55	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:
93	56
94		'''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:
95		* ''path'': Path where the executable is.
96		* ''output'': File to redirect standard output (for logging purposes)
97
98		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.
	57	'''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:
	58	* frontend
	59	* swload
	60	* exec
	61	* bridge
	62	* sync
	63	* stats
	64
	65	Optionally, the following daemons can be set:
	66	* swman
	67	* hwman
	68	* statsman
	69	* sync_master
	70
	71	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.
	72
	73	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.
99	74	* ''name'': The name of the processor.
100	75	* ''mips'': Capacity in MIPS of your computer.
…	…
103	78	* ''run_as_daemon'': Run in background.
104	79	* ''output_file'': File to redirect standard output.
105		* ''report_file'': File where save hw info reports
106		* ''priority'': Priority level for objects
	80	* ''work_path'': Path to the repository directory
107	81
108	82	'''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:
…	…
112	86	* 0xpq: p=[2..F],q=[0..F], Data Interfaces
113	87	* ''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.
	88	* ''bw'': Bandwidth (in bps) of the interface. Only for output interfaces.
114	89	* ''port'': IP port for the connection.
115	90	* ''mode'': Direction of the interface, can be one of the following:
…	…
123	98	== Launching ALOE as a Daemon ==
124	99
125		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) and appropriate selects an output file.
126
127		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).
128
129		To do so, make sure you follow these steps:
	100	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).
	101
	102	Running ALOE in background:
130	103	1. Modify Platform configuration file, adding the field '''run_as_daemon'''=''yes'' to the CPU section or launch ALOE with the '''--daemon''' argument.
131	104	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.
132		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:
	105	3. Launch ALOE:
133	106	{{{
134		[cpu_info]
135		mips=...
136		tslot=...
137		...
138		run_as_daemon=yes
139		output_file=/path/to/mylog/hwapi_output.log
140		work_path=/path/to/phal-repositories/
141		...
142		[daemon]
143		...
144		[daemon]
145		path=cmdman -l -d
146		}}}
147		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:
148		{{{
149		runph
	107	sudo runph
150	108	}}}
151	109	from any directory and ALOE will be started at background.
152		5. Now to ~~perform commands you must connect to it (from a local or remote machine)~~:
	110	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:
153	111	{{{
154	112	cmdman -c 127.0.0.1
…	…
164	122	[[BR]]
165	123
	124
	125	== Running a waveform: Basic ALOE commands ==
	126
	127	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.
	128
	129	Once ALOE has been started we load the waveform typing in the prompt:
	130	{{{
	131	runph$: phload example
	132	}}}
	133
	134	then initialize:
	135	{{{
	136	runph$: phinit example
	137	}}}
	138
	139	and finally run:
	140	{{{
	141	runph$: phrun example
	142	}}}
	143
	144	Now the waveform is running. We can see current processes information typing:
	145	{{{
	146	runph$: execinfo example
	147	}}}
	148
	149	Or the available statistics
	150	{{{
	151	runph$: statls example
	152	}}}
	153
	154	You also can pause the execution or run a finite number of steps, type:
	155	{{{
	156	runph$: phpause example
	157	runph$: phrun example 1000
	158	}}}
	159
	160	[[BR]]
	161
	162
	163	== List of ALOE commands ==
	164
	165	This is the list of all ALOE commands:
	166
	167	* help: Display list of commands.
	168	* phload: Load application. Args: phload app_name.
	169	* phrun: Run application. Args: phrun app_name.
	170	* phinit: Init application. Args: phinit app_name.
	171	* phpause: Pause application. Args: phpause app_name.
	172	* phstep: Step application. Args: phstep app_name.
	173	* phstop: Stop application. Args: phstop app_name.
	174	* statlist: List statistics. Args: statlist app_name [obj_name].
	175	* statset: Modify statistic. Args: statset app_name obj_name stat_name new_value.
	176	* statget: Get a statistic value. Args: statget app_name obj_name stat_name.
	177	* statreport: Start/stop report. Args: statreport start/stop app_name obj_name stat_name window_len period.
	178	* applist: List applications.
	179	* pelist: List PE in platform.
	180	* execinfo: Exec information. Args: execinfo app_name [obj_name].
	181	* exit: Exit this program.
	182
	183	[[BR]]
	184
166	185	== Performance Notes ==
167	186
168	187	To get the best performance of your waveform, the following hints may be useful:
169		* Compile your modules with '''highest optimization''' and specify your processor architecture~~, e.g.~~:
	188	* Compile your modules with '''highest optimization''' and specify your processor architecture. You can pass CFLAGS to the default configure script. At source type:
170	189	{{{
171		gcc -O3 -march=native -mfpmath=sse
	190	./configure CFLAGS='-O3 -march=native -mfpmath=sse'
	191	make clean && make && sudo make install
172	192	}}}
173		if you have a pentium/athlon processor with sse extensions.
174
175		* '''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.
	193	if you have a pentium/athlon processor with sse extensions. Or:
	194	{{{
	195	./configure CFLAGS='-O3 -march=armv5te'
	196	make clean && make && sudo make install
	197	}}}
	198	to optimize for the SheevaPlug.
	199
	200	* '''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.
176	201
177	202