Changes between Version 18 and Version 19 of ObjectDeveloperGuide

Show
Ignore:
Timestamp:
02/09/10 11:03:37 (15 years ago)
Author:
antoni (IP: 192.168.100.175)
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • ObjectDeveloperGuide

    v18 v19  
    22ALOE generates waveforms by linking a set of Signal Processing blocks following a defined graph. The concatenation of each processing function, applied to a flow of data produces the desired signal. Each of these components must be written (in ANSI C) following a set of rules which enable it to interact with the rest of components and with the underlying Operating Environment. 
    33 
    4 A Signal Processing Block or '''"ALOE Object"''' has the following properties: 
     4A Signal Processing Block or '''"ALOE Module"''' has the following properties: 
    55 
    66 * A set of ''input ''interfaces 
    … …  
    1313 * Generates data for a set of output streams as a function of any, one or more input streams 
    1414 
    15 == Defining an Object == 
    16 Given the previous definition of an object, we will organize object files following this directory structure: 
     15== Defining a Module == 
     16Given the previous definition of a module, we will organize module files following this directory structure: 
    1717 
    1818||'''Directory'''||'''Files'''||'''Comment'''|| 
    19 ||''myobj''/platform_make/||...||One directory for each platform it can be compiled. For example:[[BR]]''lnx_make'' shall contain the Makefile, ''c6000_make'' shall contain CCS' .pjt files, etc.|| 
    20 ||''myobj''/interfaces/||inputs.h[[BR]]outputs.h[[BR]]stats.h||Definition of input/output interfaces, statistics variables and initialization parameters|| 
    21 ||''myobj''/src/||module.c[[BR]]module_imp.c[[BR]]myobj.c||myobj.c: Standalone function implementing the algorithm.[[BR]]module.c and module_imp.c is the skeleton[[BR]]See below for more information|| 
    22 ||''myobj''/bin/||myobj||Binaries after compilation and linking are placed here.|| 
     19||''mymod''/platform_make/||...||One directory for each platform it can be compiled. For example:[[BR]]''lnx_make'' shall contain the Makefile, ''c6000_make'' shall contain CCS' .pjt files, etc.|| 
     20||''mymod''/interfaces/||inputs.h[[BR]]outputs.h[[BR]]stats.h||Definition of input/output interfaces, statistics variables and initialization parameters|| 
     21||''mymod''/src/||module.c[[BR]]module_imp.c[[BR]]mymod.c||mymod.c: Standalone function implementing the algorithm.[[BR]]module.c and module_imp.c is the skeleton[[BR]]See below for more information|| 
     22||''mymod''/bin/||mymod||Binaries after compilation and linking are placed here.|| 
    2323 
    2424==  == 
    25 == Implementing the Object == 
    26 Once your object has been properly defined, you can begin coding it. Here we assume the reader is familiar with basic ALOE concepts, nevertheless, this section describes how to implement an ALOE Object and provides some examples. 
     25== Implementing the Module == 
     26Once your module has been properly defined, you can begin coding it. Here we assume the reader is familiar with basic ALOE concepts, nevertheless, this section describes how to implement an ALOE Module and provides some examples. 
    2727 
    2828=== Process Structure === 
    … …  
    3434Return” 
    3535}}} 
    36 Figure 1 represents this concept. Notice how the object must announce its presence to ALOE prior to receive any order. 
    37  
    38 The first order the object will receive will be to initialize (INIT) itself. Then, the object will read a set of initialization parameters, activate the communications interfaces and declare a set of statistics variables (for monitoring purposes). This procedure is executed just once in the life-cycle of the object. 
     36Figure 1 represents this concept. Notice how the module must announce its presence to ALOE prior to receive any order. 
     37 
     38The first order the object will receive will be to initialize (INIT) itself. Then, the module will read a set of initialization parameters, activate the communications interfaces and declare a set of statistics variables (for monitoring purposes). This procedure is executed just once in the life-cycle of the module. 
    3939 
    4040If an execution order is received (RUN), the object will receive any pending message, dispatch the required task (for example process a block of data received from an interface and send the result through another interface) and return to the initial point. 
    4141 
    42 The last case is the reception of the order to close (STOP) the object. In such case, the object must tell to ALOE to close all the allocated resources and finish its execution. 
    43  
    44 Note how the object owns the CPU during the time it process the message. After that, the object returns to the STATUS point handing the CPU over to ALOE again. In anomalous or time rules violation, ALOE may release the ownership from the object before returning to the STATUS point. 
     42The last case is the reception of the order to close (STOP) the module. In such case, the module must tell to ALOE to close all the allocated resources and finish its execution. 
     43 
     44Note how the module owns the CPU during the time it process the message. After that, the object returns to the STATUS point handing the CPU over to ALOE again. In anomalous or time rules violation, ALOE may release the ownership from the module before returning to the STATUS point. 
    4545 
    4646=== Coding an Object === 
    47 The programming language used to describe an object may change between different processing devices, depending on the tools provided by the device manufacturer. However, it would be very interesting to use always the same language so the code can be reused. This is unrealistic, because currently programmable devices as GPP or DSP can use C/C++ while others like logic programmable devices as FPGA use totally different languages (VHDL). 
     47The programming language used to describe a module may change between different processing devices, depending on the tools provided by the device manufacturer. However, it would be very interesting to use always the same language so the code can be reused. This is unrealistic, because currently programmable devices as GPP or DSP can use C/C++ while others like logic programmable devices as FPGA use totally different languages (VHDL). 
    4848 
    4949Nevertheless, these are the chosen standard programming language for the ALOE Framework: 
    … …  
    5555Not only the use of a standard language is a requirement to enable the whole set of functionalities provided by ALOE. Also the use of the ALOE Software Library API is a requirement as well as other considerations. At this point, we strongly recommend the reader to check [htdocs:swapi_doc/index.html ALOE SW-API Documentation] to get an insight on the available functions and its behaviour. 
    5656 
    57 An Object designer must be concerned about the misinformation of the final platform to be executed on. This means that very important concepts (in software radio) like sampling frequency, time slot duration, memory distribution or architecture, etc. are totally unknown when objects are designed. Thus, it would need to support such sort of frequency ranges and architectures under parameter reconfigurations. 
    58  
    59 A special function provided by the ALOE Software Library API will serve for this purpose. The number of samples to be generated every time the object is executed (every time slot) will be obtained using the following function: 
     57A Module designer must be concerned about the misinformation of the final platform to be executed on. This means that very important concepts (in software radio) like sampling frequency, time slot duration, memory distribution or architecture, etc. are totally unknown when objects are designed. Thus, it would need to support such sort of frequency ranges and architectures under parameter reconfigurations. 
     58 
     59A special function provided by the ALOE Software Library API will serve for this purpose. The number of samples to be generated every time the module is executed (every time slot) will be obtained using the following function: 
    6060 
    6161{{{ 
    6262int GetTempo(float freq); 
    6363}}} 
    64 This function receive as parameter the frequency the object desires to operate. As the environment (ALOE) is the only who knows the execution interval associated to the process, a simply operation will be done to calculate the number of samples to be generated at that precise moment. The amount of samples that the object needs at its input will depend on the algorithm, more precisely, in the rate relation between the input and output frequency. Anyway, the object will wait until all the data it needs is available. Note that this could lead to time violations if frequency relations between collateral objects are not defined with caution. 
    65  
    66 In order to facilitate objects programming an skeleton implementing some common functionalities has been defined. In this sense, the user will only have to define the interfaces in a constant structure and provide some functions to process data. The initialization and buffer management will be done by the skeleton. 
     64This function receive as parameter the frequency the module desires to operate. As the environment (ALOE) is the only who knows the execution interval associated to the process, a simply operation will be done to calculate the number of samples to be generated at that precise moment. The amount of samples that the module needs at its input will depend on the algorithm, more precisely, in the rate relation between the input and output frequency. Anyway, the object will wait until all the data it needs is available. Note that this could lead to time violations if frequency relations between collateral objects are not defined with caution. 
     65 
     66In order to facilitate modules programming an skeleton implementing some common functionalities has been defined. In this sense, the user will only have to define the interfaces in a constant structure and provide some functions to process data. The initialization and buffer management will be done by the skeleton. 
    6767 
    6868This skeleton is provided in the module.c file and is exactly the same for any object (so you can copy anyone provided by the example objects). The skeleton needs three header files: inputs.h, outputs.h and stats.h. Interfaces and statistics are defined in structures (defined in swapi_utils.h) which name has to be mantained (input_itfs, output_itfs, params and stats). The following figure describe these structures: 
    … …  
    215215 
    216216}}} 
    217 The last two functions ({{{InitCustom()}}} and {{{RunCustom()}}}) have also to be defined. The {{{InitCustom}}} function is used to implement custom initialization routines not related with interface or statistics initialization. For example, if an object has to compute a set of filter coeficients given an initialization parameter, it can be done in this function. The skeleton will get the parameter(s) value if we define it in the specific structure. After that, the {{{InitCustom}}} function will be called and we will perform the computations.  
     217The last two functions ({{{InitCustom()}}} and {{{RunCustom()}}}) have also to be defined. The {{{InitCustom}}} function is used to implement custom initialization routines not related with interface or statistics initialization. For example, if a module has to compute a set of filter coeficients given an initialization parameter, it can be done in this function. The skeleton will get the parameter(s) value if we define it in the specific structure. After that, the {{{InitCustom}}} function will be called and we will perform the computations.  
    218218 
    219219Analogously, the {{{RunCustom}}} function might be useful to perform some background tasks not related directly with data processing (more formally, asyncrhonous with data flow). An example of this may be updating an internal state. 
    … …  
    238238 
    239239== Compiling and Linking == 
    240 Compiling an ALOE objects does not need any other consideration rather than linking with the ALOE SW Library and HW Library. Obviously, we have to pick the HW library of our system. Under linux, and once we have installed ALOE (binary or source), the libraries should appear at /usr/local/lib with the names libsw_api.a and libhw_api.a. 
     240Compiling an ALOE modules does not need any other consideration rather than linking with the ALOE SW Library and HW Library. Obviously, we have to pick the HW library of our system. Under linux, and once we have installed ALOE (binary or source), the libraries should appear at /usr/local/lib with the names libsw_api.a and libhw_api.a. 
    241241 
    242242If your prefer to use autoconf/automake tools you might find useful the example Makefile.am included in the sample modules shipped in the ALOE distribution (under lnx_make).