diff options
| author | Johnathan Corgan <johnathan@corganlabs.com> | 2017-10-05 14:44:45 -0700 |
|---|---|---|
| committer | Johnathan Corgan <johnathan@corganlabs.com> | 2017-10-05 14:44:45 -0700 |
| commit | eda2ad20ab579057e9acc1aa76f1178a6071e1d4 (patch) | |
| tree | 7526e9d16871ea2cf1478229eba5d187e9b30e2c /docs/doxygen | |
| parent | be8f0c0cadca9ffa92a982e27d7e9a88753b6fac (diff) | |
| parent | 6d2221196082a4954c249dc6955e33d5832a56f2 (diff) | |
Merge branch 'maint'
Diffstat (limited to 'docs/doxygen')
| -rw-r--r-- | docs/doxygen/other/stream_tags.dox | 96 |
1 files changed, 46 insertions, 50 deletions
diff --git a/docs/doxygen/other/stream_tags.dox b/docs/doxygen/other/stream_tags.dox index 8edc598e96..146218796e 100644 --- a/docs/doxygen/other/stream_tags.dox +++ b/docs/doxygen/other/stream_tags.dox @@ -15,7 +15,7 @@ GNU Radio was originally a streaming system with no other mechanism to pass data between blocks. Streams of data are a model that work well for samples, bits, etc., but can lack for control and meta data. -Part of this is solved using the message passing interface, which +Part of this is solved using the existing message passing interface, which allows blocks to subscribe to messages published by any other block in the flowgraph (see \ref page_msg_passing). The main drawback to the message passing system is that is works asynchronously, meaning that @@ -24,18 +24,18 @@ stream. Stream tags are an isosynchronous data stream that runs parallel to the main data stream. A stream \a tag is generated by a block's work -function and from there on flows downstream with a particular sample +function and from there on flows downstream alongside a particular sample, until it reaches a sink or is forced to stop propagating by another block. Stream tags are defined for a specific item in the data stream and are -formed as a key:value pair. The \a key identifies what the \a value is +formed as a key:value pair. The \a key identifies what the \a value represents while the value holds the data that the tag contains. Both \a key and \a value are PMTs (\ref page_pmt) where the \a key is a PMT symbol while -the \a value any type of PMT and can therefore handle any data we wish -to pass. A fourth part of the tag is the \a srcid, which is a PMT +the \a value is any type of PMT and can therefore handle any data we wish +to pass. An additional part of the tag is the \a srcid, which is a PMT symbol and is used to identify the block that created the tag (which -is usually the block's alias()). +is usually the block's alias). \section stream_tags_block_api_extensions API Extensions to the gr::block @@ -45,10 +45,10 @@ understand \a absolute item numbers. In the data stream model, each block's work function is given a buffer in the data stream that is referenced from 0 to N-1. This is a \a relative offset into the data stream. The absolute reference starts from the beginning of the -flowgraph and continues to count up with ever item. Each input stream +flowgraph and continues to count up with every item. Each input stream is associated with a concept of the 'number of items read' and each -output stream has a 'number of items written.' These are programmed -using the two API calls: +output stream has a 'number of items written'. These are retrieved during +runtime using the two API calls: \code unsigned long int nitems_read(unsigned int which_input); @@ -69,40 +69,25 @@ at <em>nitems_written(0)+i</em> for the 0th output port. \section stream_tags_api Stream Tags API -The stream tags API consists of four functions, two to add and two to -get the stream tags. These functions are only meant to be accessed -within a call to general_work/work. While they can be called elsewhere +The stream tags API is split into two parts: adding tags to a stream, +and getting tags from a stream. +Note that the functions described below are only meant to be accessed +within a call to general_work/work. While they can be called at other points in time by a block, the behavior outside of work is undefined without exact knowledge of the item counts in the buffers. -\li gr::block::add_item_tag: Adds an item tag to a particular output port using a -gr::tag_t data type. -\li gr::block::add_item_tag: Adds an item tag to a particular output -port where each value of the tag is explicitly given. - -\li gr::block::get_tags_in_range: Gets all tags from a particular -input port between a certain range of items (in absolute item time). - -\li gr::block::get_tags_in_range: Gets any tag that has a specified -key from a particular input port between a certain range of items (in -absolute item time). - -\li gr::block::get_tags_in_window: Gets all tags from a particular -input port between a certain range of items (in relative item time -within the work function). - -\li gr::block::get_tags_in_range: Gets any tag that has a specified -key from a particular input port between a certain range of items (in -relative item time within the work function). +\subsection stream_tags_add_item_tag Adding a Tag to a Stream +We add a tag to a particular output stream of the block using: -\subsection stream_tags_add_item_tag Adding a Tag to a Stream +\li gr::block::add_item_tag: Adds an item tag to a particular output port +using a gr::tag_t data type or by specifying the tag values. -The two function calls to add items tags are defined here. We add a -tag to a particular output stream of the block. We can output them to -multiple output streams if we want, but to do so means calling one of -these functions once for each port. +We can output them to multiple output streams if we want, but to do so +means calling this function once for each port. This function can be +provided with a gr::tag_t data type, or each value of the tag can be +explicitly given. Again, a tag is defined as: @@ -136,14 +121,25 @@ of the tag information in the function call: \subsection stream_tags_get_item_tags Getting tags from a Stream -To get tags from a particular input stream, we again have two -functions we can use. Both of these pass back vectors of -gr::tag_t. The second function allows us to specify a particular key -(as a PMT symbol) that filters out all but the key we are interested -in, which reduces the effort inside the work function for getting the -right tag's data. +To get tags from a particular input stream, we have two +functions we can use: + +\li gr::block::get_tags_in_range: Gets all tags from a particular +input port between a certain range of items (in absolute item time). + +\li gr::block::get_tags_in_window: Gets all tags from a particular +input port between a certain range of items (in relative item time +within the work function). -The first call just returns any tags between the given range of items: +The difference between these functions is working in absolute item +time versus relative item time. Both of these pass back vectors of +gr::tag_t, and they both allow +specifying a particular key (as a PMT symbol) to filter against +(or the fifth argument can be left out to search for all keys). +Filtering for a certain key reduces the effort inside the work function +for getting the right tag's data. + +For example, this call just returns any tags between the given range of items: \code void get_tags_in_range(std::vector<tag_t> &v, @@ -167,7 +163,7 @@ key \a key. \section stream_tags_propagation Tag Propagation Tags are propagated downstream from block to block like the normal -data streams. How blocks are actually moved depends on a specific +data streams. How tags are actually moved depends on a specific propagation policy. We defined three types of policies: \li All-to-All: all tags from any input port are replicated to all @@ -175,7 +171,7 @@ output ports \li One-to-One: tags from input port \a i are only copied to output port \a i (depends on num inputs = num outputs). \li Dont: Does not propagate tags. Tags are either stopped here or the -work function propagates them itself. +work function recreates them in some manner. The default behavior of a block is the 'All-to-All' method of propagation. @@ -217,9 +213,9 @@ block. This becomes relevant when using \ref page_tagged_stream_blocks. Tags can be very useful to an application, and their use is spreading. USRP sources generate tag information on the time, sample rate, and frequency of the board if anything changes. We have a meta -data file source/sink that use tags to store information about the -data stream. But there are things to think about when using tags in a -block. +data file source/sink (see \ref page_metadata) that use tags to store +information about the data stream. But there are things to think about +when using tags in a block. First, when tags are not being used, there is almost no effect on the scheduler. However, when we use tags, we add overhead by getting and @@ -233,7 +229,7 @@ necessary and try to provide some control over how tags are generated to control their frequency. A good example is the USRP source, which generates a time tag. If it generated a tag with every sample, we would have thousands of tags per second, which would add a significant -amount of overhead. Conversely, if we started at time <em>t0</em> at +amount of overhead. This is because if we started at time <em>t0</em> at sample rate <em>sr</em>, then after <em>N</em> samples, we know that we are now at time <em>t0 + N/sr</em>. So continuously producing new tags adds no information. @@ -243,7 +239,7 @@ there is a discontinuity in the packets received from the USRP. Since we have no way of knowing in the flowgraph how many samples were potentially lost, we have lost track of the timing information. The USRP driver recognizes when packets have been dropped and uses this to -queue another tag, which allows us to resync. Likewise, any time the +queue another tag, which allows us to resync. Likewise, any point the sample rate or frequency changes, a new tag is issued. */ |