= ALOE Waveform Developer Guide =

Here you will find information on how to design, debug and test Software Radio applications for ALOE.

== Creating Waveforms ==
Creating a new waveform is as simple as link the set of processing blocks' (or objects') interfaces that compromise the whole waveform. Future releases of ALOE plan to use a graphical front-end to perform this task, currently, however, you must do it by editing a text file. 

In this text file you must indicate the modules you want to load (and their executable file name), their interfaces and how they should be interconnected. The following example illustrates how it must be written. In the example, a single executable (test_exec) is launched as two instances, each is assigned a different object name and different interfaces.

[[BR]]

'''Listing 1: Waveform definition'''
{{{

object {                    # begins a description of a new obje t
        obj_name=test_w     # object name used in ALOE (must be unique)
        exe_name=test_exec  # executable name in the system (as SWMAN will access)
        proc=100            # processing demand (in MIPS)

        outputs {                             # begins output interfaces definitions
                name=test_w_itf               # name of the output interface (as the object will use in its code)
                remote_itf=test_r_itf         # name of the remote interface
                remote_obj=test_r             # name of the remote objec
        }
        outputs {                             # another output could just be added...
                name=output_2
                remote_itf=...
                remote_obj=...
        }
                

}

object {
        obj_name=test_r        # Note how we instantiate another object with a different name, although the executable is the same            
        exe_name=test_exec
        proc=100

        inputs {
                name=test_r_itf
                remote_itf=test_w_itf
                remote_obj=test_w
        }
}

}}}

Once you have created this file, you have to rename to ''your_waveform_name.app'' and save in your swman_apps directory. Don't forget to make accessible the executables at the swman_execs/'''platform'''/ path. 
 
[[BR]]
[[BR]]

== Debugging Waveforms ==

Once your ALOE is running, and just after loading the application, you can attach to the running process using your favourite debugger (gdb, ddd, eclipse, etc.). The following steps explain how to debug a waveform component:

1. Launch ALOE with the debug option argument. This will prevent the components to be killed when stopped by the debugger:

{{{
 runph phal-repositories --debug
}}}

2. On the prompt, as usual, load your waveform

{{{
 runph$: phload my_app
}}}

3. Open your debugger and attach to the component process. 

4. Back to the runph prompt, type:

{{{
 runph$: phinit my_app
}}}

5. If you placed a breakpoint in the initialization phase, you will see how the program stops on it. You can continue the execution (step by step or free running) until the component arrives to the Status() call. At that point, you can begin to debug the RUN phase. We recommended using  phstep execution, because you can place a breakpoint anywhere in the RUN piece of code and you will see how the program stops on every timeslot. In the runph prompt type:

{{{
 runph$: phstep my_app
}}}

6. Leave the component in free-run, it will fall to idle, until the next step, so, go back to runph prompt and type ''phstep'' again. Remember that you also have the option to remove breakpoints and run a finite number of steps, you can do so by typing, in the runph prompt:

{{{
 runph$: phrun my_app 100
}}}

To run 100 timeslots.


[[BR]]
[[BR]]

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