Creating OOT Module in GR 4.0
Steps
The process to create a GR 4.0 custom block in an OOT is very simple:
- Create the OOT
- Create the Block
- Edit the .yml file
- Implement the constructor
- Implement the
work
method
Creating the OOT
In place of modtool, there is a script in the gnuradio
source tree that will perform the same function
python3 $GR_PREFIX/src/gnuradio/utils/modtool/create_mod.py myOOT
This will create a skeleton OOT with the following structure:
gr4-myOOT/ ├── blocklib │ └── myOOT │ ├── include │ │ └── gnuradio │ │ └── myOOT │ │ └── meson.build │ ├── lib │ │ └── meson.build │ ├── python │ │ └── myOOT │ │ └── __init__.py │ └── test │ └── meson.build ├── meson.build └── meson_options.txt
Creating a Block
To create a block, there is a helper scripts in the gnuradio
source tree:
cd gr4-myOOT python3 $GR_PREFIX/src/gnuradio/utils/modtool/create_block.py myblock
This will create the necessary files for compiling a block by placing a minimal set of files in the following structure:
├── blocklib │ └── myOOT │ ├── myblock │ │ ├── myblock_cpu.cc │ │ ├── myblock_cpu.h │ │ └── myblock.yml
All of the files needed to create the block are located in one place, and all of the normal boilerplate will be automatically generated.
From here let's start with the .yml
file
YML File
Top level properties
module: myOOT
block: myblock
label: myblock
blocktype: sync_block
The first section contains the top level properties. Module and block need to match the module/filename.
Label corresponds to how it would be displayed in GRC or other interface.
Blocktype currently can be block
, sync_block
, or grc
and corresponds to the type of block that will be implemented
Parameters
# Example Parameters
parameters:
- id: itemsize
label: Item Size
dtype: size
settable: false
default: 0
grc:
hide: part
Next we declare the parameters in the block. These correspond to the constructor of the block, as well as setters and getters if desired. The example parameter that is given is for an itemsize parameter, which is by default set to 0 - this can be used to attach an untyped port to an arbitrarily typed port, in the case of e.g. a head or throttle block that doesn't really consider the type of the incoming/outgoing data
dtype
dtype
uses sigmf data type names, and should be from the set (listed as c++, python, and grc type)
type_lookup = {
'cf64': ['std::complex<double>', 'complex', 'complex'],
'cf32': ['std::complex<float>', 'complex', 'complex'],
'rf64': ['double', 'float', 'float'],
'rf32': ['float', 'float', 'float'],
'ri64': ['int64_t', 'int', 'int'],
'ri32': ['int32_t', 'int', 'int'],
'ri16': ['int16_t', 'int', 'short'],
'ri8': ['int8_t', 'int', 'byte'],
'ru64': ['uint64_t', 'int', 'int'],
'ru32': ['uint32_t', 'int', 'int'],
'ru16': ['uint16_t', 'int', 'short'],
'ru8': ['uint8_t', 'int', 'byte'],
'size': ['size_t', 'int', 'int'],
'string': ['std::string', 'str', 'string'],
'bool': ['bool', 'bool', 'bool'],
}
id/label
This gives the parameter a name, which will show up in the constructor arguments as well as the pmt
object instantiated to represent this parameter in the base block
settable/gettable
If the settable
is set true
(default false), the parameter can be changed at runtime via an autogenerated callback method
settable=true
also enables a getter method - but settable=false/gettable=true will only provide the getter
default
The value set for default is a hard default in the constructor arguments. All parameters after this must also have a default set. Parameters with a default value are given keyword arguments in the python bindings
grc
The grc section is passed directly to the generated grc bindings as these pertain specifically to grc fields. These include: - category - hide - default (a soft default when a block is placed on the canvas)
Ports
# Example Ports
ports:
- domain: stream
id: in
direction: input
type: untyped
size: parameters/itemsize
- domain: stream
id: out
direction: output
type: untyped
size: parameters/itemsize
The ports section includes both message and streaming ports, which can be of different types
domain
stream
or message
id
The unique (for this block) id for the port
direction
input
or output
type
untyped
- This is a sized port where the block knows nothing about the type of the data being consumed.
{cf32, rf32, ri32, ...}
- The sigmf types described above. Field not used for message ports
size
For untyped
ports, this fixes the size of the port so it is checked at flowgraph initialization. If set to 0, that check is bypassed and it is up to the block to infer the size of the data from the incoming buffer.
Implementations
implementations:
- id: cpu
# - id: cuda
The Implementations section allows multiple implementations for each block. cpu
is the default, which would then automatically generate the compile targets for myblock_cpu.cc
.
If an implementation is python, this needs to be indicated as follows
implementations:
- id: cpu
- id: numpy
lang: python
domain: cpu
Templated Blocks
As was commonly, but difficultly implemented in GR 3.x, templated blocks use c++ templating to allow selectable types, and this workflow removes much of the boilerplate code associated with this mechanism.
In the .yml file, a typekeys section is added that specifies a series of supported types for the block implementations. Multiple types can be implemented with different ids
typekeys:
- id: T
type: class
options:
- cf32
- rf32
- ri32
- ri16
- ri8
For the above typekeys, blocks will be compiled as myblock_c, myblock_f, etc. corresponding to the suffix that maps to the type option
Implementation Files
The myblock_cpu.cc
and myblock_cpu.h
are designed to get the developer as quickly to the work
method as possible
#include <gnuradio/myOOT/myblock.h>
namespace gr {
namespace myOOT {
class myblock_cpu : public virtual myblock
{
public:
myblock_cpu(block_args args);
work_return_t work(work_io& wio) override;
private:
// private variables here
};
The provided .h
file is very simple and only contains the constructor and work method and derives from an autogenerated base block (lives in the build/
directory)
Constructor
First, notice that the arguments to the constructor are contained in a block_args
struct - this is to minimize the number of things that need to be changed when adding/removing/changing a parameter. This struct will contain in order and with provided defaults the parameters from the .yml
file and be updated when that file changes.
Class Variables
Two things that are not necessary to implement
- Setters/Getters - Local variables that correspond to block parameters
This is because the parameter mechanism handles this in a consistent fashion that we will explore later.
The myblock_cpu.cc
file implements the constructor (some boilerplate abstracted from the INHERITED_CONSTRUCTORS
macro and the work method
#include "myblock_cpu.h"
#include "myblock_cpu_gen.h"
namespace gr {
namespace myOOT {
myblock_cpu::myblock_cpu(block_args args) : INHERITED_CONSTRUCTORS {}
work_return_t myblock_cpu::work(work_io& wio)
{
// Do <+signal processing+>
// Block specific code goes here
return work_return_t::OK;
}
} // namespace myOOT
} // namespace gr