Introduction to

Stream Tags
Tom Rondeau

GNU Radio Conference

9/15/2011
 Stream Tag Layer

Adds a control/logic/synchronous message

interface to data flow layer
 Polymorphic Types (PMTs)
● Generic data type for other objects
● ints (long, int64), floats, complex, bools, strings
● Tests for specific types (pmt_is_?)
● Containers
● Pair, tuple, vector, blob, dictionary
● Operators on PMTs
● Equivalence, length, reverse, access items
 Global Item Counters
● nitems_read
● 64-bit, unsigned
● Count of all items read from an input stream
● nitems_written
● 64-bit, unsigned
● Count of all items sent to an output stream
● All counters start at 0 when flowgraph is
created.
 Tags Data Structure
● uint64_t offset
● absolute sample number of items tag is associated
with.
● pmt::pmt_t key (a PMT symbol)
● Key identifying the tag type (think dictionary)
● pmt::pmt_t value
● Value of tag that can be any PMT data
● pmt::pmt_t srcid (a PMT symbol) (optional)
● Name to identify the creator of the tag
Stream Tags API

Add Tags to Stream

Get Tags in Range

Get Tags in Range by Key

 Add Tags to Stream

Inserts a tag into a stream

void
gr_block::add_item_tag( unsigned int which_output,
uint64_t offset,
const pmt::pmt_t &key,
const pmt::pmt_t &value,
const pmt::pmt_t &srcid )
 Add Tags to Stream
Which output stream should the tag be sent to?
→ which_output,
What sample number is the tag associated with?
→ offset
What is a unique identifier for the tag?
→ key
What data, metedata, information, etc, is being sent?
→ value
What block created this tag?
→ srcid
 Get Tags in Range

Gets all tags within a specified

sample range

void
gr_block::get_tags_in_range(std::vector<pmt::pmt_t> &v,
unsigned int which_output,
uint64_t start,
uint64_t stop )
 Get Tags in Range by Key

Gets all tags that contain a specific key

within a specified sample range

void
gr_block::get_tags_in_range(std::vector<pmt::pmt_t> &v,
unsigned int which_output,
uint64_t start,
uint64_t stop,
const pmt::pmt_t &key )
 Propagation Policies
● Tags are put on a specific output stream but are
propagated downstream based on a policy
● TPP_ALL_TO_ALL (default)
● Tags on all inputs are copied to all outputs
● TPP_ONE_TO_ONE
● Tags on input i are copied only to output i
● Block must have num. inputs == num. Outputs
● TPP_DONT
● Don't copy tags; tag propagation stops
● Block may implement its own policy in work()
Propagation: All-to-All
Propagation: One-to-One
 Tags Through Rate Changes
● All blocks have a relative_rate()
● gr_sync_block: 1.0
● gr_sync_decimator: 1.0/decim
● gr_sync_interpolator: (float)interp
● gr_block: must be set (defaults to 1.0)
 Tags Through Rate Changes
● During tag propagation, tag offsets are updated
by rrate = relative_rate():

uint64_t newcount = 
pmt::pmt_to_uint64(pmt::pmt_tuple_ref(*t, 0));
pmt::pmt_t newtup =
pmt::mp(pmt::pmt_from_uint64(newcount * rrate),
pmt::pmt_tuple_ref(*t, 1),
pmt::pmt_tuple_ref(*t, 2),
pmt::pmt_tuple_ref(*t, 3));
 Example: Burst Detector
● Found in gnuradio-examples/python/tags/

Usage: uhd_burst_detector.py: [options]

Options:
-h, --help show this help message and exit
-a , --address select address of the device
[default=addr=192.168.10.2]
-f, --freq set frequency to FREQ
-g, --gain set gain in dB [default=0]
-R, --samp-rate set USRP sample rate [default=200000]
-t, --threshold Set the detection power threshold (dBm)
[default=-60]
-T, --trigger Use internal trigger instead of detector
[default=False]
 Example: Burst Detector
● Reads a stream from a UHD device
● Waits for a burst of energy over a specified
threshold (-60 dBm default)
● Saves burst to file
● When signal falls below threshold, stop saving
● When the threshold is crossed, a tag is
generated either to start or stop recording
● File sink reads tags for when to start
● Files are timestamped based on tag info
 Burst Detector: Tag Structure
● Key: pmt::pmt_string_to_symbol(“burst”)
● Srcid: pmt::pmt_string_to_symbol(
strcat(name(), unique_id())
● Value:
● pmt::PMT_T (true) if start of tag
● Pmt::PMT_F (false) if end of tag
● Offset: sample number of start or end event
Burst Detector: Diagram

Detects energy over a threshold

Averages stream to smooth out (“debounce”) signal
Stream becomes 0 for no burst and > 0 for burst
Demo
 Consequences
● When there are no tags, almost no added
overhead
● With tags, copying and handing rate changes
will add processing time
● Try not to add more tags then necessary
● Blocks designed to send or receive tags
become more coupled together
● Try to make the blocks independent of tags