GNU Radio Internals

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceBlock signature A bloc signature is a specification of the data types that enter orexit the bloc. There are always two bloc signatures, one for inputs, the otherfor outputs. Each bloc signature specifies the number and types of ports. excerpt from gr io signature.h:class GR RUNTIME API io signature{intd min streams;intd max streams;std::vector int d sizeof stream item;io signature(int min streams, int max streams,const std::vector int &sizeof stream items);public:typedef boost::shared ptr io signature sptr; io signature();static sptr make(int min streams, int max streams,int sizeof stream item);/*!* \brief Create an i/o signature*Tanguy RissetGNU Radio Internals* \ingroup internal21

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceBoost Pointer Gnu radio uses Boost smart pointers. Boost is a software library that provides a smart implementationof C pointers that offers garbage collection (i.e. delete objectnot used anymore). Gnu radio uses only the shared ptr type of Boost Instead of declaring a pointer to a type X:X* myPointer;you can declare:boost::shared ptr X myBoostPointer example in gr io signaturetypedef boost::shared ptr io signature sptr;static sptr make(int min streams, int max streams,int sizeof stream item);Tanguy RissetGNU Radio Internals22

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceVolk library Gnu radio uses VOLK (which stands for Vector-Optimized Libraryof Kernels) volk provides a number of optimized function for vectorprocessing using SIMD instructions. Developing with volk might be tricky because it is sensible toalignment of vector in memory. Understanding code using volk simply requires to understandvolk naming convention: The basic naming scheme will look something like this:volk (inputs params) [name] (output params) [alignment] example:volk 32f invsqrt 32fTanguy RissetGNU Radio Internals23

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceOther Volk example General naming convention when there are several inputs oroutputs:volk (input type 0) x(input num 0) (input type 1) x(input num 1) .[name] (output type 0) x(output num 0) (output type 1) x(output num 1) . [alignment] Examples: Multiply two complex float vectors together (aligned and unalignedversions) and the dispatcher:volk 32fc x2 multiply 32fc avolk 32fc x2 multiply 32fc uvolk 32fc x2 multiply 32fc Add four unsigned short vectors together:volk 16u x4 add 16u Multiply a complex float vector by a short integer:volk 32fc s16i multiply 32fcTanguy RissetGNU Radio Internals24

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceSWIG SWIG is a software development tool that connects programswritten in C and C with a variety of high-level programminglanguages. SWIG is used in GNU Radio to link Python and C codeTanguy RissetGNU Radio Internals25

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceSWIG example (1) write a C file example.c code that defines the int fact(int n)function. write an interface file for SWIG:%module example%{int fact(int n);%}int fact(int n); execute the swig command:swig -python example.i it generates a file example wrap.c Compile the .c files with -fPIC option (and path to Python.h):gcc -fPIC -I/usr/include/python2.7 -c example.c example wrap.cTanguy RissetGNU Radio Internals26

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceSWIG example (1) link it to example.so:ld -shared example.o example wrap.o -o example.so import example in python and use the func function:python [.] import example example.fact(5)120Tanguy RissetGNU Radio Internals27

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceCreating GNU radio modules A gnu radio module newModule corresponds to a directorynewModule should contain the following directories:CMakeLists.txt docs grc include lib python swig the gr modtool tool helps you create the various directory Hence the flow for creating a block in a module Create the module file hierarchy with gr modtool Create a block in the module with gr modtool Edit the C file to code the module functionalities Test, debug and validate the functionalitiesTanguy RissetGNU Radio Internals28

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceCreating a trivial module: module creation creating the module directory structure:gr modtool newmod arith Go into the new directory: cd gr-arith/ lsapps CMakeLists.txt examples includecmake docsgrclibTanguy RissetGNU Radio InternalsMANIFEST.mdpythonswig29

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceCreating a trivial module: adding a bloc times2 We will create a bloc of type general block without parameter. Go into the module directory ( cd gr-arith/) and type thefollowing command:gr modtool add -t general times2Answer cpp to the first question and nothing to the otherquestions. create a python test method: edit python/qa times2.py update python/CMakeLists.txt (nothing to do here) create the build directory cd .;mkdir build; build the project: cd build; cmake ./Tanguy RissetGNU Radio Internals30

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceCreating a trivial module: directory hierarchygr-arith[.] -- CMakeLists.txt -- docs -- CMakeLists.txt -- doxygen -- CMakeLists.txt[.] -- grc -- arith times2.xml -- CMakeLists.txt -- include -- arith -- api.h -- CMakeLists.txt -- times2.h -- lib -- CMakeLists.txt -- qa arith.cc -- qa arith.h -- qa times2.cc -- qa times2.h -- test arith.cc -- times2 impl.cc -- times2 impl.cc -- times2 impl.h -- python -- CMakeLists.txt -- init .py -- qa times2.py -- qa times2.py Tanguy RissetGNU Radio Internals31

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceCreating a trivial module: The C part Header files are in include/arith directory Code is in lib/times2 impl.cc, edit it and replace the by values. in times2 impl() (constructor in forecast (indicate scheduler how many input are requires forhow many output items) in general work core of the treatment. make it (in the build directory), and make testTanguy RissetGNU Radio Internals32

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceCreating a trivial module: initial debugging use printf (#include sdtio.h ) use make; make test (from python testbench) log output in Testing/Temporary/LastTest.log Or equivalently: ctest -VTanguy RissetGNU Radio Internals33

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceCreating a trivial module: gnuradio-companion block Now that you have written a valid block, you can create a validgrc block go up to gr-arith directory:gr modtool makexml times2 install it:cd build; sudo make install You can also install the new blocks in a local directory and setenvironnement variables to indicate where gnuradio-companionshould find them (see labs) create a simple grc application (use throttle, remove printf) run it (warning: no print!)Tanguy RissetGNU Radio Internals34

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceTable of Contents1Introduction to GNU RadioWhat is GNU RadioGNU radio with gnuradio-companion2Creating Gnu radio blocksNaming conventionBoost, Volk ad SwigCreating a simple GNU radio module: gr-arith module3Block behavior and Schedulergeneral worksync blocks4Message passing interfacePMTMetadataTags & MessagesTanguy RissetGNU Radio Internals35

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceBlock important function Each Gnu radio bloc inherits from the gr block class. The gr block class contains the following important function (file GNURADIO/include/gnuradio:void set history(unsigned history);virtual void forecast(int noutput tems,gr vector int &ninput items required);virtual int general work(int noutput items,gr vector int &ninput items,gr vector const void star &input items,gr vector void star &output items);void consume(int which input, int how many items);Tanguy RissetGNU Radio Internals36

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfacefunction general work The general work() function computes output streams frominput streams It has 4 arguments int noutput items Number of output items to write on each outputstream (all output streams must produce the same number ofoutput). int ninput items[] Number of input items to read in each inputstream void* intput items[] Vectors of pointers to elements of the inputstream(s), i.e., element i of this vector points to the i th input stream. void* output items[] Vectors of pointers to elements of the outputstream(s), i.e., element i of this vector points to the i th output stream.Tanguy RissetGNU Radio Internals37

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfacefunction general work The general work function implement the signal processingalgorithm. It is called by the scheduler (implicitly, i.e. you do not have toinvoke this function explicitly) The consume function indicates to the scheduler how many datahave been consumed once the general work has been executed Use of input items and output items vectors:input items[0][0]input items[0][1]General Blockoutput items[0][0]output items[0][1]data.data.data.input items[1][0]Tanguy RissetGNU Radio Internals38

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceOne execution of the block Before executioninput items[0][0]input items[0][1]General Blockdata.A6 A5 A4 A3 A2 A1noutput items 1data.output items[0][0]ninput items[0] 4ninput items[1] 2B3 B2 B1data.C1consume(0,4)consume(0,2)input items[1][0] after executioninput items[0][0]input items[0][1]General Blockdata.A6 A5noutput items 1data.output items[0][0]ninput items[0] 4ninput items[1] 2data.C1B3input items[1][0]Tanguy RissetGNU Radio Internals39

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceWhat the code of work function could be Example: sum the 6 samples in input on the outputfor(unsigned int j 0; j 4; j ) {output items[0][0] input items[0][j];}for(unsigned int j 0; j 2; j ) {output items[0][0] input items[1][j];} But it is not that simple. Gnu radio scheduler invokes the work function for computing achunks of output (i.e. not one output by one output, in order toavoid too many context switches) noutput item stays symbolic, it will be set dynamically duringthe execution by the scheduler for performance optimization(usually between 4000 and 10000).Tanguy RissetGNU Radio Internals40

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceWhat the code of work function should be add one loop over all noutput items output samples:for (i 0; i noutput items; i ) {for(j 0 ; j 4; j ) {output items[0][i] input items[0][4*i j];}for(unsigned int j 0; j 2; j ) {output items[0][i] input items[1][2*i j];}} Remember to avoid as much as possible samples copy.Tanguy RissetGNU Radio Internals41

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceWhat the code of work function really is Usual Gnu radio way of writing:const gr complex *in1 (const gr complex*)input items[0];const gr complex *in2 (const gr complex*)input items[1];gr complex *out (gr complex*)output items[0];for (i 0; i noutput items; i ) {for(j 0 ; j 4; j ) {*out *in1 ;}for(unsigned int j 0; j 2; j ) {*out *in2 ;}*out ;}Tanguy RissetGNU Radio Internals42

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceforecast function forecast() is a function which tells the scheduler how manyinput items are required to produce noutput items output items. In most of the case, they are the same:voidmy general block::forecast (int noutput items,gr vector int &ninput items required{ninput items required[0] noutput items;} It is used as an information by the scheduler to schedule theexecutions of the different blocs so as to prevent starvation orbuffer overflows.Tanguy RissetGNU Radio Internals43

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceconsume function The consume (int which input, int how many items)function tells the scheduler that how many items of input streamwhich input were consumed. This function should be called at the end of general work(),after all processing is finished consume each (int how many items) can be used it thenumber of items to consume is the same on each input streamsTanguy RissetGNU Radio Internals44

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfacesummary: code for my general block{my general block::general work (int noutput items,gr vector int &ninput items,gr vector const void star &input items,gr vector void star &output items)const gr complex *in1 (const gr complex*)input items[0];const gr complex *in2 (const gr complex*)input items[1];gr complex *out (gr complex*)output items[0];for (i 0; i noutput items; i ) {for(j 0 ; j 4; j ) {*out *in1 ;}for(unsigned int j 0; j 2; j ) {*out *in2 ;}*out ;}consume(0,4*noutput items);consume(1,4*noutput items);}voidmy general block::forecast (int noutput items,gr vector int &ninput items required){}ninput items required[0] 4*noutput items;ninput items required[1] 2*noutput items;Tanguy RissetGNU Radio Internals45

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceHistory or pipelined blocs Previous example was referred as a block without history in GnuRadio: every input is read only once to produce a single output. Or equivalently: each data read is immediately consumed Many processing blocs act in a pipeline fashion: produce one output data per input data but. use more than one input data to produce an output data. Example of a 4 taps FIR filter:x(i) 4Xy (i k )w(k )k 0input items[0][0]input items[0][1]output items[0][0]current itemset history(4)data.y6 y5 y4 y3 y2 y1data.Tanguy Rissetx6 x5 x4GNU Radio Internals46

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceuse of history in blocsCurrenthistorysampleold samplesdata.output items[0][0]set history(4)y6 y5 y4 y3 y2 y1data.x6 x5 x4input items[0][0] the set history() function is used by the scheduler to keepsome old sample alive (or available) to current samplecomputation. set history(hist) means that we are using hist sample(including current) to produce current output. input item[0][0] points to the oldest sample. Usually we shift the input stream: *in *(in hist-1) such that*in point to the current sample.Tanguy RissetGNU Radio Internals47

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceOther types of blocs gr::sync block is derived from gr::block and implements a1:1 block: It has a work() function rather than general work() function it omits the unnecessary ninput items parameter, and do not needthe consume each() to be called gr::gr sync decimator is used when the number of input itemsis a fixed multiple of the number of output items. The gr sync decimator constructor takes a 4th parameter, thedecimation factor The user should assume that the number of ninput items noutput items*decimation gr::gr sync interpolator is used when the number of outputitems is a fixed multiple of the number of input items. The gr sync interpolator constructor takes a 4th parameter, theinterpolation factor The user should assume that the number of ninput items noutput items/interpolationTanguy RissetGNU Radio Internals48

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceGNU Radio scheduler Dataflow programming model Each block needs a given number of data before running once(i.e. running the general work method) the forecast method of a bloc indicate this information to thescheduler. The scheduler decides to group several execution of each blocand provides a trade-off between performance efficiency andbuffer size between blocs.Tanguy RissetGNU Radio Internals49

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceTable of Contents1Introduction to GNU RadioWhat is GNU RadioGNU radio with gnuradio-companion2Creating Gnu radio blocksNaming conventionBoost, Volk ad SwigCreating a simple GNU radio module: gr-arith module3Block behavior and Schedulergeneral worksync blocks4Message passing interfacePMTMetadataTags & MessagesTanguy RissetGNU Radio Internals50

Introduction to GNU RadioCreating Gnu radio blocksBlock behavior and SchedulerMessage passing interfaceMessage passing protocols GNU Radio was originally a (infinite) streaming system with noother mechanism to pass data between blocks. Not adapted to control data, metadata, and, packet processing For solving this problem, gnuradio introduced Metada filesStream tagsMessage passingAll that heavily relying

Introduction to GNU Radio Creating Gnu radio blocks Block behavior and Scheduler Message passing interface Table of contents 1 Introduction to GNU Radio What is GNU Radio GNU radio with gnuradio-companion . Debugged (with spectrum analyzer for instanc