Blocks
This page is a summary of the blocks in the GREX project. These blocks provide unique and useful functionality not found in mainline GNU Radio. Also, these blocks act as a demonstration of the advanced functionality and API found in GRAS.
See the GRAS wiki for more: https://github.com/guruofquality/gras/wiki
Table of Contents
The following blocks deal with packetization and recovery of datagrams that may pass through modulation, transmission, reception, and demodulation.
These blocks use the gras::PacketMsg type to pass a reference counted buffer + metadata between blocks.
The packet framer and deframer are based off the blocks of the same name in gr-digital. These blocks are written in python and use the gr-digital packet utils for framing. However, the gr-digital blocks are meant to integrate with a hand-coded python MAC layer; so they cant really be used in a modular block environment, let-alone in GRC. These blocks differ because:
- The packet framer accepts messages as input, and outputs a byte stream to a modulator
- The packet deframer accepts a byte stream from a demodultor, and outputs messages
Sources for these blocks:
- https://github.com/guruofquality/grex/tree/master/packet/packet_framer.py
- https://github.com/guruofquality/grex/tree/master/packet/packet_deframer.py
The burst tagger is meant to accompany the packet framer at the end of the transmit chain. Use case: Packet framer -> modulator -> burst tagger -> USRP sink. The burst tagger deals with the length tag from the packet framer, combined with the interpolation factors from the modulator, and produces the end of burst tags used by the USRP sink.
Source for this block:
The scramber and descrabler blocks are highly configurable blocks. The scrambler block takes a bit stream and applies multiplicative or additive scrambling as well as a configurable sync word. The descrabler handles the scrambled bitstream and deals with recovery of the sync work. See wikipedia for more: http://en.wikipedia.org/wiki/Scrambler
Sources for these blocks:
- https://github.com/guruofquality/grex/blob/master/packet/scrambler.cpp
- https://github.com/guruofquality/grex/blob/master/packet/descrambler.cpp
The following blocks make use of the message passing capabilities of GRAS to pass bounded message between blocks. These blocks use the gras::PacketMsg type to pass a reference counted buffer + metadata between blocks.
Definition of the packet message type: https://github.com/guruofquality/gras/blob/master/include/gras/tags.hpp
See the code guide for API reference: https://github.com/guruofquality/gras/wiki/Codeguide#wiki-messages
The socket and TUN/TAP block provide a message IO interface to a socket, or in the case of TUN/TAP a specially setup file descriptor. The implementations are highly efficient with memory allocation overhead at runtime by reusing pre-allocated buffers from the scheduler.
The socket block may encompass a TCP or UDP server or client (4 cases). This is intended to help users easily get packetized data into and out of flowgraphs, and to maintain those packet boundaires in the flow graph. Imagine streaming a VLC media source to a socket for consumption in a flow graph; or a socket based instant message protocol over the air using GNU Radio flow graphs!
The TUN/TAP block provides a similar interface, but instead, to a virtual network device. A little history: the original GNU Radio two-way comms apps used TUN/TAP to create a lazy send and repead MAC layer over TCP. This is highly discouraged! Read more about TUN/TAP here: http://en.wikipedia.org/wiki/TUN/TAP
Source for these blocks:
- https://github.com/guruofquality/grex/tree/master/network/tcp_socket_message.hpp
- https://github.com/guruofquality/grex/tree/master/network/udp_socket_message.hpp
- https://github.com/guruofquality/grex/tree/master/network/socket_message.cpp
- https://github.com/guruofquality/grex/tree/master/network/tuntap.cpp
The serialization block accepts arbitrary input on any of its input ports and serializes the input into a VITA Radio Link Layer encapsulation. The input can be typical item stream, tagged streams, or messages. The output of this block is a gras::PacketMsg containing a VRL packet. This packet message can be sent over a network, or into a file, using one of the other blocks in this project.
The de-serialization block performs the reverse operation. The input to this block is a gras::PacketMsg containing a VRL packet. This packet is unpacked: Streams, tags, and messages are posted to the appropriate output port. The de-serialization block also performs alignment recovery of the VRL packet because file storage and network streams do not preserve the boundaries of the packet.
VITA usage:
- Item streams are encapsulated into a VITA49 IF data packet
- Streams are kept in the original binary format within the packet
- Message and tags are encapsulated in an extension context packet
- Messages and tags are serialized with boost's text archive module
- The stream ID (SID) of the VITA packet represents the port number
- The ticks count (TSF) of the VITA packet represents the tag's offset
Source for these blocks:
- https://github.com/guruofquality/grex/tree/master/network/serializer.cpp
- https://github.com/guruofquality/grex/tree/master/network/deserializer.cpp
The following blocks make use of C++ templating to effectivly write one block, but get an implementation for many different data types. As opposed to generating the code N times, this model flows more nicely with the C++ paradigm.
Awesome 1: The add and multiply math blocks make use of VOLK (vector optimized library) to implement work functions. In these blocks, we make use of C++'s template overloading to integrate the VOLK routine.
Awesome 2: All of the multi-input blocks are faster than their GNU Radio equivalents because they avoid an unnecessary memcpy. Please note that this isnt due to a particular GRAS advancement, its just a different implemention.
Awesome 3: Because these math blocks are all synchronous 1:1 ratio blocks, they also demonstrate the GRAS feature of buffer inlining. See code guide for more: https://github.com/guruofquality/gras/wiki/Codeguide#wiki-automatic-buffer-inlining
Source for these blocks:
- https://github.com/guruofquality/grex/tree/master/math/add.cpp
- https://github.com/guruofquality/grex/tree/master/math/multiply.cpp
- etc...
The noise and signal source blocks are much like the similarly named blocks in mainline GNU Radio. However, these blocks pre-calculate a sample look-up-table for lower runtime overhead (better performance).
Source for these blocks:
- https://github.com/guruofquality/grex/tree/master/sources/signal_source.cpp
- https://github.com/guruofquality/grex/tree/master/sources/noise_source.cpp
The JIT (just in time) compilation aspect means users can modify their sources continually without dealing in the intricacies compilation and execution. Simply click run in GRC!
The OpenCL block allows a user to interface with an OpenCL compatible device, like a GPU. This block handles most of the complications of using the OpenCL API. All the user has to do is feed the block a .cl file with the kernel source and click run! This block makes use of GRAS's special buffer model so memory allocated from OpenCL can be directly written by upstream blocks and read by downstream blocks.
Read more on the official page for this block: https://github.com/guruofquality/grex/wiki/Opencl
Sources for this block:
- https://github.com/guruofquality/grex/tree/master/jit/opencl_block.cpp
- https://github.com/guruofquality/grex/tree/master/jit/opencl_buffer.hpp
With the ORC block, users simply provide the block a .orc file and click run. The block handles the compilation and execution of the orc kernel automatically. The ORC library will compile the .orc code into SIMD instructions optimized for the host CPU's SIMD units (SSE, AVX, etc...) The ORC language itself is a platform-independent high-level assembly language that can represent SIMD operations.
- Homepage for ORC: http://code.entropywave.com/orc/
Source for this block:
With the Clang block, users simply provide the block a C++ source and click run. The source file contains any custom C++ block written by the user. The Clang block compiles the code at runtime and calls the factory function. The user can write full run-of-the-mill C++ block this way, but without bothering with compilers, cmake, swig, or modtool.
To use this block, GRAS must be built with Clang and LLVM support: https://github.com/guruofquality/gras/wiki/Build
This section contains misc zero copy blocks that didn't fit into another section. You may find some of these blocks useful!
The stream selector allows the user to dynamically (at runtime) change the destination of an input stream to any one of the output ports. Stream selector uses GRAS's zero-copy API to simply forward stream buffers from input ports to output ports. Stream tags are also forwarded properly.
https://github.com/guruofquality/gras/wiki/Codeguide#wiki-passive-workflows
Source for this block:
The delay block has a configurable runtime delay setting, which inserts or removes samples from a stream for a specific absolute sample offset. This block also uses the zero-copy API to passively forward buffers.
Source for this block:
The time align block takes in tagged receive streams and outputs synchronous time-aligned streams. The block works by using the rx_time tags on the input streams to determine absolute time for each sample. Input samples are then dropped on a given stream until output alignment is possible. The implementation is zero-copy, since the work function only needs to inspect input tags, and forward or drop input buffers.
Source for this block:
The stream to datagram and datagram to stream blocks allow the user to go between a stream domain to a packet message domain. Though largely used for testing purposes, one can imagine slicing up a contiguous stream into discrete messages, and vice-versa; reassembling a contiguoys stream from discrete messages.
Also noteworthy: these blocks are completely zero-copy, so they have very little overhead. This is because the stream domain and the packet message type use the same underlying buffer primitive, the blocks do very little more than copy a reference to a buffer between the domains.
Source for these blocks:
- https://github.com/guruofquality/grex/tree/master/misc/datagram_to_stream.cpp
- https://github.com/guruofquality/grex/tree/master/misc/stream_to_datagram.cpp
Various USRP related blocks taking advantage of GRAS features.
The UHD status block provides a message-based access to the USRP sensors API.
Source for this block:
The UHD control block registers handlers into the property tree so other blocks or IP in the flow-graph can seamlessly access the properties of the USRP in a programmatic fashion.
Source for this block:
This block runs an HTML server which drives GRAS's web-based monitor GUI. There is actually little implementation of this block in GREX, its just that GRAS exports a scheduler API, not blocks; so this block is in the GREX package.
See GRAS query client wiki page for more info: https://github.com/guruofquality/gras/wiki/Stats