ComLinC User Manual. Kefei Lu

Size: px

Start display at page:

Download "ComLinC User Manual. Kefei Lu"

Laurence Mervin Harrell
5 years ago
Views:

1 ComLinC User Manual Kefei Lu December 3, 2007

2 Contents 1 Introduction to ComLinC Licensing Getting Started Prerequists How to Compile Using ComLinC ComLinC Basic 4 3 Modulation and Demodulation 5 4 Digital Signal Processing Filtering Wireless Environment 8 1

3 Abstract ComLinC (a COMmunications Library IN C programming language) is a C library for communications research and simulation. It s based on GSL (GNU scientific library). ComLinC aims at providing general, elegent, yet easy-to-use functionality to the frequently encountered problems in communications area. ComLinc is developed by Kefei Lu at the University of Miami since October Currently, ComLinc is still under development. We encourage you to download a copy of the project from the SVN repository, and tell us how you like it. If you have any suggestion, or you are interested in participating the project, please don t hesitate to let me know. You can drop me an or put a post on the forum.

4 Chapter 1 Introduction to ComLinC ComLinC (a COMmunications Library IN C programming language) is a C library for communications research and simulation. It s based on GSL (GNU scientific library). ComLinC aims at providing general, elegent, yet easy-to-use functionality to the frequently encountered problems in communications area. ComLinc is developed by Kefei Lu at the University of Miami since October Currently, ComLinc is still under development. 1.1 Licensing ComLinC is distributed under the terms of the GNU General Public License (GPL). ComLinC is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. ComLinC is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABIL- ITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA USA 1.2 Getting Started Prerequists To compile ComLinC library and make programs which based on ComLinC run, the following applications/libraries are neccesary: GCC GNU scientific library (GSL) You might notice that to make ComLinC work properly, not much things are needed. As a matter of fact it is. Actually, ComLinC should work on any 1

5 platform that GSL is able to work. And, according to GSL website, it is claimed that at least it is able to work under these platforms: SunOS & Solaris 2.x (Sparc) Alpha GNU/Linux, gcc HP-UX 9/10/11, PA-RISC, gcc/cc IRIX 6.5, gcc m68k NeXTSTEP, gcc Compaq Alpha Tru64 Unix, gcc FreeBSD, OpenBSD & NetBSD, gcc Cygwin Apple Darwin 5.4 Hitachi SR8000 Super Technical Server, cc ComLinC/GSL should also work under Windows systems, even without cygwin. But I didn t try that yet How to Compile ComLinC comes with a Makefile in the project main directory. To compile the project to a shared library under GNU Linux, simply type make command. This will produce a libcomlinc.so file in the project main directory. The output screen looks like: gcc -fpic -c -Wall -ggdb -I. -I.. cl_base.c gcc -fpic -c -Wall -ggdb -I. -I.. cl_modem.c gcc -fpic -c -Wall -ggdb -I. -I.. cl_wireless.c gcc -fpic -c -Wall -ggdb -I. -I.. cl_dsp.c gcc -shared -W1,soname,libcomlinc.so -o libcomlinc.so cl_base.o cl_modem.o cl_wireless.o cl_dsp.o As seen, the library is debuggable using GNU GDB. Currently we don t provide an option to the make utility to produce a static library. But this can be done by modify the makefile manually. The library should work under operating systems other than Linux, such as Unix and Windows, because ComLinC is developed upon GNU scientific library (GSL), which should work on OS s other than Linux. Once the library is successfully compiled, you might want to run some tests or demo programs, which are located in the test directory. To make the test programs, type make test. To clean the project directory, use make clean command. This will remove all the object files and the shared library, as well as the test programs, if any. 2

6 1.2.3 Using ComLinC Include the header files Once an application/program is developped based on ComLinC, it needs some settings to get it run. Firstly, make sure that the proper ComLinC header files are included in the program. Basically, the commonly used headers are grouped in cl common.h, so #include <cl_common.h> should be enough most time. In order to let the compiler find where the ComLinC headers locates, passing -IHeaderDIR to the compiler, where HeaderDIR is the directory containing the ComLinC header files. For example: gcc -c -Wall -ggdb yourfile.c -I. This will compile (-c) yourfile.c, and let the program DGB debuggable (-ggdb), warning everything during the compiling (-Wall), also notifying the compiler that the header files are located in current directory (-I.). Linking with ComLinC and GSL After successfully compiling the code, it needs to be linked with ComLinC and GSL. To link with GSL, two libraries are needed to be specified, libgsl and libgslcblas. Similarly, ComLinC s library is libcomlinc. So, to link with those libraries, pass the following arguments to the linker: -lgsl -lgslcblas -lcomlinc. If any of the above libraries are not installed in system library path, an extra argument is need: -Llibdir, where libdir is the directory where those libraries locate. An Important Step, LD LIBRARY PATH So far, the program that make use of ComLinC should work. One last thing to do is to let the dynamic library loader be able to find the shared libraries at run time. To do this, export the following environment value before running: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:libdir, where libdir is the place the shared library locates. To automate this step, put the above command in the.bashrc file in the home directory. Note that this is not necessary if all the necessary libraries are put in the system library path such as /lib or /usr/lib. An Example An example: Suppose the application is test.c. The ComLinC headers are in /home/me/comlinc/include. libcomlinc.so is in /home/me/comlinc. And the compiler is gcc. Then the following operations will make the program run. > gcc -c -Wall -ggdb test.c -I/home/me/comlinc/include > gcc -o test.out test.o -lgsl -lgslcblas -lcomlinc -L/home/me/comlinc > export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/me/comlinc >./test.out 3

7 Chapter 2 ComLinC Basic Basic concepts in ComLinc. The use of gsl things... 4

8 Chapter 3 Modulation and Demodulation 5

9 Chapter 4 Digital Signal Processing 4.1 Filtering ComLinC implemented digital filter in the similar way that of MatLab. Infinite Impulse Response (IIR) Filter Consider an IIR filter such that: or equivalently, N 1 k=0 a k y n k = H(z) = Y (z) X(z) = So the output can be written as: y n = M 1 k=0 M 1 k=0 b k x n k, (4.1) M 1 k=0 b kz k N 1 k=0 a kz N 1 c k x n k k=1 k. (4.2) d k y n k, (4.3) where c k = b k /a 0, d k = a k /a 0, and n = 0, 1,..., L 1, L = length(x). In ComLinC, the IIR filter is implemented according to eq To use the IIR filter, call the function cl_filter_iir(). The function prototype looks like the following: gsl_vector* cl_filter_iir( gsl_vector* b, gsl_vector* a, gsl_vector* x ); b,a are the filter coefficients defined in eq x is the input to the filter. The output of cl_filter_iir is a double vector of the same length as the input vector. 6

10 Finite Impulse Response (FIR) Filter An FIR filter can be implemented using the IIR filter described the above. Since an FIR filter can be expressed as: or equivalently, y n = M 1 k=0 b k x n k, (4.4) H(z) = Y (z) M 1 X(z) = b k z k. (4.5) k=0 So in fact, the FIR filter implementation is: gsl_vector* y = cl_filter_iir(b,&a.vector,x); where a.vector is an all-one vector with length 1, e.g., a 0 = 1, a k = 0, k > 0. 7

11 Chapter 5 Wireless Environment 8

Follow us on Twitter for important news and Compiling Programs

Follow us on Twitter for important news and updates: @ACCREVandy Compiling Programs Outline Compiling process Linking libraries Common compiling op2ons Automa2ng the process Program compilation Programmers